mirror of
https://github.com/airblade/vim-gitgutter.git
synced 2025-11-10 12:33:47 -05:00
264 lines
9.3 KiB
Markdown
264 lines
9.3 KiB
Markdown
## Vim Git Gutter
|
|
|
|
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][st2gg] plugin for Sublime Text 2.
|
|
|
|
|
|
### 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.
|
|
|
|
If you don't have a preferred installation method, I recommend installing [pathogen.vim][pathogen], and then simply copy and paste:
|
|
|
|
```
|
|
cd ~/.vim/bundle
|
|
git clone git://github.com/airblade/vim-gitgutter.git
|
|
```
|
|
|
|
Or for [Vundle](https://github.com/gmarik/vundle) users:
|
|
|
|
Add `Bundle 'airblade/vim-gitgutter'` to your `~/.vimrc` and then:
|
|
|
|
* either within Vim: `:BundleInstall`
|
|
* or in your shell: `vim +BundleInstall +qall`
|
|
|
|
|
|
### Usage
|
|
|
|
You don't have to do anything: it just works.
|
|
|
|
You can explicitly turn vim-gitgutter off and on (defaults to on):
|
|
|
|
* turn off with `:GitGutterDisable`
|
|
* turn on with `:GitGutterEnable`
|
|
* toggle with `:GitGutterToggle`.
|
|
|
|
And you can turn line highlighting on and off (defaults to off):
|
|
|
|
* turn on with `:GitGutterLineHighlightsEnable`
|
|
* turn off with `:GitGutterLineHighlightsDisable`
|
|
* toggle with `:GitGutterLineHighlightsToggle`.
|
|
|
|
Furthermore you can jump between `[count]` hunks:
|
|
|
|
* jump to next hunk: `:[count]GitGutterNextHunk [count]`
|
|
* jump to previous hunk: `:[count]GitGutterPrevHunk [count]`.
|
|
|
|
You may want to add mappings for these if you use them often. For example:
|
|
|
|
```viml
|
|
nmap <silent> ]h :<C-U>execute v:count1 . "GitGutterNextHunk"<CR>
|
|
nmap <silent> [h :<C-U>execute v:count1 . "GitGutterPrevHunk"<CR>
|
|
```
|
|
|
|
Finally, you can force vim-gitgutter to update its signs across all buffers with `:GitGutterAll`.
|
|
|
|
See the customisation section below for how to change the defaults.
|
|
|
|
|
|
### 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
|
|
* Whether or not vim-gitgutter is on initially (defaults to on)
|
|
* Whether or not line highlighting is on initially (defaults to off)
|
|
* Whether or not vim-gitgutter runs on `BufEnter` (defaults to yes)
|
|
* Whether or not vim-gitgutter runs for all buffers on `FocusGained` (defaults to yes)
|
|
|
|
Please note that vim-gitgutter won't override any colours or highlights you've set in your colorscheme.
|
|
|
|
|
|
#### Sign column
|
|
|
|
The background colour of the sign column is controlled by the `SignColumn` highlight group. This will be either set in your colorscheme or Vim's default.
|
|
|
|
To find out where it's set, and to what it's set, use `:verbose highlight SignColumn`.
|
|
|
|
If your `SignColumn` is not set (`:highlight SignColumn` gives you `SignColumn xxx cleared`), vim-gitgutter will set it to the same as your line number column (i.e. the `LineNr` highlight group).
|
|
|
|
To change your sign column's appearance, update your colorscheme or `~/.vimrc` like this:
|
|
|
|
* For the same appearance as your line number column: `highlight clear SignColumn`
|
|
* For a specific appearance on terminal Vim: `highlight SignColumn ctermbg=whatever`
|
|
* For a specific appearance on gVim/MacVim: `highlight SignColumn guibg=whatever`
|
|
|
|
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_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
|
|
```
|
|
|
|
#### To turn off vim-gitgutter by default
|
|
|
|
Add `let g:gitgutter_enabled = 0` to your `~/.vimrc`.
|
|
|
|
|
|
#### To turn on line highlighting by default
|
|
|
|
Add `let g:gitgutter_highlight_lines = 1` to your `~/.vimrc`.
|
|
|
|
|
|
#### To stop vim-gitgutter running on `BufEnter`
|
|
|
|
This is on by default but causes a noticeable lag for some people. To turn it off, add this to your `~/.vimrc`:
|
|
|
|
```
|
|
let g:gitgutter_on_bufenter = 0
|
|
```
|
|
|
|
If you turn it off, vim-gitgutter will instead run every time you read or write a buffer.
|
|
|
|
|
|
#### To stop vim-gitgutter running for all buffers on `FocusGained`
|
|
|
|
This is on by default but causes a noticeable lag for some people. To turn it off, add this to your `~/.vimrc`:
|
|
|
|
```viml
|
|
let g:gitgutter_all_on_focusgained = 0
|
|
```
|
|
|
|
Note that this is always off with gVim on Windows due to a Vim/shell bug causing an infinite loop.
|
|
|
|
|
|
### FAQ
|
|
|
|
> 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.
|
|
|
|
> Why does the window flicker when the signs are redrawn?
|
|
|
|
This happens on certain combinations of OS and Vim. You can prevent the flicker by adding `let g:gitgutter_sign_column_always = 1` to your `~/.vimrc`.
|
|
|
|
> 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. However on some systems this causes a noticeable lag. If you would like to trade a little accuracy for speed, add one or both of these to your `~/.vimrc`:
|
|
|
|
```viml
|
|
let g:gitgutter_on_bufenter = 0
|
|
let g:gitgutter_all_on_focusgained = 0
|
|
```
|
|
|
|
> Why is no sign shown if I delete the first line(s) in a file?
|
|
|
|
vim-gitgutter shows removed lines with a sign on the line above. In this case there isn't a line above so vim-gitgutter can't show the sign.
|
|
|
|
> 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:
|
|
|
|
* Your git config is compatible with the version of git which your Vim is calling (`:echo system('git --version')`).
|
|
* Your Vim supports signs (`:echo has('signs')` should give `1`).
|
|
* Your file is being tracked by git and has unstaged changes.
|
|
|
|
|
|
### Alternatives
|
|
|
|
Related:
|
|
|
|
* [textobj-gitgutter][togg] (lets you treat diff hunks as text objects)
|
|
* [vim-gitgutter][mercurial] - Mercurial fork
|
|
|
|
Vim alternatives:
|
|
|
|
* [git-gutter-vim][ggv]
|
|
* [vim-git-inline-diff][vgid]
|
|
* [quickfixsigns_vim][qf] (a superset of this functionality)
|
|
* [iwilldiffer][iwd]
|
|
* [svndiff][svndiff]
|
|
* [sign-diff][signdiff]
|
|
* [changesPlugin][changes]
|
|
|
|
Other editors:
|
|
|
|
* [Git Gutter][st2gg] for Sublime Text 2
|
|
* [git-gutter.el][gge] for Emacs
|
|
|
|
Also, this may be of interest:
|
|
|
|
* [fugitive.vim][fugitive] is a full-on Git wrapper. It doesn't show git diffs in the gutter (ha!) but it does a bazillion other git things.
|
|
|
|
|
|
### Shameless Plug
|
|
|
|
If this plugin has helped you, or you'd like to learn more about Vim, why not check out these two screencasts I wrote for PeepCode:
|
|
|
|
* [Smash Into Vim I][siv1]
|
|
* [Smash Into Vim II][siv2]
|
|
|
|
You can read reviews at PeepCode and also on my [portfolio][].
|
|
|
|
|
|
### Intellectual Property
|
|
|
|
Copyright Andrew Stewart, AirBlade Software Ltd. Released under the MIT licence.
|
|
|
|
|
|
[st2gg]: https://github.com/jisaacks/GitGutter
|
|
[pathogen]: https://github.com/tpope/vim-pathogen
|
|
[qf]: https://github.com/tomtom/quickfixsigns_vim
|
|
[fugitive]: https://github.com/tpope/vim-fugitive
|
|
[siv1]: https://peepcode.com/products/smash-into-vim-i
|
|
[siv2]: https://peepcode.com/products/smash-into-vim-ii
|
|
[portfolio]: http://airbladesoftware.com/portfolio#vim
|
|
[vgid]: https://github.com/luxflux/vim-git-inline-diff
|
|
[gge]: https://github.com/syohex/emacs-git-gutter
|
|
[iwd]: https://bitbucket.org/sirpengi/iwilldiffer
|
|
[svndiff]: http://www.vim.org/scripts/script.php?script_id=1881
|
|
[signdiff]: http://www.vim.org/scripts/script.php?script_id=2712
|
|
[changes]: http://www.vim.org/scripts/script.php?script_id=3052
|
|
[ggv]: https://github.com/akiomik/git-gutter-vim
|
|
[togg]:https://github.com/gilligan/textobj-gitgutter
|
|
[mercurial]: https://github.com/safetydank/vim-gitgutter
|
|
[macvim]: http://code.google.com/p/macvim/
|