mirror of
https://github.com/airblade/vim-gitgutter.git
synced 2025-11-08 11:33:48 -05:00
267 lines
8.3 KiB
Plaintext
267 lines
8.3 KiB
Plaintext
*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. 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*
|
|
|
|
If you don't have a preferred installation method, I recommend installing
|
|
pathogen.vim, and then simply copy and paste:
|
|
>
|
|
cd ~/.vim/bundle
|
|
git clone git://github.com/airblade/vim-gitgutter.git
|
|
<
|
|
Or for Vundle users:
|
|
|
|
Add Bundle 'airblade/vim-gitgutter' to your |vimrc| and then:
|
|
|
|
- either within Vim: :BundleInstall
|
|
- or in your shell: vim +BundleInstall +qall
|
|
|
|
===============================================================================
|
|
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 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 reverting individual hunks:
|
|
|
|
:GitGutterStageHunk *:GitGutterStageHunk*
|
|
Stage the hunk the cursor is in.
|
|
|
|
:GitGutterRevertHunk *:GitGutterRevertHunk*
|
|
Revert the hunk the cursor is in.
|
|
|
|
===============================================================================
|
|
5. CUSTOMISATION *GitGutterCustomisation*
|
|
|
|
You can customise:
|
|
|
|
- The sign column's colours
|
|
- The signs' colours and symbols
|
|
- Line highlights
|
|
- Extra arguments for git-diff
|
|
- Key mappings
|
|
- Whether or not to escape grep (defaults to no)
|
|
- 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)
|
|
|
|
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 |hlSignColumn|
|
|
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, i.e if
|
|
>
|
|
:highlight SignColumn " gives you `SignColumn xxx cleared`
|
|
<
|
|
vim-gitgutter will set it to the same as your line number column (i.e. the
|
|
|hl-LineNr| highlight group).
|
|
|
|
To change your sign column's appearance, update your colorscheme or |vimrc|
|
|
like this:
|
|
|
|
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'
|
|
<
|
|
|
|
SIGNS
|
|
|
|
To never show signs, use this:
|
|
>
|
|
let g:gitgutter_signs = 0
|
|
<
|
|
|
|
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
|
|
<
|
|
|
|
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:
|
|
>
|
|
nmap [h <Plug>GitGutterPrevHunk
|
|
nmap ]h <Plug>GitGutterNextHunk
|
|
<
|
|
|
|
To change the hunk-staging/reverting maps:
|
|
>
|
|
nmap <Leader>hs <Plug>GitGutterStageHunk
|
|
nmap <Leader>hr <Plug>GitGutterRevertHunk
|
|
<
|
|
|
|
TO ESCAPE GREP
|
|
|
|
To avoid any alias you have for grep, use this:
|
|
>
|
|
let g:gitgutter_escape_grep = 1
|
|
<
|
|
|
|
TO TURN OFF VIM-GITGUTTER BY DEFAULT
|
|
|
|
Add to your |vimrc|
|
|
>
|
|
let g:gitgutter_enabled = 0
|
|
<
|
|
|
|
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
|
|
<
|
|
|
|
|
|
===============================================================================
|
|
6. 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. 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.
|
|
|
|
c. 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.
|