hgrev/doc/hgrev.txt
branchvim-stuff
changeset 15 285603587539
child 16 88c3c5bc695a
equal deleted inserted replaced
14:c7136005d459 15:285603587539
       
     1 *hgrev.txt* Last change: $Id$
       
     2 
       
     3                 VIM REFERENCE MANUAL    by Mahlon E. Smith
       
     4 
       
     5 
       
     6                                    HGRev
       
     7 
       
     8 A simple plugin for showing the current buffer's HG revision           *HGRev*
       
     9 ==============================================================================
       
    10 CONTENTS                                                       *HGRevContents*
       
    11 
       
    12 
       
    13     1) Intro........................................|HGRevIntro|
       
    14     2) Configuration................................|HGRevOptions|
       
    15         2.1) Altering revision info shown...........|g:hgrevFlags|
       
    16         2.2) Appending file status info.............|g:hgrevAddStatus|
       
    17         2.3) Automatically updating status..........|g:hgrevAutoUpdate|
       
    18         2.4) Automatically updating status..........|g:hgrevAutoUpdate|
       
    19     3) Author.......................................|HGRevAuthor|
       
    20     4) License......................................|HGRevLicense|
       
    21 
       
    22 
       
    23 
       
    24 ==============================================================================
       
    25 1. INTRO                                                          *HGRevIntro*
       
    26 
       
    27 HGRev is a small plugin that can find the current buffer's revision ID from a
       
    28 Mercurial repository.  For more information on Mercurial, see:
       
    29 
       
    30 	http://mercurial.selenic.com/
       
    31 
       
    32 It is intended for use in the |statusline|- here's an example to enable it:
       
    33 
       
    34 	set statusline=[r%{HGRev()}] ~
       
    35 
       
    36 HGRev exports the 'HGRev()' function (for use in the statusline), and a
       
    37 command called
       
    38 >
       
    39 	:RefreshMercurialRev
       
    40 
       
    41 Which you can use to manually update the revision information for the current
       
    42 buffer.  If you've added HGRev() to your statusline, you'll see the file
       
    43 revision, branch, tags, and file status reflected -- if you used the
       
    44 statusline example above, you should see something like this:
       
    45 
       
    46 	[r192+ default tip M] ~
       
    47 
       
    48 The information displayed can be easily customized, and HGRev can also
       
    49 automatically update the status line on file changes.  (This behavior is
       
    50 disabled by default.)
       
    51 
       
    52 
       
    53 ==============================================================================
       
    54 2. CONFIGURATION-OPTIONS                                        *HGRevOptions*
       
    55 
       
    56 Here are the available configuration options and their defaults:
       
    57 >
       
    58 	let g:hgrevFlags = '-nbt'
       
    59 	let g:hgrevAddStatus = 1
       
    60 	let g:hgrevAutoUpdate = 0
       
    61 	let g:hgrevNoRepoChar = '-'
       
    62 
       
    63 
       
    64 ------------------------------------------------------------------------------
       
    65 2.1                                                             *g:hgrevFlags*
       
    66 
       
    67 These are the flags passed directly to 'hg id'.  The flags "-nbt" are passed
       
    68 by default, which show a local rev id, branch, and tags.
       
    69 
       
    70 If you wanted to show the global rev hash (and nothing else) as an example,
       
    71 you can set this to:
       
    72 >
       
    73 	let g:hgrevFlags = '-i'
       
    74 
       
    75 
       
    76 ------------------------------------------------------------------------------
       
    77 2.2                                                         *g:hgrevAddStatus*
       
    78 
       
    79 This settings will append the current file status to the output, by running
       
    80 'hg stat'.  I find it useful, so it is enabled by default -- you can disable
       
    81 it like so:
       
    82 >
       
    83 	let g:hgrevAddStatus = 0
       
    84 >
       
    85 
       
    86 ------------------------------------------------------------------------------
       
    87 2.3                                                        *g:hgrevAutoUpdate*
       
    88 >
       
    89 When this option is enabled, some |autocmd-events| are added that
       
    90 automatically call :RefreshMercurialRev on file changes -- when a buffer is
       
    91 read, written to, or modified outside of Vim.  This is disabled by default, as
       
    92 the additional time needed (however small) to system() to hg for every
       
    93 read/write outweighs running :RefreshMercurialRev manually for my tastes.
       
    94 Yours tastes, of course, may vary, so you can enable it like so:
       
    95 >
       
    96 	let g:hgrevAutoUpdate = 1
       
    97 
       
    98 Alternatively, you can leave it disabled, and add your own |autocmd| events
       
    99 for :RefreshMercurialRev to what works best for you.
       
   100 
       
   101 
       
   102 ------------------------------------------------------------------------------
       
   103 2.4                                                        *g:hgrevNoRepoChar*
       
   104 >
       
   105 If the current buffer doesn't seem to be a member of a Mercurial repository,
       
   106 HGRev() returns this character instead of a revision ID.
       
   107 
       
   108 Some examples:
       
   109 >
       
   110 	let g:hgrevNoRepoChar = '-'    (default)
       
   111 	set statusline=[r%{HGRev()}]
       
   112 
       
   113 This will output something like '[r12+ default tip M]' for repo files,
       
   114 and '[r-]' for non-repo.
       
   115 >
       
   116 	let g:hgrevNoRepoChar = ''
       
   117 	set statusline=%{HGRev()?'[r'.HGRev().']':''}
       
   118 
       
   119 This will output something like '[r512 default tip]' for repo files, and
       
   120 nothing at all for non-repo.
       
   121 
       
   122 
       
   123 ==============================================================================
       
   124 3. AUTHOR                                                          *HGRAuthor*
       
   125 
       
   126 HGRev was written by Mahlon E. Smith.
       
   127 
       
   128     mahlon@martini.nu ~
       
   129     http://www.martini.nu/ 
       
   130 
       
   131 
       
   132 
       
   133 ==============================================================================
       
   134 4. LICENSE                                                      *HGRevLicense*
       
   135 
       
   136 HGRev is distributed under the BSD license.
       
   137     http://www.opensource.org/licenses/bsd-license.php
       
   138 >
       
   139     Copyright (c) 2010, Mahlon E. Smith <mahlon@martini.nu>
       
   140     All rights reserved.
       
   141 
       
   142     Redistribution and use in source and binary forms, with or without
       
   143     modification, are permitted provided that the following conditions are
       
   144     met:
       
   145 
       
   146         * Redistributions of source code must retain the above copyright
       
   147           notice, this list of conditions and the following disclaimer.
       
   148 
       
   149         * Redistributions in binary form must reproduce the above copyright
       
   150           notice, this list of conditions and the following disclaimer in the
       
   151           documentation and/or other materials provided with the distribution.
       
   152 
       
   153     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
       
   154     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
       
   155     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
       
   156     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
       
   157     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
       
   158     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
       
   159     TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
       
   160     PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
       
   161     LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
       
   162     NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
       
   163     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
       
   164 
       
   165 
       
   166 
       
   167 vim: set noet nosta sw=4 ts=4 ft=help :