745 lines
26 KiB
Text
745 lines
26 KiB
Text
*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*
|
|
|
|
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
|
|
<
|
|
|
|
|
|
===============================================================================
|
|
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-: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.
|
|
|
|
|
|
===============================================================================
|
|
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_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_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 GitGutterChangeLineDefault
|
|
<
|
|
|
|
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 CursorLineNr
|
|
<
|
|
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:
|