doc/hgrev.txt
branchvim-stuff
changeset 29 dda9eb90cf5d
parent 27 595320486f69
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/hgrev.txt	Sat Jan 16 11:36:34 2016 -0800
@@ -0,0 +1,167 @@
+*hgrev.txt* Last change: $Id$
+
+                VIM REFERENCE MANUAL    by Mahlon E. Smith
+
+
+                                   HGRev
+
+A simple plugin for showing the current buffer's HG revision           *HGRev*
+==============================================================================
+CONTENTS                                                       *HGRevContents*
+
+
+    1) Intro........................................|HGRevIntro|
+    2) Configuration................................|HGRevOptions|
+        2.1) Altering revision info shown...........|g:hgrevFlags|
+        2.2) Appending file status info.............|g:hgrevAddStatus|
+        2.3) Automatically updating status..........|g:hgrevAutoUpdate|
+        2.4) Changing non-repo buffer behavior......|g:hgrevNoRepoChar|
+    3) Author.......................................|HGRevAuthor|
+    4) License......................................|HGRevLicense|
+
+
+
+==============================================================================
+1. INTRO                                                          *HGRevIntro*
+
+HGRev is a small plugin that can find the current buffer's revision ID from a
+Mercurial repository.  For more information on Mercurial, see:
+
+	http://mercurial.selenic.com/
+
+It is intended for use in the |statusline|- here's an example to enable it:
+
+	set statusline=[r%{HGRev()}] ~
+
+HGRev exports the 'HGRev()' function (for use in the statusline), and a
+command called
+>
+	:RefreshMercurialRev
+
+Which you can use to manually update the revision information for the current
+buffer.  If you've added HGRev() to your statusline, you'll see the file
+revision, branch, tags, and file status reflected -- if you used the
+statusline example above, you should see something like this:
+
+	[r192+ default tip M] ~
+
+The information displayed can be easily customized, and HGRev can also
+automatically update the status line on file changes.  (This behavior is
+disabled by default.)
+
+
+==============================================================================
+2. CONFIGURATION-OPTIONS                                        *HGRevOptions*
+
+Here are the available configuration options and their defaults:
+>
+	let g:hgrevFlags = '-nbt'
+	let g:hgrevAddStatus = 1
+	let g:hgrevAutoUpdate = 0
+	let g:hgrevNoRepoChar = '-'
+
+
+------------------------------------------------------------------------------
+2.1                                                             *g:hgrevFlags*
+
+These are the flags passed directly to 'hg id'.  The flags "-nbt" are passed
+by default, which show a local rev id, branch, and tags.
+
+If you wanted to show the global rev hash (and nothing else) as an example,
+you can set this to:
+>
+	let g:hgrevFlags = '-i'
+
+
+------------------------------------------------------------------------------
+2.2                                                         *g:hgrevAddStatus*
+
+This settings will append the current file status to the output, by running
+'hg stat'.  I find it useful, so it is enabled by default -- you can disable
+it like so:
+>
+	let g:hgrevAddStatus = 0
+>
+
+------------------------------------------------------------------------------
+2.3                                                        *g:hgrevAutoUpdate*
+>
+When this option is enabled, some |autocmd-events| are added that
+automatically call :RefreshMercurialRev on file changes -- when a buffer is
+read, written to, or modified outside of Vim.  This is disabled by default, as
+the additional time needed (however small) to system() to hg for every
+read/write outweighs running :RefreshMercurialRev manually for my tastes.
+Yours tastes, of course, may vary, so you can enable it like so:
+>
+	let g:hgrevAutoUpdate = 1
+
+Alternatively, you can leave it disabled, and add your own |autocmd| events
+for :RefreshMercurialRev to what works best for you.
+
+
+------------------------------------------------------------------------------
+2.4                                                        *g:hgrevNoRepoChar*
+>
+If the current buffer doesn't seem to be a member of a Mercurial repository,
+HGRev() returns this character instead of a revision ID.
+
+Some examples:
+>
+	let g:hgrevNoRepoChar = '-'    (default)
+	set statusline=[r%{HGRev()}]
+
+This will output something like '[r12+ default tip M]' for repo files,
+and '[r-]' for non-repo.
+>
+	let g:hgrevNoRepoChar = ''
+	set statusline=%{HGRev()?'[r'.HGRev().']':''}
+
+This will output something like '[r512 default tip]' for repo files, and
+nothing at all for non-repo.
+
+
+==============================================================================
+3. AUTHOR                                                        *HGRevAuthor*
+
+HGRev was written by Mahlon E. Smith.
+
+    mahlon@martini.nu ~
+    http://www.martini.nu/ 
+
+
+
+==============================================================================
+4. LICENSE                                                      *HGRevLicense*
+
+HGRev is distributed under the BSD license.
+    http://www.opensource.org/licenses/bsd-license.php
+>
+    Copyright (c) 2010-2012, Mahlon E. Smith <mahlon@martini.nu>
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are
+    met:
+
+        * Redistributions of source code must retain the above copyright
+          notice, this list of conditions and the following disclaimer.
+
+        * Redistributions in binary form must reproduce the above copyright
+          notice, this list of conditions and the following disclaimer in the
+          documentation and/or other materials provided with the distribution.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+    TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+
+vim: set noet nosta sw=4 ts=4 ft=help :