vim-signify/doc/signify.txt

*signify.txt* Indicate changed lines within a file using a VCS.
*signify*
>
                                              ___
                    __                  __  /'___\
               ____/\_\     __     ___ /\_\/\ \__/  __  __
              /',__\/\ \  /'_ `\ /' _ `\/\ \ \ ,__\/\ \/\ \
             /\__, `\ \ \/\ \L\ \/\ \/\ \ \ \ \ \_/\ \ \_\ \
             \/\____/\ \_\ \____ \ \_\ \_\ \_\ \_\  \/`____ \
              \/___/  \/_/\/___L\ \/_/\/_/\/_/\/_/   `/___/> \
                            /\____/                     /\___/
                            \_/__/                      \/__/
<
  by Marco Hinz~

==============================================================================
TOC                                                           *signify-contents*

  INTRO .......................... |signify-intro|
  MODUS OPERANDI ................. |signify-modus-operandi|
  DEBUG .......................... |signify-debug|
  SIGNS .......................... |signify-signs|
  OPTIONS ........................ |signify-options|
  COMMANDS ....................... |signify-commands|
  AUTOCOMMAND .................... |signify-autocommand|
  MAPPINGS ....................... |signify-mappings|
  COLORS ......................... |signify-colors|
  FAQ ............................ |signify-faq|
  EXAMPLE ........................ |signify-example|

==============================================================================
INTRO                                                            *signify-intro*

Signify uses the sign column to indicate added, modified and removed lines
based on the data of an underlying version control system.

Supported VCS:~
>
    git
    mercurial
    darcs
    bzr
    subversion
    cvs
    rcs
    fossil
    accurev
    perforce
    tfs
<
==============================================================================
MODUS OPERANDI                                          *signify-modus-operandi*

When you open a new buffer, Sy registers it as `active` and tries to figure out
whether the underlying file is controlled by a VCS (version control system) or
not.

For that, it asynchronously tries all the `diff` subcommands of all the VCS
tools that are supported and executable. It's recommended to set
|g:signify_vcs_list| to limit the VCS to test for.

If one of the checks produces a proper diff, that VCS will automatically be
used for all successive calls to Sy.

If none of the checks produces a proper diff, the VCS will be set to `unknown`.
The next time Sy gets run, the buffer will be marked as `inactive`, so it won't
look for changes anymore.

Or you set |g:signify_disable_by_default|, which registers all new buffers as
`inactive`, and enable Sy on demand using |signify-:SignifyToggle|.

By default, Sy is rather conservative and only updates signs when opening a
new buffer or writing it. If you want more agressive sign updating, have a
look at |g:signify_realtime|.

Use |signify-:SignifyList| to list all buffers managed by Sy and their current
state.

==============================================================================
DEBUG                                                            *signify-debug*

If signs aren't showing up as expected, see if |signify-:SignifyDebug| shows
anything suspicious. It will try all VCS and shows either errors or a diff for
each VCS.

If the output looks fine though, create an issue on Github:

    https://github.com/mhinz/vim-signify/issues/new

Make sure to mention your Vim version and which Sy version you use (latest
release or master).

Additionally, include the output of |:messages| after executing one of the
following:

    - opening the buffer via `vim -V1 <file>`
    - or running `:verb w` in the buffer

==============================================================================
SIGNS                                                            *signify-signs*

    `+`     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.

See |g:signify_sign_add| on how to use different signs.

==============================================================================
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.

Most important options:~

    |g:signify_vcs_list|
    |g:signify_realtime|

Other options:~

    |g:signify_vcs_cmds|
    |g:signify_vcs_cmds_diffmode|
    |g:signify_disable_by_default|
    |g:signify_skip_filetype|
    |g:signify_skip_filename|
    |g:signify_skip_filename_pattern|
    |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_sign_show_text|
    |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'
                 'tfs'

NOTE: This is the most important option, so read closely.

This option determines what VCS to check for.

This can improve buffer loading time, since by default all supported and
installed VCS will be checked for. This only happens once, when signs get set
the first time. Afterwards, the VCS will either be remembered or registered as
inactive when no VCS was found.

If your Vim is recent enough, these checks will happen asynchronously.

NOTE: If you don't set this option, updating signs for a non-VCS file can lead
to a significant delay since all supported and installed VCS will be tested
for. (But this also happens only once, afterwards the buffer is registered as
inactive.)

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.

------------------------------------------------------------------------------
                                                            *g:signify_realtime*  >
    let g:signify_realtime = 0
<
By default, the plugin is quite conservative and only updates on:

    |BufRead|       Opening a buffer.
    |BufWritePost|  Saving a buffer.

When this option is set, you get more aggressive sign updates:

    |BufEnter|      Opening or switching to another buffer.
    |WinEnter|      Opening or switching to another window.
    |BufWritePost|  Saving a buffer.
    |FocusGained|   When the window containing Vim gains focus.
                  Disable with |g:signify_update_on_focusgained|.
    |CursorHold|    After 'updatetime' milliseconds without moving the cursor
                  in normal mode. Disable with |g:signify_cursorhold_normal|.
                  This also saves the buffer!~
    |CursorHoldI|   After 'updatetime' milliseconds without moving the cursor
                  in insert mode. Disable with |g:signify_cursorhold_insert|.
                  This also saves the buffer!~

You can check the autocmds yourself: `:au signify`

NOTE: Running Sy on all these events would block too often for older Vim
versions, thus this option requires Vim 7.4.1967+, which is the minimum
version needed for asynchronous execution. Older Vim versions silently ignore
this option.

------------------------------------------------------------------------------
                                                            *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`

