diff options
Diffstat (limited to 'vim/bundle/vim-gitgutter/doc/gitgutter.txt')
| -rw-r--r-- | vim/bundle/vim-gitgutter/doc/gitgutter.txt | 340 |
1 files changed, 340 insertions, 0 deletions
diff --git a/vim/bundle/vim-gitgutter/doc/gitgutter.txt b/vim/bundle/vim-gitgutter/doc/gitgutter.txt new file mode 100644 index 0000000..d4bb774 --- /dev/null +++ b/vim/bundle/vim-gitgutter/doc/gitgutter.txt @@ -0,0 +1,340 @@ +*gitgutter.txt* A Vim plugin which shows a git diff in the gutter. + + + Vim Git Gutter + + +Author: Andy Stewart <http://airbladesoftware.com/> +Plugin Homepage: <https://github.com/airblade/vim-gitgutter> + +=============================================================================== +CONTENTS *GitGutterContents* + + 1. Introduction ................. |GitGutterIntroduction| + 2. Installation ................. |GitGutterInstallation| + 3. Usage ........................ |GitGutterUsage| + 4. Commands ..................... |GitGutterCommands| + 5. Autocommand .................. |GitGutterAutocmd| + 6. CUSTOMISATION................. |GitGutterCustomisation| + 7. FAQ .......................... |GitGutterFAQ| + +=============================================================================== +1. INTRODUCTION *GitGutterIntroduction* + *GitGutter* + +Vim Git Gutter is a Vim plugin which shows a git diff in the 'gutter' (sign +column). It shows whether each line has been added, modified, and where lines +have been removed. + +This is a port of the Git Gutter plugin for Sublime Text 2. + +=============================================================================== +2. INSTALLATION *GitGutterInstallation* + +* 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|. + +=============================================================================== +3. USAGE *GitGutterUsage* + +You don't have to do anything: it just works. + +=============================================================================== +4. COMMANDS *GitGutterCommands* + +Commands for turning Git Gutter on and off: + + :GitGutterDisable *:GitGutterDisable* + Explicitly turn Git Gutter off. + + :GitGutterEnable *:GitGutterEnable* + Explicitly turn Git Gutter on. + + :GitGutterToggle *:GitGutterToggle* + Explicitly turn Git Gutter on if it was off and vice versa. + + :GitGutter *:GitGutter* + Update signs for the current buffer. + + :GitGutterAll *:GitGutterAll* + Update signs across all buffers. + +Commands for turning signs on and off (defaults to on): + + :GitGutterSignsEnable *:GitGutterSignsEnable* + Explicitly turn line signs on. + + :GitGutterSignsDisable *:GitGutterSignsDisable* + Explicitly turn line signs off. + + :GitGutterSignsToggle *:GitGutterSignsToggle* + Explicitly turn line signs on if it was off and vice versa. + +Commands for turning line highlighting on and off (defaults to off): + + :GitGutterLineHighlightsEnable *:GitGutterLineHighlightsEnable* + Explicitly turn line highlighting on. + + :GitGutterLineHighlightsDisable *:GitGutterLineHighlightsDisable* + Explicitly turn line highlighting off. + + :GitGutterLineHighlightsToggle *:GitGutterLineHighlightsToggle* + Explicitly turn line highlighting on if it was off and vice versa. + +Commands for jumping between marked hunks: + + :GitGutterNextHunk *:GitGutterNextHunk* + Jump to the next marked hunk. Takes a count. + + :GitGutterPrevHunk *:GitGutterPrevHunk* + Jump to the previous marked hunk. Takes a count. + +Commands for staging or undoing individual hunks: + + :GitGutterStageHunk *:GitGutterStageHunk* + Stage the hunk the cursor is in. + + :GitGutterUndoHunk *:GitGutterUndoHunk* + Undo the hunk the cursor is in. + + :GitGutterPreviewHunk *:GitGutterPreviewHunk* + Preview the hunk the cursor is in. + +=============================================================================== +5. AUTOCOMMAND *GitGutterAutocmd* + +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() +< + +=============================================================================== +6. CUSTOMISATION *GitGutterCustomisation* + +You can customise: + +- The sign column's colours +- The signs' colours and symbols +- Line highlights +- The base of the diff +- Extra arguments for git-diff +- Key mappings +- The grep executable used +- Whether or not vim-gitgutter is on initially (defaults to on) +- Whether or not signs are shown (defaults to yes) +- Whether or not line highlighting is on initially (defaults to off) +- Whether or not vim-gitgutter runs in realtime (defaults to yes) +- Whether or not vim-gitgutter runs eagerly (defaults to yes) +- Whether or not vim-gitgutter runs asynchronously (defaults to yes) + +Please note that vim-gitgutter won't override any colours or highlights you've +set in your colorscheme. + +SIGN COLUMN + +By default vim-gitgutter will 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} + +SIGNS' COLOURS AND SYMBOLS + +To customise the 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 DiffAdd +< + +To customise the symbols, add the following to your |vimrc|: +> + let g:gitgutter_sign_added = 'xx' + let g:gitgutter_sign_modified = 'yy' + let g:gitgutter_sign_removed = 'zz' + let g:gitgutter_sign_modified_removed = 'ww' +< + +LINE HIGHLIGHTS + +Similarly to the signs' colours, 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 +< + +THE BASE OF THE DIFF + +By default buffers are diffed against the index. To diff against a commit +instead: +> + let g:gitgutter_diff_base = '<commit SHA>' +< + +EXTRA ARGUMENTS FOR GIT-DIFF + +To pass extra arguments to git-diff, add this to your |vimrc|: +> + let g:gitgutter_diff_args = '-w' +< + +KEY MAPPINGS + +To disable all key maps: +> + let g:gitgutter_map_keys = 0 +< + +To change the hunk-jumping maps (defaults shown): +> + nmap [c <Plug>GitGutterPrevHunk + nmap ]c <Plug>GitGutterNextHunk +< + +To change the hunk-staging/undoing/previewing maps (defaults shown): +> + nmap <Leader>hs <Plug>GitGutterStageHunk + nmap <Leader>hu <Plug>GitGutterUndoHunk + nmap <Leader>hp <Plug>GitGutterPreviewHunk +< + +To change the hunk text object maps (defaults shown): +> + omap ic <Plug>GitGutterTextObjectInnerPending + omap ac <Plug>GitGutterTextObjectOuterPending + xmap ic <Plug>GitGutterTextObjectInnerVisual + xmap ac <Plug>GitGutterTextObjectOuterVisual +< + +TO USE A CUSTOM GREP COMMAND + +To use a custom invocation for grep, use this: +> + let g:gitgutter_grep_command = 'grep --color=never -e' +< + +TO TURN OFF VIM-GITGUTTER BY DEFAULT + +Add to your |vimrc| +> + let g:gitgutter_enabled = 0 +< + +TO TURN OFF SIGNS BY DEFAULT + +Add to your |vimrc| +> + let g:gitgutter_signs = 0 +< + +Note that the sign column will still be present if you have line highlighting +switched on. + +TO TURN ON LINE HIGHLIGHTING BY DEFAULT + +Add to your |vimrc| +> + let g:gitgutter_highlight_lines = 1 +< + +TO STOP VIM-GITGUTTER RUNNING IN REALTIME + +Add to your |vimrc| +> + let g:gitgutter_realtime = 0 +< + +TO STOP VIM-GITGUTTER RUNNING EAGERLY + +Add to your |vimrc| +> + let g:gitgutter_eager = 0 +< + +TO TURN OFF ASYNCHRONOUS UPDATES + +By default diffs are run asynchronously. To run diffs synchronously +instead: + +Add to your |vimrc| +> +let g:gitgutter_async = 0 +< + +=============================================================================== +7. FAQ *GitGutterFAQ* + +a. Why are the colours in the sign column weird? + + Your colorscheme is configuring the |hl-SignColumn| highlight group weirdly. + Please see |GitGutterCustomisation| on customising the sign column. + +b. What happens if I also use another plugin which uses signs (e.g. Syntastic)? + + Vim only allows one sign per line. Before adding a sign to a line, + vim-gitgutter checks whether a sign has already been added by somebody else. + If so it doesn't do anything. In other words vim-gitgutter won't overwrite + another plugin's signs. It also won't remove another plugin's signs. |