--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/contrib/vim/hgcommand.txt Mon Jul 10 23:39:08 2006 +0200
@@ -0,0 +1,617 @@
+*cvscommand.txt* CVSCommand
+
+For instructions on installing this file, type
+ :help add-local-help
+inside Vim.
+
+Author: Bob Hiestand <bob.hiestand@gmail.com>
+Credits: Benji Fisher's excellent MatchIt documentation
+
+==============================================================================
+1. Contents *cvscommand-contents*
+
+ Installation : |cvscommand-install|
+ CVSCommand Intro : |cvscommand|
+ CVSCommand Manual : |cvscommand-manual|
+ Customization : |cvscommand-customize|
+ SSH "integration" : |cvscommand-ssh|
+ Bugs : |cvscommand-bugs|
+
+==============================================================================
+
+2. CVSCommand Installation *cvscommand-install*
+
+The CVSCommand plugin comprises two files, cvscommand.vim and cvscommand.txt
+(this file). In order to install the plugin, place the cvscommand.vim file
+into a plugin' directory in your runtime path (please see |add-global-plugin|
+and |'runtimepath'|.
+
+CVSCommand may be customized by setting variables, creating maps, and
+specifying event handlers. Please see |cvscommand-customize| for more
+details.
+
+This help file can be included in the VIM help system by copying it into a
+'doc' directory in your runtime path and then executing the |:helptags|
+command, specifying the full path of the 'doc' directory. Please see
+|add-local-help| for more details.
+
+==============================================================================
+
+3. CVSCommand Intro *cvscommand*
+ *cvscommand-intro*
+
+The CVSCommand plugin provides global ex commands for manipulating
+CVS-controlled source files. In general, each command operates on the current
+buffer and accomplishes a separate cvs function, such as update, commit, log,
+and others (please see |cvscommand-commands| for a list of all available
+commands). The results of each operation are displayed in a scratch buffer.
+Several buffer variables are defined for those scratch buffers (please see
+|cvscommand-buffer-variables|).
+
+The notion of "current file" means either the current buffer, or, in the case
+of a directory buffer, the file on the current line within the buffer.
+
+For convenience, any CVSCommand invoked on a CVSCommand scratch buffer acts as
+though it was invoked on the original file and splits the screen so that the
+output appears in a new window.
+
+Many of the commands accept revisions as arguments. By default, most operate
+on the most recent revision on the current branch if no revision is specified
+(though see |CVSCommandInteractive| to prompt instead).
+
+Each CVSCommand is mapped to a key sequence starting with the <Leader>
+keystroke. The default mappings may be overridden by supplying different
+mappings before the plugin is loaded, such as in the vimrc, in the standard
+fashion for plugin mappings. For examples, please see
+|cvscommand-mappings-override|.
+
+The CVSCommand plugin may be configured in several ways. For more details,
+please see |cvscommand-customize|.
+
+==============================================================================
+
+4. CVSCommand Manual *cvscommand-manual*
+
+4.1 CVSCommand commands *cvscommand-commands*
+
+CVSCommand defines the following commands:
+
+|:CVSAdd|
+|:CVSAnnotate|
+|:CVSCommit|
+|:CVSDiff|
+|:CVSEdit|
+|:CVSEditors|
+|:CVSGotoOriginal|
+|:CVSLog|
+|:CVSRevert|
+|:CVSReview|
+|:CVSStatus|
+|:CVSUnedit|
+|:CVSUpdate|
+|:CVSVimDiff|
+|:CVSWatch|
+|:CVSWatchAdd|
+|:CVSWatchOn|
+|:CVSWatchOff|
+|:CVSWatchRemove|
+|:CVSWatchers|
+
+:CVSAdd *:CVSAdd*
+
+This command performs "cvs add" on the current file. Please note, this does
+not commit the newly-added file.
+
+:CVSAnnotate *:CVSAnnotate*
+
+This command performs "cvs annotate" on the current file. If an argument is
+given, the argument is used as a revision number to display. If not given an
+argument, it uses the most recent version of the file on the current branch.
+Additionally, if the current buffer is a CVSAnnotate buffer already, the
+version number on the current line is used.
+
+If the |CVSCommandAnnotateParent| variable is set to a non-zero value, the
+version previous to the one on the current line is used instead. This allows
+one to navigate back to examine the previous version of a line.
+
+The filetype of the CVSCommand scratch buffer is set to 'CVSAnnotate', to take
+advantage of the bundled syntax file.
+
+
+:CVSCommit[!] *:CVSCommit*
+
+If called with arguments, this performs "cvs commit" using the arguments as
+the log message.
+
+If '!' is used with no arguments, an empty log message is committed.
+
+If called with no arguments, this is a two-step command. The first step opens
+a buffer to accept a log message. When that buffer is written, it is
+automatically closed and the file is committed using the information from that
+log message. The commit can be abandoned if the log message buffer is deleted
+or wiped before being written.
+
+Alternatively, the mapping that is used to invoke :CVSCommit (by default
+<Leader>cc) can be used in the log message buffer to immediately commit. This
+is useful if the |CVSCommandCommitOnWrite| variable is set to 0 to disable the
+normal commit-on-write behavior.
+
+:CVSDiff *:CVSDiff*
+
+With no arguments, this performs "cvs diff" on the current file against the
+current repository version.
+
+With one argument, "cvs diff" is performed on the current file against the
+specified revision.
+
+With two arguments, cvs diff is performed between the specified
+revisions of the current file.
+
+This command uses the 'CVSCommandDiffOpt' variable to specify diff options.
+If that variable does not exist, then 'wbBc' is assumed. If you wish to have
+no options, then set it to the empty string.
+
+:CVSEdit *:CVSEdit*
+
+This command performs "cvs edit" on the current file. Yes, the output buffer
+in this case is almost completely useless.
+
+:CVSEditors *:CVSEditors*
+
+This command performs "cvs edit" on the current file.
+
+:CVSGotoOriginal *:CVSGotoOriginal*
+
+This command returns the current window to the source buffer, if the current
+buffer is a CVS command output buffer.
+
+:CVSGotoOriginal!
+
+Like ":CVSGotoOriginal" but also executes :bufwipeout on all CVS command
+output buffers for the source buffer.
+
+:CVSLog *:CVSLog*
+
+Performs "cvs log" on the current file.
+
+If an argument is given, it is passed as an argument to the "-r" option of
+"cvs log".
+
+:CVSRevert *:CVSRevert*
+
+Replaces the current file with the most recent version from the repository in
+order to wipe out any undesired changes.
+
+:CVSReview *:CVSReview*
+
+Retrieves a particular version of the current file. If no argument is given,
+the most recent version of the file on the current branch is retrieved.
+Otherwise, the specified version is retrieved.
+
+:CVSStatus *:CVSStatus*
+
+Performs "cvs status" on the current file.
+
+:CVSUnedit *:CVSUnedit*
+
+Performs "cvs unedit" on the current file. Again, yes, the output buffer here
+is basically useless.
+
+:CVSUpdate *:CVSUpdate*
+
+Performs "cvs update" on the current file. This intentionally does not
+automatically reload the current buffer, though vim should prompt the user to
+do so if the underlying file is altered by this command.
+
+:CVSVimDiff *:CVSVimDiff*
+
+With no arguments, this prompts the user for a revision and then uses vimdiff
+to display the differences between the current file and the specified
+revision. If no revision is specified, the most recent version of the file on
+the current branch is used.
+
+With one argument, that argument is used as the revision as above. With two
+arguments, the differences between the two revisions is displayed using
+vimdiff.
+
+With either zero or one argument, the original buffer is used to perform the
+vimdiff. When the other buffer is closed, the original buffer will be
+returned to normal mode.
+
+Once vimdiff mode is started using the above methods, additional vimdiff
+buffers may be added by passing a single version argument to the command.
+There may be up to 4 vimdiff buffers total.
+
+Using the 2-argument form of the command resets the vimdiff to only those 2
+versions. Additionally, invoking the command on a different file will close
+the previous vimdiff buffers.
+
+:CVSWatch *:CVSWatch*
+
+This command takes an argument which must be one of [on|off|add|remove]. The
+command performs "cvs watch" with the given argument on the current file.
+
+:CVSWatchAdd *:CVSWatchAdd*
+
+This command is an alias for ":CVSWatch add"
+
+:CVSWatchOn *:CVSWatchOn*
+
+This command is an alias for ":CVSWatch on"
+
+:CVSWatchOff *:CVSWatchOff*
+
+This command is an alias for ":CVSWatch off"
+
+:CVSWatchRemove *:CVSWatchRemove*
+
+This command is an alias for ":CVSWatch remove"
+
+:CVSWatchers *:CVSWatchers*
+
+This command performs "cvs watchers" on the current file.
+
+4.2 Mappings *cvscommand-mappings*
+
+By default, a mapping is defined for each command. These mappings execute the
+default (no-argument) form of each command.
+
+<Leader>ca CVSAdd
+<Leader>cn CVSAnnotate
+<Leader>cc CVSCommit
+<Leader>cd CVSDiff
+<Leader>ce CVSEdit
+<Leader>ci CVSEditors
+<Leader>cg CVSGotoOriginal
+<Leader>cG CVSGotoOriginal!
+<Leader>cl CVSLog
+<Leader>cr CVSReview
+<Leader>cs CVSStatus
+<Leader>ct CVSUnedit
+<Leader>cu CVSUpdate
+<Leader>cv CVSVimDiff
+<Leader>cwv CVSWatchers
+<Leader>cwa CVSWatchAdd
+<Leader>cwn CVSWatchOn
+<Leader>cwf CVSWatchOff
+<Leader>cwf CVSWatchRemove
+
+ *cvscommand-mappings-override*
+
+The default mappings can be overriden by user-provided instead by mapping to
+<Plug>CommandName. This is especially useful when these mappings collide with
+other existing mappings (vim will warn of this during plugin initialization,
+but will not clobber the existing mappings).
+
+For instance, to override the default mapping for :CVSAdd to set it to '\add',
+add the following to the vimrc:
+
+nmap \add <Plug>CVSAdd
+
+4.3 Automatic buffer variables *cvscommand-buffer-variables*
+
+Several buffer variables are defined in each CVSCommand result buffer. These
+may be useful for additional customization in callbacks defined in the event
+handlers (please see |cvscommand-events|).
+
+The following variables are automatically defined:
+
+b:cvsOrigBuffNR *b:cvsOrigBuffNR*
+
+This variable is set to the buffer number of the source file.
+
+b:cvscmd *b:cvscmd*
+
+This variable is set to the name of the cvs command that created the result
+buffer.
+==============================================================================
+
+5. Configuration and customization *cvscommand-customize*
+ *cvscommand-config*
+
+The CVSCommand plugin can be configured in two ways: by setting configuration
+variables (see |cvscommand-options|) or by defining CVSCommand event handlers
+(see |cvscommand-events|). Additionally, the CVSCommand plugin provides
+several option for naming the CVS result buffers (see |cvscommand-naming|) and
+supported a customized status line (see |cvscommand-statusline| and
+|cvscommand-buffer-management|).
+
+5.1 CVSCommand configuration variables *cvscommand-options*
+
+Several variables affect the plugin's behavior. These variables are checked
+at time of execution, and may be defined at the window, buffer, or global
+level and are checked in that order of precedence.
+
+
+The following variables are available:
+
+|CVSCommandAnnotateParent|
+|CVSCommandCommitOnWrite|
+|CVSCommandCVSExec|
+|CVSCommandDeleteOnHide|
+|CVSCommandDiffOpt|
+|CVSCommandDiffSplit|
+|CVSCommandEdit|
+|CVSCommandEnableBufferSetup|
+|CVSCommandInteractive|
+|CVSCommandNameMarker|
+|CVSCommandNameResultBuffers|
+|CVSCommandSplit|
+
+CVSCommandAnnotateParent *CVSCommandAnnotateParent*
+
+This variable, if set to a non-zero value, causes the zero-argument form of
+CVSAnnotate when invoked on a CVSAnnotate buffer to go to the version previous
+to that displayed on the current line. If not set, it defaults to 0.
+
+CVSCommandCommitOnWrite *CVSCommandCommitOnWrite*
+
+This variable, if set to a non-zero value, causes the pending cvs commit
+to take place immediately as soon as the log message buffer is written.
+If set to zero, only the CVSCommit mapping will cause the pending commit to
+occur. If not set, it defaults to 1.
+
+CVSCommandCVSExec *CVSCommandCVSExec*
+
+This variable controls the executable used for all CVS commands If not set,
+it defaults to "cvs".
+
+CVSCommandDeleteOnHide *CVSCommandDeleteOnHide*
+
+This variable, if set to a non-zero value, causes the temporary CVS result
+buffers to automatically delete themselves when hidden.
+
+CVSCommandDiffOpt *CVSCommandDiffOpt*
+
+This variable, if set, determines the options passed to the diff command of
+CVS. If not set, it defaults to 'wbBc'.
+
+CVSCommandDiffSplit *CVSCommandDiffSplit*
+
+This variable overrides the |CVSCommandSplit| variable, but only for buffers
+created with |:CVSVimDiff|.
+
+CVSCommandEdit *CVSCommandEdit*
+
+This variable controls whether the original buffer is replaced ('edit') or
+split ('split'). If not set, it defaults to 'edit'.
+
+CVSCommandEnableBufferSetup *CVSCommandEnableBufferSetup*
+
+This variable, if set to a non-zero value, activates CVS buffer management
+mode see (|cvscommand-buffer-management|). This mode means that two buffer
+variables, 'CVSRevision' and 'CVSBranch', are set if the file is
+CVS-controlled. This is useful for displaying version information in the
+status bar.
+
+CVSCommandInteractive *CVSCommandInteractive*
+
+This variable, if set to a non-zero value, causes appropriate commands (for
+the moment, only |:CVSReview|) to query the user for a revision to use instead
+of the current revision if none is specified.
+
+CVSCommandNameMarker *CVSCommandNameMarker*
+
+This variable, if set, configures the special attention-getting characters
+that appear on either side of the cvs buffer type in the buffer name. This
+has no effect unless |CVSCommandNameResultBuffers| is set to a true value. If
+not set, it defaults to '_'.
+
+CVSCommandNameResultBuffers *CVSCommandNameResultBuffers*
+
+This variable, if set to a true value, causes the cvs result buffers to be
+named in the old way ('<source file name> _<cvs command>_'). If not set
+or set to a false value, the result buffer is nameless.
+
+CVSCommandSplit *CVSCommandSplit*
+
+This variable controls the orientation of the various window splits that
+may occur (such as with CVSVimDiff, when using a CVS command on a CVS
+command buffer, or when the |CVSCommandEdit| variable is set to 'split'.
+If set to 'horizontal', the resulting windows will be on stacked on top of
+one another. If set to 'vertical', the resulting windows will be
+side-by-side. If not set, it defaults to 'horizontal' for all but
+CVSVimDiff windows.
+
+5.2 CVSCommand events *cvscommand-events*
+
+For additional customization, CVSCommand can trigger user-defined events.
+Event handlers are provided by defining User event autocommands (see
+|autocommand|, |User|) in the CVSCommand group with patterns matching the
+event name.
+
+For instance, the following could be added to the vimrc to provide a 'q'
+mapping to quit a CVSCommand scratch buffer:
+
+augroup CVSCommand
+ au CVSCommand User CVSBufferCreated silent! nmap <unique> <buffer> q: bwipeout<cr>
+augroup END
+
+The following hooks are available:
+
+CVSBufferCreated This event is fired just after a cvs command
+ result buffer is created and filled with the
+ result of a cvs command. It is executed within
+ the context of the CVS command buffer. The
+ CVSCommand buffer variables may be useful for
+ handlers of this event (please see
+ |cvscommand-buffer-variables|).
+
+CVSBufferSetup This event is fired just after CVS buffer setup
+ occurs, if enabled.
+
+CVSPluginInit This event is fired when the CVSCommand plugin
+ first loads.
+
+CVSPluginFinish This event is fired just after the CVSCommand
+ plugin loads.
+
+CVSVimDiffFinish This event is fired just after the CVSVimDiff
+ command executes to allow customization of,
+ for instance, window placement and focus.
+
+5.3 CVSCommand buffer naming *cvscommand-naming*
+
+By default, the buffers containing the result of CVS commands are nameless
+scratch buffers. It is intended that buffer variables of those buffers be
+used to customize the statusline option so that the user may fully control the
+display of result buffers.
+
+If the old-style naming is desired, please enable the
+|CVSCommandNameResultBuffers| variable. Then, each result buffer will receive
+a unique name that includes the source file name, the CVS command, and any
+extra data (such as revision numbers) that were part of the command.
+
+5.4 CVSCommand status line support *cvscommand-statusline*
+
+It is intended that the user will customize the |'statusline'| option to
+include CVS result buffer attributes. A sample function that may be used in
+the |'statusline'| option is provided by the plugin, CVSGetStatusLine(). In
+order to use that function in the status line, do something like the
+following:
+
+set statusline=%<%f\ %{CVSGetStatusLine()}\ %h%m%r%=%l,%c%V\ %P
+
+of which %{CVSGetStatusLine()} is the relevant portion.
+
+The sample CVSGetStatusLine() function handles both CVS result buffers and
+CVS-managed files if CVSCommand buffer management is enabled (please see
+|cvscommand-buffer-management|).
+
+5.5 CVSCommand buffer management *cvscommand-buffer-management*
+
+The CVSCommand plugin can operate in buffer management mode, which means that
+it attempts to set two buffer variables ('CVSRevision' and 'CVSBranch') upon
+entry into a buffer. This is rather slow because it means that 'cvs status'
+will be invoked at each entry into a buffer (during the |BufEnter|
+autocommand).
+
+This mode is disabled by default. In order to enable it, set the
+|CVSCommandEnableBufferSetup| variable to a true (non-zero) value. Enabling
+this mode simply provides the buffer variables mentioned above. The user must
+explicitly include those in the |'statusline'| option if they are to appear in
+the status line (but see |cvscommand-statusline| for a simple way to do that).
+
+==============================================================================
+
+6. SSH "integration" *cvscommand-ssh*
+
+The following instructions are intended for use in integrating the
+cvscommand.vim plugin with an SSH-based CVS environment.
+
+Familiarity with SSH and CVS are assumed.
+
+These instructions assume that the intent is to have a message box pop up in
+order to allow the user to enter a passphrase. If, instead, the user is
+comfortable using certificate-based authentication, then only instructions
+6.1.1 and 6.1.2 (and optionally 6.1.4) need to be followed; ssh should then
+work transparently.
+
+6.1 Environment settings *cvscommand-ssh-env*
+
+6.1.1 CVSROOT should be set to something like:
+
+ :ext:user@host:/path_to_repository
+
+6.1.2 CVS_RSH should be set to:
+
+ ssh
+
+ Together, those settings tell CVS to use ssh as the transport when
+ performing CVS calls.
+
+6.1.3 SSH_ASKPASS should be set to the password-dialog program. In my case,
+ running gnome, it's set to:
+
+ /usr/libexec/openssh/gnome-ssh-askpass
+
+ This tells SSH how to get passwords if no input is available.
+
+6.1.4 OPTIONAL. You may need to set SSH_SERVER to the location of the cvs
+ executable on the remote (server) machine.
+
+6.2 CVS wrapper program *cvscommand-ssh-wrapper*
+
+Now you need to convince SSH to use the password-dialog program. This means
+you need to execute SSH (and therefore CVS) without standard input. The
+following script is a simple perl wrapper that dissasociates the CVS command
+from the current terminal. Specific steps to do this may vary from system to
+system; the following example works for me on linux.
+
+#!/usr/bin/perl -w
+use strict;
+use POSIX qw(setsid);
+open STDIN, '/dev/null';
+fork and do {wait; exit;};
+setsid;
+exec('cvs', @ARGV);
+
+6.3 Configuring cvscommand.vim *cvscommand-ssh-config*
+
+At this point, you should be able to use your wrapper script to invoke CVS with
+various commands, and get the password dialog. All that's left is to make CVS
+use your newly-created wrapper script.
+
+6.3.1 Tell cvscommand.vim what CVS executable to use. The easiest way to do this
+ is globally, by putting the following in your .vimrc:
+
+ let CVSCommandCVSExec=/path/to/cvs/wrapper/script
+
+6.4 Where to go from here *cvscommand-ssh-other*
+
+The script given above works even when non-SSH CVS connections are used,
+except possibly when interactively entering the message for CVS commit log
+(depending on the editor you use... VIM works fine). Since the cvscommand.vim
+plugin handles that message without a terminal, the wrapper script can be used
+all the time.
+
+This allows mixed-mode operation, where some work is done with SSH-based CVS
+repositories, and others with pserver or local access.
+
+It is possible, though beyond the scope of the plugin, to dynamically set the
+CVS executable based on the CVSROOT for the file being edited. The user
+events provided (such as CVSBufferCreated and CVSBufferSetup) can be used to
+set a buffer-local value (b:CVSCommandCVSExec) to override the CVS executable
+on a file-by-file basis. Alternatively, much the same can be done (less
+automatically) by the various project-oriented plugins out there.
+
+It is highly recommended for ease-of-use that certificates with no passphrase
+or ssh-agent are employed so that the user is not given the password prompt
+too often.
+
+==============================================================================
+9. Tips *cvscommand-tips*
+
+9.1 Split window annotation, by Michael Anderson
+
+:nmap <Leader>cN :vs<CR><C-w>h<Leader>cn:vertical res 40<CR>
+ \ggdddd:set scb<CR>:set nowrap<CR><C-w>lgg:set scb<CR>
+ \:set nowrap<CR>
+
+This splits the buffer vertically, puts an annotation on the left (minus the
+header) with the width set to 40. An editable/normal copy is placed on the
+right. The two versions are scroll locked so they move as one. and wrapping
+is turned off so that the lines line up correctly. The advantages are...
+
+1) You get a versioning on the right.
+2) You can still edit your own code.
+3) Your own code still has syntax highlighting.
+
+==============================================================================
+
+8. Known bugs *cvscommand-bugs*
+
+Please let me know if you run across any.
+
+CVSUnedit may, if a file is changed from the repository, provide prompt text
+to determine whether the changes should be thrown away. Currently, that text
+shows up in the CVS result buffer as information; there is no way for the user
+to actually respond to the prompt and the CVS unedit command does nothing. If
+this really bothers anyone, please let me know.
+
+CVSVimDiff, when using the original (real) source buffer as one of the diff
+buffers, uses some hacks to try to restore the state of the original buffer
+when the scratch buffer containing the other version is destroyed. There may
+still be bugs in here, depending on many configuration details.
+
+vim:tw=78:ts=8:ft=help