Mercurial > hg-stable
changeset 2603:f80057407c07
HGcommand.vim : doc integration
| author | "Mathieu Clabaut <mathieu.clabaut@gmail.com>" |
|---|---|
| date | Wed, 12 Jul 2006 23:50:34 +0200 |
| parents | 00fc88b0b256 |
| children | d93c23b31797 |
| files | contrib/vim/hgcommand.txt contrib/vim/hgcommand.vim |
| diffstat | 2 files changed, 720 insertions(+), 568 deletions(-) [+] |
line wrap: on
line diff
--- a/contrib/vim/hgcommand.txt Wed Jul 12 08:59:20 2006 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,567 +0,0 @@ -*hgcommand.txt* HGCommand - -For instructions on installing this file, type - :help add-local-help -inside Vim. - -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 -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. - -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. 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| -|:HGUnedit| -|: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. - - -This command performs "hg edit" on the current file. - -: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. - -:HGUnedit *:HGUnedit* - -Performs "hg unedit" on the current file. Again, yes, the output buffer here -is basically useless. - -: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>hgt HGUnedit -<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 'wbBc'. - -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 two buffer -variables, '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 disabled by default. In order to enable it, set the -|HGCommandEnableBufferSetup| 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 |hgcommand-statusline| for a simple way to do that). - -============================================================================== - -6. SSH "integration" *hgcommand-ssh* - -The following instructions are intended for use in integrating the -hgcommand.vim plugin with an SSH-based HG environment. - -Familiarity with SSH and HG 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 *hgcommand-ssh-env* - -6.1.1 HGROOT should be set to something like: - - :ext:user@host:/path_to_repository - -6.1.2 HG_RSH should be set to: - - ssh - - Together, those settings tell HG to use ssh as the transport when - performing HG 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 hg - executable on the remote (server) machine. - -6.2 HG wrapper program *hgcommand-ssh-wrapper* - -Now you need to convince SSH to use the password-dialog program. This means -you need to execute SSH (and therefore HG) without standard input. The -following script is a simple perl wrapper that dissasociates the HG 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('hg', @ARGV); - -6.3 Configuring hgcommand.vim *hgcommand-ssh-config* - -At this point, you should be able to use your wrapper script to invoke HG with -various commands, and get the password dialog. All that's left is to make HG -use your newly-created wrapper script. - -6.3.1 Tell hgcommand.vim what HG executable to use. The easiest way to do this - is globally, by putting the following in your .vimrc: - - let HGCommandHGExec=/path/to/hg/wrapper/script - -6.4 Where to go from here *hgcommand-ssh-other* - -The script given above works even when non-SSH HG connections are used, -except possibly when interactively entering the message for HG commit log -(depending on the editor you use... VIM works fine). Since the hgcommand.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 HG -repositories, and others with pserver or local access. - -It is possible, though beyond the scope of the plugin, to dynamically set the -HG executable based on the HGROOT for the file being edited. The user -events provided (such as HGBufferCreated and HGBufferSetup) can be used to -set a buffer-local value (b:HGCommandHGExec) to override the HG 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 *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. - -vim:tw=78:ts=8:ft=help
--- a/contrib/vim/hgcommand.vim Wed Jul 12 08:59:20 2006 -0700 +++ b/contrib/vim/hgcommand.vim Wed Jul 12 23:50:34 2006 +0200 @@ -11,7 +11,19 @@ " cvscommand.vim from which this script was directly created by " means of sed commands and minor tweaks. -" Section: Documentation {{{1 +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +" +" Section: Documentation +"---------------------------- +" +" Documentation should be available by ":help hgcommand" command, once the +" script has been copied in you .vim/plugin directory. +" +" You still can read the documentation at the end of this file. Locate it by +" searching the "hgcommand-contents" string (and set ft=help to have +" appropriate syntaxic coloration). +" +" Section: Documentation : detail {{{1 " " Provides functions to invoke various HG commands on the current file " (either the current buffer, or, in the case of an directory buffer, the file @@ -657,6 +669,123 @@ endwhile endfunction +" Function: s:HGInstallDocumentation(full_name, revision) {{{2 +" Install help documentation. +" Arguments: +" full_name: Full name of this vim plugin script, including path name. +" revision: Revision of the vim script. #version# mark in the document file +" will be replaced with this string with 'v' prefix. +" Return: +" 1 if new document installed, 0 otherwise. +" Note: Cleaned and generalized by guo-peng Wen +"''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +function! s:HGInstallDocumentation(full_name, revision) + " Name of the document path based on the system we use: + if (has("unix")) + " On UNIX like system, using forward slash: + let l:slash_char = '/' + let l:mkdir_cmd = ':silent !mkdir -p ' + else + " On M$ system, use backslash. Also mkdir syntax is different. + " This should only work on W2K and up. + let l:slash_char = '\' + let l:mkdir_cmd = ':silent !mkdir ' + endif + + let l:doc_path = l:slash_char . 'doc' + let l:doc_home = l:slash_char . '.vim' . l:slash_char . 'doc' + + " Figure out document path based on full name of this script: + let l:vim_plugin_path = fnamemodify(a:full_name, ':h') + let l:vim_doc_path = fnamemodify(a:full_name, ':h:h') . l:doc_path + if (!(filewritable(l:vim_doc_path) == 2)) + echomsg "Doc path: " . l:vim_doc_path + execute l:mkdir_cmd . '"' . l:vim_doc_path . '"' + if (!(filewritable(l:vim_doc_path) == 2)) + " Try a default configuration in user home: + let l:vim_doc_path = expand("~") . l:doc_home + if (!(filewritable(l:vim_doc_path) == 2)) + execute l:mkdir_cmd . '"' . l:vim_doc_path . '"' + if (!(filewritable(l:vim_doc_path) == 2)) + " Put a warning: + echomsg "Unable to open documentation directory" + echomsg " type :help add-local-help for more informations." + return 0 + endif + endif + endif + endif + + " Exit if we have problem to access the document directory: + if (!isdirectory(l:vim_plugin_path) + \ || !isdirectory(l:vim_doc_path) + \ || filewritable(l:vim_doc_path) != 2) + return 0 + endif + + " Full name of script and documentation file: + let l:script_name = fnamemodify(a:full_name, ':t') + let l:doc_name = fnamemodify(a:full_name, ':t:r') . '.txt' + let l:plugin_file = l:vim_plugin_path . l:slash_char . l:script_name + let l:doc_file = l:vim_doc_path . l:slash_char . l:doc_name + + " Bail out if document file is still up to date: + if (filereadable(l:doc_file) && + \ getftime(l:plugin_file) < getftime(l:doc_file)) + return 0 + endif + + " Prepare window position restoring command: + if (strlen(@%)) + let l:go_back = 'b ' . bufnr("%") + else + let l:go_back = 'enew!' + endif + + " Create a new buffer & read in the plugin file (me): + setl nomodeline + exe 'enew!' + exe 'r ' . l:plugin_file + + setl modeline + let l:buf = bufnr("%") + setl noswapfile modifiable + + norm zR + norm gg + + " Delete from first line to a line starts with + " === START_DOC + 1,/^=\{3,}\s\+START_DOC\C/ d + + " Delete from a line starts with + " === END_DOC + " to the end of the documents: + /^=\{3,}\s\+END_DOC\C/,$ d + + " Remove fold marks: + %s/{\{3}[1-9]/ / + + " Add modeline for help doc: the modeline string is mangled intentionally + " to avoid it be recognized by VIM: + call append(line('$'), '') + call append(line('$'), ' v' . 'im:tw=78:ts=8:ft=help:norl:') + + " Replace revision: + exe "normal :1s/#version#/ v" . a:revision . "/\<CR>" + + " Save the help document: + exe 'w! ' . l:doc_file + exe l:go_back + exe 'bw ' . l:buf + + " Build help tags: + exe 'helptags ' . l:vim_doc_path + + return 1 +endfunction + " Section: Public functions {{{1 " Function: HGGetRevision() {{{2 @@ -1258,8 +1387,598 @@ call HGEnableBufferSetup() endif +" Section: Doc installation {{{1 +" + let s:revision="0.1" + silent! let s:install_status = + \ s:HGInstallDocumentation(expand('<sfile>:p'), s:revision) + if (s:install_status == 1) + echom expand("<sfile>:t:r") . ' v' . s:revision . + \ ': Help-documentation installed.' + endif + + " Section: Plugin completion {{{1 let loaded_hgcommand=2 silent do HGCommand User HGPluginFinish " vim:se expandtab sts=2 sw=2: +finish + +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +" Section: Documentation content {{{1 +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +=== START_DOC +*hgcommand.txt* Mercurial vim integration #version# + + + 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| + SSH "integration" : |hgcommand-ssh| + Bugs : |hgcommand-bugs| + +============================================================================== + *hgcommand-install* +2. HGCommand Installation + + 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 |vimspell| 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| +|:HGUnedit| +|: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. + + +This command performs "hg edit" on the current file. + +: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. + +:HGUnedit *:HGUnedit* + +Performs "hg unedit" on the current file. Again, yes, the output buffer here +is basically useless. + +: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>hgt HGUnedit +<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 'wbBc'. + +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 two buffer +variables, '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 disabled by default. In order to enable it, set the +|HGCommandEnableBufferSetup| 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 |hgcommand-statusline| for a simple way to do that). + +============================================================================== + +6. SSH "integration" *hgcommand-ssh* + +The following instructions are intended for use in integrating the +hgcommand.vim plugin with an SSH-based HG environment. + +Familiarity with SSH and HG 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 *hgcommand-ssh-env* + +6.1.1 HGROOT should be set to something like: + + :ext:user@host:/path_to_repository + +6.1.2 HG_RSH should be set to: + + ssh + + Together, those settings tell HG to use ssh as the transport when + performing HG 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 hg + executable on the remote (server) machine. + +6.2 HG wrapper program *hgcommand-ssh-wrapper* + +Now you need to convince SSH to use the password-dialog program. This means +you need to execute SSH (and therefore HG) without standard input. The +following script is a simple perl wrapper that dissasociates the HG 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('hg', @ARGV); + +6.3 Configuring hgcommand.vim *hgcommand-ssh-config* + +At this point, you should be able to use your wrapper script to invoke HG with +various commands, and get the password dialog. All that's left is to make HG +use your newly-created wrapper script. + +6.3.1 Tell hgcommand.vim what HG executable to use. The easiest way to do this + is globally, by putting the following in your .vimrc: + + let HGCommandHGExec=/path/to/hg/wrapper/script + +6.4 Where to go from here *hgcommand-ssh-other* + +The script given above works even when non-SSH HG connections are used, +except possibly when interactively entering the message for HG commit log +(depending on the editor you use... VIM works fine). Since the hgcommand.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 HG +repositories, and others with pserver or local access. + +It is possible, though beyond the scope of the plugin, to dynamically set the +HG executable based on the HGROOT for the file being edited. The user +events provided (such as HGBufferCreated and HGBufferSetup) can be used to +set a buffer-local value (b:HGCommandHGExec) to override the HG 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 *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. + +============================================================================== +=== END_DOC +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +" v im:tw=78:ts=8:ft=help:norl: +" vim600: set foldmethod=marker tabstop=8 shiftwidth=2 softtabstop=2 smartindent smarttab : +"fileencoding=iso-8859-15