view README.txt @ 200:3babbe517e2c

tweak release process
author Greg Ward <>
date Thu, 20 Feb 2014 20:59:53 -0500
parents a8a00e73b916
line source
1 vcprompt: version control information in your prompt
2 ====================================================
4 vcprompt is a little C program that prints a short string with
5 barebones information about the current working directory for various
6 version control systems. You configure your shell to include the
7 output of vcprompt in your prompt, and you get version control
8 information in your prompt.
10 vcprompt is designed to be small and lightweight rather than
11 comprehensive. Currently, it has varying degrees of support for
12 Mercurial, Git, Subversion, CVS, and Fossil working copies.
14 vcprompt has minimal dependencies: it does as much as it can with the
15 standard C library and POSIX calls. It should work on any
16 POSIX-compliant system with a C99 compiler. Some optional features
17 require external libraries (see "Dependencies" below).
19 To build vcprompt from the source tarball:
21 ./configure
22 make
24 If you're building in a source checkout, you also need GNU autoconf:
26 autoconf
27 ./configure
28 make
30 (vcprompt requires GNU make, so if you are using a BSD variant where
31 the default make is BSD make, you will need to install GNU make and
32 run "gmake".)
34 To install it in your home directory:
36 make install PREFIX=$HOME
38 To make life easier for packagers, the Makefile also supports DESTDIR:
40 make install DESTDIR=/tmp/packageroot PREFIX=/usr
42 Please report build failures to the development mailing list,
45 vcprompt includes a fairly comprehensive test suite. If you want to
46 run it, see "Testing" below.
49 Dependencies
50 ============
52 vcprompt requires GNU make to build.
54 vcprompt requires GNU autoconf to build from a source checkout (but
55 not from a source tarball).
57 Support for Subversion >= 1.7 requires SQLite 3. If it's not present on
58 the build system, vcprompt will support Subversion <= 1.6. Either way,
59 the build should succeed and the tests should pass. To install the
60 required files:
62 sudo apt-get install libsqlite3-dev # Debian, Ubuntu
63 sudo yum install libsqlite3x-devel # Fedora, Red Hat
65 If you have multiple versions of SQLite installed (this can be a
66 problem on Mac OS X), you might need to specify the installation
67 prefix of the one you want -- e.g., to use the brew package:
69 ./configure --with-sqlite3=/usr/local
71 To see which features are built-in to your vcprompt binary, run
73 ./vcprompt -F
76 Configuration
77 =============
79 (For more details, see the man page.)
81 To use it with bash, just call it in PS1:
83 PS1='\u@\h $(vcprompt)\$ '
85 To use it with zsh, you need to enable shell option PROMPT_SUBST, and
86 then do similarly to bash:
88 setopt prompt_subst
89 PROMPT='[%n@%m] [%~] $(vcprompt)'
92 Format Strings
93 ==============
95 You can customize the output of vcprompt using format strings, which
96 can be specified either on the command line or in the VCPROMPT_FORMAT
97 environment variable. For example:
99 vcprompt -f "%b"
101 and
103 VCPROMPT_FORMAT="%b" vcprompt
105 are equivalent.
107 Format strings use printf-like "%" escape sequences:
109 %n name of the VC system managing the current directory
110 (e.g. "cvs", "hg", "git", "svn")
111 %b current branch name
112 %r current revision
113 %u ? if there are any unknown files
114 %m + if there are any uncommitted changes (added, modified, or
115 removed files)
116 %% a single % character
118 All other characters are expanded as-is.
120 (For more details, see the man page.)
123 Testing
124 =======
126 To run vcprompt's test suite:
128 make check
130 Test failures should be loud and obvious. Please report any test
131 failures to the development mailing list:
135 To check for memory errors, you can run vcprompt's test suite under
136 valgrind:
138 make grind
140 Obviously, this requires that you have valgrind installed.
142 Testing multiple versions of the same tool
143 ------------------------------------------
145 Subversion changes its working copy format every couple of years, so
146 vcprompt supports three formats: the pre-1.4 XML format, the 1.4..1.6
147 plain-text format, and the post-1.7 SQLite format. Actually testing
148 these requires that you have different versions of Subversion on hand,
149 each installed in a separate prefix.
151 For example, I keep multiple versions in /usr/local/subversion-1.x, so
152 I can test them like this:
154 rm -f tests/svn-repo*.tar && make check-svn TOOLPATH=/usr/local/subversion-1.6/bin
155 rm -f tests/svn-repo*.tar && make check-svn TOOLPATH=/usr/local/subversion-1.7/bin
157 Actually *building* multiple versions of Subversion is harder than you
158 would believe. (In fact, I've been unable to build anything older than
159 1.5, so vcprompt's support for pre-1.4 working copies is currently
160 untested.)
162 TOOLPATH is supported for all tools; I also keep multiple versions of
163 Mercurial around, so I can test vcprompt against them:
165 rm -f tests/hg-repo.tar && make check-svn TOOLPATH=/usr/local/mercurial-2.4/bin
166 rm -f tests/hg-repo.tar && make check-svn TOOLPATH=/usr/local/mercurial-2.5/bin
167 [...etc...]
170 Contributing
171 ============
173 Patches are welcome. Please follow these guidelines:
175 * Ensure that the tests pass before and after your patch. To run the
176 tests quickly:
178 make check
180 To run the tests using valgrind (detect memory leaks):
182 make grind
184 If you cannot run the tests on a POSIX-compliant system, that is a
185 bug: please let me know.
187 * If at all possible, add a test whenever you fix a bug or implement
188 a feature. If you can write a test that has no dependencies (e.g.
189 no need to execute "git" or "hg" or whatever), add it to
190 tests/test-simple. Otherwise, add it to the appropriate
191 VC-specific test script, e.g. tests/test-git if it needs to be
192 able to run git.
194 * Keep the dependencies minimal: preferably just C99 and POSIX. If
195 you need to run an external executable, make sure it makes sense:
196 e.g. it's OK to run "git" in a git working directory, but *only*
197 if we already know we are in a git working directory.
199 * Performance matters! I wrote vcprompt so that people wouldn't have
200 to spawn and initialize an entire Python or Perl interpreter every
201 time they get a new shell prompt. Using system() to turn around
202 and spawn external commands -- especially ones that involve a
203 relatively large runtime penalty like Python scripts -- misses the
204 point of vcprompt.
206 In fact, you'll find that vcprompt contains hacky little
207 reimplementations of select bits and pieces of Mercurial, git,
208 Subversion, and CVS precisely in order to avoid running external
209 commands. (And, in the case of Subversion, to avoid depending on a
210 large, complex library.)
212 * Stick with my coding style:
213 - 4 space indents
214 - no tabs
215 - curly braces on the same line *except* when defining a function
216 - C99 comments and variable declarations are OK, at least until
217 someone complains that their compiler cannot handle them
219 * Feel free to add yourself to the contributors list below. (If you
220 don't do it, I'll probably forget.)
223 Author Contact
224 ==============
226 vcprompt was written by Greg Ward <greg at gerg dot ca>.
228 The latest version is available from either of my public Mercurial
229 repositories:
235 Other Contributors
236 ==================
238 In chronological order:
240 Daniel Serpell
241 Jannis Leidel
242 Yuya Nishihara
243 KOIE Hidetaka
244 Armin Ronacher
245 Jordi Fita
246 Gregg Lind
247 Jakob Kramer
248 Robson Roberto Souza Peixoto
249 Alexandre Carmel-Veilleux
251 Thanks to all!
254 Copyright & License
255 ===================
257 Copyright (C) 2009-2014, Gregory P. Ward and contributors.
259 This program is free software; you can redistribute it and/or modify
260 it under the terms of the GNU General Public License as published by
261 the Free Software Foundation; either version 2 of the License, or
262 (at your option) any later version.
264 This program is distributed in the hope that it will be useful,
265 but WITHOUT ANY WARRANTY; without even the implied warranty of
267 GNU General Public License for more details.
269 You should have received a copy of the GNU General Public License along
270 with this program; if not, write to the Free Software Foundation, Inc.,
271 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.