Bitbucket¶

vcslinks is a Python package for analyzing a local Git repository to find a URL for web pages in the hosted services like GitHub, GitLab, and Bitbucket. For example, a permalink to the file setup.py with lines 5 to 10 highlighted can be obtained by

>>> import vcslinks
>>> vcslinks.file("setup.py", lines=(5, 10))
'https://github.com/USER/PROJECT/blob/55150afe539493d650889224db136bc8d9b7ecb8/setup.py#L5-L10'

vcslinks also comes with command line program vcsbrowse for opening relevant pages of GitHub/GitLab/Bitbucket in web browser.

High-level API¶

`root`	Get a URL to GitHub/GitLab/Bitbucket.
`pull_request`	Get a URL to the web page for submitting a PR.
`commit`	Get a URL to commit page.
`log`	Get a URL to history page.
`file`	Get a URL to file.
`tree`	Get a URL to tree page.
`diff`	Get a URL to diff page.
`blame`	Get a URL to blame/annotate page.

vcslinks.root(*, path: Union[str, pathlib.Path] = '.', **kwargs) → str ¶

Get a URL to GitHub/GitLab/Bitbucket.

GitHub

>>> import vcslinks
>>> vcslinks.root()
'https://github.com/USER/PROJECT'

GitLab

>>> vcslinks.root(path="path/to/gitlab/clone")
'https://gitlab.com/USER/PROJECT'

Bitbucket

>>> vcslinks.root(path="path/to/bitbucket/clone")
'https://bitbucket.org/USER/PROJECT'

Parameters

path – Path to a Git repository. It can be a path to any file or directory inside the repository. The root of the Git repository is found automatically by the git command.
branch – Local branch name to be used. The remote service is determined from this local branch. If not specified, current local branch is used if its upstream is in one of the supported remote service (e.g., GitHub). Otherwise fallbacks to master.

vcslinks.pull_request(path: Union[str, pathlib.Path] = '.', **kwargs) → Optional[str]¶

Get a URL to the web page for submitting a PR.

GitHub

>>> import vcslinks
>>> vcslinks.pull_request()
'https://github.com/USER/PROJECT/pull/new/master'

GitLab

>>> vcslinks.pull_request(path="path/to/gitlab/clone")
'https://gitlab.com/USER/PROJECT/merge_requests/new?merge_request%5Bsource_branch%5D=master'

Bitbucket

>>> vcslinks.pull_request(path="path/to/bitbucket/clone")
'https://bitbucket.org/USER/PROJECT/pull-requests/new?source=master'

Parameters

path – Path to a Git repository. It can be a path to any file or directory inside the repository. The root of the Git repository is found automatically by the git command.
branch – Local branch name to be used. The remote service is determined from this local branch. If not specified, current local branch is used if its upstream is in one of the supported remote service (e.g., GitHub). Otherwise fallbacks to master.

vcslinks.commit(revision: str = 'HEAD', *, path: Union[str, pathlib.Path] = '.', **kwargs) → str ¶

Get a URL to commit page.

GitHub

>>> import vcslinks
>>> vcslinks.commit()
'https://github.com/USER/PROJECT/commit/55150afe539493d650889224db136bc8d9b7ecb8'
>>> vcslinks.commit("dev")
'https://github.com/USER/PROJECT/commit/40539486fdaf08a39b57519eb06e0e200c932cfd'

GitLab

>>> vcslinks.commit(path="path/to/gitlab/clone")
'https://gitlab.com/USER/PROJECT/commit/55150afe539493d650889224db136bc8d9b7ecb8'

Bitbucket

>>> vcslinks.commit(path="path/to/bitbucket/clone")
'https://bitbucket.org/USER/PROJECT/commits/55150afe539493d650889224db136bc8d9b7ecb8'

Parameters

revision – Git commit-ish. It is resolved in the local repository.
path – Path to a Git repository. It can be a path to any file or directory inside the repository. The root of the Git repository is found automatically by the git command.
branch – Local branch name to be used. The remote service is determined from this local branch. If not specified, current local branch is used if its upstream is in one of the supported remote service (e.g., GitHub). Otherwise fallbacks to master.

vcslinks.log(commit: Optional[str] = None, *, path: Union[str, pathlib.Path] = '.', **kwargs) → str ¶

