gitsigns.nvim

Git signs written in pure lua.

Status

WIP

Expect things to break sometimes but please don't hesitate to raise an issue.

Features

Signs for added, removed, and changed lines
Asynchronous using luv
Navigation between hunks
Stage hunks (with undo)
Preview diffs of hunks
Customisable (signs, highlights, mappings, etc)
Status bar integration
Git blame a specific line
Hunk text object

Requirements

Neovim >= 0.5.0

Installation

packer.nvim:

use {
  'lewis6991/gitsigns.nvim',
  requires = {
    'nvim-lua/plenary.nvim'
  }
}

vim-plug:

Plug 'nvim-lua/plenary.nvim'
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',
  requires = {
    'nvim-lua/plenary.nvim'
  },
  config = function()
    require('gitsigns').setup()
  end
}

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

require('gitsigns').setup {
  signs = {
    add          = {hl = 'DiffAdd'   , text = '│', numhl='GitSignsAddNr'},
    change       = {hl = 'DiffChange', text = '│', numhl='GitSignsChangeNr'},
    delete       = {hl = 'DiffDelete', text = '_', numhl='GitSignsDeleteNr'},
    topdelete    = {hl = 'DiffDelete', text = '‾', numhl='GitSignsDeleteNr'},
    changedelete = {hl = 'DiffChange', text = '~', numhl='GitSignsChangeNr'},
  },
  numhl = false,
  keymaps = {
    -- Default keymap options
    noremap = true,
    buffer = true,

    ['n ]c'] = { expr = true, "&diff ? ']c' : '<cmd>lua require\"gitsigns\".next_hunk()<CR>'"},
    ['n [c'] = { expr = true, "&diff ? '[c' : '<cmd>lua require\"gitsigns\".prev_hunk()<CR>'"},

    ['n <leader>hs'] = '<cmd>lua require"gitsigns".stage_hunk()<CR>',
    ['n <leader>hu'] = '<cmd>lua require"gitsigns".undo_stage_hunk()<CR>',
    ['n <leader>hr'] = '<cmd>lua require"gitsigns".reset_hunk()<CR>',
    ['n <leader>hp'] = '<cmd>lua require"gitsigns".preview_hunk()<CR>',
    ['n <leader>hb'] = '<cmd>lua require"gitsigns".blame_line()<CR>',

    -- Text objects
    ['o ih'] = ':<C-U>lua require"gitsigns".text_object()<CR>',
    ['x ih'] = ':<C-U>lua require"gitsigns".text_object()<CR>'
  },
  watch_index = {
    interval = 1000
  },
  sign_priority = 6,
  status_formatter = nil, -- Use default
}

For information on configuring neovim via lua please see nvim-lua-guide.

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.

FAQ

The default signs set the background and not the foreground. How do I get my signs to look like the GIF?

By default Gitsigns uses the highlight groups DiffAdd, DiffChange and DiffDelete for signs as these are the most appropriate highlights that are builtin to Neovim. In many colorschemes, these default highlights set the background but not the foreground. To make the signs looks more like the GIF then you need to set the highlights appropriately. Many colorschemes have specific highlights for Gitgutter (GitGutterAdd, GitGutterChange and GitGutterDelete), so you may use these highlights instead if you have them.

The following configuration will make Gitsigns look like GitGutters defaults:

require('gitsigns').setup {
  signs = {
    add          = {hl = 'GitGutterAdd'   , text = '+'},
    change       = {hl = 'GitGutterChange', text = '~'},
    delete       = {hl = 'GitGutterDelete', text = '_'},
    topdelete    = {hl = 'GitGutterDelete', text = '‾'},
    changedelete = {hl = 'GitGutterChange', text = '~'},
  }
}

wsdjeg / gitsigns.nvim