= src(1) =
:doctype: manpage
// SPDX-FileCopyrightText: Copyright Eric S. Raymond <esr@thyrsus.com>
// SPDX-License-Identifier: CC-BY-4.0

== NAME ==
src - simple revision control

== SYNOPSIS ==
*src* [command] [revision-spec] ['file'...]

== DESCRIPTION ==

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 single-file 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 records commit timestamps, but 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 is lightweight and fast. It uses two small self-contained executables,
with no libraries and no complications.

SRC interprets the EDITOR variable in the usual way, using it to spawn
an editor instance when you perform a commit or amend. If EDITOR is
not set it has a fallback list of editors it looks for, beginning with
various ways to invoke Emacs and vi.

SRC is fully supported in Emacs VC mode.

== COMMAND SUMMARY ==

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.

A filename can be a path. In that case SRC will behave as though
it were running in the lowest-level directory on the path and called
with the path basename.

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.

src help ['command']::
    Displays help for commands.

src commit [-|-m 'string'|-f 'file'|-e|-b branch] ['file'...]::
    Enters a commit for specified files.  Separately to each one.  A
    history is created for the file if it does not already exist.  With
    '-', take comment text from stdin; with '-m' use the following
    string as the comment; with '-f' take from a file.  With '-e', edit
    even after '-', '-f' or '-m'. "ci" is a synonym for "commit". With
    '-b', set the named branch to check in to (it must exist); that
    branch becomes the default for commits.

src amend [-|-m 'string'|-f 'file'|-e] ['revision'] ['file'...]::
    Amends the stored comment for a specified revision, defaulting to
    the latest revision on the current branch.  Flags are as for commit.
    "am" is a synonym for "amend".

src checkout ['revision'] ['file'...]::
    Refresh the working copy of the file(s) from their history files.
    "co" is a synonym for "checkout".

src cat ['revision'] ['file'...]::
    Send the specified revision of the files to standard output.

