gitportal.nvim

Bridging the gap between your favorite git host and neovim.

꩜ Table of contents

• Use cases
• Demo
• Requirements
• Installation
• Options
• Setup
• Commands
• Supported hosts
• How this plugin stacks up against others

꩜ Use cases

You want to quickly share a file with a coworker

• GitPortal lets you open your current file in your browser, including any selected lines in the permalink.

A coworker shares a file with you

• GitPortal lets you open shareable permalinks from your favorite Git host directly in Neovim. It seamlessly switches to the correct branch or commit, opens the specified file, and visually selects any lines included in the link.

Please note that the branch/commit must be available locally for it to switch automatically :-)

꩜ GitPortal in action

Opening your current file in your browser

Opening a github url directly in Neovim

꩜ Requirements

꩜ Installation

• lazy.nvim

return { url = 'https://codeberg.org/trevorhauter/gitportal.nvim' }

• vim-plug

Plug 'https://codeberg.org/trevorhauter/gitportal.nvim'

꩜ Options

GitPortal comes with the following options by default.

If you wish to keep these defaults, no configuration is required. To customize them, all you have to do is call setup with your overrides. An example can be seen in the basic setup below. You can read more about the default options on the wiki.

{
    -- Permalink generation | Include current line in URL regardless of current mode
    always_include_current_line = false, -- bool

    -- Permalink generation | Always use the commit hash; otherwise use current branch/commit
    always_use_commit_hash_in_url = false, -- bool

    -- Custom browser command (default: automatically determined by GitPortal)
    browser_command = nil, -- (override only if necessary, not recommended)

    -- Remote to use when generating links (applies globally)
    default_remote = "origin"

    -- Map of remote urls to git providers 
    -- (default: automatically determined by GitPortal, required for self hosted instances)
    -- Ex. {["remote_url"] = { provider = "gitlab", base_url = "https://customdomain.dev"}}
    git_provider_map = nil,

    -- Branch/commit handling when opening links in neovim
    switch_branch_or_commit_upon_ingestion = "always", -- "always" | "ask_first" | "never"
}

꩜ Basic setup

Here is a brief example of the available functions and how I have them set up in my personal config.

Note: setup() is only required if you are going to override any of GitPortals defaults.

local gitportal = require("gitportal")

gitportal.setup({
    always_include_current_line = true, -- Include the current line in permalinks by default
})

-- Key mappings for GitPortal functions:

-- Opens the current file in your browser at the correct branch/commit.
-- When in visual mode, selected lines are included in the permalink.
vim.keymap.set({"n", "v"}, "<leader>gp", gitportal.open_file_in_browser)

-- Opens a Githost link directly in Neovim, optionally switching to the branch/commit.
vim.keymap.set("n", "<leader>ig", gitportal.open_file_in_neovim)

-- Generates and copies the permalink of your current file to your clipboard.
-- When in visual mode, selected lines are included in the permalink.
vim.keymap.set({"n", "v"}, "<leader>gc", gitportal.copy_link_to_clipboard)

Advanced setup

If you use multiple remotes, you can pass a specific remote to any of gitportals core functions (open_file_in_browser, open_file_in_neovim, copy_link_to_clipboard) and it will use that remote for link generation/ingestion over the default remote setting.

-- works w/ open_file_in_browser, copy_link_to_clipboard & open_file_in_neovim
vim.keymap.set("n", "<leader>gh", function()
    gitportal.open_file_in_browser({ remote = "another_remote" })
end)

꩜ Commands

If you prefer to use commands over calling gitportals functions directly, you can use the following commands

The following command takes several arguments.

:GitPortal [action] -- browse_file (default) | open_link | copy_link_to_clipboard

• :GitPortal -- Opens the current file in your browser at the correct branch/commit. If a range is selected, opens the link for the selected lines.
• :GitPortal browse_file -- Same as above.
• :GitPortal open_link {url} -- Opens a githost link in neovim, switching to the branch/commit depending on options. Falls back to the system clipboard if no URL is given.
• :GitPortal copy_link_to_clipboard -- Generates a permalink to the current file and copies it to your system clipboard. If a range is selected, copies the link for the selected lines.

꩜ Supported git providers

Git host	Supported	Self host support
Bitbucket	✅	✅
Codeberg	✅	N/A (Uses forgejo)
Forgejo	N/A	✅
GitHub	✅	✅
GitLab	✅	✅
Onedev	N/A	✅
SourceHut	✅	❌

We are working hard to add more hosts for git, including self hosted options. If you'd like to use a host not yet listed, please check out our issues to see if an issue is present. If you don't see an issue created for your desired host, please create one!

꩜ Comparison against other popular git browsing plugins

Feature	gitportal.nvim	vim-fugitive	vim-rhubarb	gitlinker.nvim
Open current file in browser, with optional line ranges	✅	✅	✅	✅
Open permalinks in neovim, with respect to line range, branch, or commit	✅	❌	❌	❌