gitgutter.txt

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


                           Vim GitGutter


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


===============================================================================
CONTENTS                                                            *gitgutter*

  Introduction ................. |gitgutter-introduction|
  Installation ................. |gitgutter-installation|
  Windows      ................. |gitgutter-windows|
  Commands ..................... |gitgutter-commands|
  Mappings ..................... |gitgutter-mappings|
  Autocommand .................. |gitgutter-autocommand|
  Status line .................. |gitgutter-statusline|
  Options ...................... |gitgutter-options|
  Highlights ................... |gitgutter-highlights|
  FAQ .......................... |gitgutter-faq|
  TROUBLESHOOTING .............. |gitgutter-troubleshooting|


===============================================================================
INTRODUCTION                                           *gitgutter-introduction*

GitGutter is 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.  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
one in 2013.


===============================================================================
INSTALLATION                                           *gitgutter-installation*

First, use 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.

The 'signcolumn' option can have any value except "off".


===============================================================================
WINDOWS                                                     *gitgutter-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!


===============================================================================
COMMANDS                                                   *gitgutter-commands*

Commands for turning vim-gitgutter on and off:~

                                                  *gitgutter-:GitGutterDisable*
:GitGutterDisable       Turn vim-gitgutter off for all buffers.

                                                   *gitgutter-:GitGutterEnable*
:GitGutterEnable        Turn vim-gitgutter on for all buffers.

                                                   *gitgutter-:GitGutterToggle*
:GitGutterToggle        Toggle vim-gitgutter on or off for all buffers.

                                            *gitgutter-:GitGutterBufferDisable*
:GitGutterBufferDisable Turn vim-gitgutter off for current buffer.

                                             *gitgutter-:GitGutterBufferEnable*
:GitGutterBufferEnable  Turn vim-gitgutter on for current buffer.

                                             *gitgutter-:GitGutterBufferToggle*
:GitGutterBufferToggle  Toggle vim-gitgutter on or off for current buffer.

                                                         *gitgutter-:GitGutter*
:GitGutter              Update signs for the current buffer.  You shouldn't
                        need to run this.

                                                      *gitgutter-:GitGutterAll*
:GitGutterAll           Update signs for all buffers.  You shouldn't need to
                        run this.


Commands for turning signs on and off (defaults to on):~

                                              *gitgutter-:GitGutterSignsEnable*
:GitGutterSignsEnable   Show signs for the diff.

                                             *gitgutter-:GitGutterSignsDisable*
:GitGutterSignsDisable  Do not show signs for the diff.

                                              *gitgutter-:GitGutterSignsToggle*
:GitGutterSignsToggle   Toggle signs on or off.


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

                                     *gitgutter-:GitGutterLineHighlightsEnable*
:GitGutterLineHighlightsEnable  Turn on line highlighting.

                                    *gitgutter-:GitGutterLineHighlightsDisable*
:GitGutterLineHighlightsDisable Turn off line highlighting.

                                     *gitgutter-:GitGutterLineHighlightsToggle*
:GitGutterLineHighlightsToggle  Turn line highlighting on or off.


Commands for turning line number highlighting on and off (defaults to off):~
NOTE: This feature requires Neovim 0.3.2 or higher.

                                   *gitgutter-:GitGutterLineNrHighlightsEnable*
:GitGutterLineNrHighlightsEnable  Turn on line highlighting.

                                  *gitgutter-:GitGutterLineNrHighlightsDisable*
:GitGutterLineNrHighlightsDisable Turn off line highlighting.

                                   *gitgutter-:GitGutterLineNrHighlightsToggle*
:GitGutterLineNrHighlightsToggle  Turn line highlighting on or off.


Commands for jumping between hunks:~

                                                 *gitgutter-:GitGutterNextHunk*
:GitGutterNextHunk      Jump to the next [count] hunk.

                                                 *gitgutter-:GitGutterPrevHunk*
:GitGutterPrevHunk      Jump to the previous [count] hunk.

                                                 *gitgutter-:GitGutterQuickFix*
:GitGutterQuickFix      Load all hunks into the |quickfix| list.  Note this
                        ignores any unsaved changes in your buffers. The
                        |g:gitgutter_use_location_list| option can be set to
                        populate the location list of the current window
                        instead.  Use |:copen| (or |:lopen|) to open a buffer
                        containing the search results in linked form; or add a
                        custom command like this:
>
                          command! Gqf GitGutterQuickFix | copen
<
                                                 *gitgutter-:GitGutterQuickFixCurrentFile*
