A Vim plugin which shows a git diff in the 'gutter' (sign column). It shows which lines have been added, modified, or removed. You can also preview, stage, and undo individual hunks. The plugin also provides a hunk text object.
The signs are always up to date and the plugin never saves your buffer.
* Supports git only. If you work with other version control systems, I recommend [vim-signify](https://github.com/mhinz/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`.
Before installation, please check your Vim supports signs by running `:echo has('signs')`. `1` means you're all set; `0` means you need to install a Vim with signs support. If you're compiling Vim yourself you need the 'big' or 'huge' feature set. MacVim supports signs.
When you make a change to a file tracked by git, the diff markers should appear automatically. 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).
You can explicitly turn vim-gitgutter off and on (defaults to on):
* turn off with `:GitGutterDisable`
* turn on with `:GitGutterEnable`
* toggle with `:GitGutterToggle`.
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 always shows the sign column even if the signs are invisible.
If you switch off both line highlighting and signs, you won't see the sign column. That is unless you configure the sign column always to be there (see Sign Column section).
To keep your Vim snappy, vim-gitgutter will suppress the signs when a file has more than 500 changes. As soon as the number of changes falls below the limit vim-gitgutter will show the signs again. You can configure the threshold with:
By default the sign column will appear when there are signs to show and disappear when there aren't. To always have the sign column, add to your vimrc:
To customise the colours, set up the following highlight groups in your colorscheme or `~/.vimrc`:
```viml
GitGutterAdd " an added line
GitGutterChange " a changed line
GitGutterDelete " at least one removed line
GitGutterChangeDelete " a changed line followed by at least one removed line
```
You can either set these with `highlight GitGutterAdd {key}={arg}...` or link them to existing highlight groups with, say, `highlight link GitGutterAdd DiffAdd`.
To customise the symbols, add the following to your `~/.vimrc`:
```viml
let g:gitgutter_sign_added = 'xx'
let g:gitgutter_sign_modified = 'yy'
let g:gitgutter_sign_removed = 'zz'
let g:gitgutter_sign_removed_first_line = '^^'
let g:gitgutter_sign_modified_removed = 'ww'
```
#### Line highlights
Similarly to the signs' colours, set up the following highlight groups in your colorscheme or `~/.vimrc`:
```viml
GitGutterAddLine " default: links to DiffAdd
GitGutterChangeLine " default: links to DiffChange
GitGutterDeleteLine " default: links to DiffDelete
GitGutterChangeDeleteLine " default: links to GitGutterChangeLineDefault, i.e. DiffChange
```
#### The base of the diff
By default buffers are diffed against the index. However you can diff against any commit by setting:
```viml
let g:gitgutter_diff_base = '<commitSHA>'
```
#### Extra arguments for `git diff`
If you want to pass extra arguments to `git diff`, for example to ignore whitespace, do so like this:
```viml
let g:gitgutter_diff_args = '-w'
```
#### Key mappings
To disable all key mappings:
```viml
let g:gitgutter_map_keys = 0
```
See above for configuring maps for hunk-jumping and staging/undoing.
This plugin is for showing changes between the working tree and the index (and staging/undoing those changes). Unstaging a staged hunk would require showing changes between the index and HEAD, which is out of scope.
Your colorscheme is configuring the `SignColumn` highlight group weirdly. Please see the section above on customising the sign column.
> What happens if I also use another plugin which uses signs (e.g. Syntastic)?
Vim only allows one sign per line. Before adding a sign to a line, vim-gitgutter checks whether a sign has already been added by somebody else. If so it doesn't do anything. In other words vim-gitgutter won't overwrite another plugin's signs. It also won't remove another plugin's signs.
