*gitgutter.txt* A Vim plugin which shows a git diff in the gutter. Vim Git Gutter Author: Andy Stewart Plugin Homepage: =============================================================================== CONTENTS *gitgutter* Introduction ................. |gitgutter-introduction| Installation ................. |gitgutter-installation| Windows ................. |gitgutter-windows| Commands ..................... |gitgutter-commands| Mappings ..................... |gitgutter-mappings| Autocommand .................. |gitgutter-autocommand| 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. 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-hp* hp Preview the hunk under the cursor. *gitgutter-hs* hs Stage the hunk under the cursor. *gitgutter-hu* hu Undo the hunk under the cursor. You can change these mappings like this: > nmap ghp (GitGutterPreviewHunk) nmap ghs (GitGutterStageHunk) nmap ghu (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 (GitGutterPrevHunk) nmap ]c (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 (GitGutterTextObjectInnerPending) omap ac (GitGutterTextObjectOuterPending) xmap ic (GitGutterTextObjectInnerVisual) xmap ac (GitGutterTextObjectOuterVisual) < =============================================================================== 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. 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_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 = '' < 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-mapppings|. *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. =============================================================================== 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 < 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 <