*hgcommand.txt*	HGCommand

Author:  Mathieu Clabaut <mathieu.clabaut@gmail.com>

Credits:  Bob Hiestand <bob.hiestand@gmail.com>

1. Contents						*hgcommand-contents*

	Installation		: |hgcommand-install|

        HGCommand Intro	        : |hgcommand|

	HGCommand Manual	: |hgcommand-manual|

	Customization		: |hgcommand-customize|

	SSH "integration"	: |hgcommand-ssh|

	Bugs			: |hgcommand-bugs|

2. HGCommand Installation				*hgcommand-install*

The HGCommand plugin comprises two files, hgcommand.vim and hgcommand.txt

(this file).  In order to install the plugin, place the hgcommand.vim file

HGCommand may be customized by setting variables, creating maps, and

specifying event handlers.  Please see |hgcommand-customize| for more

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

|hgcommand-buffer-variables|).

For convenience, any HGCommand invoked on a HGCommand scratch buffer acts as

(though see |HGCommandInteractive| to prompt instead).

Each HGCommand is mapped to a key sequence starting with the <Leader>

|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|

|:HGUnedit|

|:HGUpdate|

|:HGVimDiff|

:HGAdd							*:HGAdd*

This command performs "hg add" on the current file.  Please note, this does

:HGAnnotate						*:HGAnnotate*

This command performs "hg annotate" on the current file.  If an argument is

Additionally, if the current buffer is a HGAnnotate buffer already, the

If the |HGCommandAnnotateParent| variable is set to a non-zero value, the

The filetype of the HGCommand scratch buffer is set to 'HGAnnotate', to take

:HGCommit[!]						*:HGCommit*

If called with arguments, this performs "hg commit" using the arguments as

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

:HGDiff						*:HGDiff*

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

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

With two arguments, hg diff is performed between the specified

This command uses the 'HGCommandDiffOpt' variable to specify diff options.

This command performs "hg edit" on the current file.

:HGGotoOriginal					*:HGGotoOriginal*

buffer is a HG command output buffer.

:HGGotoOriginal!

Like ":HGGotoOriginal" but also executes :bufwipeout on all HG command

:HGLog							*:HGLog*

Performs "hg log" on the current file.

"hg log".

:HGRevert						*:HGRevert*

:HGReview						*:HGReview*

:HGStatus						*:HGStatus*

Performs "hg status" on the current file.

:HGUnedit						*:HGUnedit*

Performs "hg unedit" on the current file.  Again, yes, the output buffer here

:HGUpdate						*:HGUpdate*

Performs "hg update" on the current file.  This intentionally does not

:HGVimDiff						*:HGVimDiff*

4.2 Mappings						*hgcommand-mappings*

<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>hgt HGUnedit

<Leader>hgu HGUpdate

<Leader>hgv HGVimDiff

						*hgcommand-mappings-override*

For instance, to override the default mapping for :HGAdd to set it to '\add',

nmap \add <Plug>HGAdd

4.3 Automatic buffer variables			*hgcommand-buffer-variables*

Several buffer variables are defined in each HGCommand result buffer.	These

handlers (please see |hgcommand-events|).

b:hgOrigBuffNR						*b:hgOrigBuffNR*

b:hgcmd						*b:hgcmd*

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

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*

|HGCommandAnnotateParent|

|HGCommandCommitOnWrite|

|HGCommandHGExec|

|HGCommandDeleteOnHide|

|HGCommandDiffOpt|

|HGCommandDiffSplit|

|HGCommandEdit|

|HGCommandEnableBufferSetup|

|HGCommandInteractive|

|HGCommandNameMarker|

|HGCommandNameResultBuffers|

|HGCommandSplit|

HGCommandAnnotateParent			*HGCommandAnnotateParent*

HGAnnotate when invoked on a HGAnnotate buffer to go to the version previous

HGCommandCommitOnWrite				*HGCommandCommitOnWrite*

This variable, if set to a non-zero value, causes the pending hg commit

If set to zero, only the HGCommit mapping will cause the pending commit to

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

HGCommandDiffOpt				*HGCommandDiffOpt*

HG.  If not set, it defaults to 'wbBc'.

HGCommandDiffSplit				*HGCommandDiffSplit*

This variable overrides the |HGCommandSplit| variable, but only for buffers

created with |:HGVimDiff|.

HGCommandEdit					*HGCommandEdit*

HGCommandEnableBufferSetup			*HGCommandEnableBufferSetup*

This variable, if set to a non-zero value, activates HG buffer management

mode see (|hgcommand-buffer-management|).  This mode means that two buffer

variables, 'HGRevision' and 'HGBranch', are set if the file is

HG-controlled.  This is useful for displaying version information in the

HGCommandInteractive				*HGCommandInteractive*

the moment, only |:HGReview|) to query the user for a revision to use instead

HGCommandNameMarker				*HGCommandNameMarker*

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

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

HGCommandSplit					*HGCommandSplit*

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'.

HGVimDiff windows.

5.2 HGCommand events				*hgcommand-events*

For additional customization, HGCommand can trigger user-defined events.

|autocommand|, |User|) in the HGCommand group with patterns matching the

mapping to quit a HGCommand scratch buffer:

augroup HGCommand

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

HGBufferCreated		This event is fired just after a hg command

				result of a hg command.  It is executed within

				the context of the HG command buffer.  The

				HGCommand buffer variables may be useful for

				|hgcommand-buffer-variables|).

HGBufferSetup			This event is fired just after HG buffer setup

HGPluginInit			This event is fired when the HGCommand plugin

HGPluginFinish			This event is fired just after the HGCommand

HGVimDiffFinish		This event is fired just after the HGVimDiff

5.3 HGCommand buffer naming				*hgcommand-naming*

By default, the buffers containing the result of HG commands are nameless

|HGCommandNameResultBuffers| variable.  Then, each result buffer will receive

a unique name that includes the source file name, the HG command, and any

5.4 HGCommand status line support			*hgcommand-statusline*

include HG result buffer attributes.  A sample function that may be used in

the |'statusline'| option is provided by the plugin, HGGetStatusLine().  In

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'

|HGCommandEnableBufferSetup| variable to a true (non-zero) value.  Enabling

the status line (but see |hgcommand-statusline| for a simple way to do that).

6. SSH "integration"					*hgcommand-ssh*

hgcommand.vim plugin with an SSH-based HG environment.

Familiarity with SSH and HG are assumed.

6.1 Environment settings				*hgcommand-ssh-env*

6.1.1 HGROOT should be set to something like:

6.1.2 HG_RSH should be set to:

	Together, those settings tell HG to use ssh as the transport when

	performing HG calls.

6.1.4 OPTIONAL.  You may need to set SSH_SERVER to the location of the hg

6.2 HG wrapper program				*hgcommand-ssh-wrapper*

you need to execute SSH (and therefore HG) without standard input.  The

following script is a simple perl wrapper that dissasociates the HG command