*signify.txt* Indicate changed lines within a file using a VCS. *signify* ___ __ __ /'___\ ____/\_\ __ ___ /\_\/\ \__/ __ __ /',__\/\ \ /'_ `\ /' _ `\/\ \ \ ,__\/\ \/\ \ /\__, `\ \ \/\ \L\ \/\ \/\ \ \ \ \ \_/\ \ \_\ \ \/\____/\ \_\ \____ \ \_\ \_\ \_\ \_\ \/`____ \ \/___/ \/_/\/___L\ \/_/\/_/\/_/\/_/ `/___/> \ /\____/ /\___/ \_/__/ \/__/ by Marco Hinz~ Twitter: https://twitter.com/_mhinz_ Github: http://github.com/mhinz IRC: mhi^ (Freenode) > If you use any of my plugins, please star them on github. It's a great way of getting feedback and gives me the kick to put more time into their development. If you encounter any bugs or have feature requests, just open an issue report on Github. Thank you for flying mhi^ airlines. Get the Vim on! < ============================================================================== TOC *signify-contents* INTRO .......................... |signify-intro| USAGE .......................... |signify-usage| OPTIONS ........................ |signify-options| COMMANDS ....................... |signify-commands| MAPPINGS ....................... |signify-mappings| COLORS ......................... |signify-colors| FAQ ............................ |signify-faq| EXAMPLE ........................ |signify-example| ============================================================================== INTRO *signify-intro* Signify (or just Sy) is a quite unobtrusive plugin. It uses signs to indicate added, modified and removed lines based on data of an underlying version control system. ============================================================================== USAGE *signify-usage* The usage is pretty straight-forward. By default you should only notice a difference, if you're working in a directory that is managed by a supported version control system and the current file was changed since the last commit. Supported VCS:~ > git mercurial darcs bzr subversion cvs rcs fossil accurev perforce < Sign explanation:~ `+` This line was added. `!` This line was modified. `_1` The number of deleted lines below this sign. If the number is larger `99` than 9, the `_` will be omitted. For numbers larger than 99, `_>` `_>` will be shown instead. `!1` This line was modified and a number of lines below were deleted. `!>` It is a combination of `!` and `_`. If the number is larger than 9, `!>` will be shown instead. `‾` The first line was removed. It's a special case of the `_` sign. ============================================================================== OPTIONS *signify-options* Put these variables into your vimrc. The provided examples also indicate the default values, as long as no "Default:" section is given. All available options:~ |g:signify_vcs_list| |g:signify_vcs_cmds| |g:signify_disable_by_default| |g:signify_skip_filetype| |g:signify_skip_filename| |g:signify_update_on_bufenter| |g:signify_update_on_focusgained| |g:signify_line_highlight| |g:signify_sign_add| |g:signify_sign_delete| |g:signify_sign_delete_first_line| |g:signify_sign_change| |g:signify_sign_changedelete| |g:signify_sign_show_count| |g:signify_cursorhold_normal| |g:signify_cursorhold_insert| |g:signify_difftool| |g:signify_fold_context| ------------------------------------------------------------------------------ *g:signify_vcs_list* > let g:signify_vcs_list = [ 'git', 'hg' ] < Default: empty Possible values: 'accurev' 'bzr' 'cvs' 'darcs' 'fossil' 'git' 'hg' 'perforce' 'rcs' 'svn' NOTE: This is the most important option, so read closely. It determines the VCS to check for and in what order. If you only use git and mercurial, you can shorten the list to the shown example. If you use mostly mercurial and only sometimes git, put 'hg' in the front of the list. It's basically a priority list. This can improve buffer loading time since by default all supported and installed VCS will be checked for, so you are advised to change this option to your needs. (This only happens once at the first time the signs get updated. Afterwards, the VCS will be remembered anyway.) NOTE: Some VCS rely on a an external diff tool to work properly (svn, darcs, bzr, fossil), thus you have to make sure that Vim can find a valid diff tool. So either the one you set through |g:signify_difftool| or "diff" by default. NOTE: If you don't set this option and Sy is activated, updating signs for a non-VCS file can lead to significant delay since all supported and installed VCS will be tested for. ------------------------------------------------------------------------------ *g:signify_vcs_cmds* > let g:signify_vcs_cmds = { \ 'cvs': 'cvs -d '. $CVSROOT .' diff -U0 -- %f' } < This is a |dict|. They key is any version control system from |g:signify_vcs_list| and the value is the corresponding command line. Modifiers:~ %f actual filepath %d |g:signify_difftool| %n Unix: "/dev/null", Windows: "NUL" NOTE: The output format mustn't change, otherwise Sy won't give any reasonable results. It's probably wise to start with the respective default values. NOTE: If your VCS program is not in $PATH and you have to specify an absolute path, escape spaces by quoting, e.g.: > let g:signify_vcs_cmds = { \ 'git': '"C:\Program Files (x86)\Git\bin\git.exe" diff --no-color --no-ext-diff -U0 -- %f' \ } < Default: > let g:signify_vcs_cmds = { \ 'git': 'git diff --no-color --no-ext-diff -U0 -- %f', \ 'hg': 'hg diff --config extensions.color=! --config defaults.diff= --nodates -U0 -- %f', \ 'svn': 'svn diff --diff-cmd %d -x -U0 -- %f', \ 'bzr': 'bzr diff --using %d --diff-options=-U0 -- %f', \ 'darcs': 'darcs diff --no-pause-for-gui --diff-command="%d -U0 %1 %2" -- %f', \ 'fossil': 'fossil set diff-command "%d -U 0" && fossil diff --unified -c 0 -- %f', \ 'cvs': 'cvs diff -U0 -- %f', \ 'rcs': 'rcsdiff -U0 %f 2>%n', \ 'accurev': 'accurev diff %f -- -U0', \ 'perforce': 'p4 info >%n 2>&1 && env P4DIFF=%d p4 diff -dU0 %f', \ } < ------------------------------------------------------------------------------ *g:signify_disable_by_default* > let g:signify_disable_by_default = 0 < This loads Sy, but it won't look for changes. You can toggle it anytime via :SignifyToggle. ------------------------------------------------------------------------------ *g:signify_skip_filetype* *g:signify_skip_filename* > let g:signify_skip_filetype = { 'vim': 1, 'c': 1 } let g:signify_skip_filename = { '/home/user/.vimrc': 1 } < Don't activate the plugin for these filetypes and/or filenames. NOTE: Filenames have to be absolute paths. Default: Both are empty. ------------------------------------------------------------------------------ *g:signify_update_on_bufenter* > let g:signify_update_on_bufenter = 0 < Update signs when entering a buffer that was modified. NOTE: This also saves the buffer to disk! ------------------------------------------------------------------------------ *g:signify_update_on_focusgained* > let g:signify_update_on_focusgained = 0 < Update signs when Vim gains focus. ------------------------------------------------------------------------------ *g:signify_line_highlight* > let g:signify_line_highlight = 0 < Enable line highlighting in addition to using signs by default. ------------------------------------------------------------------------------ *g:signify_sign_add* *g:signify_sign_delete* *g:signify_sign_delete_first_line* *g:signify_sign_change* *g:signify_sign_changedelete* > let g:signify_sign_add = '+' let g:signify_sign_delete = '_' let g:signify_sign_delete_first_line = '‾' let g:signify_sign_change = '!' let g:signify_sign_changedelete = g:signify_sign_change < The sign to use if a line was added, deleted or changed or a combination of these. NOTE: You can use unicode characters. NOTE: You can use up to 2 characters for the signs with two exceptions that happen in combination with |g:signify_sign_show_count| set: 1) |g:signify_sign_delete| uses only 1 character and truncates while the count increases. 2) |g:signify_sign_changedelete| uses only 1 character and truncates if necessary. ------------------------------------------------------------------------------ *g:signify_sign_show_count* > let g:signify_sign_show_count = 1 < Add the number of deleted lines to |g:signify_sign_delete| (up to 99) and |g:signify_sign_changedelete| (up to 9). Otherwise only the normal signs will be shown. ------------------------------------------------------------------------------ *g:signify_cursorhold_normal* *g:signify_cursorhold_insert* > let g:signify_cursorhold_normal = 0 let g:signify_cursorhold_insert = 0 < Additionally trigger sign updates in normal or insert mode after 'updatetime' miliseconds without any keypresses. This fires only once between keypresses, thus not every 'updatetime' miliseconds. NOTE: This also saves the buffer to disk! ------------------------------------------------------------------------------ *g:signify_difftool* > let g:signify_difftool = 'gnudiff' < This will avoid the attempt to find the proper diff tool for version control systems that rely on an external diff tool that supports the -U0 flag. These are: svn, bzr, darcs, fossil. Default: "diff" ------------------------------------------------------------------------------ *g:signify_fold_context* > let g:signify_fold_context = [0, 3] < This changes the number of lines of context that |signify-:SignifyFold| should use. The first element describes the context at foldlevel 0 and the second the context at foldlevel 1. Example:~ Using "[0,3]" means that after using :SignifyFold, only changed lines will be unfolded. Using |zo| (and similar |fold-commands|) on a folded line will reveal 3 more lines of context. Using |zo| a second time will reveal everything. Default: [3, 8] ============================================================================== COMMAND *signify-commands* *signify-:SignifyToggle* > :SignifyToggle < Toggle the plugin for the current buffer only. ------------------------------------------------------------------------------ *signify-:SignifyToggleHighlight* > :SignifyToggleHighlight < Toggle line highlighting for lines containing changes. ------------------------------------------------------------------------------ *signify-:SignifyRefresh* > :SignifyRefresh < Refresh signs in all windows. ------------------------------------------------------------------------------ *signify-:SignifyFold* > :SignifyFold < Open the current buffer in a new tabpage and set |'foldexpr'| so that only changed lines with their surrounding context are unfolded. The number of lines per context can be changed via |g:signify_fold_context|. The |foldtext| will be set so that the left side shows the first line in the fold and the right side shows something like "50 [1]" which whereas "50" stands for the number of folded lines and the "1" is the foldlevel. See |folds| to learn more about folding. ------------------------------------------------------------------------------ *signify-:SignifyDebug* > :SignifyDebug < Outputs debug info for all managed buffers. ------------------------------------------------------------------------------ *signify-:SignifyDebugDiff* > :SignifyDebugDiff < Print the diff command for the current buffer and its output. ------------------------------------------------------------------------------ *signify-:SignifyDebugUnknown* > :SignifyDebugUnknown < In case no signs are shown, although the buffer contains a file controlled by a supported VCS, use this command. It will show all tried commands and its output. Errors will be highlighted via |hl-ErrorMsg|. ============================================================================== MAPPINGS *signify-mappings* There are no default mappings, except for ]c / [c, but there are additional plug mappings available that you can put into your vimrc. ------------------------------------------------------------------------------ Hunk jumping:~ > nmap gj (signify-next-hunk) nmap gk (signify-prev-hunk) < NOTE: Analog to Vim's diff mode, you can also use |]c| and |[c| for jumping between hunks. ------------------------------------------------------------------------------ Hunk text object:~ > omap ic (signify-motion-inner-pending) xmap ic (signify-motion-inner-visual) omap ac (signify-motion-outer-pending) xmap ac (signify-motion-outer-visual) < "ic" operates on all lines of the current hunk. "ac" does the same, but also removes all trailing empty lines. NOTE: Don't be surprised that this also works with "deleted lines". ============================================================================== COLORS *signify-colors* This plugin defines highlighting groups for two different places: for lines and signs. Per default these don't really exist but are linked to the standard highlighting groups: DiffAdd, DiffChange, DiffDelete: > highlight link SignifyLineAdd DiffAdd highlight link SignifyLineChange DiffChange highlight link SignifyLineDelete DiffDelete highlight link SignifyLineChangeDelete SignifyLineChange highlight link SignifyLineDeleteFirstLine SignifyLineDelete highlight link SignifySignAdd DiffAdd highlight link SignifySignChange DiffChange highlight link SignifySignDelete DiffDelete highlight link SignifySignChangeDelete SignifySignChange highlight link SignifySignDeleteFirstLine SignifySignDelete < Thus if you do not want to change the standard highlighting groups, but want different colors for either your signs or lines, you can define one of these 6 Signify groups yourself in your vimrc. Personally I use (256 colors terminal): > " highlight lines in Sy and vimdiff etc.) highlight DiffAdd cterm=bold ctermbg=none ctermfg=119 highlight DiffDelete cterm=bold ctermbg=none ctermfg=167 highlight DiffChange cterm=bold ctermbg=none ctermfg=227 " highlight signs in Sy highlight SignifySignAdd cterm=bold ctermbg=237 ctermfg=119 highlight SignifySignDelete cterm=bold ctermbg=237 ctermfg=167 highlight SignifySignChange cterm=bold ctermbg=237 ctermfg=227 < For Unix people there is a small script, showcolors.bash, in the repo that shows all 256 colors available to the terminal. That makes picking the right numbers much easier. ============================================================================== FAQ *signify-faq* |signify-faq-01| What about vim-flagship support? ------------------------------------------------------------------------------ *signify-faq-01* What about vim-flagship support?~ sy#repo#get_stats() returns a list with 3 integers for added, modified and removed lines. Create a wrapper function around it and return a string: > function! s:sy_stats_wrapper() let symbols = ['+', '-', '~'] let [added, modified, removed] = sy#repo#get_stats() let stats = [added, removed, modified] " reorder let hunkline = '' for i in range(3) if stats[i] > 0 let hunkline .= printf('%s%s ', symbols[i], stats[i]) endif endfor if !empty(hunkline) let hunkline = printf('[%s]', hunkline[:-2]) endif return hunkline endfunction autocmd User Flags call Hoist('buffer', function('s:sy_stats_wrapper')) < ============================================================================== EXAMPLE *signify-example* An example configuration for Sy: > let g:signify_vcs_list = [ 'git', 'hg' ] let g:signify_cursorhold_insert = 1 let g:signify_cursorhold_normal = 1 let g:signify_update_on_bufenter = 0 let g:signify_update_on_focusgained = 1 nnoremap gt SignifyToggle nnoremap gh SignifyToggleHighlight nnoremap gr SignifyRefresh nnoremap gd SignifyDebug " hunk jumping nmap gj (signify-next-hunk) nmap gk (signify-prev-hunk) " hunk text object omap ic (signify-motion-inner-pending) xmap ic (signify-motion-inner-visual) omap ac (signify-motion-outer-pending) xmap ac (signify-motion-outer-visual) < ============================================================================== vim: tw=78