gitlinker.nvim

Maintained fork of ruifm's gitlinker, refactored with bug fixes, ssh host alias, blame support and other improvements.

A lua plugin for Neovim to generate sharable file permalinks (with line ranges) for git host websites. Inspired by tpope/vim-fugitive's :GBrowse.

Here's an example of git permalink: https://github.com/neovim/neovim/blob/2e156a3b7d7e25e56b03683cc6228c531f4c91ef/src/nvim/main.c#L137-L156.

https://github.com/linrongbin16/gitlinker.nvim/assets/6496887/d3e425a5-cf08-487f-badc-d393ca9dda2f

For now supported platforms are:

https://github.com/
https://gitlab.com/
https://bitbucket.org/
https://codeberg.org/
https://git.samba.org/

PRs are welcomed for other git host websites!

Break Changes & Updates
Requirements
Installation
Usage
Configuration
Development
Contribute

Break Changes & Updates

Break Changes:
- Provide GitLink command instead of default key mappings.
New Features:
- Windows (+wsl2) support.
- Blame support.
- Respect ssh host alias.
- Add ?plain=1 for markdown files.
- Fully customizable git url generation.
Improvements:
- Use git stderr output as error message.
- Async child process IO via coroutine and uv.spawn.
- No third-party dependencies.

Requirements

[!NOTE]

This plugin always supports the latest stable and (possibly) nightly Neovim version.

Neovim ≥ 0.10.
git.
ssh (optional for resolve ssh host alias).
wslview (optional for open browser from Windows wsl2).

Installation

require("lazy").setup({
  {
    "linrongbin16/gitlinker.nvim",
    cmd = "GitLink",
    opts = {},
    keys = {
      { "<leader>gy", "<cmd>GitLink<cr>", mode = { "n", "v" }, desc = "Yank git link" },
      { "<leader>gY", "<cmd>GitLink!<cr>", mode = { "n", "v" }, desc = "Open git link" },
    },
  },
})

</details> <details> <summary>With <a href="https://github.com/lewis6991/pckr.nvim">pckr.nvim</a></summary>

return require('pckr').add(
  {
    'linrongbin16/gitlinker.nvim',
    config = function()
      require('gitlinker').setup()
    end,
  };
)

</details>

Usage

Command

You can use the user command GitLink to generate a (perm)link to the git host website:

GitLink: copy the /blob url to clipboard.
GitLink blame: copy the /blame url to clipboard.
GitLink default_branch: copy the /main or /master url to clipboard.
GitLink current_branch: copy the current branch url to clipboard.

[!NOTE]

Add ! after the command (GitLink!) to directly open the url in browser.

There're several router types:

browse: generate the /blob url (default).
blame: generate the /blame url.
default_branch: generate the /main or /master url.
current_branch: generate the current branch url.

[!NOTE]

A router type is a collection of multiple implementations binding on different git host websites, it works for any git hosts. For example the bitbucket.org:

browse generates the /src url (default): https://bitbucket.org/gitlinkernvim/gitlinker.nvim/src/dbf3922382576391fbe50b36c55066c1768b08b6/.gitignore#lines-9:14.

blame generates the /annotate url: https://bitbucket.org/gitlinkernvim/gitlinker.nvim/annotate/dbf3922382576391fbe50b36c55066c1768b08b6/.gitignore#lines-9:14.

default_branch generates the /main or /master url: https://bitbucket.org/gitlinkernvim/gitlinker.nvim/src/master/.gitignore#lines-9:14.

current_branch generates the current branch url: https://bitbucket.org/gitlinkernvim/gitlinker.nvim/src/feat-dev/.gitignore#lines-9:14.

Multiple Remotes

When there are multiple git remotes, please specify the remote with remote=xxx parameter. For example:

GitLink remote=upstream: copy url for the upstream remote.
GitLink! blame remote=upstream: open blame url for the upstream remote.

[!NOTE]

By default GitLink will use the first detected remote (usually it's origin).

Relative File Path

When the current buffer name is not the file name you want, please specify the target file path with file=xxx parameter. For example:

GitLink file=lua/gitlinker.lua: copy url for the lua/gitlinker.lua file.
GitLink! blame file=README.md: open blame url for the README.md file.

[!NOTE]

By default GitLink will use the current buffer's name.

Commit ID

When the current git repository's commit ID is not that one you want, please specify the target commit ID with rev=xxx parameter. For example:

GitLink rev=00b3f9a1: copy url for the 00b3f9a1 commit ID.
GitLink! blame rev=00b3f9a1: open blame url for the 00b3f9a1 commit ID.

[!NOTE]

By default GitLink will use the current git repository's commit ID.

API

[!NOTE]

Highly recommend reading Customize Urls before this section, which helps understanding the router design of this plugin.

<details> <summary>Click here to see the details.</summary>

You can also use the link API to generate git permlink:

--- @alias gitlinker.Linker {remote_url:string,protocol:string?,username:string?,password:string?,host:string,port:string?,org:string?,user:string?,repo:string,rev:string,file:string,lstart:integer,lend:integer,file_changed:boolean,default_branch:string?,current_branch:string?}
--- @alias gitlinker.Router fun(lk:gitlinker.Linker):string?
--- @alias gitlinker.Action fun(url:string):any
--- @param opts {router_type:string?,router:gitlinker.Router?,action:gitlinker.Action?,lstart:integer?,lend:integer?,message:boolean?,highlight_duration:integer?,remote:string?,file:string?,rev:string?}?
require("gitlinker").link(opts)

The GitLink is actually just a user command wrapper on this API.

Parameters:

opts: (Optional) lua table that contains below fields:
- router_type: Which router type should use. By default is browse when not specified. It has below options:
  - browse
  - blame
  - default_branch
  - current_branch
- router: Which router implementation should use. By default it uses the configured implementations when this plugin is been setup (see Configuration). You can overwrite the configured behavior by passing your implementation to this field. Please see gitlinker.Router for more details.
  
  [!NOTE]
  
  Once set this field, you will get full control of generating the url, and router_type field will no longer take effect.
- action: What action should do. By default it will copy the generated link to clipboard. It has below options, please see gitlinker.Action for more details.
  - require("gitlinker.actions").clipboard: Copy url to clipboard.
  - require("gitlinker.actions").system: Open url in browser.
- lstart/lend: Line range, i.e. start and end line numbers. By default it uses the current line or visual selections. You can also overwrite them to specify the line numbers.
- message: Whether print message in command line. By default it uses the configured value while this plugin is been setup (see Configuration). You can overwrite the configured behavior by passing your option to this field.
- highlight_duration: How long (in milliseconds) to highlight the line range. By default it uses the configured value while this plugin is been setup (see Configuration). You can overwrite the configured behavior by passing your option to this field.
- remote: Specify the git remote. By default it uses the first detected git remote (usually it's origin).
- file: Specify the relative file path. By default it uses the current buffer's name.
- rev: Specify the git commit ID. By default it uses the current git repository's commit ID.

`gitlinker.Router`

A lua function that implements a router for a git host website. It uses below function signature:

function(lk:gitlinker.Linker):string?

Parameters:

lk: A lua table that presents the gitlinker.Linker data type. It contains all the information (fields) you need to generate a git link, e.g. the protocol, host, username, path, rev, etc. Please see Customize Urls - Lua Function for more details.

Returns:

Returns the generated link as a string type, if success.
Returns nil, if failed.

Gitlinker.nvim

Install / Use

README