vcslinks
: Get URLs to commit/file/log/etc. pages in GitHub/GitLab/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¶
Get a URL to GitHub/GitLab/Bitbucket. |
|
Get a URL to the web page for submitting a PR. |
|
Get a URL to commit page. |
|
Get a URL to history page. |
|
Get a URL to file. |
|
Get a URL to tree page. |
|
Get a URL to diff page. |
|
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 ifTrue
. Userevision
(e.g.,master
) as-is ifFalse
. IfNone
(default), resolverevision
if non-None
value is specified forlines
.
-
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'
-
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
. Userevision
(e.g.,master
) as-is ifFalse
.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'