src status [-a] ['file'...]::
    "A" = added, "=" = unmodified, "M" = modified, "!" = missing, "?"
    = not tracked, "I" = ignored, "L" = locked (recover with "src
    checkout").  The "A" and "L" statuses should only occur if you have
    used RCS directly on a file.  Normally "?" and "I" files are not
    listed; this changes if you either give the '-a' switch or specify
    which files to look at. "st" is a synonym for "status".

src tag [list|-l|create|-c|delete|del|-d] ['name'] ['revision'] ['file'...]::
    List tags, create tags, or delete tags.  Create/delete takes a
    revision, defaulting to the current branch tip.  List defaults to all
    revisions.

src branch [list|-l|create|-c|delete|del|-d] ['name'] ['file'...]::
    List, create, or delete branches.  When listing, the active branch
    is first in the list.  The default branch is "trunk".  Create/delete
    takes a singleton revision, defaulting to the current branch tip;
    on create, the branch becomes default for future commits.
    List defaults to all revisions, including 0 (the trunk root phantom
    revision).

src rename ['tag'|'branch'] ['oldname'] ['newname']  ['file'...]::
    Rename a tag or branch.  Refuses to step on an existing symbol or
    rename a nonexistent one. "rn" is a synonym for "rename".

src list [(-<n>|-l <n>)] [-f 'fmt'] ['revision-range'] ['file'...]::
    Sends summary information about the specified commits to standard
    output.  The summary line tagged with "*" is the state that the
    file would return to on checkout without a revision-spec.  See 'help
    list' for information about custom formats.  Use '-<n>' or '-l <n>',
    where <n> is a number, to limit the listing length.  Default range
    is the current branch, reversed.  "li" is a synonym for "list".

src log [-v] [(-<n>|-l <n>)] [(-p|-u|-c) [-b|-w]] ['revision-range'] ['file'...]::
    Sends log information about the specified commits to standard
    output.  Use '-<n>' or '-l <n>', where <n> is a number, to limit the
    listing length.  Default range is the current branch, reversed.
    The '--patch', '-p' or '-u' option additionally sends a
    unified-format diff listing to standard output for each revision
    against its immediate ancestor revision; '-c' emits a context diff
    instead. When generating a diff, '-b' ignores changes in whitespace,
    and '-w' ignores all whitespace.  Histories imported via
    'fast-import' (when not using its '-p' option) have RFC-822-style
    headers inserted into the log comment to preserve metadata not
    otherwise representable in SRC, such as distinct author and
    committer identifications and dates.  These headers are normally
    suppressed by 'log', however, '-v' shows a summarized view of
    important headers; '-v -v' shows all headers as-is.

src diff [(-u|-c) [-b|-w]] ['revision-range'] ['file'...]::
    Sends a diff listing to standard output.  With no revision spec,
    diffs the working copy against the last version checked in.  With
    one revno, diffs the working copy against that stored revision; with
    a range, diff between the beginning and end of the range.
    The actual difference generation is done with diff(1).  The default
    diff format is '-u' (unified), but if you specify a '-c' option
    after the verb a context diff will be emitted. '-b' ignores changes
    in the amount of whitespace, and '-w' ignores all whitespace.
    "di" is a synonym for "diff".

src ls::
    List all registered files.

src visualize::
    Emit a DOT visualization of repository structures.  To use this,
    install the graphviz package and pipe the output to something like
    "dot -Tpng | display -". "vis" is a synonym for "visualize".

src move 'old' 'new'::
    Rename a workfile and its history.  Refuses to step on existing
    workfiles or histories. "mv" is a synonym for "move".

src copy 'old' 'new'::
    Copy a file and its master.  Refuses to step on existing files or
    masters. "cp" is a synonym for "copy".

src fast-export ['revision-range'] ['file'...]::
    Export one or more projects as a Git fast-import stream.  For a
    history originally imported from elsewhere, author and committer
    identification is gleaned from the RFC-822-style headers inserted
    into the commit comment by 'fast-import' (if its '-p' option was not
    used).  Otherwise, this information is copied from your Git
    configuration.

src fast-import [-p] ['files'...]::
    Parse a git-fast-import stream from standard input.  The
    modifications for each individual file become separate
    SRC histories.  Mark, committer and author data, and mark
    cross-references to parent commits, are preserved in RFC-822-style
    headers on log comments unless the '-p' (plain) option is given, in
    which case this metadata is discarded.  Give arguments to restrict
    the files imported.

src release ['file'...]::
    Release locks on files.  This is never necessary in a normal
    workflow, which will be repeated edit-commit cycles, but it may be
    handy if you have to interoperate with other tools that expect RCS
    masters to be in their normal (unlocked) state.

src srcify::
    Move a directory from being RCS- or SCCS-managed to being SRC-managed.
    That is: if the current directory contains an RCS directory, rename it
    to .src (but leave any SCCS directory in place).  Then check out all
    masters for editing that are not already checked out.

src version::
    Report the versions of SRC, the underlying Python, and the RCS or
    SCCS back end.

The omission of "src remove" is a deliberate speed bump.

If no files are specified, all eligible files are operated on in
sequence.

== NOISE CONTROL ==

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 ('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 "src status", but the output of 'src status
*' will list them with status "I".

== BACKWARD COMPATIBILITY ==

SRC history files are (normally) RCS master files.  SRC maintains no
permanent state other than these files.

In order to maintain complete backwards compatibility, one other
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.

The RCS back end will be automatically selected when there is an _.src_
or _RCS_ subdirectory. If both these directories exist, SRC will
operate on _.src_ and preserve the RCS directory; in this case it will
be a little extra verbose to leave no doubt about what it is doing.

You can explicitly select the RCS back end by making the first command
keyword on the src command line be 'rcs'.  This should only be necessary
when your working directory contains two or more of the subdirectories
_.src_, _RCS_, and _SCCS_.

If your directory has both a _.src_ and an unrelated _RCS_ directory
you can force SRC to work on the RCS directory and ignore _.src_ by
giving it the option "-S RCS".

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.

== WORKING WITH SCCS ==

Using SCCS as a back end is also supported, with some limits due to
missing features in SCCS implementations:

* All commands relating to tags and branches throw an error in the SCCS back end.

* In CSSC SCCS, src cat does not necessarily pipe out binary data
  correctly. This has been fixed in the SunOS and Schilling versions.

* The CSSC SCCS, the exec bit is not propagated between master and
  workfile. This has been fixed in the SunOS and Schilling versions.

* The CSSC and SunOS SCCS backends have a Y2.1K problem that SRC
  cannot effectively work around and will probably not be fixed.  The
  Schilling version has repaired this. To be on the safe side, do not
  use the SCCS backend after the year 2067.

The SCCS back end will be automatically selected when there is an _SCCS_
subdirectory and no _.src_ or _RCS_ subdirectory.

You can explicitly select the SCCS back end by making the first command
keyword on the src command line be 'sccs'.  This should only be
necessary when your working directory contains none or two or more of
the subdirectories _.src_, _RCS_, and _SCCS_.

Working with SCCS requires an _SCCS_ subdirectory; SRC will quietly
create one, if required, then operate on the files in the _SCCS_
directory in a completely backward-compatible way.

Fast-import to SCCS is not supported.

The SCCS mode is not recommended unless you have a specific need to
work with legacy SCCS repositories. Up-converting them to something
less Paleolithic (e.g. with sccs2rcs(1) or reposurgeon(1)) would be a
better idea; in truth, the SCCS support exists mainly because it's
hilarious (for obscure hacker values of 'hilarious').

== DEBUGGING OPTIONS ==

These will be of interest mainly to developers. They must go
before the subcommand.

A '-d' (debug) option before the main command word turns on debugging
messages. Just one "-d" gives you complete visibility about what
commands the back end is running and what (if any) diagnostic output
they ship. It can be repeated for higher debugging levels that expose
more of src's internal computation.

A '-L' option sets a log file to which debug output should be
written  Without this option it is written to standard error.

A '-S' (sandbox) option can be used to set the repository directory to
something other than its default of _.src_. Use "-S RCS" to make
src operate on an _RCS_ directory even if there is already a _.src_
directory.

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".  It is for regression
testing.

== REQUIREMENTS ==

SRC is written in Python and requires 2.7 or later; it will run under
Python 3.x for x > 2.

If you wish to use the RCS support (recommended), the RCS tools at
version 5.7 or later must be installed and accessible in your
$PATH.

If you wish to use the SCCS support, some implementation of SCCS must
be accessible. GNU's CSSC (Compatibly Stupid Source Control) will
work; so will the SunOS and Schilling forks of AT&T SCCS.

The rcs-fast-import(1) tool at version 1.3 or later is required to
support the 'src fast-import' command.

SRC will die gracefully with a useful error message when it fails
due to a missing back end.

== LIMITATIONS ==

SRC will unconditionally bail out if a directory named _RCS-save_
exists. This is because in order to be able to use _.src_ when an
unrelated _RCS_ subdirectory is also present, SRC has to play a game
of three-directory monte. Before doing its work it moves _RCS_ to
_RCS-save_, then moves _.src_ to __RCS__; after doing its work it
moves _RCS_ to _.src_ and _RCS-save_ to __RCS__. If there is a
pre-existing _RCS-save_ this maneuver can't be done. If you trip over
such a pre-exiting __RCS-save__, this probably means SRC previously
underwent a hard crash and you will have to reshuffle these directories
by hand. No bug that can produce such a crash has yet been reported.

The directory shuffle also means that running more than one SRC edit
session on the same directory at the same time may produce mysterious
failures. Don't do this - it is way outside the tool's intended
performance envelope.

Branch deletions change the revision numbers of revisions downstream of
the branch join.

In src fast-export dumps of repositories with tags, branch labels may
not exactly match what git fast-export would emit.

In both RCS and SCCS revision numbers normally looked like "1.n" for n
starting at 1 and monotonically increasing. It was possible to check
in a change with a higher release number (for example, "2.1"), though
this was seldom done.  If you use SRC to view or edit an ancient
master that used this feature, commands using ranges and named
branches will not always work as expected.

== REPORTING BUGS ==

Report bugs to Eric S. Raymond <esr@thyrsus.com>.  The project page is
at http://catb.org/~esr/src

== SEE ALSO ==

rcs(1), rcs-fast-import(1), sccs(1), svn(1), hg(1), git(1), dot(1), sccs2rcs.

// end