From 3979c4f7b60548605d09cb11f21d4639bf0a1be1 Mon Sep 17 00:00:00 2001 From: Andy Stewart Date: Fri, 8 Mar 2013 13:19:25 +0100 Subject: [PATCH] Easier customisation. --- README.mkd | 49 ++++++++++++++++++------ doc/gitgutter.txt | 91 +++++++++++++++++++++++++++++++++++++++----- plugin/gitgutter.vim | 81 ++++++++++++++++++++++----------------- 3 files changed, 167 insertions(+), 54 deletions(-) diff --git a/README.mkd b/README.mkd index 234dcf0..f7819d0 100644 --- a/README.mkd +++ b/README.mkd @@ -37,9 +37,7 @@ Add `Bundle 'airblade/vim-gitgutter'` to your `~/.vimrc` and then: You don't have to do anything: it just works. -If you want vim-gitgutter off by default, add `let g:gitgutter_enabled = 0` to your `~/.vimrc`. - -You can explicitly turn vim-gitgutter off and on: +You can explicitly turn vim-gitgutter off and on (defaults to on): * turn off with `:GitGutterDisable` * turn on with `:GitGutterEnable` @@ -58,14 +56,15 @@ Furthermore you can jump between hunks: You may want to add mappings for these if you use them often. -If you want to define your own highlights, you can turn off vim-gitgutter's with `let g:gitgutter_highlights = 0` in your `~/.vimrc`. +See the customisation section below for how to change the defaults. ### Customisation +You can customise: + * The sign column's colours * The signs' colours -* The signs' 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) @@ -75,13 +74,13 @@ Please note that vim-gitgutter won't override any colours or highlights you've s #### Sign column -The background colour of the sign column is controlled by the `SignColumn` highlight group. This will be either set in your colour scheme or Vim's default. +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 colour scheme or `~/.vimrc` like this: +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` @@ -90,15 +89,43 @@ To change your sign column's appearance, update your colour scheme or `~/.vimrc` #### Signs' colours -To customise these, put this in your colorscheme or `~/.vimrc`: +To customise these, 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`. + +#### 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, 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`. ### FAQ -> The colours in the sign column are weird. +> Why are the colours in the sign column weird? -Please see the section above on customising the sign column. +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)? @@ -162,5 +189,5 @@ Copyright Andrew Stewart, AirBlade Software Ltd. Released under the MIT licence [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 + [togg]:https://github.com/gilligan/textobj-gitgutter [mercurial]: https://github.com/safetydank/vim-gitgutter diff --git a/doc/gitgutter.txt b/doc/gitgutter.txt index 53511e2..c4ca284 100644 --- a/doc/gitgutter.txt +++ b/doc/gitgutter.txt @@ -37,7 +37,7 @@ pathogen.vim, and then simply copy and paste: < Or for Vundle users: -Add Bundle 'airblade/vim-gitgutter' to your ~/.vimrc and then: +Add Bundle 'airblade/vim-gitgutter' to your |vimrc| and then: - either within Vim: :BundleInstall - or in your shell: vim +BundleInstall +qall @@ -47,9 +47,6 @@ Add Bundle 'airblade/vim-gitgutter' to your ~/.vimrc and then: You don't have to do anything: it just works. -If you want vim-gitgutter off by default, add let g:gitgutter_enabled = 0 to -your ~/.vimrc. - =============================================================================== 4. COMMANDS *GitGutterCommands* @@ -84,16 +81,92 @@ Commands for jumping between marked hunks: Jump to the previous marked hunk. =============================================================================== -5. FAQ *GitGutterFAQ* +5. CUSTOMISATION *GitGutterCustomisation* -a. The colours in the sign column are weird. +You can customise: - The syntax highlighting for your sign column is probably set strangely. Either - modify your colorscheme or add this to your ~/.vimrc: +- The sign column's colours +- The signs' colours +- Line highlights +- Whether or not vim-gitgutter is on initially (defaults to on) +- Whether or not line highlighting is on initially (defaults to off) + +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: > - highlight clear SignColumn + :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 + +To customise these, 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 +< + +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 +< + +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|. + + +=============================================================================== +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. 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, diff --git a/plugin/gitgutter.vim b/plugin/gitgutter.vim index 445bf26..bfa8797 100644 --- a/plugin/gitgutter.vim +++ b/plugin/gitgutter.vim @@ -9,20 +9,16 @@ if !exists('g:gitgutter_enabled') let g:gitgutter_enabled = 1 endif -if !exists('g:gitgutter_highlights') - let g:gitgutter_highlights = 1 -endif - if !exists('g:gitgutter_highlight_lines') let g:gitgutter_highlight_lines = 0 endif +let s:highlight_lines = g:gitgutter_highlight_lines function! s:init() if !exists('g:gitgutter_initialised') call s:define_sign_column_highlight() - let s:highlight_lines = g:gitgutter_highlight_lines - call s:define_signs() call s:define_highlights() + call s:define_signs() " Vim doesn't namespace sign ids so every plugin shares the same " namespace. Sign ids are simply integers so to avoid clashes with other @@ -91,44 +87,58 @@ endfunction " }}} -" {{{ Colours and signs +" Highlights and signs {{{ function! s:define_sign_column_highlight() highlight default link SignColumn LineNr endfunction function! s:define_highlights() - " sign highlights - hi GitGutterAddDefault guifg=#009900 guibg=NONE ctermfg=2 ctermbg=NONE - hi GitGutterChangeDefault guifg=#bbbb00 guibg=NONE ctermfg=3 ctermbg=NONE - hi GitGutterDeleteDefault guifg=#ff2222 guibg=NONE ctermfg=1 ctermbg=NONE - hi default link GitGutterChangeDeleteDefault GitGutterChangeDefault + " Highlights used by the signs. + highlight GitGutterAddDefault guifg=#009900 guibg=NONE ctermfg=2 ctermbg=NONE + highlight GitGutterChangeDefault guifg=#bbbb00 guibg=NONE ctermfg=3 ctermbg=NONE + highlight GitGutterDeleteDefault guifg=#ff2222 guibg=NONE ctermfg=1 ctermbg=NONE + highlight default link GitGutterChangeDeleteDefault GitGutterChangeDefault - if g:gitgutter_highlights - hi default link GitGutterAdd GitGutterAddDefault - hi default link GitGutterChange GitGutterChangeDefault - hi default link GitGutterDelete GitGutterDeleteDefault - hi default link GitGutterChangeDelete GitGutterChangeDeleteDefault - endif + highlight default link GitGutterAdd GitGutterAddDefault + highlight default link GitGutterChange GitGutterChangeDefault + highlight default link GitGutterDelete GitGutterDeleteDefault + highlight default link GitGutterChangeDelete GitGutterChangeDeleteDefault - " line highlight defaults, meant to be user-edited - hi default link GitGutterAddLine DiffAdd - hi default link GitGutterChangeLine DiffChange - hi default link GitGutterDeleteLine DiffDelete - hi default link GitGutterChangeDeleteLine GitGutterChangeLineDefault - - call s:update_line_highlights(s:highlight_lines) + " Highlights used for the whole line. + highlight default link GitGutterAddLine DiffAdd + highlight default link GitGutterChangeLine DiffChange + highlight default link GitGutterDeleteLine DiffDelete + highlight default link GitGutterChangeDeleteLine GitGutterChangeLineDefault endfunction function! s:define_signs() - sign define GitGutterLineAdded text=+ texthl=GitGutterAdd linehl= - sign define GitGutterLineModified text=~ texthl=GitGutterChange linehl= - sign define GitGutterLineRemoved text=_ texthl=GitGutterDelete linehl= - sign define GitGutterLineModifiedRemoved text=~_ texthl=GitGutterChangeDelete linehl= + sign define GitGutterLineAdded + sign define GitGutterLineModified + sign define GitGutterLineRemoved + sign define GitGutterLineModifiedRemoved + + call s:define_sign_symbols() + call s:define_sign_text_highlights() + call s:define_sign_line_highlights() endfunction -function! s:update_line_highlights(highlight_lines) - let s:highlight_lines = a:highlight_lines +function! s:define_sign_symbols() + sign define GitGutterLineAdded text=+ + sign define GitGutterLineModified text=~ + sign define GitGutterLineRemoved text=_ + sign define GitGutterLineModifiedRemoved text=~_ +endfunction + +function! s:define_sign_text_highlights() + sign define GitGutterLineAdded texthl=GitGutterAdd + sign define GitGutterLineModified texthl=GitGutterChange + sign define GitGutterLineRemoved texthl=GitGutterDelete + sign define GitGutterLineModifiedRemoved texthl=GitGutterChangeDelete +endfunction + + +function! s:define_sign_line_highlights() if s:highlight_lines sign define GitGutterLineAdded linehl=GitGutterAddLine sign define GitGutterLineModified linehl=GitGutterChangeLine @@ -380,17 +390,20 @@ endfunction command GitGutterToggle call GitGutterToggle() function! GitGutterLineHighlightsDisable() - call s:update_line_highlights(0) + let s:highlight_lines = 0 + call s:define_sign_line_highlights() endfunction command GitGutterLineHighlightsDisable call GitGutterLineHighlightsDisable() function! GitGutterLineHighlightsEnable() - call s:update_line_highlights(1) + let s:highlight_lines = 1 + call s:define_sign_line_highlights() endfunction command GitGutterLineHighlightsEnable call GitGutterLineHighlightsEnable() function! GitGutterLineHighlightsToggle() - call s:update_line_highlights(s:highlight_lines ? 0 : 1) + let s:highlight_lines = (s:highlight_lines ? 0 : 1) + call s:define_sign_line_highlights() endfunction command GitGutterLineHighlightsToggle call GitGutterLineHighlightsToggle()