##// END OF EJS Templates
HGcommand.vim : doc integration
"Mathieu Clabaut " -
r2603:f8005740 default
parent child Browse files
Show More
This diff has been collapsed as it changes many lines, (721 lines changed) Show them Hide them
@@ -11,7 +11,19 b''
11 11 " cvscommand.vim from which this script was directly created by
12 12 " means of sed commands and minor tweaks.
13 13
14 " Section: Documentation {{{1
14 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
15 "
16 " Section: Documentation
17 "----------------------------
18 "
19 " Documentation should be available by ":help hgcommand" command, once the
20 " script has been copied in you .vim/plugin directory.
21 "
22 " You still can read the documentation at the end of this file. Locate it by
23 " searching the "hgcommand-contents" string (and set ft=help to have
24 " appropriate syntaxic coloration).
25 "
26 " Section: Documentation : detail {{{1
15 27 "
16 28 " Provides functions to invoke various HG commands on the current file
17 29 " (either the current buffer, or, in the case of an directory buffer, the file
@@ -657,6 +669,123 b' function! s:HGWipeoutCommandBuffers(orig'
657 669 endwhile
658 670 endfunction
659 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
787 endfunction
788
660 789 " Section: Public functions {{{1
661 790
662 791 " Function: HGGetRevision() {{{2
@@ -1258,8 +1387,598 b" if s:HGGetOption('HGCommandEnableBufferS"
1258 1387 call HGEnableBufferSetup()
1259 1388 endif
1260 1389
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
1261 1401 " Section: Plugin completion {{{1
1262 1402
1263 1403 let loaded_hgcommand=2
1264 1404 silent do HGCommand User HGPluginFinish
1265 1405 " vim:se expandtab sts=2 sw=2:
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
1 NO CONTENT: file was removed
This diff has been collapsed as it changes many lines, (567 lines changed) Show them Hide them
General Comments 0
You need to be logged in to leave comments. Login now