Initial import of my home directory

[home/.git] / .vim / doc / hgcommand.txt

*hgcommand.txt*   Mercurial vim integration                          v0.2


                         HGCOMMAND REFERENCE MANUAL~


Author:  Mathieu Clabaut <mathieu.clabaut@gmail.com>
Credits:  Bob Hiestand <bob.hiestand@gmail.com>
Mercurial: http://www.selenic.com/mercurial
   Mercurial (noted Hg) is a fast, lightweight Source Control Management
   system designed for efficient handling of very large distributed projects.

==============================================================================
1. Contents                                               *hgcommand-contents*

        Installation            : |hgcommand-install|
        HGCommand Intro         : |hgcommand|
        HGCommand Manual        : |hgcommand-manual|
        Customization           : |hgcommand-customize|
        Bugs                    : |hgcommand-bugs|

==============================================================================
2. HGCommand Installation                                  *hgcommand-install*

   In order to install the plugin, place the hgcommand.vim file into a plugin'
   directory in your runtime path (please see |add-global-plugin| and
   |'runtimepath'|.

   HGCommand may be customized by setting variables, creating maps, and
   specifying event handlers.  Please see |hgcommand-customize| for more
   details.

                                                         *hgcommand-auto-help*
   The help file is automagically generated when the |hgcommand| script is
   loaded for the first time.

==============================================================================

3. HGCommand Intro                                                 *hgcommand*
                                                             *hgcommand-intro*

   The HGCommand plugin provides global ex commands for manipulating
   HG-controlled source files.  In general, each command operates on the
   current buffer and accomplishes a separate hg function, such as update,
   commit, log, and others (please see |hgcommand-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 |hgcommand-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 HGCommand invoked on a HGCommand 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 |HGCommandInteractive| to prompt instead).

   Each HGCommand 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
   |hgcommand-mappings-override|.

   The HGCommand plugin may be configured in several ways.  For more details,
   please see |hgcommand-customize|.

==============================================================================
4. HGCommand Manual                                         *hgcommand-manual*

4.1 HGCommand commands                                    *hgcommand-commands*

   HGCommand defines the following commands:

      |:HGAdd|
      |:HGAnnotate|
      |:HGCommit|
      |:HGDiff|
      |:HGGotoOriginal|
      |:HGLog|
      |:HGRevert|
      |:HGReview|
      |:HGStatus|
      |:HGUpdate|
      |:HGVimDiff|

:HGAdd                                                                *:HGAdd*

   This command performs "hg add" on the current file.  Please note, this does
   not commit the newly-added file.

:HGAnnotate                                                      *:HGAnnotate*

   This command performs "hg 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 HGAnnotate buffer
   already, the version number on the current line is used.

   If the |HGCommandAnnotateParent| 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 HGCommand scratch buffer is set to 'HGAnnotate', to
   take advantage of the bundled syntax file.


:HGCommit[!]                                                       *:HGCommit*

   If called with arguments, this performs "hg 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 :HGCommit (by default
   <Leader>hgc) can be used in the log message buffer to immediately commit.
   This is useful if the |HGCommandCommitOnWrite| variable is set to 0 to
   disable the normal commit-on-write behavior.

:HGDiff                                                              *:HGDiff*

   With no arguments, this performs "hg diff" on the current file against the
   current repository version.

   With one argument, "hg diff" is performed on the current file against the
   specified revision.

   With two arguments, hg diff is performed between the specified revisions of
   the current file.

   This command uses the 'HGCommandDiffOpt' 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.


:HGGotoOriginal                                              *:HGGotoOriginal*

   This command returns the current window to the source buffer, if the
   current buffer is a HG command output buffer.

:HGGotoOriginal!

   Like ":HGGotoOriginal" but also executes :bufwipeout on all HG command
   output buffers for the source buffer.

:HGLog                                                                *:HGLog*

   Performs "hg log" on the current file.

   If an argument is given, it is passed as an argument to the "-r" option of
   "hg log".

:HGRevert                                                          *:HGRevert*

   Replaces the current file with the most recent version from the repository
   in order to wipe out any undesired changes.

:HGReview                                                          *:HGReview*

   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.

:HGStatus                                                          *:HGStatus*

   Performs "hg status" on the current file.

