📖 browsher.nvim

browsher.nvim is a highly customizable Neovim plugin that opens the current file at the specified lines or range in your default browser, pinned to a specific branch, tag, commit, or the repository root in your remote Git repository.

✨ Features

• Open files in the browser: Quickly open the current file in your remote Git repository's web interface.
• Line and Range Support: Supports opening specific lines or ranges, including multiline selections from visual mode.
• Short commit hashes: Trim the 40 character hash down with commit_length, for links that stay readable.
• Customizable providers: Support for GitHub, GitLab, Sourcehut, and the ability to specify custom git web interfaces.
• Custom open commands: Specify custom commands to open URLs (e.g., use a specific browser).

📦 Installation

Using lazy.nvim

{
  'claydugo/browsher.nvim',
  event = "VeryLazy",
  config = function()
    -- Specify empty to use below default options
    require('browsher').setup()
  end
}

Important

Please submit a Pull Request and add to this section if you have worked through installation instructions for other plugin managers!

⚙️ Configuration

You can customize browsher.nvim by passing options to the setup function, below are the default options.

Default Options

require("browsher").setup({
    --- Default remote name (e.g., 'origin').
    default_remote = nil,
    --- Default branch name.
    default_branch = nil,
    --- Default pin type ('commit', 'branch', or 'tag').
    default_pin = "commit",
    --- Length of the commit hash to use in URLs. If nil, use full length. (40)
    commit_length = nil,
    --- Allow line numbers with uncommitted changes.
    allow_line_numbers_with_uncommitted_changes = false,
    --- Command to open URLs (e.g., 'firefox').
    --- If nil, the command is chosen based on the OS. On WSL, `wslview` is
    --- used if available, `explorer.exe` otherwise.
    --- If this is a single character, it will be interpreted as a vim register
    --- instead. For example, to copy the url to your OS clipboard instead of
    --- opening it inside an application, set `open_cmd` to `+` for unix systems,
    --- or `*` if you're on Windows.
    open_cmd = nil,
    --- Custom providers for building URLs.
    ---
    --- Each provider is a table with the following keys:
    --- - `url_template`: The URL template, where `%s` are placeholders.
    ---   The placeholders are, in order:
    ---   1. Remote URL
    ---   2. Branch or tag
    ---   3. Relative file path
    --- - `single_line_format`: Format string for a single line (e.g., `#L%d`).
    --- - `multi_line_format`: Format string for multiple lines (e.g., `#L%d-L%d`).
    ---
    --- Example:
    --- ```lua
    --- providers = {
    ---   ["mygit.com"] = {
    ---     url_template = "%s/src/%s/%s",
    ---     single_line_format = "?line=%d",
    ---     multi_line_format = "?start=%d&end=%d",
    ---   },
    --- }
    providers = {
        ["github.com"] = {
            url_template = "%s/blob/%s/%s",
            single_line_format = "#L%d",
            multi_line_format = "#L%d-L%d",
        },
        ["gitlab.com"] = {
            url_template = "%s/-/blob/%s/%s",
            single_line_format = "#L%d",
            multi_line_format = "#L%d-%d",
        },
        ["sr.ht"] = {
            url_template = "%s/tree/%s/item/%s",
            single_line_format = "#L%d",
            multi_line_format = "#L%d",
        },
    },
})

Self-hosted providers

Reuse a built-in provider definition for a self-hosted instance:

require("browsher").setup({
    providers = {
        ["gitlab.example.com"] = require("browsher").providers["gitlab.com"],
    },
})

Shorter URLs

Pinning to a commit gives a link that never drifts. The full 40 character hash makes that link long.

Set commit_length to trim the hash:

require("browsher").setup({ commit_length = 20 })

Default, commit_length = nil:

https://github.com/claydugo/browsher.nvim/blob/50d537a0a517505a6eb97288be5e789d89ba658c/lua/browsher/git.lua#L211-L229

With commit_length = 20:

https://github.com/claydugo/browsher.nvim/blob/50d537a0a517505a6eb9/lua/browsher/git.lua#L211-L229

Both links point at the same commit. 20 is a good starting point. It halves the hash and stays unambiguous in large repositories. Git expands the hash anyway if the length you pick is too short.

Key Mappings

Add the following key mappings to your Neovim configuration to quickly open files in the browser:

-- Open from the latest commit, the recommended default operation
vim.api.nvim_set_keymap('n', '<leader>b', '<cmd>Browsher commit<CR>', { noremap = true, silent = true })
vim.api.nvim_set_keymap('v', '<leader>b', ":'<,'>Browsher commit<CR>gv", { noremap = true, silent = true })

-- Open from the latest tag, for more human readable urls (with risk of outdated line numbers)
vim.api.nvim_set_keymap('n', '<leader>B', '<cmd>Browsher tag<CR>', { noremap = true, silent = true })
vim.api.nvim_set_keymap('v', '<leader>B', ":'<,'>Browsher tag<CR>gv", { noremap = true, silent = true })

🚀 Usage

Use the :Browsher command to open the current file in your browser:

:Browsher [pin_type] [commit_hash]

• pin_type (optional): Specifies how to pin the file in the URL. Can be branch, tag, or commit. If omitted, uses the default pin type from the configuration (commit by default).
• commit_hash (optional): Specific commit hash to use when pin_type is commit.

Examples

Open current file at the latest commit:

:Browsher

Open the repository root URL:

:Browsher root

Open current file at the current branch:

:Browsher branch

Open current file at the latest tag:

:Browsher tag

Open current file at a specific commit:

:Browsher commit 123abc

Open a visual selection of lines:

:'<,'>Browsher commit

Select lines in visual mode and run:

:Browsher

⚠️ Notes

• Uncommitted Changes: If the current file has uncommitted changes, line numbers may not correspond to what's on the remote repository. By default, line numbers are omitted when there are uncommitted changes unless allow_line_numbers_with_uncommitted_changes is set to true.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.