https://github.com/sshaw/git-link
Emacs package to get the GitHub/Bitbucket/GitLab/... URL for a buffer location
https://github.com/sshaw/git-link
aws-codecommit azure-devops bitbucket codeberg dired emacs git github gitlab magit sourcegraph sourcehut spacemacs tramp urls
Last synced: 15 days ago
JSON representation
Emacs package to get the GitHub/Bitbucket/GitLab/... URL for a buffer location
- Host: GitHub
- URL: https://github.com/sshaw/git-link
- Owner: sshaw
- Created: 2013-11-21T05:53:03.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2025-02-14T12:40:16.000Z (2 months ago)
- Last Synced: 2025-03-31T20:05:28.884Z (22 days ago)
- Topics: aws-codecommit, azure-devops, bitbucket, codeberg, dired, emacs, git, github, gitlab, magit, sourcegraph, sourcehut, spacemacs, tramp, urls
- Language: Emacs Lisp
- Homepage:
- Size: 158 KB
- Stars: 423
- Watchers: 7
- Forks: 79
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# git-link
[](http://melpa.org/#/git-link)
[](https://github.com/sshaw/git-link/actions)
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:
```el
(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
* [Azure DevOps](https://azure.microsoft.com/en-us/services/devops/)
* [AWS CodeCommit](https://aws.amazon.com/codecommit/)
* [Bitbucket](http://bitbucket.com)
* [Codeberg](https://codeberg.org/)
* [cgit](https://wiki.archlinux.org/title/Cgit)
* [GitHub](http://github.com)
* [GitLab](https://gitlab.com)
* [Gitea](https://about.gitea.com/)
* [Gitorious](http://gitorious.org)
* [GoogleSource](https://googlesource.com)
* [Savannah](https://git.savannah.gnu.org/cgit)
* [Sourcegraph](https://sourcegraph.com)
* [sourcehut](https://sourcehut.org)
### Git Timemachine
If [`git-timemachine-mode`](https://codeberg.org/pidu/git-timemachine)
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
```el
(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
```el
(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](#usage) when calling the desired link function or
by [setting `sourcegraph` as the default remote](#settings).
**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](#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.
### [Emacs Transient](https://www.gnu.org/software/emacs/manual/html_mono/transient.html) Support
An optional Transient interface (magit-like menu) is provided via `git-link-transient.el`. To enable you need to have
`transient` installed as a dependency.
To enable `(require 'git-link-transient)` and call `git-link-dispatch` to show the menu.
### 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:
```el
(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`
* `HOSTNAME` hostname of the remote
* `DIRNAME` directory portion of the remote
* `FILENAME` source file, relative to `DIRNAME`
* `BRANCH` active branch, may be `nil` if the repo's in "detached HEAD" state
* `COMMIT` SHA of the latest commit
* `START` starting line number
* `END` ending line number, `nil` unless region is active
The `git-link-commit` signature is:
`HOSTNAME DIRNAME COMMIT`
* `HOSTNAME` hostname of the remote
* `DIRNAME` directory portion of the remote
* `COMMIT` SHA of the commit
### See Also
* [copy-as-format](https://github.com/sshaw/copy-as-format)
* [output-as-format](https://github.com/sshaw/output-as-format)
### TODO
* More tests!
* Consolidate `git-link-*-alist`s
* `git-link-grep`