diff options
Diffstat (limited to 'vim/.vim/plugged/vim-gitgutter/doc/gitgutter.txt')
| -rw-r--r-- | vim/.vim/plugged/vim-gitgutter/doc/gitgutter.txt | 549 |
1 files changed, 549 insertions, 0 deletions
diff --git a/vim/.vim/plugged/vim-gitgutter/doc/gitgutter.txt b/vim/.vim/plugged/vim-gitgutter/doc/gitgutter.txt new file mode 100644 index 0000000..87825da --- /dev/null +++ b/vim/.vim/plugged/vim-gitgutter/doc/gitgutter.txt @@ -0,0 +1,549 @@ +*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| + 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* + +Pathogen:~ +> + cd ~/.vim/bundle + git clone git://github.com/airblade/vim-gitgutter.git +< +Voom:~ + +Edit your plugin manifest (`voom edit`) and add: +> + airblade/vim-gitgutter +< +VimPlug:~ + +Place this in your .vimrc: +> + Plug 'airblade/vim-gitgutter' +< +Then run the following in Vim: +> + :source % + :PlugInstall +< +NeoBundle:~ + +Place this in your .vimrc: +> + NeoBundle 'airblade/vim-gitgutter' +< +Then run the following in Vim: +> + :source % + :NeoBundleInstall +< +No plugin manager:~ + +Copy vim-gitgutter's subdirectories into your vim configuration directory: +> + cd tmp && git clone git://github.com/airblade/vim-gitgutter.git + cp vim-gitgutter/* ~/.vim/ +< +See |add-global-plugin|. + + +=============================================================================== +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 jumping between hunks:~ + + *gitgutter-:GitGutterNextHunk* +:GitGutterNextHunk Jump to the next [count] hunk. + + *gitgutter-:GitGutterPrevHunk* +:GitGutterPrevHunk Jump to the previous [count] hunk. + + +Commands for operating on a hunk:~ + + *gitgutter-:GitGutterStageHunk* +:GitGutterStageHunk Stage the hunk the cursor is in. + + *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. + +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 +< + + +=============================================================================== +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_base| + +Grep:~ + + |g:gitgutter_grep| + +Signs:~ + + |g:gitgutter_signs| + |g:gitgutter_highlight_lines| + |g:gitgutter_max_signs| + |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_sign_column_always| + |g:gitgutter_override_sign_column_highlight| + +Terminal:~ + + |g:gitgutter_terminal_reports_focus| + +General:~ + + |g:gitgutter_enabled| + |g:gitgutter_map_keys| + |g:gitgutter_async| + |g:gitgutter_log| + + + *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_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>' +< + + *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_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_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_sign_column_always* +Default: 0 + +This legacy option controls whether the sign column should always be shown, even +if there are no signs to display. + +From Vim 7.4.2201, use 'signcolumn' instead: +> + set signcolumn=yes +< + + *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_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. + +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 DiffChange +< + + +=============================================================================== +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 +< + |