From 95aea6b533e71e478d61d18fac71cca116c56a4d Mon Sep 17 00:00:00 2001 From: Michael Smith Date: Sun, 22 May 2022 22:47:23 +0100 Subject: Add all the plugins I currently use --- start/signify/doc/signify.txt | 689 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 689 insertions(+) create mode 100644 start/signify/doc/signify.txt (limited to 'start/signify/doc') diff --git a/start/signify/doc/signify.txt b/start/signify/doc/signify.txt new file mode 100644 index 0000000..4d4e07d --- /dev/null +++ b/start/signify/doc/signify.txt @@ -0,0 +1,689 @@ +*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 ` + - 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: + +------------------------------------------------------------------------------ + *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 gj (signify-next-hunk) + nmap gk (signify-prev-hunk) + nmap gJ 9999gj + nmap gK 9999gk +< +------------------------------------------------------------------------------ +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: |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 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: et tw=78 -- cgit v1.2.3