657 lines
22 KiB
Plaintext
657 lines
22 KiB
Plaintext
*gitgutter.txt* A Vim plugin which shows a git diff in the gutter.
|
|
|
|
|
|
Vim Git Gutter
|
|
|
|
|
|
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 'gutter' (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.
|
|
|
|
|
|
===============================================================================
|
|
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*
|
|
|
|
I recommend configuring vim-gitgutter with the full path to your git executable.
|
|
For example:
|
|
>
|
|
let g:gitgutter_git_executable = 'C:\Program Files\Git\bin\git.exe'
|
|
<
|
|
This is to avoid a problem which occurs if you have file named "git.*" (i.e.
|
|
with any extension in "PATHEXT") in your current folder. "cmd.exe" prioritises
|
|
the current folder over folders in 'PATH' and will try to execute your file
|
|
instead of the "git" binary.
|
|
|
|
|
|
===============================================================================
|
|
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
|
|
|
|
|
|
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.
|
|
Use |:pclose| or |CTRL-W_CTRL-Z| to close the preview
|
|
window.
|
|
|
|
To stage part of the hunk, move to the preview window,
|
|
delete any lines you do not want to stage, and
|
|
|GitGutterStageHunk|.
|
|
|
|
Commands for folds:~
|
|
|
|
*gitgutter-:GitGutterFold*
|
|
:GitGutterFold Fold all unchanged lines. Execute again to undo.
|
|
|
|
|
|
===============================================================================
|
|
AUTOCOMMAND *gitgutter-autocommand*
|
|
|
|
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.
|
|
|
|
|
|
===============================================================================
|
|
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_override_sign_column_highlight|
|
|
|
|
Hunk previews:~
|
|
|
|
|g:gitgutter_preview_win_floating|
|
|
|
|
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>'
|
|
<
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
*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_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_modified_removed = '~_'
|
|
<
|
|
You can use unicode characters but not images. Signs must not take up more than
|
|
2 columns.
|
|
|
|
*g:gitgutter_override_sign_column_highlight*
|
|
Default: 1
|
|
|
|
Controls whether to make the sign column look like the line-number column (i.e.
|
|
the |hl-LineNr| highlight group).
|
|
|
|
To customise your sign column's background color, first tell vim-gitgutter to
|
|
leave it alone:
|
|
>
|
|
let g:gitgutter_override_sign_column_highlight = 0
|
|
<
|
|
|
|
And then either update your colorscheme's |hlSignColumn| highlight group or set
|
|
it in your |vimrc|:
|
|
|
|
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}
|
|
|
|
|
|
*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_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.
|
|
|
|
|
|
===============================================================================
|
|
HIGHLIGHTS *gitgutter-highlights*
|
|
|
|
To change the signs' colours, 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 MyDiffAdd
|
|
<
|
|
|
|
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
|
|
<
|
|
|
|
|
|
===============================================================================
|
|
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.
|
|
Please see |g:gitgutter_override_sign_column_highlight| on customising the
|
|
sign column.
|
|
|
|
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.
|
|
|
|
|
|
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
|
|
<
|
|
|