:HGUpdate                                                          *:HGUpdate*

   Performs "hg 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.

:HGVimDiff                                                        *:HGVimDiff*

   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.


4.2 Mappings                                              *hgcommand-mappings*

   By default, a mapping is defined for each command.  These mappings execute
   the default (no-argument) form of each command.

      <Leader>hga HGAdd
      <Leader>hgn HGAnnotate
      <Leader>hgc HGCommit
      <Leader>hgd HGDiff
      <Leader>hgg HGGotoOriginal
      <Leader>hgG HGGotoOriginal!
      <Leader>hgl HGLog
      <Leader>hgr HGReview
      <Leader>hgs HGStatus
      <Leader>hgu HGUpdate
      <Leader>hgv HGVimDiff

                                                 *hgcommand-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 :HGAdd to set it to
   '\add', add the following to the vimrc: >

      nmap \add <Plug>HGAdd
<
4.3 Automatic buffer variables                    *hgcommand-buffer-variables*

   Several buffer variables are defined in each HGCommand result buffer.
   These may be useful for additional customization in callbacks defined in
   the event handlers (please see |hgcommand-events|).

   The following variables are automatically defined:

b:hgOrigBuffNR                                                *b:hgOrigBuffNR*

   This variable is set to the buffer number of the source file.

b:hgcmd                                                              *b:hgcmd*

   This variable is set to the name of the hg command that created the result
   buffer.
==============================================================================

5. Configuration and customization                       *hgcommand-customize*
                                                            *hgcommand-config*

   The HGCommand plugin can be configured in two ways:  by setting
   configuration variables (see |hgcommand-options|) or by defining HGCommand
   event handlers (see |hgcommand-events|).  Additionally, the HGCommand
   plugin provides several option for naming the HG result buffers (see
   |hgcommand-naming|) and supported a customized status line (see
   |hgcommand-statusline| and |hgcommand-buffer-management|).

5.1 HGCommand configuration variables                      *hgcommand-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:

      |HGCommandAnnotateParent|
      |HGCommandCommitOnWrite|
      |HGCommandHGExec|
      |HGCommandDeleteOnHide|
      |HGCommandDiffOpt|
      |HGCommandDiffSplit|
      |HGCommandEdit|
      |HGCommandEnableBufferSetup|
      |HGCommandInteractive|
      |HGCommandNameMarker|
      |HGCommandNameResultBuffers|
      |HGCommandSplit|

HGCommandAnnotateParent                              *HGCommandAnnotateParent*

   This variable, if set to a non-zero value, causes the zero-argument form of
   HGAnnotate when invoked on a HGAnnotate buffer to go to the version
   previous to that displayed on the current line. If not set, it defaults to
   0.

HGCommandCommitOnWrite                                *HGCommandCommitOnWrite*

   This variable, if set to a non-zero value, causes the pending hg commit to
   take place immediately as soon as the log message buffer is written.  If
   set to zero, only the HGCommit mapping will cause the pending commit to
   occur.  If not set, it defaults to 1.

HGCommandHGExec                                              *HGCommandHGExec*

   This variable controls the executable used for all HG commands.  If not
   set, it defaults to "hg".

HGCommandDeleteOnHide                                  *HGCommandDeleteOnHide*

   This variable, if set to a non-zero value, causes the temporary HG result
   buffers to automatically delete themselves when hidden.

HGCommandDiffOpt                                            *HGCommandDiffOpt*

   This variable, if set, determines the options passed to the diff command of
   HG.  If not set, it defaults to 'w'.

HGCommandDiffSplit                                        *HGCommandDiffSplit*

   This variable overrides the |HGCommandSplit| variable, but only for buffers
   created with |:HGVimDiff|.

HGCommandEdit                                                  *HGCommandEdit*

   This variable controls whether the original buffer is replaced ('edit') or
   split ('split').  If not set, it defaults to 'edit'.

HGCommandEnableBufferSetup                        *HGCommandEnableBufferSetup*

   This variable, if set to a non-zero value, activates HG buffer management
   mode see (|hgcommand-buffer-management|).  This mode means that three
   buffer variables, 'HGRepository', 'HGRevision' and 'HGBranch', are set if
   the file is HG-controlled.  This is useful for displaying version
   information in the status bar.

