various improvements
[distro-setup] / .vim / doc / vcscommand.txt
1 *vcscommand.txt* vcscommand
2 Copyright (c) Bob Hiestand
3
4 Permission is hereby granted, free of charge, to any person obtaining a copy
5 of this software and associated documentation files (the "Software"), to
6 deal in the Software without restriction, including without limitation the
7 rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8 sell copies of the Software, and to permit persons to whom the Software is
9 furnished to do so, subject to the following conditions:
10
11 The above copyright notice and this permission notice shall be included in
12 all copies or substantial portions of the Software.
13
14 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20 IN THE SOFTWARE.
21
22 For instructions on installing this file, type
23 :help add-local-help
24 inside Vim.
25
26 Author: Bob Hiestand <bob.hiestand@gmail.com>
27 Credits: Benji Fisher's excellent MatchIt documentation
28
29 ==============================================================================
30 1. Contents *vcscommand-contents*
31
32 Installation : |vcscommand-install|
33 vcscommand Intro : |vcscommand|
34 vcscommand Manual : |vcscommand-manual|
35 Customization : |vcscommand-customize|
36 SSH "integration" : |vcscommand-ssh|
37 Changes from cvscommand : |cvscommand-changes|
38 Bugs : |vcscommand-bugs|
39
40 ==============================================================================
41
42 2. vcscommand Installation *vcscommand-install*
43
44 The vcscommand plugin comprises five files: vcscommand.vim, vcssvn.vim,
45 vcscvs.vim, vcssvk.vim and vcscommand.txt (this file). In order to install
46 the plugin, place the vcscommand.vim, vcssvn.vim, vcssvk.vim, and vcscvs.vim
47 files into a plugin directory in your runtime path (please see
48 |add-global-plugin| and |'runtimepath'|.
49
50 This help file can be included in the VIM help system by copying it into a
51 'doc' directory in your runtime path and then executing the |:helptags|
52 command, specifying the full path of the 'doc' directory. Please see
53 |add-local-help| for more details.
54
55 vcscommand may be customized by setting variables, creating maps, and
56 specifying event handlers. Please see |vcscommand-customize| for more
57 details.
58
59 ==============================================================================
60
61 3. vcscommand Intro *vcscommand*
62 *vcscommand-intro*
63
64 The vcscommand plugin provides global ex commands for manipulating
65 version-controlled source files, currently those controlled either by CVS or
66 Subversion. In general, each command operates on the current buffer and
67 accomplishes a separate source control function, such as update, commit, log,
68 and others (please see |vcscommand-commands| for a list of all available
69 commands). The results of each operation are displayed in a scratch buffer.
70 Several buffer variables are defined for those scratch buffers (please see
71 |vcscommand-buffer-variables|).
72
73 The notion of "current file" means either the current buffer, or, in the case
74 of a directory buffer (such as Explorer or netrw buffers), the directory (and
75 all subdirectories) represented by the the buffer.
76
77 For convenience, any vcscommand invoked on a vcscommand scratch buffer acts as
78 though it was invoked on the original file and splits the screen so that the
79 output appears in a new window.
80
81 Many of the commands accept revisions as arguments. By default, most operate
82 on the most recent revision on the current branch if no revision is specified.
83
84 Each vcscommand is mapped to a key sequence starting with the |<Leader>|
85 keystroke. The default mappings may be overridden by supplying different
86 mappings before the plugin is loaded, such as in the vimrc, in the standard
87 fashion for plugin mappings. For examples, please see
88 |vcscommand-mappings-override|.
89
90 The vcscommand plugin may be configured in several ways. For more details,
91 please see |vcscommand-customize|.
92
93 ==============================================================================
94
95 4. vcscommand Manual *vcscommand-manual*
96
97 4.1 vcscommand commands *vcscommand-commands*
98
99 vcscommand defines the following commands:
100
101 |:VCSAdd|
102 |:VCSAnnotate|
103 |:VCSBlame|
104 |:VCSCommit|
105 |:VCSDelete|
106 |:VCSDiff|
107 |:VCSGotoOriginal|
108 |:VCSLog|
109 |:VCSRemove|
110 |:VCSRevert|
111 |:VCSReview|
112 |:VCSStatus|
113 |:VCSUpdate|
114 |:VCSVimDiff|
115
116 The following commands are specific to CVS files:
117
118 |:CVSEdit|
119 |:CVSEditors|
120 |:CVSUnedit|
121 |:CVSWatch|
122 |:CVSWatchAdd|
123 |:CVSWatchOn|
124 |:CVSWatchOff|
125 |:CVSWatchRemove|
126 |:CVSWatchers|
127
128 :VCSAdd *:VCSAdd*
129
130 This command adds the current file to source control. Please note, this does
131 not commit the newly-added file. All parameters to the command are passed to
132 the underlying VCS.
133
134 :VCSAnnotate[!] *:VCSAnnotate*
135
136 This command displays the current file with each line annotated with the
137 version in which it was most recently changed. If an argument is given, the
138 argument is used as a revision number to display. If not given an argument,
139 it uses the most recent version of the file (on the current branch, if under
140 CVS control). Additionally, if the current buffer is a VCSAnnotate buffer
141 already, the version number on the current line is used.
142
143 If '!' is used, the view of the annotated buffer is split so that the
144 annotation is in a separate window from the content, and each is highlighted
145 separately.
146
147 For CVS buffers, the 'VCSCommandCVSAnnotateParent' option, if set to non-zero,
148 will cause the above behavior to change. Instead of annotating the version on
149 the current line, the parent revision is used instead, crossing branches if
150 necessary.
151
152 With no arguments the cursor will jump to the line in the annotated buffer
153 corresponding to the current line in the source buffer.
154
155 :VCSBlame[!] *:VCSBlame*
156
157 Alias for |:VCSAnnotate|.
158
159 :VCSCommit[!] *:VCSCommit*
160
161 This command commits changes to the current file to source control.
162
163 If called with arguments, the arguments are the log message.
164
165 If '!' is used, an empty log message is committed.
166
167 If called with no arguments, this is a two-step command. The first step opens
168 a buffer to accept a log message. When that buffer is written, it is
169 automatically closed and the file is committed using the information from that
170 log message. The commit can be abandoned if the log message buffer is deleted
171 or wiped before being written.
172
173 Alternatively, the mapping that is used to invoke :VCSCommit (by default
174 |<Leader>|cc, please see |vcscommand-mappings|) can be used in the log message
175 buffer in Normal mode to immediately commit. This is useful if the
176 |VCSCommandCommitOnWrite| variable is set to 0 to disable the normal
177 commit-on-write behavior.
178
179 :VCSDelete *:VCSDelete*
180
181 Deletes the current file and removes it from source control. All parameters
182 to the command are passed to the underlying VCS.
183
184 :VCSDiff *:VCSDiff*
185
186 With no arguments, this displays the differences between the current file and
187 its parent version under source control in a new scratch buffer.
188
189 With one argument, the diff is performed on the current file against the
190 specified revision.
191
192 With two arguments, the diff is performed between the specified revisions of
193 the current file.
194
195 For CVS, this command uses the |VCSCommandCVSDiffOpt| variable to specify diff
196 options. If that variable does not exist, a plugin-specific default is used.
197 If you wish to have no options, then set it to the empty string.
198
199 For SVN, this command uses the |VCSCommandSVNDiffOpt| variable to specify diff
200 options. If that variable does not exist, the SVN default is used.
201 Additionally, |VCSCommandSVNDiffExt| can be used to select an external diff
202 application.
203
204 :VCSGotoOriginal *:VCSGotoOriginal*
205
206 This command jumps to the source buffer if the current buffer is a VCS scratch
207 buffer.
208
209 :VCSGotoOriginal!
210
211 Like ":VCSGotoOriginal" but also executes :bufwipeout on all VCS scrach
212 buffers associated with the original file.
213
214 :VCSInfo *:VCSInfo*
215
216 This command displays extended information about the current file in a new
217 scratch buffer.
218
219 :VCSLock *:VCSLock*
220
221 This command locks the current file in order to prevent other users from
222 concurrently modifying it. The exact semantics of this command depend on the
223 underlying VCS. This does nothing in CVS. All parameters are passed to the
224 underlying VCS.
225
226 :VCSLog *:VCSLog*
227
228 Displays the version history of the current file in a new scratch buffer. If
229 there is one parameter supplied, it is taken as as a revision parameters to be
230 passed through to the underlying VCS. Otherwise, all parameters are passed to
231 the underlying VCS.
232
233 :VCSRemove *:VCSRemove*
234
235 Alias for |:VCSDelete|.
236
237 :VCSRevert *:VCSRevert*
238
239 This command replaces the current file with the most recent version from the
240 repository in order to wipe out any undesired changes.
241
242 :VCSReview *:VCSReview*
243
244 Displays a particular version of the current file in a new scratch buffer. If
245 no argument is given, the most recent version of the file on the current
246 branch is retrieved.
247
248 :VCSStatus *:VCSStatus*
249
250 Displays versioning information about the current file in a new scratch
251 buffer. All parameters are passed to the underlying VCS.
252
253
254 :VCSUnlock *:VCSUnlock*
255
256 Unlocks the current file in order to allow other users from concurrently
257 modifying it. The exact semantics of this command depend on the underlying
258 VCS. All parameters are passed to the underlying VCS.
259
260 :VCSUpdate *:VCSUpdate*
261
262 Updates the current file with any relevant changes from the repository. This
263 intentionally does not automatically reload the current buffer, though vim
264 should prompt the user to do so if the underlying file is altered by this
265 command.
266
267 :VCSVimDiff *:VCSVimDiff*
268
269 Uses vimdiff to display differences between versions of the current file.
270
271 If no revision is specified, the most recent version of the file on the
272 current branch is used. With one argument, that argument is used as the
273 revision as above. With two arguments, the differences between the two
274 revisions is displayed using vimdiff.
275
276 With either zero or one argument, the original buffer is used to perform the
277 vimdiff. When the scratch buffer is closed, the original buffer will be
278 returned to normal mode.
279
280 Once vimdiff mode is started using the above methods, additional vimdiff
281 buffers may be added by passing a single version argument to the command.
282 There may be up to 4 vimdiff buffers total.
283
284 Using the 2-argument form of the command resets the vimdiff to only those 2
285 versions. Additionally, invoking the command on a different file will close
286 the previous vimdiff buffers.
287
288 :CVSEdit *:CVSEdit*
289
290 This command performs "cvs edit" on the current file. Yes, the output buffer
291 in this case is almost completely useless.
292
293 :CVSEditors *:CVSEditors*
294
295 This command performs "cvs edit" on the current file.
296
297 :CVSUnedit *:CVSUnedit*
298
299 Performs "cvs unedit" on the current file. Again, yes, the output buffer here
300 is basically useless.
301
302 :CVSWatch *:CVSWatch*
303
304 This command takes an argument which must be one of [on|off|add|remove]. The
305 command performs "cvs watch" with the given argument on the current file.
306
307 :CVSWatchAdd *:CVSWatchAdd*
308
309 This command is an alias for ":CVSWatch add"
310
311 :CVSWatchOn *:CVSWatchOn*
312
313 This command is an alias for ":CVSWatch on"
314
315 :CVSWatchOff *:CVSWatchOff*
316
317 This command is an alias for ":CVSWatch off"
318
319 :CVSWatchRemove *:CVSWatchRemove*
320
321 This command is an alias for ":CVSWatch remove"
322
323 :CVSWatchers *:CVSWatchers*
324
325 This command performs "cvs watchers" on the current file.
326
327 4.2 Mappings *vcscommand-mappings*
328
329 By default, a mapping is defined for each command. These mappings execute the
330 default (no-argument) form of each command.
331
332 |<Leader>|ca VCSAdd
333 |<Leader>|cn VCSAnnotate
334 |<Leader>|cN VCSAnnotate!
335 |<Leader>|cc VCSCommit
336 |<Leader>|cD VCSDelete
337 |<Leader>|cd VCSDiff
338 |<Leader>|cg VCSGotoOriginal
339 |<Leader>|cG VCSGotoOriginal!
340 |<Leader>|ci VCSInfo
341 |<Leader>|cl VCSLog
342 |<Leader>|cL VCSLock
343 |<Leader>|cr VCSReview
344 |<Leader>|cs VCSStatus
345 |<Leader>|cu VCSUpdate
346 |<Leader>|cU VCSUnlock
347 |<Leader>|cv VCSVimDiff
348
349 Only for CVS buffers:
350
351 |<Leader>|ce CVSEdit
352 |<Leader>|cE CVSEditors
353 |<Leader>|ct CVSUnedit
354 |<Leader>|cwv CVSWatchers
355 |<Leader>|cwa CVSWatchAdd
356 |<Leader>|cwn CVSWatchOn
357 |<Leader>|cwf CVSWatchOff
358 |<Leader>|cwf CVSWatchRemove
359
360 *vcscommand-mappings-override*
361
362 The default mappings can be overridden by user-provided instead by mapping to
363 <Plug>CommandName. This is especially useful when these mappings collide with
364 other existing mappings (vim will warn of this during plugin initialization,
365 but will not clobber the existing mappings).
366
367 There are three methods for controlling mapping:
368
369 First, maps can be overriden for individual commands. For instance, to
370 override the default mapping for :VCSAdd to set it to '\add', add the
371 following to the vimrc:
372
373 nmap \add <Plug>VCSAdd
374
375 Second, the default map prefix ('<Leader>c') can be overridden by defining the
376 |VCSCommandMapPrefix| variable.
377
378 Third, the entire set of default maps can be overridden by defining the
379 |VCSCommandMappings| variable.
380
381
382 4.3 Automatic buffer variables *vcscommand-buffer-variables*
383
384 Several buffer variables are defined in each vcscommand result buffer. These
385 may be useful for additional customization in callbacks defined in the event
386 handlers (please see |vcscommand-events|).
387
388 The following variables are automatically defined:
389
390 b:VCSCommandOriginalBuffer *b:VCSCommandOriginalBuffer*
391
392 This variable is set to the buffer number of the source file.
393
394 b:VCSCommandCommand *b:VCSCommandCommand*
395
396 This variable is set to the name of the vcscommand that created the result
397 buffer.
398
399 b:VCSCommandSourceFile *b:VCSCommandSourceFile*
400
401 This variable is set to the name of the original file under source control.
402
403 b:VCSCommandVCSType *b:VCSCommandVCSType*
404
405 This variable is set to the type of the source control. This variable is also
406 set on the original file itself.
407 ==============================================================================
408
409 5. Configuration and customization *vcscommand-customize*
410 *vcscommand-config*
411
412 The vcscommand plugin can be configured in several ways: by setting
413 configuration variables (see |vcscommand-options|) or by defining vcscommand
414 event handlers (see |vcscommand-events|). Additionally, the vcscommand plugin
415 supports a customized status line (see |vcscommand-statusline| and
416 |vcscommand-buffer-management|).
417
418 5.1 vcscommand configuration variables *vcscommand-options*
419
420 Several variables affect the plugin's behavior. These variables are checked
421 at time of execution, and may be defined at the window, buffer, or global
422 level and are checked in that order of precedence.
423
424
425 The following variables are available:
426
427 |VCSCommandCommitOnWrite|
428 |VCSCommandCVSDiffOpt|
429 |VCSCommandCVSExec|
430 |VCSCommandDeleteOnHide|
431 |VCSCommandDiffSplit|
432 |VCSCommandDisableAll|
433 |VCSCommandDisableMappings|
434 |VCSCommandDisableExtensionMappings|
435 |VCSCommandDisableMenu|
436 |VCSCommandEdit|
437 |VCSCommandEnableBufferSetup|
438 |VCSCommandMappings|
439 |VCSCommandMapPrefix|
440 |VCSCommandMenuPriority|
441 |VCSCommandMenuRoot|
442 |VCSCommandResultBufferNameExtension|
443 |VCSCommandResultBufferNameFunction|
444 |VCSCommandSplit|
445 |VCSCommandSVKExec|
446 |VCSCommandSVNDiffExt|
447 |VCSCommandSVNDiffOpt|
448 |VCSCommandSVNExec|
449 |VCSCommandVCSTypeOverride|
450
451 VCSCommandCommitOnWrite *VCSCommandCommitOnWrite*
452
453 This variable, if set to a non-zero value, causes the pending commit
454 to take place immediately as soon as the log message buffer is written.
455 If set to zero, only the VCSCommit mapping will cause the pending commit to
456 occur. If not set, it defaults to 1.
457
458 VCSCommandCVSExec *VCSCommandCVSExec*
459
460 This variable controls the executable used for all CVS commands If not set,
461 it defaults to "cvs".
462
463 VCSCommandDeleteOnHide *VCSCommandDeleteOnHide*
464
465 This variable, if set to a non-zero value, causes the temporary result buffers
466 to automatically delete themselves when hidden.
467
468 VCSCommandCVSDiffOpt *VCSCommandCVSDiffOpt*
469
470 This variable, if set, determines the options passed to the diff command of
471 CVS. If not set, it defaults to 'u'.
472
473 VCSCommandDiffSplit *VCSCommandDiffSplit*
474
475 This variable overrides the |VCSCommandSplit| variable, but only for buffers
476 created with |:VCSVimDiff|.
477
478 VCSCommandDisableAll *VCSCommandDisableAll*
479
480 This variable, if set, prevents the plugin or any extensions from loading at
481 all. This is useful when a single runtime distribution is used on multiple
482 systems with varying versions.
483
484 VCSCommandDisableMappings *VCSCommandDisableMappings*
485
486 This variable, if set to a non-zero value, prevents the default command
487 mappings from being set. This supercedes
488 |VCSCommandDisableExtensionMappings|.
489
490 VCSCommandDisableExtensionMappings *VCSCommandDisableExtensionMappings*
491
492 This variable, if set to a non-zero value, prevents the default command
493 mappings from being set for commands specific to an individual VCS.
494
495 VCSCommandEdit *VCSCommandEdit*
496
497 This variable controls whether the original buffer is replaced ('edit') or
498 split ('split'). If not set, it defaults to 'split'.
499
500 VCSCommandDisableMenu *VCSCommandDisableMenu*
501
502 This variable, if set to a non-zero value, prevents the default command menu
503 from being set.
504
505 VCSCommandEnableBufferSetup *VCSCommandEnableBufferSetup*
506
507 This variable, if set to a non-zero value, activates VCS buffer management
508 mode see (|vcscommand-buffer-management|). This mode means that the
509 'VCSCommandBufferInfo' variable is filled with version information if the file
510 is VCS-controlled. This is useful for displaying version information in the
511 status bar.
512
513 VCSCommandMappings *VCSCommandMappings*
514
515 This variable, if set, overrides the default mappings used for shortcuts. It
516 should be a List of 2-element Lists, each containing a shortcut and function
517 name pair. The value of the '|VCSCommandMapPrefix|' variable will be added to
518 each shortcut.
519
520 VCSCommandMapPrefix *VCSCommandMapPrefix*
521
522 This variable, if set, overrides the default mapping prefix ('<Leader>c').
523 This allows customization of the mapping space used by the vcscommand
524 shortcuts.
525
526 VCSCommandMenuPriority *VCSCommandMenuPriority*
527
528 This variable, if set, overrides the default menu priority '' (empty)
529
530 VCSCommandMenuRoot *VCSCommandMenuRoot*
531
532 This variable, if set, overrides the default menu root 'Plugin.VCS'
533
534 VCSCommandResultBufferNameExtension *VCSCommandResultBufferNameExtension*
535
536 This variable, if set to a non-blank value, is appended to the name of the VCS
537 command output buffers. For example, '.vcs'. Using this option may help
538 avoid problems caused by autocommands dependent on file extension.
539
540 VCSCommandResultBufferNameFunction *VCSCommandResultBufferNameFunction*
541
542 This variable, if set, specifies a custom function for naming VCS command
543 output buffers. This function is expected to return the new buffer name, and
544 will be passed the following arguments:
545
546 command - name of the VCS command being executed (such as 'Log' or
547 'Diff').
548
549 originalBuffer - buffer number of the source file.
550
551 vcsType - type of VCS controlling this file (such as 'CVS' or 'SVN').
552
553 statusText - extra text associated with the VCS action (such as version
554 numbers).
555
556 VCSCommandSplit *VCSCommandSplit*
557
558 This variable controls the orientation of the various window splits that
559 may occur.
560
561 If set to 'horizontal', the resulting windows will be on stacked on top of
562 one another. If set to 'vertical', the resulting windows will be
563 side-by-side. If not set, it defaults to 'horizontal' for all but
564 VCSVimDiff windows. VCSVimDiff windows default to the user's 'diffopt'
565 setting, if set, otherwise 'vertical'.
566
567 VCSCommandSVKExec *VCSCommandSVKExec*
568
569 This variable controls the executable used for all SVK commands If not set,
570 it defaults to "svk".
571
572 VCSCommandSVNDiffExt *VCSCommandSVNDiffExt*
573
574 This variable, if set, is passed to SVN via the --diff-cmd command to select
575 an external application for performing the diff.
576
577 VCSCommandSVNDiffOpt *VCSCommandSVNDiffOpt*
578
579 This variable, if set, determines the options passed with the '-x' parameter
580 to the SVN diff command. If not set, no options are passed.
581
582 VCSCommandSVNExec *VCSCommandSVNExec*
583
584 This variable controls the executable used for all SVN commands If not set,
585 it defaults to "svn".
586
587 VCSCommandVCSTypeOverride *VCSCommandVCSTypeOverride*
588
589 This variable allows the VCS type detection to be overridden on a path-by-path
590 basis. The value of this variable is expected to be a List of Lists. Each
591 item in the high-level List is a List containing two elements. The first
592 element is a regular expression that will be matched against the full file
593 name of a given buffer. If it matches, the second element will be used as the
594 VCS type.
595
596 5.2 VCSCommand events *vcscommand-events*
597
598 For additional customization, vcscommand can trigger user-defined events.
599 Event handlers are provided by defining User event autocommands (see
600 |autocommand|, |User|) in the vcscommand group with patterns matching the
601 event name.
602
603 For instance, the following could be added to the vimrc to provide a 'q'
604 mapping to quit a vcscommand scratch buffer:
605
606 augroup VCSCommand
607 au User VCSBufferCreated silent! nmap <unique> <buffer> q :bwipeout<cr>
608 augroup END
609
610 The following hooks are available:
611
612 VCSBufferCreated This event is fired just after a vcscommand
613 result buffer is created and populated. It is
614 executed within the context of the vcscommand
615 buffer. The vcscommand buffer variables may
616 be useful for handlers of this event (please
617 see |vcscommand-buffer-variables|).
618
619 VCSBufferSetup This event is fired just after vcscommand buffer
620 setup occurs, if enabled.
621
622 VCSPluginInit This event is fired when the vcscommand plugin
623 first loads.
624
625 VCSPluginFinish This event is fired just after the vcscommand
626 plugin loads.
627
628 VCSVimDiffFinish This event is fired just after the VCSVimDiff
629 command executes to allow customization of,
630 for instance, window placement and focus.
631
632 Additionally, there is another hook which is used internally to handle loading
633 the multiple scripts in order. This hook should probably not be used by an
634 end user without a good idea of how it works. Among other things, any events
635 associated with this hook are cleared after they are executed (during
636 vcscommand.vim script initialization).
637
638 VCSLoadExtensions This event is fired just before the
639 VCSPluginFinish. It is used internally to
640 execute any commands from the VCS
641 implementation plugins that needs to be
642 deferred until the primary plugin is
643 initialized.
644
645 5.3 vcscommand buffer naming *vcscommand-naming*
646
647 vcscommand result buffers use the following naming convention:
648 [{VCS type} {VCS command} {Source file name}]
649
650 If additional buffers are created that would otherwise conflict, a
651 distinguishing number is added:
652
653 [{VCS type} {VCS command} {Source file name}] (1,2, etc)
654
655 5.4 vcscommand status line support *vcscommand-statusline*
656
657 It is intended that the user will customize the |'statusline'| option to
658 include vcscommand result buffer attributes. A sample function that may be
659 used in the |'statusline'| option is provided by the plugin,
660 VCSCommandGetStatusLine(). In order to use that function in the status line, do
661 something like the following:
662
663 set statusline=%<%f\ %{VCSCommandGetStatusLine()}\ %h%m%r%=%l,%c%V\ %P
664
665 of which %{VCSCommandGetStatusLine()} is the relevant portion.
666
667 The sample VCSCommandGetStatusLine() function handles both vcscommand result
668 buffers and VCS-managed files if vcscommand buffer management is enabled
669 (please see |vcscommand-buffer-management|).
670
671 5.5 vcscommand buffer management *vcscommand-buffer-management*
672
673 The vcscommand plugin can operate in buffer management mode, which means that
674 it attempts to set a buffer variable ('VCSCommandBufferInfo') upon entry into
675 a buffer. This is rather slow because it means that the VCS will be invoked
676 at each entry into a buffer (during the |BufEnter| autocommand).
677
678 This mode is disabled by default. In order to enable it, set the
679 |VCSCommandEnableBufferSetup| variable to a true (non-zero) value. Enabling
680 this mode simply provides the buffer variable mentioned above. The user must
681 explicitly include information from the variable in the |'statusline'| option
682 if they are to appear in the status line (but see |vcscommand-statusline| for
683 a simple way to do that).
684
685 The 'VCSCommandBufferInfo' variable is a list which contains, in order, the
686 revision of the current file, the latest revision of the file in the
687 repository, and (for CVS) the name of the branch. If those values cannot be
688 determined, the list is a single element: 'Unknown'.
689
690 ==============================================================================
691
692 6. SSH "integration" *vcscommand-ssh*
693
694 The following instructions are intended for use in integrating the
695 vcscommand.vim plugin with an SSH-based CVS environment.
696
697 Familiarity with SSH and CVS are assumed.
698
699 These instructions assume that the intent is to have a message box pop up in
700 order to allow the user to enter a passphrase. If, instead, the user is
701 comfortable using certificate-based authentication, then only instructions
702 6.1.1 and 6.1.2 (and optionally 6.1.4) need to be followed; ssh should then
703 work transparently.
704
705 6.1 Environment settings *vcscommand-ssh-env*
706
707 6.1.1 CVSROOT should be set to something like:
708
709 :ext:user@host:/path_to_repository
710
711 6.1.2 CVS_RSH should be set to:
712
713 ssh
714
715 Together, those settings tell CVS to use ssh as the transport when
716 performing CVS calls.
717
718 6.1.3 SSH_ASKPASS should be set to the password-dialog program. In my case,
719 running gnome, it's set to:
720
721 /usr/libexec/openssh/gnome-ssh-askpass
722
723 This tells SSH how to get passwords if no input is available.
724
725 6.1.4 OPTIONAL. You may need to set SSH_SERVER to the location of the cvs
726 executable on the remote (server) machine.
727
728 6.2 CVS wrapper program *vcscommand-ssh-wrapper*
729
730 Now you need to convince SSH to use the password-dialog program. This means
731 you need to execute SSH (and therefore CVS) without standard input. The
732 following script is a simple perl wrapper that dissasociates the CVS command
733 from the current terminal. Specific steps to do this may vary from system to
734 system; the following example works for me on linux.
735
736 #!/usr/bin/perl -w
737 use strict;
738 use POSIX qw(setsid);
739 open STDIN, '/dev/null';
740 fork and do {wait; exit;};
741 setsid;
742 exec('cvs', @ARGV);
743
744 6.3 Configuring vcscommand.vim *vcscommand-ssh-config*
745
746 At this point, you should be able to use your wrapper script to invoke CVS with
747 various commands, and get the password dialog. All that's left is to make CVS
748 use your newly-created wrapper script.
749
750 6.3.1 Tell vcscommand.vim what CVS executable to use. The easiest way to do this
751 is globally, by putting the following in your .vimrc:
752
753 let VCSCommandCVSExec=/path/to/cvs/wrapper/script
754
755 6.4 Where to go from here *vcscommand-ssh-other*
756
757 The script given above works even when non-SSH CVS connections are used,
758 except possibly when interactively entering the message for CVS commit log
759 (depending on the editor you use... VIM works fine). Since the vcscommand.vim
760 plugin handles that message without a terminal, the wrapper script can be used
761 all the time.
762
763 This allows mixed-mode operation, where some work is done with SSH-based CVS
764 repositories, and others with pserver or local access.
765
766 It is possible, though beyond the scope of the plugin, to dynamically set the
767 CVS executable based on the CVSROOT for the file being edited. The user
768 events provided (such as VCSBufferCreated and VCSBufferSetup) can be used to
769 set a buffer-local value (b:VCSCommandCVSExec) to override the CVS executable
770 on a file-by-file basis. Alternatively, much the same can be done (less
771 automatically) by the various project-oriented plugins out there.
772
773 It is highly recommended for ease-of-use that certificates with no passphrase
774 or ssh-agent are employed so that the user is not given the password prompt
775 too often.
776
777 ==============================================================================
778
779 7. Changes from cvscommand *cvscommand-changes*
780
781 1. Require Vim 7 in order to leverage several convenient features; also
782 because I wanted to play with Vim 7.
783
784 2. Renamed commands to start with 'VCS' instead of 'CVS'. The exceptions are
785 the 'CVSEdit' and 'CVSWatch' family of commands, which are specific to CVS.
786
787 3. Renamed options, events to start with 'VCSCommand'.
788
789 4. Removed option to jump to the parent version of the current line in an
790 annotated buffer, as opposed to the version on the current line. This made
791 little sense in the branching scheme used by subversion, where jumping to a
792 parent branch required finding a different location in the repository. It
793 didn't work consistently in CVS anyway.
794
795 5. Removed option to have nameless scratch buffers.
796
797 6. Changed default behavior of scratch buffers to split the window instead of
798 displaying in the current window. This may still be overridden using the
799 'VCSCommandEdit' option.
800
801 7. Split plugin into multiple plugins.
802
803 8. Added 'VCSLock' and 'VCSUnlock' commands. These are implemented for
804 subversion but not for CVS. These were not kept specific to subversion as they
805 seemed more general in nature and more likely to be supported by any future VCS
806 supported by this plugin.
807
808 9. Changed name of buffer variables set by commands.
809
810 'b:cvsOrigBuffNR' became 'b:VCSCommandOriginalBuffer'
811 'b:cvscmd' became 'b:VCSCommandCommand'
812
813 10. Added new automatic variables to command result buffers.
814
815 'b:VCSCommandSourceFile'
816 'b:VCSCommandVCSType'
817
818 ==============================================================================
819
820 8. Known bugs *vcscommand-bugs*
821
822 Please let me know if you run across any.
823
824 CVSUnedit may, if a file is changed from the repository, provide prompt text
825 to determine whether the changes should be thrown away. Currently, that text
826 shows up in the CVS result buffer as information; there is no way for the user
827 to actually respond to the prompt and the CVS unedit command does nothing. If
828 this really bothers anyone, please let me know.
829
830 VCSVimDiff, when using the original (real) source buffer as one of the diff
831 buffers, uses some hacks to try to restore the state of the original buffer
832 when the scratch buffer containing the other version is destroyed. There may
833 still be bugs in here, depending on many configuration details.
834
835 vim:tw=78:ts=8:ft=help