diff options
Diffstat (limited to 'vim/.vim/plugged/vim-gitgutter/README.mkd')
| -rw-r--r-- | vim/.vim/plugged/vim-gitgutter/README.mkd | 582 |
1 files changed, 582 insertions, 0 deletions
diff --git a/vim/.vim/plugged/vim-gitgutter/README.mkd b/vim/.vim/plugged/vim-gitgutter/README.mkd new file mode 100644 index 0000000..a08507b --- /dev/null +++ b/vim/.vim/plugged/vim-gitgutter/README.mkd @@ -0,0 +1,582 @@ +## vim-gitgutter + +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. + +Features: + +* Shows signs for added, modified, and removed lines. +* Runs the diffs asynchronously where possible. +* Ensures signs are always up to date. +* Never saves the buffer. +* Quick jumping between blocks of changed lines ("hunks"). +* Stage/undo/preview individual hunks. +* Provides a hunk text object. +* Diffs against index (default) or any commit. +* Allows folding all unchanged text. +* Handles line endings correctly, even with repos that do CRLF conversion. +* Optional line highlighting. +* Fully customisable (signs, sign column, line highlights, mappings, extra git-diff arguments, etc). +* Can be toggled on/off, globally or per buffer. +* Preserves signs from other plugins. +* Easy to integrate diff stats into status line; built-in integration with [vim-airline](https://github.com/bling/vim-airline/). +* Works with fish shell (in addition to the usual shells). + +Constraints: + +* Supports git only. If you work with other version control systems, I recommend [vim-signify](https://github.com/mhinz/vim-signify). +* Relies on the `FocusGained` event. If your terminal doesn't report focus events, either use something like [Terminus][] or set `let g:gitgutter_terminal_reports_focus=0`. + + +### Screenshot + + + +In the screenshot above you can see: + +* Line 15 has been modified. +* Lines 21-24 are new. +* A line or lines were removed between lines 25 and 26. + + +### Installation + +Before installation, please check your Vim supports signs by running `:echo has('signs')`. `1` means you're all set; `0` means you need to install a Vim with signs support. If you're compiling Vim yourself you need the 'big' or 'huge' feature set. MacVim supports signs. + +You install vim-gitgutter like any other vim plugin. + +##### 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: + +```viml +Plug 'airblade/vim-gitgutter' +``` + +Then run the following in Vim: + +``` +:source % +:PlugInstall +``` + +##### NeoBundle + +Place this in your .vimrc: + +```viml +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 -r vim-gitgutter/* ~/.vim/ +``` + +See `:help add-global-plugin`. + + +### Getting started + +When you make a change to a file tracked by git, the diff markers should appear automatically. The delay is governed by vim's `updatetime` option; the default value is `4000`, i.e. 4 seconds, but I suggest reducing it to around 100ms (add `set updatetime=100` to your vimrc). + +You can jump between hunks with `[c` and `]c`. You can preview, stage, and undo hunks with `<leader>hp`, `<leader>hs`, and `<leader>hu` respectively. + +You cannot unstage a staged hunk. + + +#### Activation + +You can explicitly turn vim-gitgutter off and on (defaults to on): + +* turn off with `:GitGutterDisable` +* turn on with `:GitGutterEnable` +* toggle with `:GitGutterToggle`. + +To toggle vim-gitgutter per buffer: + +* turn off with `:GitGutterBufferDisable` +* turn on with `:GitGutterBufferEnable` +* toggle with `:GitGutterBufferToggle` + +You can turn the signs on and off (defaults to on): + +* turn on with `:GitGutterSignsEnable` +* turn off with `:GitGutterSignsDisable` +* toggle with `:GitGutterSignsToggle`. + +And you can turn line highlighting on and off (defaults to off): + +* turn on with `:GitGutterLineHighlightsEnable` +* turn off with `:GitGutterLineHighlightsDisable` +* toggle with `:GitGutterLineHighlightsToggle`. + +Note that if you have line highlighting on and signs off, you will have an empty sign column – more accurately, a sign column with invisible signs. This is because line highlighting requires signs and Vim always shows the sign column even if the signs are invisible. + +If you switch off both line highlighting and signs, you won't see the sign column. That is unless you configure the sign column always to be there (see Sign Column section). + +To keep your Vim snappy, vim-gitgutter will suppress the signs when a file has more than 500 changes. As soon as the number of changes falls below the limit vim-gitgutter will show the signs again. You can configure the threshold with: + +```viml +let g:gitgutter_max_signs = 500 " default value +``` + +#### Hunks + +You can jump between hunks: + +* jump to next hunk (change): `]c` +* jump to previous hunk (change): `[c`. + +Both of those take a preceding count. + +To set your own mappings for these, for example `]h` and `[h`: + +```viml +nmap ]h <Plug>GitGutterNextHunk +nmap [h <Plug>GitGutterPrevHunk +``` + +You can stage or undo an individual hunk when your cursor is in it: + +* stage the hunk with `<Leader>hs` or +* undo it with `<Leader>hu`. + +See the FAQ if you want to unstage staged changes. + +The `.` command will work with both these if you install [repeat.vim](https://github.com/tpope/vim-repeat). + +To set your own mappings for these, for example if you prefer the mnemonics hunk-add and hunk-revert: + +```viml +nmap <Leader>ha <Plug>GitGutterStageHunk +nmap <Leader>hr <Plug>GitGutterUndoHunk +``` + +And you can preview a hunk's changes with `<Leader>hp`. You can of course change this mapping, e.g: + +```viml +nmap <Leader>hv <Plug>GitGutterPreviewHunk +``` + +A hunk text object is provided which works in visual and operator-pending modes. + +- `ic` operates on all lines in the current hunk. +- `ac` operates on all lines in the current hunk and any trailing empty lines. + +To re-map these, for example to `ih` and `ah`: + +```viml +omap ih <Plug>GitGutterTextObjectInnerPending +omap ah <Plug>GitGutterTextObjectOuterPending +xmap ih <Plug>GitGutterTextObjectInnerVisual +xmap ah <Plug>GitGutterTextObjectOuterVisual +``` + +If you don't want vim-gitgutter to set up any mappings at all, use this: + +```viml +let g:gitgutter_map_keys = 0 +``` + +Finally, you can force vim-gitgutter to update its signs across all visible buffers with `:GitGutterAll`. + +See the customisation section below for how to change the defaults. + + +### Folding + +Use the `GitGutterFold` command to fold all unchanged lines, leaving just the hunks visible. Use `zr` to unfold 3 lines of context above and below a hunk. + +Execute `GitGutterFold` a second time to restore the previous view. + + +### Customisation + +You can customise: + +* The sign column's colours +* Whether or not the sign column is shown when there aren't any signs (defaults to no) +* The signs' colours and symbols +* Line highlights +* The base of the diff +* Extra arguments for `git` when running `git diff` +* Extra arguments for `git diff` +* Key mappings +* 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. + +To customise your sign column's background color, first tell vim-gitgutter to leave it alone: + +```viml +let g:gitgutter_override_sign_column_highlight = 0 +``` + +And then either update your colorscheme's `SignColumn` highlight group or set it in your vimrc: + +```viml +highlight SignColumn ctermbg=whatever " terminal Vim +highlight SignColumn guibg=whatever " gVim/MacVim +``` + +By default the sign column will appear when there are signs to show and disappear when there aren't. To always have the sign column, add to your vimrc: + +```viml +if exists('&signcolumn') " Vim 7.4.2201 + set signcolumn=yes +else + let g:gitgutter_sign_column_always = 1 +endif +``` + + +#### Signs' colours and symbols + +By default vim-gitgutter uses your colourscheme's `Diff*` highlight groups' foreground colours for the signs' foreground colours. For example, your `DiffAdd` foreground colour will be used for the `+` sign's foreground colour. + +The signs' background colours will all be set to the sign column's background colour. + +If you don't like the default colours, you can either fix your colourscheme's `Diff*` highlights or configure your own `GitGutter*` highlight groups. These groups are: + +```viml +GitGutterAdd " an added line (default: links to DiffAdd) +GitGutterChange " a changed line (default: links to DiffChange) +GitGutterDelete " at least one removed line (default: links to DiffDelete) +GitGutterChangeDelete " a changed line followed by at least one removed line (default: links to GitGutterChange) +``` + +You can either set these with `highlight GitGutterAdd {key}={arg}...` or link them to existing highlight groups with, say, `highlight link GitGutterAdd MyDiffAdd`. + +To get vim-gitgutter's original colours (based on git-diff's colours in my terminal): + +```viml +highlight GitGutterAdd guifg=#009900 guibg=<X> ctermfg=2 ctermbg=<Y> +highlight GitGutterChange guifg=#bbbb00 guibg=<X> ctermfg=3 ctermbg=<Y> +highlight GitGutterDelete guifg=#ff2222 guibg=<X> ctermfg=1 ctermbg=<Y> +``` + +– where you would replace `<X>` and `<Y>` with the background colour of your `SignColumn` in the gui and the terminal respectively. For example, with the solarized colorscheme and a dark background, `guibg=#073642` and `ctermbg=0`. + +To customise the symbols, add the following to your `~/.vimrc`: + +```viml +let g:gitgutter_sign_added = 'xx' +let g:gitgutter_sign_modified = 'yy' +let g:gitgutter_sign_removed = 'zz' +let g:gitgutter_sign_removed_first_line = '^^' +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`: + +```viml +GitGutterAddLine " default: links to DiffAdd +GitGutterChangeLine " default: links to DiffChange +GitGutterDeleteLine " default: links to DiffDelete +GitGutterChangeDeleteLine " default: links to GitGutterChangeLineDefault, i.e. DiffChange +``` + +For example, in some colorschemes the `DiffText` highlight group is easier to read than `DiffChange`. You could use it like this: + +```viml +highlight link GitGutterChangeLine DiffText +``` + + +#### The base of the diff + +By default buffers are diffed against the index. However you can diff against any commit by setting: + +```viml +let g:gitgutter_diff_base = '<commit SHA>' +``` + + +#### Extra arguments for `git` when running `git diff` + +If you want to pass extra arguments to `git` when running `git diff`, do so like this: + +```viml +let g:gitgutter_git_args = '--git-dir-""' +``` + +#### Extra arguments for `git diff` + +If you want to pass extra arguments to `git diff`, for example to ignore whitespace, do so like this: + +```viml +let g:gitgutter_diff_args = '-w' +``` + +#### Key mappings + +To disable all key mappings: + +```viml +let g:gitgutter_map_keys = 0 +``` + +See above for configuring maps for hunk-jumping and staging/undoing. + + +#### Use a custom `grep` command + +If you use an alternative to grep, you can tell vim-gitgutter to use it here. + +```viml +" Default: +let g:gitgutter_grep = 'grep' +``` + +#### To turn off vim-gitgutter by default + +Add `let g:gitgutter_enabled = 0` to your `~/.vimrc`. + + +#### To turn off signs by default + +Add `let g:gitgutter_signs = 0` to your `~/.vimrc`. + + +#### To turn on line highlighting by default + +Add `let g:gitgutter_highlight_lines = 1` to your `~/.vimrc`. + + +#### To turn off asynchronous updates + +By default diffs are run asynchronously. To run diffs synchronously instead: + +```viml +let g:gitgutter_async = 0 +``` + + +### Extensions + +#### Operate on every line in a hunk + +You can map an operator to do whatever you want to every line in a hunk. + +Let's say, for example, you want to remove trailing whitespace. + +```viml +function! CleanUp(...) + if a:0 " opfunc + let [first, last] = [line("'["), line("']")] + else + let [first, last] = [line("'<"), line("'>")] + endif + for lnum in range(first, last) + let line = getline(lnum) + + " clean up the text, e.g.: + let line = substitute(line, '\s\+$', '', '') + + call setline(lnum, line) + endfor +endfunction + +nmap <silent> <Leader>x :set opfunc=CleanUp<CR>g@ +``` + +Then place your cursor in a hunk and type `\xic` (assuming a leader of `\`). + +Alternatively you could place your cursor in a hunk, type `vic` to select it, then `:call CleanUp()`. + + +#### Operate on every changed line in a file + +You can write a command to do whatever you want to every changed line in a file. + +```viml +function! GlobalChangedLines(ex_cmd) + for hunk in GitGutterGetHunks() + for lnum in range(hunk[2], hunk[2]+hunk[3]-1) + let cursor = getcurpos() + silent! execute lnum.a:ex_cmd + call setpos('.', cursor) + endfor + endfor +endfunction + +command -nargs=1 Glines call GlobalChangedLines(<q-args>) +``` + +Let's say, for example, you want to remove trailing whitespace from all changed lines: + +```viml +:Glines s/\s\+$// +``` + + +#### Cycle through hunks in all buffers + +`]c` and `[c` jump from one hunk to the next in the current buffer. You can use this code to jump to the next hunk no matter which buffer it's in. + +```viml +function! NextHunkAllBuffers() + let line = line('.') + GitGutterNextHunk + if line('.') != line + return + endif + + let bufnr = bufnr('') + while 1 + bnext + if bufnr('') == bufnr + return + endif + if !empty(GitGutterGetHunks()) + normal! 1G + GitGutterNextHunk + return + endif + endwhile +endfunction + +function! PrevHunkAllBuffers() + let line = line('.') + GitGutterPrevHunk + if line('.') != line + return + endif + + let bufnr = bufnr('') + while 1 + bprevious + if bufnr('') == bufnr + return + endif + if !empty(GitGutterGetHunks()) + normal! G + GitGutterPrevHunk + return + endif + endwhile +endfunction + +nmap <silent> ]c :call NextHunkAllBuffers()<CR> +nmap <silent> [c :call PrevHunkAllBuffers()<CR> +``` + + +### FAQ + +> How can I turn off realtime updates? + +Add this to your vim configuration (in an `/after/plugin` directory): + +```viml +" .vim/after/plugin/gitgutter.vim +autocmd! gitgutter CursorHold,CursorHoldI +``` + +> 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: + +```viml +autocmd BufWritePost * GitGutter +``` + +> 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. + +> Why are the colours in the sign column weird? + +Your colorscheme is configuring the `SignColumn` highlight group weirdly. Please see the section above on customising the sign column. + +> 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. + + +### Troubleshooting + +#### When no signs are showing at all + +Here are some things you can check: + +* Try adding `let g:gitgutter_grep=''` to your vimrc. If it works, the problem is grep producing non-plain output; e.g. ANSI escape codes or colours. +* Verify `:echo system("git --version")` succeeds. +* Verify your git config is compatible with the version of git returned by the command above. +* Verify your Vim supports signs (`:echo has('signs')` should give `1`). +* Verify your file is being tracked by git and has unstaged changes. + +#### When the whole file is marked as added + +* If you use zsh, and you set `CDPATH`, make sure `CDPATH` doesn't include the current directory. + +#### When signs take a few seconds to appear + +* Try reducing `updatetime`, e.g. `set updatetime=100`. + +#### When signs don't update after focusing Vim + +* Your terminal probably isn't reporting focus events. Either try installing [Terminus][] or set `let g:gitgutter_terminal_reports_focus=0`. + + +### Shameless Plug + +If this plugin has helped you, or you'd like to learn more about Vim, why not check out this screencast I wrote for PeepCode: + +* [Smash Into Vim][siv] + +This was one of PeepCode's all-time top three bestsellers and is now available at Pluralsight. + +You can read reviews on my [website][airblade]. + + +### Intellectual Property + +Copyright Andrew Stewart, AirBlade Software Ltd. Released under the MIT licence. + + + [pathogen]: https://github.com/tpope/vim-pathogen + [siv]: http://pluralsight.com/training/Courses/TableOfContents/smash-into-vim + [airblade]: http://airbladesoftware.com/peepcode-vim + [terminus]: https://github.com/wincent/terminus |