amadeus / vim-gitgutter Goto Github PK

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 plugin for Sublime Text 2.

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.

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, and then simply copy and paste:

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

Or for Vundle users:

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

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

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:

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.

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)

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

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.

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.

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

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

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

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.

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.

Related:

• textobj-gitgutter (lets you treat diff hunks as text objects)
• vim-gitgutter - Mercurial fork

Vim alternatives:

• git-gutter-vim
• vim-git-inline-diff
• quickfixsigns_vim (a superset of this functionality)
• iwilldiffer
• svndiff
• sign-diff
• changesPlugin

Other editors:

• Git Gutter for Sublime Text 2
• git-gutter.el for Emacs

Also, this may be of interest:

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

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
• Smash Into Vim II

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

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