Home

Awesome

git-link

MELPA Build Status

Interactive Emacs functions that create URLs for files and commits in GitHub/Bitbucket/GitLab/... repositories.

git-link returns the URL for the current buffer's file location at the current line number or active region.

git-link-commit returns the URL for the commit at point.

git-link-homepage returns the URL for the repository's homepage.

URLs are added to the kill ring.

Usage

Functions can be called interactively (M-x git-link) or via a key binding of your choice. For example:

(global-set-key (kbd "C-c g l") 'git-link)

With a single prefix argument prompt for the remote's name. Defaults to "origin".

With a double prefix argument invert the value of git-link-use-commit.

With a prefix argument of -, generate a link without line numbers.

Works with Dired, Magit, VC revisions, and Tramp too.

Settings

Global setting are elisp variables. They can be set directly or via M-x customize.

Local settings are managed via the repository's git configuration. They can be set via:

git config --local --add setting value

Local settings have precedence over global settings.

Global

git-link-default-remote

Name of the remote to link to, defaults to nil.

git-link-default-branch

Name of the remote branch to link to, defaults to the current branch.

git-link-open-in-browser

If t also open the link via browse-url. To use an alternate function set to that function's symbol. Defaults to nil.

git-link-use-commit

If non-nil use the latest commit's hash in the link instead of the branch name, defaults to nil.

git-link-use-single-line-number

If nil line numbers are only added when the selection contains more than 1 line, defaults to t.

Note that git-link will exclude line numbers when invoked with the - prefix argument.

git-link-add-to-kill-ring

If t the link will be added to the kill-ring, defaults to t

git-link-consider-ssh-config

If t consider ssh configuration file for resolving the remote's hostname. If there's a match (using ssh -G), the link will be generated to the matching host instead of the remote's host. Defaults to nil.

Local

git-link.remote

Name of the remote to link to.

git-link.branch

Name of the remote branch to link to.

Supported Services

Git Timemachine

If git-timemachine-mode is active git-link generates a URL for the version of the file being visited.

cgit and Gitea

git-link comes with functions for linking to repositories hosted by these services but, because they're self-hosted there is no default URL to match. To make git-link work with these you must configure your URLs to use the appropriate matching function.

cgit

(eval-after-load 'git-link
 '(progn
   (add-to-list 'git-link-remote-alist
     '("your-cgit\\.example\\.com" git-link-cgit))
   (add-to-list 'git-link-commit-remote-alist
     '("your-cgit\\.domain\\.tld" git-link-commit-cgit))))

Gitea

(eval-after-load 'git-link
 '(progn
   (add-to-list 'git-link-remote-alist
     '("your-gitea\\.example\\.com" git-link-gitea))
   (add-to-list 'git-link-commit-remote-alist
     '("your-gitea\\.domain\\.tld" git-link-commit-gitea))))

Sourcegraph

To link to files on a Sourcegraph server add a git remote pointing to the repository's Sourcegraph page:

git remote add sourcegraph https://sourcegraph.com/github.com/sshaw/copy-as-format

Links can be generated by specifying sourcegraph as your remote when calling the desired link function or by setting sourcegraph as the default remote.

Note that the remote can be named anything but its URL's host must match what's in the associated link function's alist. This defaults to "sourcegraph" but can be changed. See Building Links and Adding Services.

URLs with ports or an http scheme will not work. It's a trivial fix so if it's a problem for you please open an issue.

Building Links and Adding Services

git-link-remote-alist is an alist containing (REGEXP FUNCTION) elements. The FUNCTION creates URLs for file on remote host names that match the REGEXP. To add (or modify) how URLs are created for a given host, add appropriate elements to this list.

As an example, one of the default elements in this alist is ("gitlab" git-link-gitlab). So the git-link-gitlab function will be used to create URLs to files in remotes that match the regexp "gitlab". That would cover common Gitlab host URLs like "gitlab.com", "gitlab.example.com" and "gitlab.example.org".

git-link-commit-remote-alist is also an alist containing (REGEXP FUNCTION) elements. Here, the FUNCTION creates URLs to the commit pages, for remote hosts matching REGEXP.

If you use a self-hosted version of one of the supported services, but your remote URL does match with the defaults, you can configure these link function alists. For example, for a GitHub Enterprise instance at gh.example.com, you could add the following to your .emacs file:

(eval-after-load 'git-link
 '(progn
   (add-to-list 'git-link-remote-alist
     '("gh\\.example\\.com" git-link-github))
   (add-to-list 'git-link-commit-remote-alist
     '("gh\\.example\\.com" git-link-commit-github))))

The git-link signature is:

HOSTNAME DIRNAME FILENAME BRANCH COMMIT START END

The git-link-commit signature is:

HOSTNAME DIRNAME COMMIT

See Also

TODO