view README.txt @ 148:f1b7ef2052df
Add release instructions
|author||Greg Ward <firstname.lastname@example.org>|
|date||Thu, 02 May 2013 11:03:51 -0400|
4 vcprompt is a little C program that prints a short string, to be
5 included in your shell prompt, with barebones information about the
6 current working directory for various version control systems. It is
7 designed to be small and lightweight rather than comprehensive.
9 Currently, it has varying degrees of recognition for Mercurial, Git,
10 Subversion, CVS, and Fossil working copies.
12 vcprompt has no external dependencies: it does everything with the
13 standard C library and POSIX calls. It should work on any
14 POSIX-compliant system with a C99 compiler.
16 To compile vcprompt:
20 (vcprompt requires GNU make, so if you are using a BSD variant where
21 the default make is BSD make, you will need to install GNU make and
22 run "gmake".)
24 To install it:
26 make install PREFIX=$HOME
28 To make life easier for packagers, the Makefile also supports DESTDIR:
30 make install DESTDIR=/tmp/packageroot PREFIX=/usr
36 (For more details, see the man page.)
38 To use it with bash, just call it in PS1:
40 PS1='\u@\h $(vcprompt)\$ '
42 To use it with zsh, you need to enable shell option PROMPT_SUBST, and
43 then do similarly to bash:
45 setopt prompt_subst
46 PROMPT='[%n@%m] [%~] $(vcprompt)'
49 Format Strings
52 You can customize the output of vcprompt using format strings, which
53 can be specified either on the command line or in the VCPROMPT_FORMAT
54 environment variable. For example:
56 vcprompt -f "%b"
60 VCPROMPT_FORMAT="%b" vcprompt
62 are equivalent.
64 Format strings use printf-like "%" escape sequences:
66 %n name of the VC system managing the current directory
67 (e.g. "cvs", "hg", "git", "svn")
68 %b current branch name
69 %r current revision
70 %u ? if there are any unknown files
71 %m + if there are any uncommitted changes (added, modified, or
72 removed files)
73 %% a single % character
75 All other characters are expanded as-is.
77 (For more details, see the man page.)
83 Patches are welcome. Please follow these guidelines:
85 * Ensure that the tests pass before and after your patch. To run the
86 tests quickly:
88 make check
90 To run the tests using valgrind (detect memory leaks):
92 make grind
94 If you cannot run the tests on a POSIX-compliant system, that is a
95 bug: please let me know.
97 * If at all possible, add a test whenever you fix a bug or implement
98 a feature. If you can write a test that has no dependencies (e.g.
99 no need to execute "git" or "hg" or whatever), add it to
100 tests/test-simple. Otherwise, add it to the appropriate
101 VC-specific test script, e.g. tests/test-git if it needs to be
102 able to run git.
104 * Keep the dependencies minimal: preferably just C99 and POSIX. If
105 you need to run an external executable, make sure it makes sense:
106 e.g. it's OK to run "git" in a git working directory, but *only*
107 if we already know we are in a git working directory.
109 * Performance matters! I wrote vcprompt so that people wouldn't have
110 to spawn and initialize an entire Python or Perl interpreter every
111 time they execute a new shell command. Using system() to turn
112 around and spawn external commands -- especially ones that involve
113 a relatively large runtime penalty like Python scripts -- misses
114 the point of vcprompt.
116 In fact, you'll find that vcprompt contains hacky little
117 reimplementations of select bits and pieces of Mercurial, git,
118 Subversion, and CVS precisely in order to avoid running external
119 commands. (And, in the case of Subversion, to avoid depending on a
120 large, complex library.)
122 * Stick with my coding style:
123 - 4 space indents
124 - no tabs
125 - curly braces on the same line *except* when defining a function
126 - C99 comments and variable declarations are OK, at least until
127 someone complains that their compiler cannot handle them
129 * Feel free to add yourself to the contributors list below. (If you
130 don't do it, I'll probably forget.)
133 Author Contact
136 vcprompt was written by Greg Ward <greg at gerg dot ca>.
138 The latest version is available from either of my public Mercurial
145 Other Contributors
148 In chronological order:
150 Daniel Serpell
151 Jannis Leidel
152 Yuya Nishihara
153 KOIE Hidetaka
154 Armin Ronacher
155 Jordi Fita
156 Gregg Lind
157 Jakob Kramer
159 Thanks to all!
162 Copyright & License
165 Copyright (C) 2009-2013, Gregory P. Ward and contributors.
167 This program is free software; you can redistribute it and/or modify
168 it under the terms of the GNU General Public License as published by
169 the Free Software Foundation; either version 2 of the License, or
170 (at your option) any later version.
172 This program is distributed in the hope that it will be useful,
173 but WITHOUT ANY WARRANTY; without even the implied warranty of
174 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
175 GNU General Public License for more details.
177 You should have received a copy of the GNU General Public License along
178 with this program; if not, write to the Free Software Foundation, Inc.,
179 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.