Get a URL to history page.

GitHub

>>> import vcslinks
>>> vcslinks.log()
'https://github.com/USER/PROJECT/commits/master'
>>> vcslinks.log("dev")
'https://github.com/USER/PROJECT/commits/dev'

GitLab

>>> vcslinks.log(path="path/to/gitlab/clone/")
'https://gitlab.com/USER/PROJECT/commits/master'

Bitbucket

>>> vcslinks.log(path="path/to/bitbucket/clone/")
'https://bitbucket.org/USER/PROJECT/commits/branch/master'

Parameters

commit – Git commit-ish. Note that it must be a remote branch name for Bitbucket.
path – Path to a Git repository. It can be a path to any file or directory inside the repository. The root of the Git repository is found automatically by the git command.
branch – Local branch name to be used. The remote service is determined from this local branch. If not specified, current local branch is used if its upstream is in one of the supported remote service (e.g., GitHub). Otherwise fallbacks to master.

vcslinks.file(file: Union[str, pathlib.Path], lines: Union[None, int, Tuple[int, int]] = None, revision: Optional[str] = None, permalink: Optional[bool] = None, **kwargs) → str ¶

Get a URL to file.

GitHub

>>> import vcslinks
>>> vcslinks.file("README.md")
'https://github.com/USER/PROJECT/blob/master/README.md'
>>> vcslinks.file("README.md")
'https://github.com/USER/PROJECT/blob/master/README.md'
>>> vcslinks.file("README.md", permalink=True)
'https://github.com/USER/PROJECT/blob/55150afe539493d650889224db136bc8d9b7ecb8/README.md'
>>> vcslinks.file("README.md", lines=1)
'https://github.com/USER/PROJECT/blob/55150afe539493d650889224db136bc8d9b7ecb8/README.md#L1'
>>> vcslinks.file("README.md", lines=(1, 2))
'https://github.com/USER/PROJECT/blob/55150afe539493d650889224db136bc8d9b7ecb8/README.md#L1-L2'
>>> vcslinks.file("README.md", lines=(1, 2), permalink=False)
'https://github.com/USER/PROJECT/blob/master/README.md#L1-L2'

GitLab

>>> vcslinks.file("path/to/gitlab/clone/README.md")
'https://gitlab.com/USER/PROJECT/blob/master/README.md'
>>> vcslinks.file("path/to/gitlab/clone/README.md", lines=1)
'https://gitlab.com/USER/PROJECT/blob/55150afe539493d650889224db136bc8d9b7ecb8/README.md#L1'
>>> vcslinks.file("path/to/gitlab/clone/README.md", lines=(1, 2))
'https://gitlab.com/USER/PROJECT/blob/55150afe539493d650889224db136bc8d9b7ecb8/README.md#L1-2'

Bitbucket

>>> vcslinks.file("path/to/bitbucket/clone/README.md")
'https://bitbucket.org/USER/PROJECT/src/master/README.md'
>>> vcslinks.file("path/to/bitbucket/clone/README.md", lines=1)
'https://bitbucket.org/USER/PROJECT/src/55150afe539493d650889224db136bc8d9b7ecb8/README.md#lines-1'
>>> vcslinks.file("path/to/bitbucket/clone/README.md", lines=(1, 2))
'https://bitbucket.org/USER/PROJECT/src/55150afe539493d650889224db136bc8d9b7ecb8/README.md#lines-1:2'

Parameters

file – Path to a file to be shown.
lines – Line(s) to be highlighted. A tuple of two integers specifies a range of lines. An integer specifies a line. No lines are highlighted if a None is passed.
revision – Git commit-ish.
permalink – Resolve the revision in the local repository to a full revision if True. Use revision (e.g., master) as-is if False. If None (default), resolve revision if non-None value is specified for lines.

vcslinks.tree(directory: Optional[Union[str, pathlib.Path]] = None, revision: Optional[str] = None, permalink: bool = False, **kwargs) → str ¶

Get a URL to tree page.

GitHub

>>> import vcslinks
>>> vcslinks.tree()
'https://github.com/USER/PROJECT/tree/master'
>>> vcslinks.tree(revision="dev")
'https://github.com/USER/PROJECT/tree/dev'
>>> vcslinks.tree(permalink=True)
'https://github.com/USER/PROJECT/tree/55150afe539493d650889224db136bc8d9b7ecb8'

