Vim Gitgutter

vim-gitgutter

A Vim plugin which shows a git diff in the sign column. It shows which lines have been added, modified, or removed. You can also preview, stage, and undo individual hunks; and stage partial hunks. The plugin also provides a hunk text object.

The signs are always up to date and the plugin never saves your buffer.

The name "gitgutter" comes from the Sublime Text 3 plugin which inspired this in 2013.

Features:

• Shows signs for added, modified, and removed lines.
• Runs the diffs asynchronously where possible.
• Ensures signs are always up to date.
• Never saves the buffer.
• Quick jumping between blocks of changed lines ("hunks").
• Stage/undo/preview individual hunks.
• Previews highlight intra-line changes.
• Stage partial hunks.
• Provides a hunk text object.
• Diffs against index (default) or any commit.
• Handles file moves / renames.
• Heeds git's "assume unchanged" bit.
• Allows folding all unchanged text.
• Provides fold text showing whether folded lines have been changed.
• Can load all hunk locations into quickfix list or the current window's location list.
• Handles line endings correctly, even with repos that do CRLF conversion.
• Handles clean/smudge filters.
• Optional line highlighting.
• Optional line number highlighting. (Only available in Vim 8.2.3874 or Neovim 0.3.2 or higher)
• Fully customisable (signs, sign column, line (number) highlights, mappings, extra git-diff arguments, etc).
• Can be toggled on/off, globally or per buffer.
• Preserves signs from other plugins.
• Does the right thing when viewing revisions with fugitive's :0Gclog.
• Easy to integrate diff stats into status line; built-in integration with vim-airline.
• Works with fish shell (in addition to the usual shells).

Constraints:

• Supports git only. If you work with other version control systems, I recommend vim-signify.
• Relies on the FocusGained event. If your terminal doesn't report focus events, either use something like [Terminus][] or set let g:gitgutter_terminal_reports_focus=0. For tmux, set -g focus-events on in your tmux.conf.

Compatibility:

Compatible back to Vim 7.4, and probably 7.3.

Screenshot

In the screenshot above you can see:

• Lines 183-184 are new.
• Lines 186-187 have been modified.
• The preview for the modified lines highlights changed regions within the line.

Installation

First, install using your favourite package manager, or use Vim's built-in package support.

Vim:

mkdir -p ~/.vim/pack/airblade/start
cd ~/.vim/pack/airblade/start
git clone https://github.com/airblade/vim-gitgutter.git
vim -u NONE -c "helptags vim-gitgutter/doc" -c q

Neovim:

mkdir -p ~/.config/nvim/pack/airblade/start
cd ~/.config/nvim/pack/airblade/start
git clone https://github.com/airblade/vim-gitgutter.git
nvim -u NONE -c "helptags vim-gitgutter/doc" -c q

Second, ensure your updatetime and signcolumn options are set appropriately.

When you make a change to a file tracked by git, the diff markers should appear automatically after a short delay. The delay is governed by vim's updatetime option; the default value is 4000, i.e. 4 seconds, but I suggest reducing it to around 100ms (add set updatetime=100 to your vimrc). Note updatetime also controls the delay before vim writes its swap file (see :help updatetime).

The signcolumn option can have any value except 'no'.

Windows

There is a potential risk on Windows due to cmd.exe prioritising the current folder over folders in PATH. If you have a file named git.* (i.e. with any extension in PATHEXT) in your current folder, it will be executed instead of git whenever the plugin calls git.

You can avoid this risk by configuring the full path to your git executable. For example:

" This path probably won't work
let g:gitgutter_git_executable = 'C:\Program Files\Git\bin\git.exe'

Unfortunately I don't know the correct escaping for the path - if you do, please let me know!

Getting started

When you make a change to a file tracked by git, the diff markers should appear automatically after a short delay.

You can jump between hunks with [c and ]c. You can preview, stage, and undo hunks with <leader>hp, <leader>hs, and <leader>hu respectively.

You cannot unstage a staged hunk.

After updating the signs, the plugin fires the GitGutter User autocommand.

After staging a hunk or part of a hunk, the plugin fires the GitGutterStage User autocommand.

Activation

You can explicitly turn vim-gitgutter off and on (defaults to on):

• turn off with :GitGutterDisable
• turn on with :GitGutterEnable
• toggle with :GitGutterToggle.

To toggle vim-gitgutter per buffer:

• turn off with :GitGutterBufferDisable
• turn on with :GitGutterBufferEnable
• toggle with :GitGutterBufferToggle

You can turn the signs on and off (defaults to on):

• turn on with :GitGutterSignsEnable
• turn off with :GitGutterSignsDisable
• toggle with :GitGutterSignsToggle.

