Commits

Greg Ward committed 5649b8e

Beef up README.

Comments (0)

Files changed (1)

 working directory for various version control systems.  It is designed
 to be small and lightweight rather than comprehensive.
 
-Currently, it knows how to get (and print) the current branch for CVS,
-Git, and Mercurial working copies.  Eventually, I plan to add support
-for Subversion and Bazaar, and give it the (optional) ability to also
-indicate how dirty the working copy is, i.e. whether there are unknown
-files and whether there are local changes (modified/removed/added
-files).
+Currently, it has varying degrees of recognition for Mercurial, Git,
+CVS, and Subversion working copies.
 
-vcprompt currently has no external dependencies: it does everything with
-the standard C library.  I suspect this will not last long: e.g. to
-determine anything about a Subversion working copy will probably require
-using the Subversion C API.
+vcprompt has no external dependencies: it does everything with the
+standard C library and POSIX calls.  It should work on any
+POSIX-compliant system with a C99 compiler.
 
 To compile vcprompt:
 
 
   setopt prompt_subst
   PROMPT='[%n@%m] [%~] $(vcprompt)'
+
+vcprompt prints nothing if the current directory is not managed by a
+recognized VC system.
+
+
+Format Strings
+==============
+
+You can customize the output of vcprompt using format strings, which can
+be specified either on the command line or in the VCPROMPT_FORMAT
+environment variable.  For example:
+
+  vcprompt -f "%b"
+
+and
+
+  VCPROMPT_FORMAT="%b" vcprompt
+
+are equivalent.
+
+Format strings use printf-like "%" escape sequences:
+
+  %n  name of the VC system managing the current directory
+      (e.g. "cvs", "hg", "git", "svn")
+  %b  current branch name
+  %r  current revision
+  %u  ? if there are any unknown files
+  %m  + if there are any uncommitted changes (added, modified, or
+      removed files)
+  %%  a single % character
+
+All other characters are expanded as-is.
+
+The default format string is
+
+  [%n:%b]
+
+which is notable because it works with every supported VC system.  In
+fact, some features are meaningless with some systems: there is no
+single current revision with CVS, for example.  (And there is no good
+way to quickly find out if there are any uncommitted changes or unknown
+files, for that matter.)
+
+
+Contributing
+============
+
+Patches are welcome.  Please follow these guidelines:
+
+  * Ensure that the tests pass before and after your patch.
+    If you cannot run the tests on a POSIX-compliant system,
+    that is a bug: please let me know.
+
+  * If at all possible, add a test whenever you fix a bug or implement a
+    feature.  If you can write a test that has no dependencies (e.g. no
+    need to execute "git" or "hg" or whatever), add it to
+    tests/test-simple.  Otherwise, add it to the appropriate VC-specific
+    test script, e.g. tests/test-git if it needs to be able to run git.
+
+  * Keep the dependencies minimal: preferably just C99 and POSIX.
+    If you need to run an external executable, make sure it makes
+    sense: e.g. it's OK to run "git" in a git working directory, but
+    *only* if we already know we are in a git working directory.
+
+  * Performance matters!  I wrote vcprompt so that people wouldn't have
+    to spawn and initialize and entire Python or Perl interpreter every
+    time they execute a new shell command.  Using system() to turn
+    around and spawn external commands -- especially ones that involve a
+    relatively large runtime penalty like Python scripts -- misses the
+    point of vcprompt.
+
+    In fact, you'll find that vcprompt contains hacky little
+    reimplementations of select bits and pieces of Mercurial, git,
+    Subversion, and CVS precisely in order to avoid running external
+    commands.  (And, in the case of Subversion, to avoid depending on a
+    large, complex library.)
+
+  * Stick with my coding style:
+    - 4 space indents
+    - no tabs
+    - curly braces on the same line *except* when defining a function
+    - C99 comments and variable declarations are OK, at least until
+      someone complains that their compiler cannot handle them
+
+  
+Author Contact
+==============
+
+vcprompt was written by Greg Ward <greg at gerg dot ca>.
+
+The latest version is available from either of my public Mercurial
+repositories:
+
+  http://hg.gerg.ca/vcprompt/
+  https://bitbucket.org/gward/vcprompt/overview
+
+
+Other Contributors
+==================
+
+In chronological order:
+
+  Daniel Serpell
+  Jannis Leidel
+  Yuya Nishihara
+  KOIE Hidetaka
+  Armin Ronache
+
+Thanks to all!
+
+
+Copyright & License
+===================
+
+Copyright (c) 2009, 2010, Gregory P. Ward.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+  1. Redistributions of source code must retain the above copyright
+     notice, this list of conditions and the following disclaimer.
+  2. 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
+HOLDER 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.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.