Redirection: Instead of `>foo` use `sy#util#shell_redirect('foo')`. This
helper function takes 'shellredir' into account.

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.

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'
      \ }
<
NOTE: Always test these commands on the shell first and make sure that no
colors are emitted. Our parser expects lines in the diff output to start with
"@@", but with colors the line starts with escape sequences instead.

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 diff --unified -c 0 -- %f',
      \ 'cvs':      'cvs diff -U0 -- %f',
      \ 'rcs':      'rcsdiff -U0 %f 2>%n',
      \ 'accurev':  'accurev diff %f -- -U0',
      \ 'perforce': 'p4 info '. sy#util#shell_redirect('%n') . (has('win32') ? '' : ' env P4DIFF= P4COLORS=') .' p4 diff -du0 %f',
      \ 'tfs':      'tf diff -version:W -noprompt %f',
      \ }
<
------------------------------------------------------------------------------
                                                   *g:signify_vcs_cmds_diffmode*  >
    let g:signify_vcs_cmds_diffmode = {
      \ 'git':      'git show HEAD:./%f',
      \ 'hg':       'hg cat %f',
      \ 'svn':      'svn cat %f',
      \ 'bzr':      'bzr cat %f',
      \ 'darcs':    'darcs show contents -- %f',
      \ 'cvs':      'cvs up -p -- %f 2>%n',
      \ 'perforce': 'p4 print %f',
      \ }
<
The command to use for |:SignifyDiff|. This option takes the same format as
|g:signify_vcs_cmds|.

------------------------------------------------------------------------------
                                                  *g:signify_disable_by_default*  >
    let g:signify_disable_by_default = 0
<
This makes Sy not looking for changes for each new buffer. You can easily
enable it later using |signify-:SignifyToggle|.

------------------------------------------------------------------------------
                                               *g:signify_skip_filename_pattern*
                                                       *g:signify_skip_filename*
                                                       *g:signify_skip_filetype*
>
    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. Filenames have
to be absolute paths.

These options must be |Dict|s for faster lookup.
>
    let g:signify_skip_filename_pattern = [ 'foo.*bar', 'tmp' ]
<
Don't activate the plugin for filenames matching these patterns.

Default: <none>

------------------------------------------------------------------------------
                                                  *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 the signs on |FocusGained|, thus when the window holding Vim gains focus.
It does so by executing |signify-:SignifyRefresh|.

NOTE: The |FocusGained| event is fired for all GUIs and even a few terminal
emulators. If you use tmux, put `set-option -g focus-events on` in your
tmux.conf.

------------------------------------------------------------------------------
                                                      *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.

You can use unicode characters, but signs must not take up more than two
cells. Otherwise |E239| is thrown.

If |g:signify_sign_show_count| is set, |g:signify_sign_delete| and
|g:signify_sign_changedelete| get truncated as needed.

------------------------------------------------------------------------------
                                                     *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_sign_show_text*  >
    let g:signify_sign_show_text = 1
<
Don't show any text in the sign column. (Actually it will show a non-breaking
space.)

This is useful if you only want to see colors instead. If your colorscheme
doesn't do it for you, you can set the background color of a particular sign
yourself: |signify-colors|.

If you want no sign column at all and use Vim 7.4.2201+, use 'signcolumn'.

------------------------------------------------------------------------------
                                                   *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-:SignifyEnable*  >
    :SignifyEnable
<
Enable the plugin for the current buffer only.

Can also be used to when a repository was initialized while Sy was already
loaded.

------------------------------------------------------------------------------
                                                       *signify-:SignifyDisable*  >
    :SignifyDisable
<
Disable the plugin for the current buffer only.

------------------------------------------------------------------------------
                                                        *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.

NOTE: Nothing will happen, if :SignifyRefresh is used from the |cmdline-window|.

