src — simple revision control
SRC (or src) is simple revision control, a version-control system for single-file projects by solo developers and authors. It modernizes the venerable RCS, hence the anagrammatic acronym. The design is tuned for use cases like all those little scripts in your ~/bin directory, or a directory full of HOWTOs.
SRC revision histories are single, human-readable files beneath a hidden .src subdirectory in the directory where they live. There may be multiple histories under one directory; SRC treats them as separate projects, and history files can be moved elsewhere at any time.
SRC gives you simple, consecutive integer revision numbers. It supports tags and branching. It does not show committer information, because the committer is always you. The command set is intended to look familiar if you have ever used Subversion, Mercurial, or Git.
SRC interprets the EDITOR variable in the usual way, using it to spawn an editor instance when you perform a commit or amend.
SRC is fully supported in Emacs VC mode, though at time of writing only in the development tree.
A revision is a 1-origin integer, or a tag name designating an integer revision, or a branch name designating the tip revision of its branch. Revision numbers always increase in commit-date order.
A revision range is a single revision, or a pair of revisions M-N (all revisions numerically from M to N) or M..N (all revisions that are branch ancestors of N and branch successors of M).
If src complains that your revision spec looks like a nonexistent filename, you can prefix it with @ (this is always allowed). @ by itself means the current (checked-out) revision.
Unless otherwise noted under individual commands, the default revision is the tip revision on the current branch and the default range is all revisions on the current branch.
The token "--" tells the command-line interpreter that subcommands, switches, and revision-specs are done - everything after it is a filename, even if it looks like a subcommand or revision number.
The omission of src remove is a deliberate speed bump.
If no files are specified, all eligible files are operated on in sequence.
Silence is golden. When you have selected only one file to operate on, and the command is not a report generator (status, cat, log, list, fast-export, the listing modes of tag and branch, ls) you will see a reply only if the operation failed.
Other commands (add, commit, checkout, tag creation and deletion) give you a success message per file when operating on multiple files, so you will not be in doubt about which operation succeeded. This behavior can be suppressed with the -q option, placed before the subcommand word.
If your directory contains a file named ".srcignore", each line that
is neither blank nor begins with a "#" is interpreted as an ignore
pattern. It is expanded with glob(3), and files in the expansion are
omitted from src status - unless the file is named as an argument,
of the status command, in which case its status is "I". Thus, for
example, a line reading "*.html" will cause all files with an HTML
extension to be omitted from the output of "git status", but the
output of "git status *" will list them with status "I".
SRC history files are RCS master files. SRC maintains no permanent state other than these files. It keeps some transient state as stamp files to speed up src status.
In order to maintain complete backwards compatibility, one compromise was made: any commit comment containing a string exactly matching an RCS log delimiter (a long string of "-" characters) will be rejected as malformed.
By default, history files are kept in a hidden subdirectory named ".src". But if you have an RCS subdirectory and no .src, SRC will quietly operate on the files in the RCS directory in a completely backward-compatible way.
These will be of interest mainly to developers.
A -d (debug) option before the main command word turns on debugging messages; it can be repeated for higher debugging levels.
A -S (sandbox) option can be used to set the repository directory to something other than its default of ".src".
A -T option sets up an artificial clock that ticks once on each revision and fixes the user information to be used in fast-export; It also attributes all commits to J. Random Hacker and sets a constant screen width of 79. It’s for regression testing.
SRC is written in Python and requires 2.7 or later. The RCS tools at version 4 or later must be installed and accessible on your path. The rcs-fast-import(1) tool at version 1.0 or later is required to support the src fast-import command.
Branch deletions change the revision numbers of revisions downstream of the branch join. This behavior may change in a future release.
Report bugs to Eric S. Raymond <esr@thyrsus.com>. The project page is at http://catb.org/~esr/src