670 endfunction

   671 

   672 " Function: s:HGInstallDocumentation(full_name, revision)              {{{2

   673 "   Install help documentation.

   674 " Arguments:

   675 "   full_name: Full name of this vim plugin script, including path name.

   676 "   revision:  Revision of the vim script. #version# mark in the document file

   677 "              will be replaced with this string with 'v' prefix.

   678 " Return:

   679 "   1 if new document installed, 0 otherwise.

   680 " Note: Cleaned and generalized by guo-peng Wen

   681 "'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

   682 

   683 function! s:HGInstallDocumentation(full_name, revision)

   684     " Name of the document path based on the system we use:

   685     if (has("unix"))

   686         " On UNIX like system, using forward slash:

   687         let l:slash_char = '/'

   688         let l:mkdir_cmd  = ':silent !mkdir -p '

   689     else

   690         " On M$ system, use backslash. Also mkdir syntax is different.

   691         " This should only work on W2K and up.

   692         let l:slash_char = '\'

   693         let l:mkdir_cmd  = ':silent !mkdir '

   694     endif

   695 

   696     let l:doc_path = l:slash_char . 'doc'

   697     let l:doc_home = l:slash_char . '.vim' . l:slash_char . 'doc'

   698 

   699     " Figure out document path based on full name of this script:

   700     let l:vim_plugin_path = fnamemodify(a:full_name, ':h')

   701     let l:vim_doc_path    = fnamemodify(a:full_name, ':h:h') . l:doc_path

   702     if (!(filewritable(l:vim_doc_path) == 2))

   703         echomsg "Doc path: " . l:vim_doc_path

   704         execute l:mkdir_cmd . '"' . l:vim_doc_path . '"'

   705         if (!(filewritable(l:vim_doc_path) == 2))

   706             " Try a default configuration in user home:

   707             let l:vim_doc_path = expand("~") . l:doc_home

   708             if (!(filewritable(l:vim_doc_path) == 2))

   709                 execute l:mkdir_cmd . '"' . l:vim_doc_path . '"'

   710                 if (!(filewritable(l:vim_doc_path) == 2))

   711                     " Put a warning:

   712                     echomsg "Unable to open documentation directory"

   713                     echomsg " type :help add-local-help for more informations."

   714                     return 0

   715                 endif

   716             endif

   717         endif

   718     endif

   719 

   720     " Exit if we have problem to access the document directory:

   721     if (!isdirectory(l:vim_plugin_path)

   722         \ || !isdirectory(l:vim_doc_path)

   723         \ || filewritable(l:vim_doc_path) != 2)

   724         return 0

   725     endif

   726 

   727     " Full name of script and documentation file:

   728     let l:script_name = fnamemodify(a:full_name, ':t')

   729     let l:doc_name    = fnamemodify(a:full_name, ':t:r') . '.txt'

   730     let l:plugin_file = l:vim_plugin_path . l:slash_char . l:script_name

   731     let l:doc_file    = l:vim_doc_path    . l:slash_char . l:doc_name

   732 

   733     " Bail out if document file is still up to date:

   734     if (filereadable(l:doc_file)  &&

   735         \ getftime(l:plugin_file) < getftime(l:doc_file))

   736         return 0

   737     endif

   738 

   739     " Prepare window position restoring command:

   740     if (strlen(@%))

   741         let l:go_back = 'b ' . bufnr("%")

   742     else

   743         let l:go_back = 'enew!'

   744     endif

   745 

   746     " Create a new buffer & read in the plugin file (me):

   747     setl nomodeline

   748     exe 'enew!'

   749     exe 'r ' . l:plugin_file

   750 

   751     setl modeline

   752     let l:buf = bufnr("%")

   753     setl noswapfile modifiable

   754 

   755     norm zR

   756     norm gg

   757 

   758     " Delete from first line to a line starts with

   759     " === START_DOC

   760     1,/^=\{3,}\s\+START_DOC\C/ d

   761 

   762     " Delete from a line starts with

   763     " === END_DOC

   764     " to the end of the documents:

   765     /^=\{3,}\s\+END_DOC\C/,$ d

   766 

   767     " Remove fold marks:

   768     %s/{\{3}[1-9]/    /

   769 

   770     " Add modeline for help doc: the modeline string is mangled intentionally

   771     " to avoid it be recognized by VIM:

   772     call append(line('$'), '')

   773     call append(line('$'), ' v' . 'im:tw=78:ts=8:ft=help:norl:')

   774 

   775     " Replace revision:

   776     exe "normal :1s/#version#/ v" . a:revision . "/\<CR>"

   777 

   778     " Save the help document:

   779     exe 'w! ' . l:doc_file

   780     exe l:go_back

   781     exe 'bw ' . l:buf

   782 

   783     " Build help tags:

   784     exe 'helptags ' . l:vim_doc_path

   785 

   786     return 1

  1390 " Section: Doc installation {{{1

  1391 "

  1392   let s:revision="0.1"

  1393   silent! let s:install_status =

  1394       \ s:HGInstallDocumentation(expand('<sfile>:p'), s:revision)

  1395   if (s:install_status == 1)

  1396       echom expand("<sfile>:t:r") . ' v' . s:revision .

  1397 		\ ': Help-documentation installed.'

  1398   endif

  1399 

  1400 

  1406 finish

  1407 

  1408 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

  1409 " Section: Documentation content                                          {{{1

  1410 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

  1411 === START_DOC

  1412 *hgcommand.txt*	  Mercurial vim integration		             #version#

  1413 

  1414 

  1415 			 HGCOMMAND REFERENCE MANUAL~

  1416 

  1417 

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

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

  1420 Mercurial: http://www.selenic.com/mercurial

  1421    Mercurial (noted Hg) is a fast, lightweight Source Control Management

  1422    system designed for efficient handling of very large distributed projects.

  1423 

  1424 ==============================================================================

  1425 1. Contents						*hgcommand-contents*

  1426 

  1427 	Installation		: |hgcommand-install|

  1428         HGCommand Intro	        : |hgcommand|

  1429 	HGCommand Manual	: |hgcommand-manual|

  1430 	Customization		: |hgcommand-customize|

  1431 	SSH "integration"	: |hgcommand-ssh|

  1432 	Bugs			: |hgcommand-bugs|

  1433 

  1434 ==============================================================================

  1435                                                            *hgcommand-install*

  1436 2. HGCommand Installation				

  1437 

  1438    In order to install the plugin, place the hgcommand.vim file into a plugin' 

  1439    directory in your runtime path (please see |add-global-plugin| and 

  1440    |'runtimepath'|.

  1441 

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

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

  1444    details.

  1445 

  1446                                                          *hgcommand-auto-help*

  1447    The help file is automagically generated when the |vimspell| script is 

  1448    loaded for the first time.

  1449 

  1450 ==============================================================================

  1451 

  1452 3. HGCommand Intro					*hgcommand*

  1453 							*hgcommand-intro*

  1454 

  1455 The HGCommand plugin provides global ex commands for manipulating

  1456 HG-controlled source files.  In general, each command operates on the current

  1457 buffer and accomplishes a separate hg function, such as update, commit, log,

  1458 and others (please see |hgcommand-commands| for a list of all available

  1459 commands).  The results of each operation are displayed in a scratch buffer.

  1460 Several buffer variables are defined for those scratch buffers (please see

  1461 |hgcommand-buffer-variables|).

  1462 

  1463 The notion of "current file" means either the current buffer, or, in the case

  1464 of a directory buffer, the file on the current line within the buffer.

  1465 

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

  1467 though it was invoked on the original file and splits the screen so that the

  1468 output appears in a new window.

  1469 

  1470 Many of the commands accept revisions as arguments.  By default, most operate

  1471 on the most recent revision on the current branch if no revision is specified

  1472 (though see |HGCommandInteractive| to prompt instead).

  1473 

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

  1475 keystroke.  The default mappings may be overridden by supplying different

  1476 mappings before the plugin is loaded, such as in the vimrc, in the standard

  1477 fashion for plugin mappings.  For examples, please see

  1478 |hgcommand-mappings-override|.

  1479 

  1480 The HGCommand plugin may be configured in several ways.  For more details,

  1481 please see |hgcommand-customize|.

  1482 

  1483 ==============================================================================

  1484 

  1485 4. HGCommand Manual					*hgcommand-manual*

  1486 

  1487 4.1 HGCommand commands					*hgcommand-commands*

  1488 

  1489 HGCommand defines the following commands:

  1490 

  1491 |:HGAdd|

  1492 |:HGAnnotate|

  1493 |:HGCommit|

  1494 |:HGDiff|

  1495 |:HGGotoOriginal|

  1496 |:HGLog|

  1497 |:HGRevert|

  1498 |:HGReview|

  1499 |:HGStatus|

  1500 |:HGUnedit|

  1501 |:HGUpdate|

  1502 |:HGVimDiff|

  1503 

  1504 :HGAdd							*:HGAdd*

  1505 

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

  1507 not commit the newly-added file.

  1508 

  1509 :HGAnnotate						*:HGAnnotate*

  1510 

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

  1512 given, the argument is used as a revision number to display.  If not given an

  1513 argument, it uses the most recent version of the file on the current branch.

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

  1515 version number on the current line is used.

  1516 

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

  1518 version previous to the one on the current line is used instead.  This allows

  1519 one to navigate back to examine the previous version of a line.

  1520 

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

  1522 advantage of the bundled syntax file.

  1523 

  1524 

  1525 :HGCommit[!]						*:HGCommit*

  1526 

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

  1528 the log message.

  1529 

  1530 If '!' is used with no arguments, an empty log message is committed.

  1531 

  1532 If called with no arguments, this is a two-step command.  The first step opens

  1533 a buffer to accept a log message.  When that buffer is written, it is

  1534 automatically closed and the file is committed using the information from that

  1535 log message.  The commit can be abandoned if the log message buffer is deleted

  1536 or wiped before being written.

  1537 

  1538 Alternatively, the mapping that is used to invoke :HGCommit (by default

  1539 <Leader>hgc) can be used in the log message buffer to immediately commit.  

  1540 This

  1541 is useful if the |HGCommandCommitOnWrite| variable is set to 0 to disable the

  1542 normal commit-on-write behavior.

  1543 

  1544 :HGDiff						*:HGDiff*

  1545 

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

  1547 current repository version.

  1548 

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

  1550 specified revision.

  1551 

  1552 With two arguments, hg diff is performed between the specified

  1553 revisions of the current file.

  1554 

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

  1556 If that variable does not exist, then 'wbBc' is assumed.  If you wish to have

  1557 no options, then set it to the empty string.

  1558 

  1559 

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

  1561 

  1562 :HGGotoOriginal					*:HGGotoOriginal*

  1563 

  1564 This command returns the current window to the source buffer, if the current

  1565 buffer is a HG command output buffer.

  1566 

  1567 :HGGotoOriginal!

  1568 

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

  1570 output buffers for the source buffer.

  1571 

  1572 :HGLog							*:HGLog*

  1573 

  1574 Performs "hg log" on the current file.

  1575 

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

  1577 "hg log".

  1578 

  1579 :HGRevert						*:HGRevert*

  1580 

  1581 Replaces the current file with the most recent version from the repository in

  1582 order to wipe out any undesired changes.

  1583 

  1584 :HGReview						*:HGReview*

  1585 

  1586 Retrieves a particular version of the current file.  If no argument is given,

  1587 the most recent version of the file on the current branch is retrieved.

  1588 Otherwise, the specified version is retrieved.

  1589 

  1590 :HGStatus						*:HGStatus*

  1591 

  1592 Performs "hg status" on the current file.

  1593 

  1594 :HGUnedit						*:HGUnedit*

  1595 

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

  1597 is basically useless.

  1598 

  1599 :HGUpdate						*:HGUpdate*

  1600 

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

  1602 automatically reload the current buffer, though vim should prompt the user to

  1603 do so if the underlying file is altered by this command.

  1604 

  1605 :HGVimDiff						*:HGVimDiff*

  1606 

  1607 With no arguments, this prompts the user for a revision and then uses vimdiff

  1608 to display the differences between the current file and the specified

  1609 revision.  If no revision is specified, the most recent version of the file on

  1610 the current branch is used.

  1611 

  1612 With one argument, that argument is used as the revision as above.  With two

  1613 arguments, the differences between the two revisions is displayed using

  1614 vimdiff.

  1615 

  1616 With either zero or one argument, the original buffer is used to perform the

  1617 vimdiff.  When the other buffer is closed, the original buffer will be

  1618 returned to normal mode.

  1619 

  1620 Once vimdiff mode is started using the above methods, additional vimdiff

  1621 buffers may be added by passing a single version argument to the command.

  1622 There may be up to 4 vimdiff buffers total.

  1623 

  1624 Using the 2-argument form of the command resets the vimdiff to only those 2

  1625 versions.  Additionally, invoking the command on a different file will close

  1626 the previous vimdiff buffers.

  1627 

  1628 

  1629 4.2 Mappings						*hgcommand-mappings*

  1630 

  1631 By default, a mapping is defined for each command.  These mappings execute the

  1632 default (no-argument) form of each command.

  1633 

  1634 <Leader>hga HGAdd

  1635 <Leader>hgn HGAnnotate

  1636 <Leader>hgc HGCommit

  1637 <Leader>hgd HGDiff

  1638 <Leader>hgg HGGotoOriginal

  1639 <Leader>hgG HGGotoOriginal!

  1640 <Leader>hgl HGLog

  1641 <Leader>hgr HGReview

  1642 <Leader>hgs HGStatus

  1643 <Leader>hgt HGUnedit

  1644 <Leader>hgu HGUpdate

  1645 <Leader>hgv HGVimDiff

  1646 

  1647 						*hgcommand-mappings-override*

  1648 

  1649 The default mappings can be overriden by user-provided instead by mapping to

  1650 <Plug>CommandName.  This is especially useful when these mappings collide with

  1651 other existing mappings (vim will warn of this during plugin initialization,

  1652 but will not clobber the existing mappings).

  1653 

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

  1655 add the following to the vimrc:

  1656 

  1657 nmap \add <Plug>HGAdd

  1658 

  1659 4.3 Automatic buffer variables			*hgcommand-buffer-variables*

  1660 

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

  1662 may be useful for additional customization in callbacks defined in the event

  1663 handlers (please see |hgcommand-events|).

  1664 

  1665 The following variables are automatically defined:

  1666 

  1667 b:hgOrigBuffNR						*b:hgOrigBuffNR*

  1668 

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

  1670 

  1671 b:hgcmd						*b:hgcmd*

  1672 

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

  1674 buffer.

  1675 ==============================================================================

  1676 

  1677 5. Configuration and customization			*hgcommand-customize*

  1678 							*hgcommand-config*

  1679 

  1680 The HGCommand plugin can be configured in two ways:  by setting configuration

  1681 variables (see |hgcommand-options|) or by defining HGCommand event handlers

  1682 (see |hgcommand-events|).  Additionally, the HGCommand plugin provides

  1683 several option for naming the HG result buffers (see |hgcommand-naming|) and

  1684 supported a customized status line (see |hgcommand-statusline| and

  1685 |hgcommand-buffer-management|).

  1686 

  1687 5.1 HGCommand configuration variables			*hgcommand-options*

  1688 

  1689 Several variables affect the plugin's behavior.  These variables are checked

  1690 at time of execution, and may be defined at the window, buffer, or global

  1691 level and are checked in that order of precedence.

  1692 

  1693 

  1694 The following variables are available:

  1695 

  1696 |HGCommandAnnotateParent|

  1697 |HGCommandCommitOnWrite|

  1698 |HGCommandHGExec|

  1699 |HGCommandDeleteOnHide|

  1700 |HGCommandDiffOpt|

  1701 |HGCommandDiffSplit|

  1702 |HGCommandEdit|

  1703 |HGCommandEnableBufferSetup|

  1704 |HGCommandInteractive|

  1705 |HGCommandNameMarker|

  1706 |HGCommandNameResultBuffers|

  1707 |HGCommandSplit|

  1708 

  1709 HGCommandAnnotateParent			*HGCommandAnnotateParent*

  1710 

  1711 This variable, if set to a non-zero value, causes the zero-argument form of

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

  1713 to that displayed on the current line.  If not set, it defaults to 0.

  1714 

  1715 HGCommandCommitOnWrite				*HGCommandCommitOnWrite*

  1716 

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

  1718 to take place immediately as soon as the log message buffer is written.

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

  1720 occur.	If not set, it defaults to 1.

  1721 

  1722 HGCommandHGExec				*HGCommandHGExec*

  1723 

  1724 This variable controls the executable used for all HG commands  If not set,

  1725 it defaults to "hg".

  1726 

  1727 HGCommandDeleteOnHide				*HGCommandDeleteOnHide*

  1728 

  1729 This variable, if set to a non-zero value, causes the temporary HG result

  1730 buffers to automatically delete themselves when hidden.

  1731 

  1732 HGCommandDiffOpt				*HGCommandDiffOpt*

  1733 

  1734 This variable, if set, determines the options passed to the diff command of

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

  1736 

  1737 HGCommandDiffSplit				*HGCommandDiffSplit*

  1738 

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

  1740 created with |:HGVimDiff|.

  1741 

  1742 HGCommandEdit					*HGCommandEdit*

  1743 

  1744 This variable controls whether the original buffer is replaced ('edit') or

  1745 split ('split').  If not set, it defaults to 'edit'.

  1746 

  1747 HGCommandEnableBufferSetup			*HGCommandEnableBufferSetup*

  1748 

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

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

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

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

  1753 status bar.

  1754 

  1755 HGCommandInteractive				*HGCommandInteractive*

  1756 

  1757 This variable, if set to a non-zero value, causes appropriate commands (for

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

  1759 of the current revision if none is specified.

  1760 

  1761 HGCommandNameMarker				*HGCommandNameMarker*

  1762 

  1763 This variable, if set, configures the special attention-getting characters

  1764 that appear on either side of the hg buffer type in the buffer name.  This

  1765 has no effect unless |HGCommandNameResultBuffers| is set to a true value.  If

  1766 not set, it defaults to '_'.  

  1767 

  1768 HGCommandNameResultBuffers			*HGCommandNameResultBuffers*

  1769 

  1770 This variable, if set to a true value, causes the hg result buffers to be

  1771 named in the old way ('<source file name> _<hg command>_').  If not set

  1772 or set to a false value, the result buffer is nameless.

  1773 

  1774 HGCommandSplit					*HGCommandSplit*

  1775 

  1776 This variable controls the orientation of the various window splits that

  1777 may occur (such as with HGVimDiff, when using a HG command on a HG

  1778 command buffer, or when the |HGCommandEdit| variable is set to 'split'.

  1779 If set to 'horizontal', the resulting windows will be on stacked on top of

  1780 one another.  If set to 'vertical', the resulting windows will be

  1781 side-by-side.  If not set, it defaults to 'horizontal' for all but

  1782 HGVimDiff windows.

  1783 

  1784 5.2 HGCommand events				*hgcommand-events*

  1785 

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

  1787 Event handlers are provided by defining User event autocommands (see

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

  1789 event name.

  1790 

  1791 For instance, the following could be added to the vimrc to provide a 'q'

  1792 mapping to quit a HGCommand scratch buffer:

  1793 

  1794 augroup HGCommand

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

  1796 augroup END

  1797 

  1798 The following hooks are available:

  1799 

  1800 HGBufferCreated		This event is fired just after a hg command

  1801 				result buffer is created and filled with the

  1802 				result of a hg command.  It is executed within

  1803 				the context of the HG command buffer.  The

  1804 				HGCommand buffer variables may be useful for

  1805 				handlers of this event (please see

  1806 				|hgcommand-buffer-variables|).

  1807 

  1808 HGBufferSetup			This event is fired just after HG buffer setup

  1809 				occurs, if enabled.

  1810 

  1811 HGPluginInit			This event is fired when the HGCommand plugin

  1812 				first loads.

  1813 

  1814 HGPluginFinish			This event is fired just after the HGCommand

  1815 				plugin loads.

  1816 

  1817 HGVimDiffFinish		This event is fired just after the HGVimDiff

  1818 				command executes to allow customization of,

  1819 				for instance, window placement and focus.

  1820 

  1821 5.3 HGCommand buffer naming				*hgcommand-naming*

  1822 

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

  1824 scratch buffers.  It is intended that buffer variables of those buffers be

  1825 used to customize the statusline option so that the user may fully control the

  1826 display of result buffers.

  1827 

  1828 If the old-style naming is desired, please enable the

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

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

  1831 extra data (such as revision numbers) that were part of the command.

  1832 

  1833 5.4 HGCommand status line support			*hgcommand-statusline*

  1834 

  1835 It is intended that the user will customize the |'statusline'| option to

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

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

  1838 order to use that function in the status line, do something like the

  1839 following:

  1840 

  1841 set statusline=%<%f\ %{HGGetStatusLine()}\ %h%m%r%=%l,%c%V\ %P

  1842 

  1843 of which %{HGGetStatusLine()} is the relevant portion.

  1844 

  1845 The sample HGGetStatusLine() function handles both HG result buffers and

  1846 HG-managed files if HGCommand buffer management is enabled (please see

  1847 |hgcommand-buffer-management|).

  1848 

  1849 5.5 HGCommand buffer management		*hgcommand-buffer-management*

  1850 

  1851 The HGCommand plugin can operate in buffer management mode, which means that

  1852 it attempts to set two buffer variables ('HGRevision' and 'HGBranch') upon

  1853 entry into a buffer.  This is rather slow because it means that 'hg status'

  1854 will be invoked at each entry into a buffer (during the |BufEnter|

  1855 autocommand).

  1856 

  1857 This mode is disabled by default.  In order to enable it, set the

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

  1859 this mode simply provides the buffer variables mentioned above.  The user must

  1860 explicitly include those in the |'statusline'| option if they are to appear in

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

  1862 

  1863 ==============================================================================

  1864 

  1865 6. SSH "integration"					*hgcommand-ssh*

  1866 

  1867 The following instructions are intended for use in integrating the

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

  1869 

  1870 Familiarity with SSH and HG are assumed.

  1871 

  1872 These instructions assume that the intent is to have a message box pop up in

  1873 order to allow the user to enter a passphrase.  If, instead, the user is

  1874 comfortable using certificate-based authentication, then only instructions

  1875 6.1.1 and 6.1.2 (and optionally 6.1.4) need to be followed; ssh should then

  1876 work transparently.

  1877 

  1878 6.1 Environment settings				*hgcommand-ssh-env*

  1879 

  1880 6.1.1 HGROOT should be set to something like:

  1881 

  1882 	:ext:user@host:/path_to_repository

  1883 

  1884 6.1.2 HG_RSH should be set to:

  1885 

  1886 	ssh

  1887 

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

  1889 	performing HG calls.

  1890 

  1891 6.1.3 SSH_ASKPASS should be set to the password-dialog program.  In my case,

  1892 	running gnome, it's set to:

  1893 

  1894 	/usr/libexec/openssh/gnome-ssh-askpass

  1895 

  1896 	This tells SSH how to get passwords if no input is available.

  1897 

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

  1899 	executable on the remote (server) machine.

  1900 

  1901 6.2 HG wrapper program				*hgcommand-ssh-wrapper*

  1902 

  1903 Now you need to convince SSH to use the password-dialog program.  This means

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

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

  1906 from the current terminal.  Specific steps to do this may vary from system to

  1907 system; the following example works for me on linux.

  1908 

  1909 #!/usr/bin/perl -w

  1910 use strict;

  1911 use POSIX qw(setsid);

  1912 open STDIN, '/dev/null';

  1913 fork and do {wait; exit;};

  1914 setsid;

  1915 exec('hg', @ARGV);

  1916 

  1917 6.3 Configuring hgcommand.vim			*hgcommand-ssh-config*

  1918 

  1919 At this point, you should be able to use your wrapper script to invoke HG with

  1920 various commands, and get the password dialog.  All that's left is to make HG

  1921 use your newly-created wrapper script.

  1922 

  1923 6.3.1 Tell hgcommand.vim what HG executable to use.  The easiest way to do this

  1924 	is globally, by putting the following in your .vimrc:

  1925 

  1926 	let HGCommandHGExec=/path/to/hg/wrapper/script

  1927 

  1928 6.4 Where to go from here			*hgcommand-ssh-other*

  1929 

  1930 The script given above works even when non-SSH HG connections are used,

  1931 except possibly when interactively entering the message for HG commit log

  1932 (depending on the editor you use... VIM works fine).  Since the hgcommand.vim

  1933 plugin handles that message without a terminal, the wrapper script can be used

  1934 all the time.

  1935 

  1936 This allows mixed-mode operation, where some work is done with SSH-based HG

  1937 repositories, and others with pserver or local access.

  1938 

  1939 It is possible, though beyond the scope of the plugin, to dynamically set the

  1940 HG executable based on the HGROOT for the file being edited.  The user

  1941 events provided (such as HGBufferCreated and HGBufferSetup) can be used to

  1942 set a buffer-local value (b:HGCommandHGExec) to override the HG executable

  1943 on a file-by-file basis.  Alternatively, much the same can be done (less

  1944 automatically) by the various project-oriented plugins out there.

  1945 

  1946 It is highly recommended for ease-of-use that certificates with no passphrase

  1947 or ssh-agent are employed so that the user is not given the password prompt

  1948 too often.

  1949 

  1950 ==============================================================================

  1951 9. Tips							*hgcommand-tips*

  1952 

  1953 9.1 Split window annotation, by Michael Anderson

  1954 

  1955 :nmap <Leader>hgN :vs<CR><C-w>h<Leader>hgn:vertical res 40<CR>

  1956                  \ggdddd:set scb<CR>:set nowrap<CR><C-w>lgg:set scb<CR>

  1957                  \:set nowrap<CR>

  1958 

  1959 This splits the buffer vertically, puts an annotation on the left (minus the

  1960 header) with the width set to 40. An editable/normal copy is placed on the

  1961 right.  The two versions are scroll locked so they  move as one. and wrapping

  1962 is turned off so that the lines line up correctly. The advantages are...

  1963 

  1964 1) You get a versioning on the right.

  1965 2) You can still edit your own code.

  1966 3) Your own code still has syntax highlighting.

  1967 

  1968 ==============================================================================

  1969 

  1970 8. Known bugs						*hgcommand-bugs*

  1971 

  1972 Please let me know if you run across any.

  1973 

  1974 HGVimDiff, when using the original (real) source buffer as one of the diff

  1975 buffers, uses some hacks to try to restore the state of the original buffer

  1976 when the scratch buffer containing the other version is destroyed.  There may

  1977 still be bugs in here, depending on many configuration details.

  1978 

  1979 ==============================================================================

  1980 === END_DOC

  1981 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

  1982 " v im:tw=78:ts=8:ft=help:norl:

  1983 " vim600: set foldmethod=marker  tabstop=8 shiftwidth=2 softtabstop=2 smartindent smarttab  :

  1984 "fileencoding=iso-8859-15