HGCommandInteractive                                    *HGCommandInteractive*

   This variable, if set to a non-zero value, causes appropriate commands (for
   the moment, only |:HGReview|) to query the user for a revision to use
   instead of the current revision if none is specified.

HGCommandNameMarker                                      *HGCommandNameMarker*

   This variable, if set, configures the special attention-getting characters
   that appear on either side of the hg buffer type in the buffer name.  This
   has no effect unless |HGCommandNameResultBuffers| is set to a true value.
   If not set, it defaults to '_'.

HGCommandNameResultBuffers                        *HGCommandNameResultBuffers*

   This variable, if set to a true value, causes the hg result buffers to be
   named in the old way ('<source file name> _<hg command>_').  If not set or
   set to a false value, the result buffer is nameless.

HGCommandSplit                                                *HGCommandSplit*

   This variable controls the orientation of the various window splits that
   may occur (such as with HGVimDiff, when using a HG command on a HG command
   buffer, or when the |HGCommandEdit| 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 HGVimDiff windows.

5.2 HGCommand events                                        *hgcommand-events*

   For additional customization, HGCommand can trigger user-defined events.
   Event handlers are provided by defining User event autocommands (see
   |autocommand|, |User|) in the HGCommand 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 HGCommand scratch buffer: >

      augroup HGCommand
         au HGCommand User HGBufferCreated silent! nmap <unique> <buffer> q:
         bwipeout<cr>
      augroup END
<

   The following hooks are available:

HGBufferCreated         This event is fired just after a hg command result
                        buffer is created and filled with the result of a hg
                        command.  It is executed within the context of the HG
                        command buffer.  The HGCommand buffer variables may be
                        useful for handlers of this event (please see
                        |hgcommand-buffer-variables|).

HGBufferSetup           This event is fired just after HG buffer setup occurs,
                        if enabled.

HGPluginInit            This event is fired when the HGCommand plugin first
                        loads.

HGPluginFinish          This event is fired just after the HGCommand plugin
                        loads.

HGVimDiffFinish         This event is fired just after the HGVimDiff command
                        executes to allow customization of, for instance,
                        window placement and focus.

5.3 HGCommand buffer naming                                 *hgcommand-naming*

   By default, the buffers containing the result of HG 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
   |HGCommandNameResultBuffers| variable.  Then, each result buffer will
   receive a unique name that includes the source file name, the HG command,
   and any extra data (such as revision numbers) that were part of the
   command.

5.4 HGCommand status line support                       *hgcommand-statusline*

   It is intended that the user will customize the |'statusline'| option to
   include HG result buffer attributes.  A sample function that may be used in
   the |'statusline'| option is provided by the plugin, HGGetStatusLine().  In
   order to use that function in the status line, do something like the
   following: >

      set statusline=%<%f\ %{HGGetStatusLine()}\ %h%m%r%=%l,%c%V\ %P
<
   of which %{HGGetStatusLine()} is the relevant portion.

   The sample HGGetStatusLine() function handles both HG result buffers and
   HG-managed files if HGCommand buffer management is enabled (please see
   |hgcommand-buffer-management|).

5.5 HGCommand buffer management                  *hgcommand-buffer-management*

   The HGCommand plugin can operate in buffer management mode, which means
   that it attempts to set two buffer variables ('HGRevision' and 'HGBranch')
   upon entry into a buffer.  This is rather slow because it means that 'hg
   status' will be invoked at each entry into a buffer (during the |BufEnter|
   autocommand).

   This mode is enabled by default.  In order to disable it, set the
   |HGCommandEnableBufferSetup| variable to a false (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 |hgcommand-statusline| for a simple way
   to do that).

==============================================================================
9. Tips                                                       *hgcommand-tips*

9.1 Split window annotation, by Michael Anderson >

   :nmap <Leader>hgN :vs<CR><C-w>h<Leader>hgn: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                                                 *hgcommand-bugs*

   Please let me know if you run across any.

   HGVimDiff, 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.

==============================================================================

9. TODO                                                       *hgcommand-todo*

   Integrate symlink tracking once HG will support them.
==============================================================================

 vim:tw=78:ts=8:ft=help:norl: