*gitgutter.txt*              A Vim plugin which shows a git diff in the gutter.


                           Vim Git Gutter


Author:            Andy Stewart <http://airbladesoftware.com/>
Plugin Homepage:   <https://github.com/airblade/vim-gitgutter>

===============================================================================
CONTENTS                                                    *GitGutterContents*

  1.  Introduction ................. |GitGutterIntroduction|
  2.  Installation ................. |GitGutterInstallation|
  3.  Usage ........................ |GitGutterUsage|
  4.  Commands ..................... |GitGutterCommands|
  5.  FAQ .......................... |GitGutterFAQ|

===============================================================================
1. INTRODUCTION                                         *GitGutterIntroduction*
                                                                    *GitGutter*

Vim Git Gutter is 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.

===============================================================================
2. INSTALLATION                                         *GitGutterInstallation*

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

===============================================================================
3. USAGE                                                       *GitGutterUsage*

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

===============================================================================
4. COMMANDS                                                 *GitGutterCommands*

Commands for turning Git Gutter on and off:

  :GitGutterDisable                                         *:GitGutterDisable*
      Explicitly turn Git Gutter off.

  :GitGutterEnable                                           *:GitGutterEnable*
      Explicitly turn Git Gutter on.

  :GitGutterToggle                                           *:GitGutterToggle*
      Explicitly turn Git Gutter on if it was off and vice versa.

Commands for turning line highlighting on and off (defaults to off):

  :GitGutterLineHighlightsEnable               *:GitGutterLineHighlightsEnable*
      Explicitly turn line highlighting on.

  :GitGutterLineHighlightsDisable             *:GitGutterLineHighlightsDisable*
      Explicitly turn line highlighting off.

  :GitGutterLineHighlightsToggle               *:GitGutterLineHighlightsToggle*
      Explicitly turn line highlighting on if it was off and vice versa.

Commands for jumping between marked hunks:

  :GitGutterNextHunk                                       *:GitGutterNextHunk*
      Jump to the next marked hunk.

  :GitGutterPrevHunk                                       *:GitGutterPrevHunk*
      Jump to the previous marked hunk.

===============================================================================
5. CUSTOMISATION                                       *GitGutterCustomisation*

You can customise:

- The sign column's colours
- 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.

SIGN COLUMN

The background colour of the sign column is controlled by the |hlSignColumn|
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, i.e if
>
  :highlight SignColumn  " gives you `SignColumn xxx cleared`
<
vim-gitgutter will set it to the same as your line number column (i.e. the
|hl-LineNr| highlight group).

To change your sign column's appearance, update your colorscheme or |vimrc|
like this:

  Desired appearance                  Command ~
  Same as line number column          highlight clear SignColumn
  User-defined (terminal Vim)         highlight SignColumn ctermbg={whatever}
  User-defined (graphical Vim)        highlight SignColumn guibg={whatever}

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
<

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


===============================================================================
6. FAQ                                                           *GitGutterFAQ*

a. Why are the colours in the sign column weird?

  Your colorscheme is configuring the |hl-SignColumn| highlight group weirdly.
  Please see |GitGutterCustomisation| on customising the sign column.

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

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