------------------------------------------------------------------------------
                                                          *signify-:SignifyDiff*  >
    :SignifyDiff[!]
<
Open a new tab with two windows using |diff-mode| to show the differences
between the current file and its version that was last checked in.

With [!], no new tab will be opened.

Also see |g:signify_vcs_cmds_diffmode|.

------------------------------------------------------------------------------
                                                          *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.

If [!] is given, Sy will do the same without opening an extra tabpage. Another
":SignifyFold!" will toggle back to the previous settings.

See |folds| to learn more about folding.

------------------------------------------------------------------------------
                                                          *signify-:SignifyList*  >
    :SignifyList
<
Outputs debug info for all managed buffers.

------------------------------------------------------------------------------
                                                         *signify-:SignifyDebug*  >
    :SignifyDebug
<
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 their output. Errors will be highlighted
via |hl-ErrorMsg|.

==============================================================================
AUTOCOMMAND                                                *signify-autocommand*

User SignifySetup~

  This event fires at the end of `plugin/signify.vim`, in case you want to
  change any of the default autocmds, commands, or mappings.

User Signify~

  This event fires when Sy updated the signs.

NOTE: Autocmds don't nest by default. If you use any command that triggers new
events, make sure to use |autocmd-nested|.

==============================================================================
MAPPINGS                                                      *signify-mappings*

------------------------------------------------------------------------------
Hunk jumping:~

    ]c   Jump to next hunk.
    [c   Jump to previous hunk.

    ]C   Jump to last hunk.
    [C   Jump to first hunk.

These keys only get mapped by default when:

  - The keys are not mapped already (by you or another plugin).
  - There are no other keys that are mapped to do the same (to avoid duplicate
    mappings).

Mapping other keys:
>
    nmap <leader>gj <plug>(signify-next-hunk)
    nmap <leader>gk <plug>(signify-prev-hunk)
    nmap <leader>gJ 9999<leader>gj
    nmap <leader>gK 9999<leader>gk
<
------------------------------------------------------------------------------
Hunk text object:~
>
    omap ic <plug>(signify-motion-inner-pending)
    xmap ic <plug>(signify-motion-inner-visual)
    omap ac <plug>(signify-motion-outer-pending)
    xmap ac <plug>(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: |hl-DiffAdd|, |hl-DiffChange|, |hl-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 overwrite these
highlighting groups in your vimrc.

Assuming you prefer |hl-DiffText| over |hl-DiffChange| for changed lines:
>
    highlight link SignifyLineChange DiffText
<
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.

Default highlight groups:~

The sign column (often mistakenly called "gutter") itself (all lines without
signs) is highlighted by |hl-SignColumn|. Some colorschemes define no background
color for |hl-Normal| but for |hl-SignColumn|. To avoid that visible difference:
>
    highlight SignColumn ctermbg=NONE cterm=NONE guibg=NONE gui=NONE
<
==============================================================================
FAQ                                                                *signify-faq*

    |signify-faq-01|  What about vim-flagship support?
    |signify-faq-02|  The plugin is slow!
    |signify-faq-03|  Line highlighting without showing signs?

------------------------------------------------------------------------------
                                                                *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'))
<
------------------------------------------------------------------------------
                                                                *signify-faq-02*
The plugin is slow!~

  * Set |g:signify_vcs_list|. Always.

  * Sy relies on external tools. Check if these are the bottleneck.

    If you use a centralized VCS like Subversion, is the connection to the
    server slow?

    If you use a decentralized VCS like Git, are you working on a slow remote
    file system?

  * Vim its sign handling code is known to be slow. If the delay is very long,
    chances are the diff is just huge. This often happens after adding (or
    removing) a huge file to the repo.

------------------------------------------------------------------------------
                                                                *signify-faq-03*
Line highlighting without showing signs?~

The line highlighting relies on signs being placed. The sign column is being
shown automatically if there are placed signs.

With a recent Vim, you can change that behaviour using 'signcolumn'.

==============================================================================
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 <leader>gt :SignifyToggle<CR>
    nnoremap <leader>gh :SignifyToggleHighlight<CR>
    nnoremap <leader>gr :SignifyRefresh<CR>
    nnoremap <leader>gd :SignifyDebug<CR>

    " hunk jumping
    nmap <leader>gj <plug>(signify-next-hunk)
    nmap <leader>gk <plug>(signify-prev-hunk)

    " hunk text object
    omap ic <plug>(signify-motion-inner-pending)
    xmap ic <plug>(signify-motion-inner-visual)
    omap ac <plug>(signify-motion-outer-pending)
    xmap ac <plug>(signify-motion-outer-visual)
<
==============================================================================
vim: et tw=78