:GitGutterQuickFixCurrentFile     Same as :GitGutterQuickFix, but only load hunks for
                                  the file in the focused buffer. This has the same
                                  functionality as :GitGutterQuickFix when the focused
                                  buffer is empty.


Commands for operating on a hunk:~

                                                *gitgutter-:GitGutterStageHunk*
:GitGutterStageHunk     Stage the hunk the cursor is in.  Use a visual selection
                        to stage part of an (additions-only) hunk; or use a
                        range.

                        To stage part of any hunk, first |GitGutterPreviewHunk|
                        it, then move to the preview window, delete the lines
                        you do not want to stage, and |write| or
                        |GitGutterStageHunk|.

                                                 *gitgutter-:GitGutterUndoHunk*
:GitGutterUndoHunk      Undo the hunk the cursor is in.

                                              *gitgutter-:GitGutterPreviewHunk*
:GitGutterPreviewHunk   Preview the hunk the cursor is in.

                        To stage part of the hunk, move to the preview window,
                        delete any lines you do not want to stage, and
                        |GitGutterStageHunk|.

                        To close a non-floating preview window use |:pclose|
                        or |CTRL-W_z| or |CTRL-W_CTRL-Z|; or normal window-
                        closing (|:quit| or |:close| or |CTRL-W_c|) if your cursor
                        is in the preview window.

                        To close a floating window when the cursor is in the
                        original buffer, move the cursor.

                        To close a floating window when the cursor is in the
                        floating window use normal window-closing, or move to
                        the original window with |CTRL-W_p|.  Alternatively set
                        |g:gitgutter_close_preview_on_escape| and use <Esc>.

                        Two functions are available for your own logic:
>
                          gitgutter#hunk#is_preview_window_open()
                          gitgutter#hunk#close_hunk_preview_window()
<

Commands for folds:~

                                                     *gitgutter-:GitGutterFold*
:GitGutterFold          Fold all unchanged lines.  Execute again to undo.


Other commands:~

                                                 *gitgutter-:GitGutterDiffOrig*
:GitGutterDiffOrig      Similar to |:DiffOrig| but shows gitgutter's diff.


===============================================================================
AUTOCOMMANDS                                           *gitgutter-autocommands*

User GitGutter~

After updating a buffer's signs vim-gitgutter fires a |User| |autocmd| with the
event GitGutter.  You can listen for this event, for example:
>
  autocmd User GitGutter call updateMyStatusLine()
<
A dictionary `g:gitgutter_hook_context` is made available during its execution,
which contains an entry `bufnr` that contains the buffer number being updated.

User GitGutterStage~

After staging a hunk or part of a hunk vim-gitgutter fires a |User| |autocmd|
with the event GitGutterStage.  Staging always happens in the current buffer.

===============================================================================
MAPPINGS                                                   *gitgutter-mappings*

You can disable all these mappings with:
>
    let g:gitgutter_map_keys = 0
<

Hunk operations:~

These can be repeated with `.` if you have vim-repeat installed.

                                                         *gitgutter-<Leader>hp*
<Leader>hp              Preview the hunk under the cursor.

                                                         *gitgutter-<Leader>hs*
<Leader>hs              Stage the hunk under the cursor.

                                                         *gitgutter-<Leader>hu*
<Leader>hu              Undo the hunk under the cursor.

You can change these mappings like this:
>
    nmap ghp <Plug>(GitGutterPreviewHunk)
    nmap ghs <Plug>(GitGutterStageHunk)
    nmap ghu <Plug>(GitGutterUndoHunk)
<

