## Vim Git Gutter

A Vim plugin which shows a git diff in the 'gutter' (sign column).  It shows whether each line has been added, modified, and where lines have been removed.

This is a port of the [Git Gutter][st2gg] plugin for Sublime Text 2.


### Screenshot

![screenshot](https://raw.github.com/airblade/vim-gitgutter/master/screenshot.png)

In the screenshot above you can see:

* Line 15 has been modified.
* Lines 21-24 are new.
* A line or lines were removed between lines 25 and 26.


### Installation

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.

If you don't have a preferred installation method, I recommend installing [pathogen.vim][pathogen], and then simply copy and paste:

```
cd ~/.vim/bundle
git clone git://github.com/airblade/vim-gitgutter.git
```

Or for [Vundle](https://github.com/gmarik/vundle) users:

Add `Bundle 'airblade/vim-gitgutter'` to your `~/.vimrc` and then:

* either within Vim: `:BundleInstall`
* or in your shell: `vim +BundleInstall +qall`


### Usage

You don't have to do anything: it just works.

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

* turn off with `:GitGutterDisable`
* turn on with `:GitGutterEnable`
* toggle with `:GitGutterToggle`.

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

* turn on with `:GitGutterLineHighlightsEnable`
* turn off with `:GitGutterLineHighlightsDisable`
* toggle with `:GitGutterLineHighlightsToggle`.

Furthermore you can jump between `[count]` hunks:

* jump to next hunk: `:[count]GitGutterNextHunk [count]`
* jump to previous hunk: `:[count]GitGutterPrevHunk [count]`.

You may want to add mappings for these if you use them often.  For example:

```viml
nmap <silent> ]h :<C-U>execute v:count1 . "GitGutterNextHunk"<CR>
nmap <silent> [h :<C-U>execute v:count1 . "GitGutterPrevHunk"<CR>
```

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

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


### Customisation

You can customise:

* The sign column's colours
* Whether or not the sign column is shown when there aren't any signs (defaults to no)
* The signs' colours
* Line highlights
* Whether or not vim-gitgutter is on initially (defaults to on)
* Whether or not line highlighting is on initially (defaults to off)
* Whether or not vim-gitgutter runs on `BufEnter` (defaults to yes)
* Whether or not vim-gitgutter runs for all buffers on `FocusGained` (defaults to yes)

Please note that vim-gitgutter won't override any colours or highlights you've set in your colorscheme.


#### Sign column

The background colour of the sign column is controlled by the `SignColumn` highlight group.  This will be either set in your colorscheme or Vim's default.

To find out where it's set, and to what it's set, use `:verbose highlight SignColumn`.

If your `SignColumn` is not set (`:highlight SignColumn` gives you `SignColumn xxx cleared`), vim-gitgutter will set it to the same as your line number column (i.e. the `LineNr` highlight group).

To change your sign column's appearance, update your colorscheme or `~/.vimrc` like this:

* For the same appearance as your line number column: `highlight clear SignColumn`
* For a specific appearance on terminal Vim: `highlight SignColumn ctermbg=whatever`
* For a specific appearance on gVim/MacVim: `highlight SignColumn guibg=whatever`

By default the sign column will appear when there are signs to show and disappear when there aren't.  If you would always like the sign column to be there, add `let g:gitgutter_sign_column_always = 1` to your `~/.vimrc`.


#### Signs' colours

To customise these, set up the following highlight groups in your colorscheme or `~/.vimrc`:

```
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`.

#### Line highlights

Similarly to the signs' colours, set up the following highlight groups in your colorscheme or `~/.vimrc`:

```
GitGutterAddLine          " default: links to DiffAdd
GitGutterChangeLine       " default: links to DiffChange
GitGutterDeleteLine       " default: links to DiffDelete
GitGutterChangeDeleteLine " default: links to GitGutterChangeLineDefault, i.e. DiffChange
```

#### To turn off vim-gitgutter by default

Add `let g:gitgutter_enabled = 0` to your `~/.vimrc`.


#### To turn on line highlighting by default

Add `let g:gitgutter_highlight_lines = 1` to your `~/.vimrc`.


#### To stop vim-gitgutter running on `BufEnter`

This is on by default but causes a noticeable lag for some people.  To turn it off, add this to your ~/.vimrc`:

```
let g:gitgutter_on_bufenter = 0
```


#### To stop vim-gitgutter running for all buffers on `FocusGained`

This is on by default but causes a noticeable lag for some people.  To turn it off, add this to your `~/.vimrc`:

```
let g:gitgutter_all_on_focusgained = 0
```

Note that this is always off with gVim on Windows due to a Vim/shell bug causing an infinite loop.


### FAQ

> Why are the colours in the sign column weird?

Your colorscheme is configuring the `SignColumn` highlight group weirdly.  Please see the section above on customising the sign column.

> Why does the window flicker when the signs are redrawn?

This happens on certain combinations of OS and Vim.  You can prevent the flicker by adding `let g:gitgutter_sign_column_always = 1` to your `~/.vimrc`.

> There's a noticeable lag when vim-gitter runs; how can I avoid it?

By default vim-gitgutter runs often so the signs are as accurate as possible.  However on some systems this causes a noticeable lag.  If you would like to trade a little accuracy for speed, add one or both of these to your ~/.vimrc`:

```
let g:gitgutter_on_bufenter = 0
let g:gitgutter_all_on_focusgained = 0
```

> Why is no sign shown if I delete the first line(s) in a file?

vim-gitgutter shows removed lines with a sign on the line above.  In this case there isn't a line above so vim-gitgutter can't show the sign.

> 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.

> Why aren't any signs showing at all?

Here are some things you can check:

* Your git config is compatible with the version of git which your Vim is calling (`:echo system('git --version')`).
* Your Vim supports signs (`:echo has('signs')` should give `1`).
* Your file is being tracked by git and has unstaged changes.


### Alternatives

Related:

* [textobj-gitgutter][togg] (lets you treat diff hunks as text objects)
* [vim-gitgutter][mercurial] - Mercurial fork

Vim alternatives:

* [git-gutter-vim][ggv]
* [vim-git-inline-diff][vgid]
* [quickfixsigns_vim][qf] (a superset of this functionality)
* [iwilldiffer][iwd]
* [svndiff][svndiff]
* [sign-diff][signdiff]
* [changesPlugin][changes]

Other editors:

* [Git Gutter][st2gg] for Sublime Text 2
* [git-gutter.el][gge] for Emacs

Also, this may be of interest:

* [fugitive.vim][fugitive] is a full-on Git wrapper.  It doesn't show git diffs in the gutter (ha!) but it does a bazillion other git things.


### Shameless Plug

If this plugin has helped you, or you'd like to learn more about Vim, why not check out these two screencasts I wrote for PeepCode:

* [Smash Into Vim I][siv1]
* [Smash Into Vim II][siv2]

You can read reviews at PeepCode and also on my [portfolio][].


### Intellectual Property

Copyright Andrew Stewart, AirBlade Software Ltd.  Released under the MIT licence.


  [st2gg]: https://github.com/jisaacks/GitGutter
  [pathogen]: https://github.com/tpope/vim-pathogen
  [qf]: https://github.com/tomtom/quickfixsigns_vim
  [fugitive]: https://github.com/tpope/vim-fugitive
  [siv1]: https://peepcode.com/products/smash-into-vim-i
  [siv2]: https://peepcode.com/products/smash-into-vim-ii
  [portfolio]: http://airbladesoftware.com/portfolio#vim
  [vgid]: https://github.com/luxflux/vim-git-inline-diff
  [gge]: https://github.com/syohex/emacs-git-gutter
  [iwd]: https://bitbucket.org/sirpengi/iwilldiffer
  [svndiff]: http://www.vim.org/scripts/script.php?script_id=1881
  [signdiff]: http://www.vim.org/scripts/script.php?script_id=2712
  [changes]: http://www.vim.org/scripts/script.php?script_id=3052
  [ggv]: https://github.com/akiomik/git-gutter-vim
  [togg]:https://github.com/gilligan/textobj-gitgutter
  [mercurial]: https://github.com/safetydank/vim-gitgutter
  [macvim]: http://code.google.com/p/macvim/