And you can turn line highlighting on and off (defaults to off):

• turn on with :GitGutterLineHighlightsEnable
• turn off with :GitGutterLineHighlightsDisable
• toggle with :GitGutterLineHighlightsToggle.

Note that if you have line highlighting on and signs off, you will have an empty sign column – more accurately, a sign column with invisible signs. This is because line highlighting requires signs and Vim/NeoVim always shows the sign column when there are signs even if the signs are invisible.

With Vim 8.2.3874 or Neovim 0.3.2 or higher, you can turn line number highlighting on and off (defaults to off):

• turn on with :GitGutterLineNrHighlightsEnable
• turn off with :GitGutterLineNrHighlightsDisable
• toggle with :GitGutterLineNrHighlightsToggle.

The same caveat applies to line number highlighting as to line highlighting just above.

If you switch off both line highlighting and signs, you won't see the sign column.

In older Vims (pre 8.1.0614 / Neovim 0.4.0) vim-gitgutter will suppress the signs when a file has more than 500 changes, to avoid slowing down the UI. As soon as the number of changes falls below the limit vim-gitgutter will show the signs again. You can configure the threshold with:

let g:gitgutter_max_signs = 500  " default value (Vim < 8.1.0614, Neovim < 0.4.0)
let g:gitgutter_max_signs = -1   " default value (otherwise)

You can also remove the limit by setting g:gitgutter_max_signs = -1.

Hunks

You can jump between hunks:

• jump to next hunk (change): ]c
• jump to previous hunk (change): [c.

Both of those take a preceding count.

To set your own mappings for these, for example ]h and [h:

nmap ]h <Plug>(GitGutterNextHunk)
nmap [h <Plug>(GitGutterPrevHunk)

When you jump between hunks, a message like Hunk 4 of 11 is shown on the command line. If you want to turn the message off, you can use:

let g:gitgutter_show_msg_on_hunk_jumping = 0

You can load all your hunks into the quickfix list with :GitGutterQuickFix. Note this ignores any unsaved changes in your buffers. If the option g:gitgutter_use_location_list is set, this command will load hunks into the current window's location list instead. Use :copen (or :lopen) to open the quickfix / location list or add a custom command like this:

command! Gqf GitGutterQuickFix | copen

You can stage or undo an individual hunk when your cursor is in it:

• stage the hunk with <Leader>hs or
• undo it with <Leader>hu.

To stage part of an additions-only hunk by:

• either visually selecting the part you want and staging with your mapping, e.g. <Leader>hs;
• or using a range with the GitGutterStageHunk command, e.g. :42,45GitGutterStageHunk.

To stage part of any hunk:

• preview the hunk, e.g. <Leader>hp;
• move to the preview window, e.g. :wincmd P;
• delete the lines you do not want to stage;
• stage the remaining lines: either write (:w) the window or stage via <Leader>hs or :GitGutterStageHunk.

Note the above workflow is not possible if you have opted in to preview hunks with Vim's popup windows.

See the FAQ if you want to unstage staged changes.

The . command will work with both these if you install repeat.vim.

To set your own mappings for these, for example if you prefer g-based maps:

nmap ghs <Plug>(GitGutterStageHunk)
nmap ghu <Plug>(GitGutterUndoHunk)

And you can preview a hunk's changes with <Leader>hp. The location of the preview window is configured with g:gitgutter_preview_win_location (default 'bo'). You can of course change this mapping, e.g:

nmap ghp <Plug>(GitGutterPreviewHunk)

A hunk text object is provided which works in visual and operator-pending modes.

• ic operates on all lines in the current hunk.
• ac operates on all lines in the current hunk and any trailing empty lines.

To re-map these, for example to ih and ah:

omap ih <Plug>(GitGutterTextObjectInnerPending)
omap ah <Plug>(GitGutterTextObjectOuterPending)
xmap ih <Plug>(GitGutterTextObjectInnerVisual)
xmap ah <Plug>(GitGutterTextObjectOuterVisual)

If you don't want vim-gitgutter to set up any mappings at all, use this:

let g:gitgutter_map_keys = 0

Finally, you can force vim-gitgutter to update its signs across all visible buffers with :GitGutterAll.

See the customisation section below for how to change the defaults.

Vimdiff

Use the GitGutterDiffOrig command to open a vimdiff view of the current buffer, respecting g:gitgutter_diff_relative_to and :gitgutter_diff_base.

Folding

Use the GitGutterFold command to fold all unchanged lines, leaving just the hunks visible. Use zr to unfold 3 lines of context above and below a hunk.

Execute `GitG