Hunk jumping:~

                                                                 *gitgutter-]c*
]c                      Jump to the next [count] hunk.

                                                                 *gitgutter-[c*
[c                      Jump to the previous [count] hunk.

You can change these mappings like this:
>
    nmap [c <Plug>(GitGutterPrevHunk)
    nmap ]c <Plug>(GitGutterNextHunk)
<

Hunk text object:~

                          *gitgutter-ic* *gitgutter-ac* *gitgutter-text-object*
"ic" operates on the current hunk's lines.  "ac" does the same but also includes
trailing empty lines.
>
    omap ic <Plug>(GitGutterTextObjectInnerPending)
    omap ac <Plug>(GitGutterTextObjectOuterPending)
    xmap ic <Plug>(GitGutterTextObjectInnerVisual)
    xmap ac <Plug>(GitGutterTextObjectOuterVisual)
<


===============================================================================
STATUS LINE                                              *gitgutter-statusline*


Call the `GitGutterGetHunkSummary()` function from your status line to get a
list of counts of added, modified, and removed lines in the current buffer.
For example:
>
    " Your vimrc
    function! GitStatus()
      let [a,m,r] = GitGutterGetHunkSummary()
      return printf('+%d ~%d -%d', a, m, r)
    endfunction
    set statusline+=%{GitStatus()}
<


===============================================================================
OPTIONS                                                     *gitgutter-options*

The most important option is 'updatetime' which determines how long (in
milliseconds) the plugin will wait after you stop typing before it updates the
signs.  Vim's default is 4000.  I recommend 100.  Note this also controls how
long vim waits before writing its swap file.

Most important option:~

    'updatetime'

Git:~

    |g:gitgutter_git_executable|
    |g:gitgutter_git_args|
    |g:gitgutter_diff_args|
    |g:gitgutter_diff_relative_to|
    |g:gitgutter_diff_base|

Grep:~

    |g:gitgutter_grep|

Signs:~

    |g:gitgutter_signs|
    |g:gitgutter_highlight_lines|
    |g:gitgutter_highlight_linenrs|
    |g:gitgutter_max_signs|
    |g:gitgutter_sign_priority|
    |g:gitgutter_sign_allow_clobber|
    |g:gitgutter_sign_added|
    |g:gitgutter_sign_modified|
    |g:gitgutter_sign_removed|
    |g:gitgutter_sign_removed_first_line|
    |g:gitgutter_sign_modified_removed|
    |g:gitgutter_set_sign_backgrounds|

Hunk jumping:~

    |g:gitgutter_show_msg_on_hunk_jumping|

Hunk previews:~

    |g:gitgutter_preview_win_floating|
    |g:gitgutter_floating_window_options|
    |g:gitgutter_close_preview_on_escape|

Terminal:~

    |g:gitgutter_terminal_reports_focus|

General:~

    |g:gitgutter_enabled|
    |g:gitgutter_map_keys|
    |g:gitgutter_async|
    |g:gitgutter_log|
    |g:gitgutter_use_location_list|


                                             *g:gitgutter_preview_win_location*
Default: 'bo'

This option determines where the preview window pops up as a result of the
:GitGutterPreviewHunk command. Other plausible values are 'to', 'bel', 'abo'.
See the end of the |opening-window| docs.

                                                   *g:gitgutter_git_executable*
Default: 'git'

This option determines what git binary to use.  Set this if git is not on your
path.

                                                         *g:gitgutter_git_args*
Default: empty

Use this option to pass any extra arguments to git when running git-diff.
For example:
>
    let g:gitgutter_git_args = '--git-dir=""'
<

                                                        *g:gitgutter_diff_args*
Default: empty

Use this option to pass any extra arguments to git-diff.  For example:
>
    let g:gitgutter_diff_args = '-w'
<

                                                 *g:gitgutter_diff_relative_to*
Default: empty

By default buffers are diffed against the index.  Use this option to diff against
the working tree.  For example:
>
    let g:gitgutter_diff_relative_to = 'working_tree'
<

                                                        *g:gitgutter_diff_base*
Default: empty

By default buffers are diffed against the index.  Use this option to diff against
a revision instead.  For example:
>
    let g:gitgutter_diff_base = '<some commit SHA>'
<

If you are looking at a previous version of a file with Fugitive (e.g.
via :0Gclog), gitgutter sets the diff base to the parent of the current revision.

This setting is ignore when the diff is relative to the working tree
(|g:gitgutter_diff_relative_to|).

                                                             *g:gitgutter_grep*
Default: 'grep'

The plugin pipes the output of git-diff into grep to minimise the amount of data
vim has to process.  Set this option if grep is not on your path.

grep must produce plain-text output without any ANSI escape codes or colours.
Use this option to turn off colours if necessary.
>
    let g:gitgutter_grep = 'grep --color=never'
<
If you do not want to use grep at all (perhaps to debug why signs are not
showing), set this option to an empty string:
>
    let g:gitgutter_grep = ''
<

                                                            *g:gitgutter_signs*
Default: 1

Determines whether or not to show signs.

                                                  *g:gitgutter_highlight_lines*
Default: 0

Determines whether or not to show line highlights.

                                                *g:gitgutter_highlight_linenrs*
Default: 0

Determines whether or not to show line number highlights.

                                                        *g:gitgutter_max_signs*
Default: 500 (Vim < 8.1.0614, Neovim < 0.4.0)
          -1 (otherwise)

Sets the maximum number of signs to show in a buffer.  Vim is slow at updating
signs, so to avoid slowing down the GUI the number of signs is capped.  When
the number of changed lines exceeds this value, the plugin removes all signs
and displays a warning message.

When set to -1 the limit is not applied.

                                                   *g:gitgutter_sign_priority*
Default: 10

Sets the |sign-priority| gitgutter assigns to its signs.

                                               *g:gitgutter_sign_allow_clobber*
Default: 0 (Vim < 8.1.0614, Neovim < 0.4.0)
         1 (otherwise)

Determines whether gitgutter preserves non-gitgutter signs. When 1, gitgutter
will not preserve non-gitgutter signs.

                                          *g:gitgutter_sign_added*
                                          *g:gitgutter_sign_modified*
                                          *g:gitgutter_sign_removed*
                                          *g:gitgutter_sign_removed_first_line*
                                          *g:gitgutter_sign_removed_above_and_below*
                                          *g:gitgutter_sign_modified_removed*
Defaults:
>
    let g:gitgutter_sign_added              = '+'
    let g:gitgutter_sign_modified           = '~'
    let g:gitgutter_sign_removed            = '_'
    let g:gitgutter_sign_removed_first_line = '‾'
    let g:gitgutter_sign_removed_above_and_below = '_¯'
    let g:gitgutter_sign_modified_removed   = '~_'
<
You can use unicode characters but not images.  Signs must not take up more than
2 columns.

                                              *g:gitgutter_set_sign_backgrounds*
Default: 0

Only applies to existing GitGutter* highlight groups.  See
|gitgutter-highlights|.

Controls whether to override the signs' background colours to match the
|hl-SignColumn|.

                                             *g:gitgutter_preview_win_floating*
Default: 0 (Vim)
         0 (NeoVim which does not support floating windows)
         1 (NeoVim which does support floating windows)

Whether to use floating/popup windows for hunk previews.  Note that if you use
popup windows on Vim you will not be able to stage partial hunks via the
preview window.

                                          *g:gitgutter_floating_window_options*
Default:
>
    " Vim
    {
        \ 'line': 'cursor+1',
        \ 'col': 'cursor',
        \ 'moved': 'any'
    }

    " Neovim
    {
        \ 'relative': 'cursor',
        \ 'row': 1,
        \ 'col': 0,
        \ 'width': 42,
        \ 'height': &previewheight,
        \ 'style': 'minimal'
    }
<
This dictionary is passed directly to |popup_create()| (Vim) or
|nvim_open_win()| (Neovim).

If you simply want to override one or two of the default values, create a file
in an after/ directory.  For example:
>
    " ~/.vim/after/vim-gitgutter/overrides.vim
    let g:gitgutter_floating_window_options['border'] = 'single'
<

                                          *g:gitgutter_close_preview_on_escape*
Default: 0

Whether pressing <Esc> in a preview window closes it.

                                           *g:gitgutter_terminal_reports_focus*
Default: 1

Normally the plugin uses |FocusGained| to force-update all buffers when Vim
receives focus.  However some terminals do not report focus events and so the
|FocusGained| autocommand never fires.

If this applies to you, either install something like Terminus
(https://github.com/wincent/terminus) to make |FocusGained| work or set this
option to 0.

If you use tmux, try this in your tmux.conf:
>
    set -g focus-events on
<

When this option is 0, the plugin force-updates the buffer on |BufEnter|
(instead of only updating if the buffer's contents has changed since the last
update).

                                                          *g:gitgutter_enabled*
Default: 1

Controls whether or not the plugin is on at startup.

                                                         *g:gitgutter_map_keys*
Default: 1

Controls whether or not the plugin provides mappings.  See |gitgutter-mappings|.

                                                            *g:gitgutter_async*
Default: 1

Controls whether or not diffs are run in the background.  This has no effect if
your Vim does not support background jobs.

                                                              *g:gitgutter_log*
Default: 0

When switched on, the plugin logs to gitgutter.log in the directory where it is
installed.  Additionally it logs channel activity to channel.log.

                                                *g:gitgutter_use_location_list*
Default: 0

When switched on, the :GitGutterQuickFix command populates the location list
of the current window instead of the global quickfix list.

                                         *g:gitgutter_show_msg_on_hunk_jumping*
Default: 1

When switched on, a message like "Hunk 4 of 11" is shown on hunk jumping.


===============================================================================
HIGHLIGHTS                                               *gitgutter-highlights*

To change the signs' colours, specify these highlight groups in your |vimrc|:
>
    highlight GitGutterAdd    guifg=#009900 ctermfg=2
    highlight GitGutterChange guifg=#bbbb00 ctermfg=3
    highlight GitGutterDelete guifg=#ff2222 ctermfg=1
<

See |highlight-guifg| and |highlight-ctermfg| for the values you can use.

If you do not like the signs' background colours and you do not want to update
the GitGutter* highlight groups yourself, you can get the plugin to do it
|g:gitgutter_set_sign_backgrounds|.

To change the line highlights, 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 GitGutterChangeLine
<

For example, to use |hl-DiffText| instead of |hl-DiffChange|:
>
    highlight link GitGutterChangeLine DiffText
<
To change the line number highlights, set up the following highlight groups in
your colorscheme or |vimrc|:
>
    GitGutterAddLineNr          " default: links to CursorLineNr
    GitGutterChangeLineNr       " default: links to CursorLineNr
    GitGutterDeleteLineNr       " default: links to CursorLineNr
    GitGutterChangeDeleteLineNr " default: links to GitGutterChangeLineNr
<
For example, to use |hl-Underlined| instead of |hl-CursorLineNr|:
>
    highlight link GitGutterChangeLineNr Underlined
<
To change the diff syntax colours used in the preview window, set up the diff*
highlight groups in your colorscheme or |vimrc|:
>
    diffAdded   " if not set: use GitGutterAdd's foreground colour
    diffChanged " if not set: use GitGutterChange's foreground colour
    diffRemoved " if not set: use GitGutterDelete's foreground colour
<
Note the diff* highlight groups are used in any buffer whose 'syntax' is
"diff".

To change the intra-line diff highlights used in the preview window, set up
the following highlight groups in your colorscheme or |vimrc|:
>
    GitGutterAddIntraLine    " default: gui=reverse cterm=reverse
    GitGutterDeleteIntraLine " default: gui=reverse cterm=reverse
<
For example, to use |hl-DiffAdd| for intra-line added regions:
>
    highlight link GitGutterAddIntraLine DiffAdd
<


===============================================================================
FAQ                                                             *gitgutter-faq*

a. How do I turn off realtime updates?

  Add this to your vim configuration in an |after-directory|:
>
    autocmd! gitgutter CursorHold,CursorHoldI
<

b. I turned off realtime updates, how can I have signs updated when I save a
   file?

  If you really want to update the signs when you save a file, add this to your
  |vimrc|:
>
    autocmd BufWritePost * GitGutter
<

c. Why can't I unstage staged changes?

  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.

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

  Your colorscheme is configuring the |hl-SignColumn| highlight group weirdly.
  Here are two ways you could change the colours:
>
    highlight! link SignColumn LineNr
    highlight SignColumn guibg=whatever ctermbg=whatever
<

e. What happens if I also use another plugin which uses signs (e.g. Syntastic)?

  Vim only allows one sign per line.  Vim-gitgutter will not interfere with
  signs it did not add.


===============================================================================
TROUBLESHOOTING                                     *gitgutter-troubleshooting*

When no signs are showing at all:~

1. Try bypassing grep with:
>
    let g:gitgutter_grep = ''
<
  If it works, the problem is grep outputting ANSI escape codes.  Use this
  option to pass arguments to grep to turn off the escape codes.

2. Verify git is on your path:
>
    :echo system('git --version')
<

3. Verify your git config is compatible with the version of git return by the
   command above.

4. Verify your Vim supports signs.  The following should give 1:
>
    :echo has('signs')
<

5. Check whether the plugin thinks git knows about your file:
>
    :echo getbufvar('','gitgutter').path
<
  If the result is -2, the plugin thinks your file is not tracked by git.

6. Check whether the signs have been placed:
>
    :sign place group=gitgutter
<
  If you see a list of signs, this is a colorscheme / highlight problem.
  Compare these two highlight values:
>
    :highlight GitGutterAdd
    :highlight SignColumn
<
  If no signs are listed, the call to git-diff is probably failing.  Turn on
  logging by adding the following to your vimrc, restart, reproduce the problem,
  and examing the gitgutter.log file in the plugin's directory.
>
    let g:gitgutter_log = 1
<

When the whole file is marked as added:~

If you use zsh, and you set "CDPATH", make sure "CDPATH" does not include the
current directory.


When signs take a few seconds to appear:~

Try reducing 'updatetime':
>
    set updatetime=100
<

Note this also controls how long vim waits before writing its swap file.


When signs don't update after focusing Vim:~

Your terminal probably isn't reporting focus events.  Either try installing
Terminus (https://github.com/wincent/terminus) or set:
>
    let g:gitgutter_terminal_reports_focus = 0
<

  vim:tw=78:et:ft=help:norl: