~spacexplorer/+junk/myenv

« back to all changes in this revision

Viewing changes to vim/vim/doc/vcscommand.txt

  • Committer: Kim Allamandola
  • Date: 2011-05-02 05:39:17 UTC
  • Revision ID: spacexplorer@gmail.com-20110502053917-x0yl2lr9ri4yskr2
InitĀ import

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
*vcscommand.txt*        vcscommand
 
2
Copyright (c) 2007 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
For CVS buffers, the 'VCSCommandCVSAnnotateParent' option, if set to non-zero,
 
144
will cause the above behavior to change.  Instead of annotating the version on
 
145
the current line, the parent revision is used instead, crossing branches if
 
146
necessary.
 
147
 
 
148
The filetype of the vcscommand scratch buffer is set to one of 'CVSAnnotate',
 
149
'SVNAnnotate', or 'SVKAnnotate' as appropriate, to take advantage of the
 
150
bundled syntax files.
 
151
 
 
152
:VCSBlame                                               *:VCSBlame*
 
153
 
 
154
Alias for |:VCSAnnotate|.
 
155
 
 
156
:VCSCommit[!]                                           *:VCSCommit*
 
157
 
 
158
This command commits changes to the current file to source control.
 
159
 
 
160
If called with arguments, the arguments are the log message.
 
161
 
 
162
If '!' is used, an empty log message is committed.
 
163
 
 
164
If called with no arguments, this is a two-step command.  The first step opens
 
165
a buffer to accept a log message.  When that buffer is written, it is
 
166
automatically closed and the file is committed using the information from that
 
167
log message.  The commit can be abandoned if the log message buffer is deleted
 
168
or wiped before being written.
 
169
 
 
170
Alternatively, the mapping that is used to invoke :VCSCommit (by default
 
171
<Leader>cc) can be used in the log message buffer to immediately commit.  This
 
172
is useful if the |VCSCommandCommitOnWrite| variable is set to 0 to disable the
 
173
normal commit-on-write behavior.
 
174
 
 
175
:VCSDelete                                              *:VCSDelete*
 
176
 
 
177
Deletes the current file and removes it from source control.  All parameters
 
178
to the command are passed to the underlying VCS.
 
179
 
 
180
:VCSDiff                                                *:VCSDiff*
 
181
 
 
182
With no arguments, this displays the differences between the current file and
 
183
its parent version under source control in a new scratch buffer.
 
184
 
 
185
With one argument, the diff is performed on the current file against the
 
186
specified revision.
 
187
 
 
188
With two arguments, the diff is performed between the specified revisions of
 
189
the current file.
 
190
 
 
191
For CVS, this command uses the |VCSCommandCVSDiffOpt| variable to specify diff
 
192
options.  If that variable does not exist, a plugin-specific default is used.
 
193
If you wish to have no options, then set it to the empty string.
 
194
 
 
195
For SVN, this command uses the |VCSCommandSVNDiffOpt| variable to specify diff
 
196
options.  If that variable does not exist, the SVN default is used.
 
197
Additionally, |VCSCommandSVNDiffExt| can be used to select an external diff
 
198
application.
 
199
 
 
200
:VCSGotoOriginal                                        *:VCSGotoOriginal*
 
201
 
 
202
This command jumps to the source buffer if the current buffer is a VCS scratch
 
203
buffer.
 
204
 
 
205
:VCSGotoOriginal!
 
206
 
 
207
Like ":VCSGotoOriginal" but also executes :bufwipeout on all VCS scrach
 
208
buffers associated with the original file.
 
209
 
 
210
:VCSInfo                                                *:VCSInfo*
 
211
 
 
212
This command displays extended information about the current file in a new
 
213
scratch buffer. 
 
214
 
 
215
:VCSLock                                                *:VCSLock*
 
216
 
 
217
This command locks the current file in order to prevent other users from
 
218
concurrently modifying it.  The exact semantics of this command depend on the
 
219
underlying VCS.  This does nothing in CVS.  All parameters are passed to the
 
220
underlying VCS.
 
221
 
 
222
:VCSLog                                                 *:VCSLog*
 
223
 
 
224
Displays the version history of the current file in a new scratch buffer.  If
 
225
there is one parameter supplied, it is taken as as a revision parameters to be
 
226
passed through to the underlying VCS.  Otherwise, all parameters are passed to
 
227
the underlying VCS.
 
228
 
 
229
:VCSRemove                                              *:VCSRemove*
 
230
 
 
231
Alias for |:VCSDelete|.
 
232
 
 
233
:VCSRevert                                              *:VCSRevert*
 
234
 
 
235
This command replaces the current file with the most recent version from the
 
236
repository in order to wipe out any undesired changes.
 
237
 
 
238
:VCSReview                                              *:VCSReview*
 
239
 
 
240
Displays a particular version of the current file in a new scratch buffer.  If
 
241
no argument is given, the most recent version of the file on the current
 
242
branch is retrieved.
 
243
 
 
244
:VCSStatus                                              *:VCSStatus*
 
245
 
 
246
Displays versioning information about the current file in a new scratch
 
247
buffer.  All parameters are passed to the underlying VCS.
 
248
 
 
249
 
 
250
:VCSUnlock                                              *:VCSUnlock*
 
251
 
 
252
Unlocks the current file in order to allow other users from concurrently
 
253
modifying it.  The exact semantics of this command depend on the underlying
 
254
VCS.  All parameters are passed to the underlying VCS.
 
255
 
 
256
:VCSUpdate                                              *:VCSUpdate*
 
257
 
 
258
Updates the current file with any relevant changes from the repository.  This
 
259
intentionally does not automatically reload the current buffer, though vim
 
260
should prompt the user to do so if the underlying file is altered by this
 
261
command.
 
262
 
 
263
:VCSVimDiff                                             *:VCSVimDiff*
 
264
 
 
265
Uses vimdiff to display differences between versions of the current file.
 
266
 
 
267
If no revision is specified, the most recent version of the file on the
 
268
current branch is used.  With one argument, that argument is used as the
 
269
revision as above.  With two arguments, the differences between the two
 
270
revisions is displayed using vimdiff.
 
271
                                                            
 
272
With either zero or one argument, the original buffer is used to perform the
 
273
vimdiff.  When the scratch buffer is closed, the original buffer will be
 
274
returned to normal mode.
 
275
                                                            
 
276
Once vimdiff mode is started using the above methods, additional vimdiff
 
277
buffers may be added by passing a single version argument to the command.
 
278
There may be up to 4 vimdiff buffers total.
 
279
                                                            
 
280
Using the 2-argument form of the command resets the vimdiff to only those 2
 
281
versions.  Additionally, invoking the command on a different file will close
 
282
the previous vimdiff buffers.
 
283
 
 
284
:CVSEdit                                                *:CVSEdit*
 
285
 
 
286
This command performs "cvs edit" on the current file.  Yes, the output buffer
 
287
in this case is almost completely useless.
 
288
 
 
289
:CVSEditors                                             *:CVSEditors*
 
290
 
 
291
This command performs "cvs edit" on the current file.
 
292
 
 
293
:CVSUnedit                                              *:CVSUnedit*
 
294
 
 
295
Performs "cvs unedit" on the current file.  Again, yes, the output buffer here
 
296
is basically useless.
 
297
 
 
298
:CVSWatch                                               *:CVSWatch*
 
299
 
 
300
This command takes an argument which must be one of [on|off|add|remove].  The
 
301
command performs "cvs watch" with the given argument on the current file.
 
302
 
 
303
:CVSWatchAdd                                            *:CVSWatchAdd*
 
304
 
 
305
This command is an alias for ":CVSWatch add"
 
306
 
 
307
:CVSWatchOn                                             *:CVSWatchOn*
 
308
 
 
309
This command is an alias for ":CVSWatch on"
 
310
 
 
311
:CVSWatchOff                                            *:CVSWatchOff*
 
312
 
 
313
This command is an alias for ":CVSWatch off"
 
314
 
 
315
:CVSWatchRemove                                         *:CVSWatchRemove*
 
316
 
 
317
This command is an alias for ":CVSWatch remove"
 
318
 
 
319
:CVSWatchers                                            *:CVSWatchers*
 
320
 
 
321
This command performs "cvs watchers" on the current file.
 
322
 
 
323
4.2 Mappings                                            *vcscommand-mappings*
 
324
 
 
325
By default, a mapping is defined for each command.  These mappings execute the
 
326
default (no-argument) form of each command.
 
327
 
 
328
<Leader>ca VCSAdd
 
329
<Leader>cn VCSAnnotate
 
330
<Leader>cc VCSCommit
 
331
<Leader>cD VCSDelete
 
332
<Leader>cd VCSDiff
 
333
<Leader>cg VCSGotoOriginal
 
334
<Leader>cG VCSGotoOriginal!
 
335
<Leader>ci VCSInfo
 
336
<Leader>cl VCSLog
 
337
<Leader>cL VCSLock
 
338
<Leader>cr VCSReview
 
339
<Leader>cs VCSStatus
 
340
<Leader>cu VCSUpdate
 
341
<Leader>cU VCSUnlock
 
342
<Leader>cv VCSVimDiff
 
343
 
 
344
Only for CVS buffers:
 
345
 
 
346
<Leader>ce CVSEdit
 
347
<Leader>cE CVSEditors
 
348
<Leader>ct CVSUnedit
 
349
<Leader>cwv CVSWatchers
 
350
<Leader>cwa CVSWatchAdd
 
351
<Leader>cwn CVSWatchOn
 
352
<Leader>cwf CVSWatchOff
 
353
<Leader>cwf CVSWatchRemove
 
354
 
 
355
                                                *vcscommand-mappings-override*
 
356
 
 
357
The default mappings can be overriden by user-provided instead by mapping to
 
358
<Plug>CommandName.  This is especially useful when these mappings collide with
 
359
other existing mappings (vim will warn of this during plugin initialization,
 
360
but will not clobber the existing mappings).
 
361
 
 
362
For instance, to override the default mapping for :VCSAdd to set it to '\add',
 
363
add the following to the vimrc:
 
364
 
 
365
nmap \add <Plug>VCSAdd
 
366
 
 
367
4.3 Automatic buffer variables                  *vcscommand-buffer-variables*
 
368
 
 
369
Several buffer variables are defined in each vcscommand result buffer.  These
 
370
may be useful for additional customization in callbacks defined in the event
 
371
handlers (please see |vcscommand-events|).
 
372
 
 
373
The following variables are automatically defined:
 
374
 
 
375
b:VCSCommandOriginalBuffer                      *b:VCSCommandOriginalBuffer*
 
376
 
 
377
This variable is set to the buffer number of the source file.
 
378
 
 
379
b:VCSCommandCommand                             *b:VCSCommandCommand*
 
380
 
 
381
This variable is set to the name of the vcscommand that created the result
 
382
buffer.
 
383
 
 
384
b:VCSCommandSourceFile                          *b:VCSCommandSourceFile*
 
385
 
 
386
This variable is set to the name of the original file under source control.
 
387
 
 
388
b:VCSCommandVCSType                             *b:VCSCommandVCSType*
 
389
 
 
390
This variable is set to the type of the source control.  This variable is also
 
391
set on the original file itself.
 
392
==============================================================================
 
393
 
 
394
5. Configuration and customization                      *vcscommand-customize*
 
395
                                                        *vcscommand-config*
 
396
 
 
397
The vcscommand plugin can be configured in several ways:  by setting
 
398
configuration variables (see |vcscommand-options|) or by defining vcscommand
 
399
event handlers (see |vcscommand-events|).  Additionally, the vcscommand plugin
 
400
supports a customized status line (see |vcscommand-statusline| and
 
401
|vcscommand-buffer-management|).
 
402
 
 
403
5.1 vcscommand configuration variables                  *vcscommand-options*
 
404
 
 
405
Several variables affect the plugin's behavior.  These variables are checked
 
406
at time of execution, and may be defined at the window, buffer, or global
 
407
level and are checked in that order of precedence.
 
408
 
 
409
 
 
410
The following variables are available:
 
411
 
 
412
|VCSCommandCommitOnWrite|
 
413
|VCSCommandCVSDiffOpt|
 
414
|VCSCommandCVSExec|
 
415
|VCSCommandDeleteOnHide|
 
416
|VCSCommandDiffSplit|
 
417
|VCSCommandDisableMappings|
 
418
|VCSCommandDisableExtensionMappings|
 
419
|VCSCommandEdit|
 
420
|VCSCommandEnableBufferSetup|
 
421
|VCSCommandResultBufferNameExtension|
 
422
|VCSCommandResultBufferNameFunction|
 
423
|VCSCommandSplit|
 
424
|VCSCommandSVKExec|
 
425
|VCSCommandSVNDiffExt|
 
426
|VCSCommandSVNDiffOpt|
 
427
|VCSCommandSVNExec|
 
428
 
 
429
VCSCommandCommitOnWrite                         *VCSCommandCommitOnWrite*
 
430
 
 
431
This variable, if set to a non-zero value, causes the pending commit
 
432
to take place immediately as soon as the log message buffer is written.
 
433
If set to zero, only the VCSCommit mapping will cause the pending commit to
 
434
occur.  If not set, it defaults to 1.
 
435
 
 
436
VCSCommandCVSExec                               *VCSCommandCVSExec*
 
437
 
 
438
This variable controls the executable used for all CVS commands  If not set,
 
439
it defaults to "cvs".
 
440
 
 
441
VCSCommandDeleteOnHide                          *VCSCommandDeleteOnHide*
 
442
 
 
443
This variable, if set to a non-zero value, causes the temporary result buffers
 
444
to automatically delete themselves when hidden.
 
445
 
 
446
VCSCommandCVSDiffOpt                            *VCSCommandCVSDiffOpt*
 
447
 
 
448
This variable, if set, determines the options passed to the diff command of
 
449
CVS.  If not set, it defaults to 'u'.
 
450
 
 
451
VCSCommandDiffSplit                             *VCSCommandDiffSplit*
 
452
 
 
453
This variable overrides the |VCSCommandSplit| variable, but only for buffers
 
454
created with |:VCSVimDiff|.
 
455
 
 
456
VCSCommandDisableMappings                       *VCSCommandDisableMappings*
 
457
 
 
458
This variable, if set to a non-zero value, prevents the default command
 
459
mappings from being set.  This supercedes 
 
460
|VCSCommandDisableExtensionMappings|.
 
461
 
 
462
VCSCommandDisableExtensionMappings      *VCSCommandDisableExtensionMappings*
 
463
 
 
464
This variable, if set to a non-zero value, prevents the default command
 
465
mappings from being set for commands specific to an individual VCS.
 
466
 
 
467
VCSCommandEdit                                  *VCSCommandEdit*
 
468
 
 
469
This variable controls whether the original buffer is replaced ('edit') or
 
470
split ('split').  If not set, it defaults to 'split'.
 
471
 
 
472
VCSCommandEnableBufferSetup                     *VCSCommandEnableBufferSetup*
 
473
 
 
474
This variable, if set to a non-zero value, activates VCS buffer management
 
475
mode see (|vcscommand-buffer-management|).  This mode means that the
 
476
'VCSCommandBufferInfo' variable is filled with version information if the file
 
477
is VCS-controlled.  This is useful for displaying version information in the
 
478
status bar.
 
479
 
 
480
VCSCommandResultBufferNameExtension     *VCSCommandResultBufferNameExtension*
 
481
 
 
482
This variable, if set to a non-blank value, is appended to the name of the VCS
 
483
command output buffers.  For example, '.vcs'.  Using this option may help
 
484
avoid problems caused by autocommands dependent on file extension.
 
485
 
 
486
VCSCommandResultBufferNameFunction      *VCSCommandResultBufferNameFunction*
 
487
 
 
488
This variable, if set, specifies a custom function for naming VCS command
 
489
output buffers.  This function is expected to return the new buffer name, and
 
490
will be passed the following arguments:
 
491
 
 
492
  command - name of the VCS command being executed (such as 'Log' or
 
493
  'Diff').
 
494
  
 
495
  originalBuffer - buffer number of the source file.
 
496
  
 
497
  vcsType - type of VCS controlling this file (such as 'CVS' or 'SVN').
 
498
  
 
499
  statusText - extra text associated with the VCS action (such as version
 
500
  numbers).
 
501
 
 
502
VCSCommandSplit                                 *VCSCommandSplit*
 
503
 
 
504
This variable controls the orientation of the various window splits that
 
505
may occur.
 
506
 
 
507
If set to 'horizontal', the resulting windows will be on stacked on top of
 
508
one another.  If set to 'vertical', the resulting windows will be
 
509
side-by-side.  If not set, it defaults to 'horizontal' for all but
 
510
VCSVimDiff windows.
 
511
 
 
512
VCSCommandSVKExec                               *VCSCommandSVKExec*
 
513
 
 
514
This variable controls the executable used for all SVK commands  If not set,
 
515
it defaults to "svk".
 
516
 
 
517
VCSCommandSVNDiffExt                            *VCSCommandSVNDiffExt*
 
518
 
 
519
This variable, if set, is passed to SVN via the --diff-cmd command to select
 
520
an external application for performing the diff.
 
521
 
 
522
VCSCommandSVNDiffOpt                            *VCSCommandSVNDiffOpt*
 
523
 
 
524
This variable, if set, determines the options passed with the '-x' parameter
 
525
to the SVN diff command.  If not set, no options are passed.
 
526
 
 
527
VCSCommandSVNExec                               *VCSCommandSVNExec*
 
528
 
 
529
This variable controls the executable used for all SVN commands  If not set,
 
530
it defaults to "svn".
 
531
 
 
532
5.2 VCSCommand events                           *vcscommand-events*
 
533
 
 
534
For additional customization, vcscommand can trigger user-defined events.
 
535
Event handlers are provided by defining User event autocommands (see
 
536
|autocommand|, |User|) in the vcscommand group with patterns matching the
 
537
event name.
 
538
 
 
539
For instance, the following could be added to the vimrc to provide a 'q'
 
540
mapping to quit a vcscommand scratch buffer:
 
541
 
 
542
augroup VCSCommand
 
543
  au User VCSBufferCreated silent! nmap <unique> <buffer> q: bwipeout<cr>
 
544
augroup END
 
545
 
 
546
The following hooks are available:
 
547
 
 
548
VCSBufferCreated                This event is fired just after a vcscommand
 
549
                                result buffer is created and populated.  It is
 
550
                                executed within the context of the vcscommand
 
551
                                buffer.  The vcscommand buffer variables may
 
552
                                be useful for handlers of this event (please
 
553
                                see |vcscommand-buffer-variables|).
 
554
 
 
555
VCSBufferSetup                  This event is fired just after vcscommand buffer
 
556
                                setup occurs, if enabled.
 
557
 
 
558
VCSPluginInit                   This event is fired when the vcscommand plugin
 
559
                                first loads.
 
560
 
 
561
VCSPluginFinish                 This event is fired just after the vcscommand
 
562
                                plugin loads.
 
563
 
 
564
VCSVimDiffFinish                This event is fired just after the VCSVimDiff
 
565
                                command executes to allow customization of,
 
566
                                for instance, window placement and focus.
 
567
 
 
568
Additionally, there is another hook which is used internally to handle loading
 
569
the multiple scripts in order.  This hook should probably not be used by an
 
570
end user without a good idea of how it works.  Among other things, any events
 
571
associated with this hook are cleared after they are executed (during
 
572
vcscommand.vim script initialization).
 
573
 
 
574
VCSLoadExtensions               This event is fired just before the
 
575
                                VCSPluginFinish.  It is used internally to
 
576
                                execute any commands from the VCS
 
577
                                implementation plugins that needs to be
 
578
                                deferred until the primary plugin is
 
579
                                initialized.
 
580
 
 
581
5.3 vcscommand buffer naming                            *vcscommand-naming*
 
582
 
 
583
vcscommand result buffers use the following naming convention:
 
584
[{VCS type} {VCS command} {Source file name}]
 
585
 
 
586
If additional buffers are created that would otherwise conflict, a
 
587
distinguishing number is added:
 
588
 
 
589
[{VCS type} {VCS command} {Source file name}] (1,2, etc)
 
590
 
 
591
5.4 vcscommand status line support                      *vcscommand-statusline*
 
592
 
 
593
It is intended that the user will customize the |'statusline'| option to
 
594
include vcscommand result buffer attributes.  A sample function that may be
 
595
used in the |'statusline'| option is provided by the plugin,
 
596
VCSCommandGetStatusLine().  In order to use that function in the status line, do
 
597
something like the following:
 
598
 
 
599
set statusline=%<%f\ %{VCSCommandGetStatusLine()}\ %h%m%r%=%l,%c%V\ %P
 
600
 
 
601
of which %{VCSCommandGetStatusLine()} is the relevant portion.
 
602
 
 
603
The sample VCSCommandGetStatusLine() function handles both vcscommand result
 
604
buffers and VCS-managed files if vcscommand buffer management is enabled
 
605
(please see |vcscommand-buffer-management|).
 
606
 
 
607
5.5 vcscommand buffer management                *vcscommand-buffer-management*
 
608
 
 
609
The vcscommand plugin can operate in buffer management mode, which means that
 
610
it attempts to set a buffer variable ('VCSCommandBufferInfo') upon entry into
 
611
a buffer.  This is rather slow because it means that the VCS will be invoked
 
612
at each entry into a buffer (during the |BufEnter| autocommand).
 
613
 
 
614
This mode is disabled by default.  In order to enable it, set the
 
615
|VCSCommandEnableBufferSetup| variable to a true (non-zero) value.  Enabling
 
616
this mode simply provides the buffer variable mentioned above.  The user must
 
617
explicitly include information from the variable in the |'statusline'| option
 
618
if they are to appear in the status line (but see |vcscommand-statusline| for
 
619
a simple way to do that).
 
620
 
 
621
The 'VCSCommandBufferInfo' variable is a list which contains, in order, the
 
622
revision of the current file, the latest revision of the file in the
 
623
repository, and (for CVS) the name of the branch.  If those values cannot be
 
624
determined, the list is a single element:  'Unknown'.
 
625
 
 
626
==============================================================================
 
627
 
 
628
6. SSH "integration"                                    *vcscommand-ssh*
 
629
 
 
630
The following instructions are intended for use in integrating the
 
631
vcscommand.vim plugin with an SSH-based CVS environment.
 
632
 
 
633
Familiarity with SSH and CVS are assumed.
 
634
 
 
635
These instructions assume that the intent is to have a message box pop up in
 
636
order to allow the user to enter a passphrase.  If, instead, the user is
 
637
comfortable using certificate-based authentication, then only instructions
 
638
6.1.1 and 6.1.2 (and optionally 6.1.4) need to be followed; ssh should then
 
639
work transparently.
 
640
 
 
641
6.1 Environment settings                                *vcscommand-ssh-env*
 
642
 
 
643
6.1.1 CVSROOT should be set to something like:
 
644
 
 
645
        :ext:user@host:/path_to_repository
 
646
 
 
647
6.1.2 CVS_RSH should be set to:
 
648
 
 
649
        ssh
 
650
 
 
651
        Together, those settings tell CVS to use ssh as the transport when
 
652
        performing CVS calls.
 
653
 
 
654
6.1.3 SSH_ASKPASS should be set to the password-dialog program.  In my case,
 
655
        running gnome, it's set to:
 
656
 
 
657
        /usr/libexec/openssh/gnome-ssh-askpass
 
658
 
 
659
        This tells SSH how to get passwords if no input is available.
 
660
 
 
661
6.1.4 OPTIONAL.  You may need to set SSH_SERVER to the location of the cvs
 
662
        executable on the remote (server) machine.
 
663
 
 
664
6.2 CVS wrapper program                         *vcscommand-ssh-wrapper*
 
665
 
 
666
Now you need to convince SSH to use the password-dialog program.  This means
 
667
you need to execute SSH (and therefore CVS) without standard input.  The
 
668
following script is a simple perl wrapper that dissasociates the CVS command
 
669
from the current terminal.  Specific steps to do this may vary from system to
 
670
system; the following example works for me on linux.
 
671
 
 
672
#!/usr/bin/perl -w
 
673
use strict;
 
674
use POSIX qw(setsid);
 
675
open STDIN, '/dev/null';
 
676
fork and do {wait; exit;};
 
677
setsid;
 
678
exec('cvs', @ARGV);
 
679
 
 
680
6.3 Configuring vcscommand.vim                  *vcscommand-ssh-config*
 
681
 
 
682
At this point, you should be able to use your wrapper script to invoke CVS with
 
683
various commands, and get the password dialog.  All that's left is to make CVS
 
684
use your newly-created wrapper script.
 
685
 
 
686
6.3.1 Tell vcscommand.vim what CVS executable to use.  The easiest way to do this
 
687
        is globally, by putting the following in your .vimrc:
 
688
 
 
689
        let VCSCommandCVSExec=/path/to/cvs/wrapper/script
 
690
 
 
691
6.4 Where to go from here                       *vcscommand-ssh-other*
 
692
 
 
693
The script given above works even when non-SSH CVS connections are used,
 
694
except possibly when interactively entering the message for CVS commit log
 
695
(depending on the editor you use... VIM works fine).  Since the vcscommand.vim
 
696
plugin handles that message without a terminal, the wrapper script can be used
 
697
all the time.
 
698
 
 
699
This allows mixed-mode operation, where some work is done with SSH-based CVS
 
700
repositories, and others with pserver or local access.
 
701
 
 
702
It is possible, though beyond the scope of the plugin, to dynamically set the
 
703
CVS executable based on the CVSROOT for the file being edited.  The user
 
704
events provided (such as VCSBufferCreated and VCSBufferSetup) can be used to
 
705
set a buffer-local value (b:VCSCommandCVSExec) to override the CVS executable
 
706
on a file-by-file basis.  Alternatively, much the same can be done (less
 
707
automatically) by the various project-oriented plugins out there.
 
708
 
 
709
It is highly recommended for ease-of-use that certificates with no passphrase
 
710
or ssh-agent are employed so that the user is not given the password prompt
 
711
too often.
 
712
 
 
713
==============================================================================
 
714
 
 
715
7. Changes from cvscommandi                             *cvscommand-changes*
 
716
 
 
717
1.  Require Vim 7 in order to leverage several convenient features; also
 
718
because I wanted to play with Vim 7.
 
719
 
 
720
2.  Renamed commands to start with 'VCS' instead of 'CVS'.  The exceptions are
 
721
the 'CVSEdit' and 'CVSWatch' family of commands, which are specific to CVS.
 
722
 
 
723
3.  Renamed options, events to start with 'VCSCommand'.
 
724
 
 
725
4.  Removed option to jump to the parent version of the current line in an
 
726
annotated buffer, as opposed to the version on the current line.  This made
 
727
little sense in the branching scheme used by subversion, where jumping to a
 
728
parent branch required finding a different location in the repository.  It
 
729
didn't work consistently in CVS anyway.
 
730
 
 
731
5.  Removed option to have nameless scratch buffers.
 
732
 
 
733
6.  Changed default behavior of scratch buffers to split the window instead of
 
734
displaying in the current window.  This may still be overridden using the
 
735
'VCSCommandEdit' option.
 
736
 
 
737
7.  Split plugin into multiple plugins.
 
738
 
 
739
8.  Added 'VCSLock' and 'VCSUnlock' commands.  These are implemented for
 
740
subversion but not for CVS.  These were not kept specific to subversion as they
 
741
seemed more general in nature and more likely to be supported by any future VCS
 
742
supported by this plugin.
 
743
 
 
744
9.  Changed name of buffer variables set by commands.
 
745
 
 
746
'b:cvsOrigBuffNR' became 'b:VCSCommandOriginalBuffer'
 
747
'b:cvscmd' became 'b:VCSCommandCommand'
 
748
 
 
749
10.  Added new automatic variables to command result buffers.
 
750
 
 
751
'b:VCSCommandSourceFile'
 
752
'b:VCSCommandVCSType'
 
753
 
 
754
==============================================================================
 
755
 
 
756
8. Known bugs                                           *vcscommand-bugs*
 
757
 
 
758
Please let me know if you run across any.
 
759
 
 
760
CVSUnedit may, if a file is changed from the repository, provide prompt text
 
761
to determine whether the changes should be thrown away.  Currently, that text
 
762
shows up in the CVS result buffer as information; there is no way for the user
 
763
to actually respond to the prompt and the CVS unedit command does nothing.  If
 
764
this really bothers anyone, please let me know.
 
765
 
 
766
VCSVimDiff, when using the original (real) source buffer as one of the diff
 
767
buffers, uses some hacks to try to restore the state of the original buffer
 
768
when the scratch buffer containing the other version is destroyed.  There may
 
769
still be bugs in here, depending on many configuration details.
 
770
 
 
771
vim:tw=78:ts=8:ft=help