GitLab

>>> vcslinks.tree("path/to/gitlab/clone/SUBDIRECTORY")
'https://gitlab.com/USER/PROJECT/tree/master/SUBDIRECTORY'
>>> vcslinks.tree("path/to/gitlab/clone/SUBDIRECTORY", permalink=True)
'https://gitlab.com/USER/PROJECT/tree/55150afe539493d650889224db136bc8d9b7ecb8/SUBDIRECTORY'

Bitbucket

>>> vcslinks.tree("path/to/bitbucket/clone/SUBDIRECTORY")
'https://bitbucket.org/USER/PROJECT/src/master/SUBDIRECTORY'
>>> vcslinks.tree("path/to/bitbucket/clone/SUBDIRECTORY", permalink=True)
'https://bitbucket.org/USER/PROJECT/src/55150afe539493d650889224db136bc8d9b7ecb8/SUBDIRECTORY'

Parameters

directory – Path to a directory to be shown.
revision – Git commit-ish.
permalink – Resolve the revisions in the local repository to a full revision if True. Use revision (e.g., master) as-is if False.

vcslinks.diff(revision1: Optional[str] = None, revision2: Optional[str] = None, permalink: bool = False, path: Union[str, pathlib.Path] = '.', **kwargs) → str ¶

Get a URL to diff page.

GitHub

>>> import vcslinks
>>> vcslinks.diff("dev")
'https://github.com/USER/PROJECT/compare/master...dev'
>>> vcslinks.diff(permalink=True)
'https://github.com/USER/PROJECT/compare/master...55150afe539493d650889224db136bc8d9b7ecb8'
>>> vcslinks.diff("master", "dev", permalink=True) == (
...     'https://github.com/USER/PROJECT/compare/'
...     '55150afe539493d650889224db136bc8d9b7ecb8'
...     '...'
...     '40539486fdaf08a39b57519eb06e0e200c932cfd'
... )
True

GitLab

>>> vcslinks.diff("dev", path="path/to/gitlab/clone/")
'https://gitlab.com/USER/PROJECT/compare/master...dev'

Bitbucket

>>> vcslinks.diff("dev", path="path/to/bitbucket/clone/")
'https://bitbucket.org/USER/PROJECT/branches/compare/dev%0Dmaster#diff'

Parameters

revision1 –
revision2 – Function diff takes zero, one, or two commits as positional arguments. If two commits are given, the first commit is the source and the second commit is the target. If one commit is given, it is the target and remote master is the source. If no revisions are given, the remote branch upstream to the current local branch is compared to the remote master.
permalink – Resolve the revisions in the local repository to a full revision if True. Use revision (e.g., master) as-is if False.
path – Path to a Git repository. It can be a path to any file or directory inside the repository. The root of the Git repository is found automatically by the git command.
branch – Local branch name to be used. The remote service is determined from this local branch. If not specified, current local branch is used if its upstream is in one of the supported remote service (e.g., GitHub). Otherwise fallbacks to master.

vcslinks.blame(file: Union[str, pathlib.Path], lines: Union[None, int, Tuple[int, int]] = None, revision: Optional[str] = None, permalink: Optional[bool] = None, **kwargs) → str ¶

Get a URL to blame/annotate page.

See vcslinks.file for how the arguments are used.

GitHub

>>> import vcslinks
>>> vcslinks.blame("README.md")
'https://github.com/USER/PROJECT/blame/master/README.md'

GitLab

>>> vcslinks.blame("path/to/gitlab/clone/README.md")
'https://gitlab.com/USER/PROJECT/blame/master/README.md'

Bitbucket

>>> vcslinks.blame("path/to/bitbucket/clone/README.md")
'https://bitbucket.org/USER/PROJECT/annotate/master/README.md'

Indices and tables¶

Contents:

vcslinks: Get URLs to commit/file/log/etc. pages in GitHub/GitLab/Bitbucket¶

High-level API¶

Indices and tables¶

`vcslinks`: Get URLs to commit/file/log/etc. pages in GitHub/GitLab/Bitbucket¶