gitsigns.nvim

Deep buffer integration for Git

👀 Preview

| Hunk Actions | Line Blame | | --- | ----------- | | | |

✨ Features

set statusline+=%{get(b:,'gitsigns_status','')}

📋 Requirements

• Neovim >= 0.9.0

[!TIP]

If your version of Neovim is too old, then you can use a past [release].

[!WARNING]

If you are running a development version of Neovim (aka master), then

breakage may occur if your build is behind latest.

• Newish version of git. Older versions may not work with some features.

🛠️ Installation & Usage

Install using your package manager of choice. No setup required.

Optional configuration can be passed to the setup function. Here is an example with most of the default settings:

require('gitsigns').setup {
  signs = {
    add          = { text = '┃' },
    change       = { text = '┃' },
    delete       = { text = '_' },
    topdelete    = { text = '‾' },
    changedelete = { text = '~' },
    untracked    = { text = '┆' },
  },
  signs_staged = {
    add          = { text = '┃' },
    change       = { text = '┃' },
    delete       = { text = '_' },
    topdelete    = { text = '‾' },
    changedelete = { text = '~' },
    untracked    = { text = '┆' },
  },
  signsstagedenable = true,
  signcolumn = true,  -- Toggle with :Gitsigns toggle_signs
  numhl      = false, -- Toggle with :Gitsigns toggle_numhl
  linehl     = false, -- Toggle with :Gitsigns toggle_linehl
  worddiff  = false, -- Toggle with :Gitsigns toggleword_diff
  watch_gitdir = {
    follow_files = true
  },
  auto_attach = true,
  attachtountracked = false,
  currentlineblame = false, -- Toggle with :Gitsigns togglecurrentline_blame
  currentlineblame_opts = {
    virt_text = true,
    virttextpos = 'eol', -- 'eol' | 'overlay' | 'right_align'
    delay = 1000,
    ignore_whitespace = false,
    virttextpriority = 100,
    use_focus = true,
  },
  currentlineblameformatter = '<author>, <authortime:%R> - <summary>',
  blame_formatter = nil, -- Use default
  sign_priority = 6,
  update_debounce = 100,
  status_formatter = nil, -- Use default
  maxfilelength = 40000, -- Disable if file is longer than this (in lines)
  preview_config = {
    -- Options passed to nvimopenwin
    style = 'minimal',
    relative = 'cursor',
    row = 0,
    col = 1
  },
}

For information on configuring Neovim via lua please see [nvim-lua-guide].

🎹 Keymaps

Gitsigns provides an on_attach callback which can be used to setup buffer mappings.

Here is a suggested example:

require('gitsigns').setup{
  ...
  on_attach = function(bufnr)
    local gitsigns = require('gitsigns')
local function map(mode, l, r, opts)       opts = opts or {}       opts.buffer = bufnr       vim.keymap.set(mode, l, r, opts)     end
-- Navigation     map('n', ']c', function()       if vim.wo.diff then         vim.cmd.normal({']c', bang = true})       else         gitsigns.nav_hunk('next')       end     end)
map('n', '[c', function()       if vim.wo.diff then         vim.cmd.normal({'[c', bang = true})       else         gitsigns.nav_hunk('prev')       end     end)
-- Actions     map('n', '<leader>hs', gitsigns.stage_hunk)     map('n', '<leader>hr', gitsigns.reset_hunk)
map('v', '<leader>hs', function()       gitsigns.stage_hunk({ vim.fn.line('.'), vim.fn.line('v') })     end)
map('v', '<leader>hr', function()       gitsigns.reset_hunk({ vim.fn.line('.'), vim.fn.line('v') })     end)
map('n', '<leader>hS', gitsigns.stage_buffer)     map('n', '<leader>hR', gitsigns.reset_buffer)     map('n', '<leader>hp', gitsigns.preview_hunk)     map('n', '<leader>hi', gitsigns.previewhunkinline)
map('n', '<leader>hb', function()       gitsigns.blame_line({ full = true })     end)
map('n', '<leader>hd', gitsigns.diffthis)
map('n', '<leader>hD', function()       gitsigns.diffthis('~')     end)
map('n', '<leader>hQ', function() gitsigns.setqflist('all') end)     map('n', '<leader>hq', gitsigns.setqflist)
-- Toggles     map('n', '<leader>tb', gitsigns.togglecurrentline_blame)     map('n', '<leader>tw', gitsigns.toggleworddiff)
-- Text object     map({'o', 'x'}, 'ih', gitsigns.select_hunk)   end }

🔗 Plugin Integrations

[vim-fugitive]

When viewing revisions of a file (via :0Gclog for example), Gitsigns will attach to the fugitive buffer with the base set to the commit immediately before the commit of that revision. This means the signs placed in the buffer reflect the changes introduced by that revision of the file.

[trouble.nvim]

If installed and enabled (via config.trouble; defaults to true if installed), :Gitsigns setqflist or :Gitsigns setloclist will open Trouble instead of Neovim's built-in quickfix or location list windows.

🚫 Non-Goals

Implement every feature in [vim-fugitive]

This plugin is actively developed and by one of the most well regarded vim plugin developers. Gitsigns will only implement features of this plugin if: it is simple, or, the technologies leveraged by Gitsigns (LuaJIT, Libuv, Neovim's API, etc) can provide a better experience.

Support for other VCS

There aren't any active developers of this plugin who use other kinds of VCS, so adding support for them isn't feasible. However a well written PR with a commitment of future support could change this.

🔌 Similar plugins

• [mini.diff]
• [coc-git]
• [vim-gitgutter]
• [vim-signify]