git-link

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

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

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

git-link-homepagereturns 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 ofgit-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 viaM-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 tonil.

git-link-default-branch

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

git-link-open-in-browser

Iftalso open the link viabrowse-url.To use an alternate function set to that function's symbol. Defaults tonil.

git-link-use-commit

If non-niluse the latest commit's hash in the link instead of the branch name, defaults tonil.

git-link-use-single-line-number

Ifnilline numbers are only added when the selection contains more than 1 line, defaults tot.

Note thatgit-linkwill exclude line numbers when invoked with the-prefix argument.

git-link-add-to-kill-ring

Iftthe link will be added to the kill-ring, defaults tot

git-link-consider-ssh-config

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

Local

git-link.remote

Name of the remote to link to.

git-link.branch

Name of the remote branch to link to.

Supported Services

• Azure DevOps
• AWS CodeCommit
• Bitbucket
• Codeberg
• cgit
• GitHub
• GitLab
• Gitea
• Gitorious
• GoogleSource
• Savannah
• Sourcegraph
• sourcehut

Git Timemachine

Ifgit-timemachine-mode is activegit-linkgenerates 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\\"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\\"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 /github /sshaw/copy-as-format

Links can be generated byspecifyingsourcegraphas your remotewhen calling the desired link function or bysettingsourcegraphas the default remote.

Notethat 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. SeeBuilding 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.

Emacs TransientSupport

An optional Transient interface (magit-like menu) is provided viagit-link-transient.el.To enable you need to have transientinstalled as a dependency.

To enable(require 'git-link-transient)and callgit-link-dispatchto show the menu.

Building Links and Adding Services

git-link-remote-alistis 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 thegit-link-gitlabfunction will be used to create URLs to files in remotes that match the regexp"gitlab".That would cover common Gitlab host URLs like "gitlab","gitlab.example"and"gitlab.example.org".

git-link-commit-remote-alistis 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 atgh.example,you could add the following to your.emacs file:

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

Thegit-linksignature is:

HOSTNAME DIRNAME FILENAME BRANCH COMMIT START END

• HOSTNAMEhostname of the remote
• DIRNAMEdirectory portion of the remote
• FILENAMEsource file, relative toDIRNAME
• BRANCHactive branch, may benilif the repo's in "detached HEAD" state
• COMMITSHA of the latest commit
• STARTstarting line number
• ENDending line number,nilunless region is active

Thegit-link-commitsignature is:

HOSTNAME DIRNAME COMMIT

• HOSTNAMEhostname of the remote
• DIRNAMEdirectory portion of the remote
• COMMITSHA of the commit

See Also

• copy-as-format
• output-as-format

TODO

• More tests!
• Consolidategit-link-*-alists
• git-link-grep