aboutsummaryrefslogtreecommitdiff
path: root/vim/bundle/vim-gitgutter/README.mkd
diff options
context:
space:
mode:
authorKarel Kočí <cynerd@email.cz>2016-06-30 16:11:56 +0200
committerKarel Kočí <cynerd@email.cz>2016-06-30 16:11:56 +0200
commit9931e0888b2419326ae10ebbfae532261c5c125f (patch)
tree7504be5daccbb7b7d1ea396754de47b11ed790e5 /vim/bundle/vim-gitgutter/README.mkd
parente573b3020c032400eed60b649a2cbf55266e6bb0 (diff)
downloadmyconfigs-9931e0888b2419326ae10ebbfae532261c5c125f.tar.gz
myconfigs-9931e0888b2419326ae10ebbfae532261c5c125f.tar.bz2
myconfigs-9931e0888b2419326ae10ebbfae532261c5c125f.zip
Fix submodules
Diffstat (limited to 'vim/bundle/vim-gitgutter/README.mkd')
m---------vim/bundle/vim-gitgutter0
-rw-r--r--vim/bundle/vim-gitgutter/README.mkd499
2 files changed, 0 insertions, 499 deletions
diff --git a/vim/bundle/vim-gitgutter b/vim/bundle/vim-gitgutter
new file mode 160000
+Subproject b5f23e986747a6f4b1dc1196d2a5bd3dc7c8c2b
diff --git a/vim/bundle/vim-gitgutter/README.mkd b/vim/bundle/vim-gitgutter/README.mkd
deleted file mode 100644
index 6fc92ae..0000000
--- a/vim/bundle/vim-gitgutter/README.mkd
+++ /dev/null
@@ -1,499 +0,0 @@
-## vim-gitgutter
-
-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. You can also stage and undo individual hunks.
-
-Features:
-
-* Shows signs for added, modified, and removed lines.
-* Runs the diffs asynchronously in terminal Vim/MacVim (7.4.1826+), gVim (7.4.1850+), MacVim GUI (7.4.1832+), and NeoVim.
-* Ensures signs are always as up to date as possible (but without running more than necessary).
-* 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.
-* 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.
-* 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).
-
-
-### Screenshot
-
-![screenshot](https://raw.github.com/airblade/vim-gitgutter/master/screenshot.png)
-
-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`.
-
-
-If you are on Windows you may find the command prompt pops up briefly every time vim-gitgutter runs. You can avoid this by installing both [vim-misc](https://github.com/xolox/vim-misc) and [vim-shell](https://github.com/xolox/vim-shell). If you have those two plugins but don't want vim-gitgutter to use them, you can opt out with `let g:gitgutter_avoid_cmd_prompt_on_windows = 0` in your `~/.vimrc`.
-
-
-### 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 4 seconds but I suggest reducing it to around 250ms (add `set updatetime=250` 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 currently 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`.
-
-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 have set `let g:gitgutter_sign_column_always = 1` so it's always there.
-
-To keep your Vim snappy, vim-gitgutter will suppress itself 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.
-
-
-### When are the signs updated?
-
-By default the signs are updated as follows:
-
-| Event | Reason for update | Configuration |
-|---------------------------|--------------------------------------|------------------------|
-| Stop typing | So the signs are real time | `g:gitgutter_realtime` |
-| Switch buffer | To notice change to git index | `g:gitgutter_eager` |
-| Switch tab | To notice change to git index | `g:gitgutter_eager` |
-| Focus the GUI | To notice change to git index | `g:gitgutter_eager` (not gVim on Windows) |
-| Read a file into a buffer | To display initial signs | [always] |
-| Save a buffer | So non-realtime signs are up to date | [always] |
-| Change a file outside Vim | To notice `git stash` | [always] |
-
-The length of time Vim waits after you stop typing before it triggers the plugin is governed by the setting `updatetime`. This defaults to `4000` milliseconds which is rather too long. I recommend around `250` milliseconds but it depends on your system and your preferences. Note that in terminal Vim pre-7.4.427 an `updatetime` of less than approximately `1000` milliseconds can lead to random highlighting glitches; the lower the `updatetime`, the more glitches.
-
-If you experience a lag, you can trade speed for accuracy:
-
-```viml
-let g:gitgutter_realtime = 0
-let g:gitgutter_eager = 0
-```
-
-Note the realtime updating requires Vim 7.3.105 or higher.
-
-
-### 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 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. If you would always like the sign column to be there, add `let g:gitgutter_sign_column_always = 1` to your `~/.vimrc`.
-
-
-#### Signs' colours and symbols
-
-To customise the colours, set up the following highlight groups in your colorscheme or `~/.vimrc`:
-
-```viml
-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`:
-
-```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
-```
-
-
-#### 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 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, or your grep does not support the `color` flag, you can tell vim-gitgutter to use it here. It only needs to support extended POSIX regex.
-
-```viml
-" Default:
-let g:gitgutter_grep_command = 'grep --color=never -e'
-```
-
-#### 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\+$//
-```
-
-
-### FAQ
-
-> Why can't I unstage staged changes?
-
-Unstaging staged hunks is feasible but not quite as easy as it sounds. There are three relevant versions of a file at any one time:
-
-1. The version at HEAD in the repo.
-2. The version staged in the index.
-3. The version in the working tree, in your vim buffer.
-
-`git-diff` without arguments shows you how 3 and 2 differ; this is what vim-gitgutter shows too.
-
-`git-diff --staged` shows you how 2 and 1 differ.
-
-Let's say your are looking at a file in vim which has some unstaged changes. Now you stage a hunk, either via vim-gitgutter or another means. The hunk is no longer marked in vim-gitgutter because it is the same in 3 and 2.
-
-Now you want to unstage that hunk. To see it, you need the difference between 2 and 1. For vim-gitgutter to shows those differences, it would need to show you 2 instead of 3 in your vim buffer. But 2 is virtual so vim-gitgutter would need to handle it without touching 3.
-
-I intend to implement this but I can't commit to any deadline.
-
-> 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.
-
-> There's a noticeable lag when vim-gitter runs; how can I avoid it?
-
-By default vim-gitgutter runs often so the signs are as accurate as possible. The delay is governed by `updatetime`; see [above](#when-are-the-signs-updated) for more information.
-
-If you don't want realtime updates and would like to trade a little accuracy for speed, add this to your `~/.vimrc`:
-
-```viml
-let g:gitgutter_realtime = 0
-let g:gitgutter_eager = 0
-```
-
-> 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.
-
-> Why aren't any signs showing at all?
-
-Here are some things you can check:
-
-* `:echo system("git --version")` succeeds.
-* Your git config is compatible with the version of git returned by the command above.
-* Your Vim supports signs (`:echo has('signs')` should give `1`).
-* Your file is being tracked by git and has unstaged changes.
-* If your grep does not support the `color` flag, add `let g:gitgutter_grep_command = 'grep -e'` to your `~/.vimrc`.
-
-
-### 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
- [macvim]: http://code.google.com/p/macvim/