Mercurial > hg > mercurial-crew-with-dirclash
comparison contrib/vim/hgcommand.vim @ 2603:f80057407c07
HGcommand.vim : doc integration
author | "Mathieu Clabaut <mathieu.clabaut@gmail.com>" |
---|---|
date | Wed, 12 Jul 2006 23:50:34 +0200 |
parents | 457846f400e8 |
children | d93c23b31797 |
comparison
equal
deleted
inserted
replaced
2601:00fc88b0b256 | 2603:f80057407c07 |
---|---|
9 " Credits: {{{1 | 9 " Credits: {{{1 |
10 " Bob Hiestand <bob.hiestand@gmail.com> for the fabulous | 10 " Bob Hiestand <bob.hiestand@gmail.com> for the fabulous |
11 " cvscommand.vim from which this script was directly created by | 11 " cvscommand.vim from which this script was directly created by |
12 " means of sed commands and minor tweaks. | 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 " Provides functions to invoke various HG commands on the current file | 28 " Provides functions to invoke various HG commands on the current file |
17 " (either the current buffer, or, in the case of an directory buffer, the file | 29 " (either the current buffer, or, in the case of an directory buffer, the file |
18 " on the current line). The output of the commands is captured in a new | 30 " on the current line). The output of the commands is captured in a new |
19 " scratch window. For convenience, if the functions are invoked on a HG | 31 " scratch window. For convenience, if the functions are invoked on a HG |
653 execute 'bw' buffer | 665 execute 'bw' buffer |
654 endif | 666 endif |
655 endif | 667 endif |
656 let buffer = buffer + 1 | 668 let buffer = buffer + 1 |
657 endwhile | 669 endwhile |
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 | |
658 endfunction | 787 endfunction |
659 | 788 |
660 " Section: Public functions {{{1 | 789 " Section: Public functions {{{1 |
661 | 790 |
662 " Function: HGGetRevision() {{{2 | 791 " Function: HGGetRevision() {{{2 |
1256 | 1385 |
1257 if s:HGGetOption('HGCommandEnableBufferSetup', 0) | 1386 if s:HGGetOption('HGCommandEnableBufferSetup', 0) |
1258 call HGEnableBufferSetup() | 1387 call HGEnableBufferSetup() |
1259 endif | 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 " Section: Plugin completion {{{1 | 1401 " Section: Plugin completion {{{1 |
1262 | 1402 |
1263 let loaded_hgcommand=2 | 1403 let loaded_hgcommand=2 |
1264 silent do HGCommand User HGPluginFinish | 1404 silent do HGCommand User HGPluginFinish |
1265 " vim:se expandtab sts=2 sw=2: | 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 |