bew / gitsigns.nvim

Git integration for buffers

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

gitsigns.nvim

CI Version License: MIT Gitter

Super fast git decorations implemented purely in lua/teal.

Preview

Hunk Actions Line Blame

Features

  • Signs for added, removed, and changed lines
  • Asynchronous using luv
  • Navigation between hunks
  • Stage hunks (with undo)
  • Preview diffs of hunks (with word diff)
  • Customisable (signs, highlights, mappings, etc)
  • Status bar integration
  • Git blame a specific line using virtual text.
  • Hunk text object
  • Automatically follow files moved in the index.
  • Live intra-line word diff
  • Ability to display deleted/changed lines via virtual lines.
  • Support for yadm

Requirements

  • Neovim >= 0.5.0

    Note: 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

packer.nvim:

use {
  'lewis6991/gitsigns.nvim',
  -- tag = 'release' -- To use the latest release
}

vim-plug:

Plug 'lewis6991/gitsigns.nvim'

Usage

For basic setup with all batteries included:

require('gitsigns').setup()

If using packer.nvim gitsigns can be setup directly in the plugin spec:

use {
  'lewis6991/gitsigns.nvim',
  config = function()
    require('gitsigns').setup()
  end
}

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

require('gitsigns').setup {
  signs = {
    add          = {hl = 'GitSignsAdd'   , text = '', numhl='GitSignsAddNr'   , linehl='GitSignsAddLn'},
    change       = {hl = 'GitSignsChange', text = '', numhl='GitSignsChangeNr', linehl='GitSignsChangeLn'},
    delete       = {hl = 'GitSignsDelete', text = '_', numhl='GitSignsDeleteNr', linehl='GitSignsDeleteLn'},
    topdelete    = {hl = 'GitSignsDelete', text = '', numhl='GitSignsDeleteNr', linehl='GitSignsDeleteLn'},
    changedelete = {hl = 'GitSignsChange', text = '~', numhl='GitSignsChangeNr', linehl='GitSignsChangeLn'},
  },
  signcolumn = true,  -- Toggle with `:Gitsigns toggle_signs`
  numhl      = false, -- Toggle with `:Gitsigns toggle_numhl`
  linehl     = false, -- Toggle with `:Gitsigns toggle_linehl`
  word_diff  = false, -- Toggle with `:Gitsigns toggle_word_diff`
  watch_gitdir = {
    interval = 1000,
    follow_files = true
  },
  attach_to_untracked = true,
  current_line_blame = false, -- Toggle with `:Gitsigns toggle_current_line_blame`
  current_line_blame_opts = {
    virt_text = true,
    virt_text_pos = 'eol', -- 'eol' | 'overlay' | 'right_align'
    delay = 1000,
    ignore_whitespace = false,
  },
  current_line_blame_formatter = '<author>, <author_time:%Y-%m-%d> - <summary>',
  sign_priority = 6,
  update_debounce = 100,
  status_formatter = nil, -- Use default
  max_file_length = 40000,
  preview_config = {
    -- Options passed to nvim_open_win
    border = 'single',
    style = 'minimal',
    relative = 'cursor',
    row = 0,
    col = 1
  },
  yadm = {
    enable = false
  },
}

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 gs = package.loaded.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 return ']c' end
      vim.schedule(function() gs.next_hunk() end)
      return '<Ignore>'
    end, {expr=true})

    map('n', '[c', function()
      if vim.wo.diff then return '[c' end
      vim.schedule(function() gs.prev_hunk() end)
      return '<Ignore>'
    end, {expr=true})

    -- Actions
    map({'n', 'v'}, '<leader>hs', ':Gitsigns stage_hunk<CR>')
    map({'n', 'v'}, '<leader>hr', ':Gitsigns reset_hunk<CR>')
    map('n', '<leader>hS', gs.stage_buffer)
    map('n', '<leader>hu', gs.undo_stage_hunk)
    map('n', '<leader>hR', gs.reset_buffer)
    map('n', '<leader>hp', gs.preview_hunk)
    map('n', '<leader>hb', function() gs.blame_line{full=true} end)
    map('n', '<leader>tb', gs.toggle_current_line_blame)
    map('n', '<leader>hd', gs.diffthis)
    map('n', '<leader>hD', function() gs.diffthis('~') end)
    map('n', '<leader>td', gs.toggle_deleted)

    -- Text object
    map({'o', 'x'}, 'ih', ':<C-U>Gitsigns select_hunk<CR>')
  end
}

Note this requires Neovim v0.7 which introduces vim.keymap.set. If you are using Neovim with version prior to v0.7 then use the following:

Click to expand
require('gitsigns').setup {
  ...
  on_attach = function(bufnr)
    local function map(mode, lhs, rhs, opts)
        opts = vim.tbl_extend('force', {noremap = true, silent = true}, opts or {})
        vim.api.nvim_buf_set_keymap(bufnr, mode, lhs, rhs, opts)
    end

    -- Navigation
    map('n', ']c', "&diff ? ']c' : '<cmd>Gitsigns next_hunk<CR>'", {expr=true})
    map('n', '[c', "&diff ? '[c' : '<cmd>Gitsigns prev_hunk<CR>'", {expr=true})

    -- Actions
    map('n', '<leader>hs', ':Gitsigns stage_hunk<CR>')
    map('v', '<leader>hs', ':Gitsigns stage_hunk<CR>')
    map('n', '<leader>hr', ':Gitsigns reset_hunk<CR>')
    map('v', '<leader>hr', ':Gitsigns reset_hunk<CR>')
    map('n', '<leader>hS', '<cmd>Gitsigns stage_buffer<CR>')
    map('n', '<leader>hu', '<cmd>Gitsigns undo_stage_hunk<CR>')
    map('n', '<leader>hR', '<cmd>Gitsigns reset_buffer<CR>')
    map('n', '<leader>hp', '<cmd>Gitsigns preview_hunk<CR>')
    map('n', '<leader>hb', '<cmd>lua require"gitsigns".blame_line{full=true}<CR>')
    map('n', '<leader>tb', '<cmd>Gitsigns toggle_current_line_blame<CR>')
    map('n', '<leader>hd', '<cmd>Gitsigns diffthis<CR>')
    map('n', '<leader>hD', '<cmd>lua require"gitsigns".diffthis("~")<CR>')
    map('n', '<leader>td', '<cmd>Gitsigns toggle_deleted<CR>')

    -- Text object
    map('o', 'ih', ':<C-U>Gitsigns select_hunk<CR>')
    map('x', 'ih', ':<C-U>Gitsigns select_hunk<CR>')
  end
}

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.

Status Line

Use b:gitsigns_status or b:gitsigns_status_dict. b:gitsigns_status is formatted using config.status_formatter. b:gitsigns_status_dict is a dictionary with the keys added, removed, changed and head.

Example:

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

For the current branch use the variable b:gitsigns_head.

Comparison with vim-gitgutter

Feature gitsigns gitgutter Note
Shows signs for added, modified, and removed lines
Asynchronous
Runs diffs in-process (no IO or pipes) ✅ * * Via lua or FFI.
Only adds signs for drawn lines ✅ * * Via Neovims decoration API
Updates immediately * * Triggered on CursorHold
Ensures signs are always up to date ✅ * * Watches the git dir to do so
Never saves the buffer ✅ ❗ * * Writes buffer (and index) to short lived temp files
Quick jumping between hunks
Stage/reset/preview individual hunks
Stage/reset hunks in range/selection ✅ ❗ * * Only stage
Stage/reset all hunks in buffer
Undo staged hunks
Word diff in buffer
Word diff in hunk preview
Show deleted/changes lines directly in buffer ✅ * * Via virtual lines
Stage partial hunks
Hunk text object
Diff against index or any commit
Folding of unchanged text
Fold text showing whether folded lines have been changed
Load hunk locations into the quickfix or location list
Optional line highlighting
Optional line number highlighting
Optional counts on signs
Customizable signs and mappings
Customizable extra diff arguments
Can be toggled globally or per buffer ✅ * * Through the detach/attach functions
Statusline integration
Works with yadm
Live blame in buffer (using virtual text)
Blame preview
Automatically follows open files moved with git mv
CLI with completion * * Provides individual commands for some actions
Open diffview with any revision/commit

As of 2021-07-05

Integrations

vim-repeat

If installed, stage_hunk() and reset_hunk() are repeatable with the . (dot) operator.

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.

null-ls

Null-ls can provide code actions from Gitsigns. To setup:

local null_ls = require("null-ls")

null_ls.setup {
  sources = {
    null_ls.builtins.code_actions.gitsigns,
    ...
  }
}

Will enable :lua vim.lsp.buf.code_action() to retrieve code actions from Gitsigns.

trouble.nvim

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

Similar plugins

About

Git integration for buffers

License:MIT License


Languages

Language:Lua 99.5%Language:Makefile 0.5%