Low-level API¶

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

Analyze a Git repository and return a WebURL instance.

>>> weburl = analyze()                                 
>>> weburl.rooturl
'https://github.com/USER/PROJECT'
>>> weburl.commit("master")
'https://github.com/USER/PROJECT/commit/55150afe539493d650889224db136bc8d9b7ecb8'
>>> weburl.file("README.md")
'https://github.com/USER/PROJECT/blob/master/README.md'
>>> weburl.log()
'https://github.com/USER/PROJECT/commits/master'
>>> weburl.pull_request()
'https://github.com/USER/PROJECT/pull/new/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.

class vcslinks.WebURL(local_branch: LocalBranch)¶

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

Get a URL to blame/annotate page.

GitHub

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

GitLab

>>> weburl.blame("README.md")
'https://gitlab.com/USER/PROJECT/blame/master/README.md'

Bitbucket

>>> weburl.blame("README.md")
'https://bitbucket.org/USER/PROJECT/annotate/master/README.md'

commit(revision: str) → str ¶

Get a URL to commit page.

>>> weburl.commit("master")
'https://github.com/USER/PROJECT/commit/55150afe539493d650889224db136bc8d9b7ecb8'

diff(revision1: Optional[str] = None, revision2: Optional[str] = None, permalink: bool = False) → str ¶

Get a URL to diff page.

GitHub

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

GitLab

>>> weburl.diff("dev")
'https://gitlab.com/USER/PROJECT/compare/master...dev'

Bitbucket

>>> weburl.diff("dev")
'https://bitbucket.org/USER/PROJECT/branches/compare/dev%0Dmaster#diff'

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

Get a URL to file.

GitHub

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

GitLab

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

Bitbucket

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

log(branch: Optional[str] = None) → str ¶

Get a URL to history page.

>>> weburl_github.log()
'https://github.com/USER/PROJECT/commits/master'
>>> weburl_gitlab.log()
'https://gitlab.com/USER/PROJECT/commits/master'
>>> weburl_bitbucket.log()
'https://bitbucket.org/USER/PROJECT/commits/branch/master'

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

pull_request() → Optional[str]¶

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

>>> weburl_github.pull_request()
'https://github.com/USER/PROJECT/pull/new/master'
>>> weburl_gitlab.pull_request()
'https://gitlab.com/USER/PROJECT/merge_requests/new?merge_request%5Bsource_branch%5D=master'
>>> weburl_bitbucket.pull_request()
'https://bitbucket.org/USER/PROJECT/pull-requests/new?source=master'

tree(directory: Optional[Union[str, pathlib.Path]] = None, revision: Optional[str] = None, permalink: bool = False) → str ¶: Get a URL to tree page.