diff options
Diffstat (limited to 'src.1')
| -rw-r--r-- | src.1 | 311 |
1 files changed, 311 insertions, 0 deletions
@@ -0,0 +1,311 @@ +'\" t +.\" Title: src +.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] +.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/> +.\" Date: 10/28/2018 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "SRC" "1" "10/28/2018" "\ \&" "\ \&" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +src \- simple revision control +.SH "SYNOPSIS" +.sp +\fBsrc\fR [command] [revision\-spec] [\fIfile\fR\&...] +.SH "DESCRIPTION" +.sp +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\&. +.sp +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\&. +.sp +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\&. +.sp +SRC interprets the EDITOR variable in the usual way, using it to spawn an editor instance when you perform a commit or amend\&. +.sp +SRC is fully supported in Emacs VC mode\&. +.SH "COMMAND SUMMARY" +.sp +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\&. +.sp +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)\&. +.sp +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\&. +.sp +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\&. +.sp +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\&. +.PP +src help [\fIcommand\fR] +.RS 4 +Displays help for commands\&. +.RE +.PP +src commit [\-|\-m \fIstring\fR|\-f \fIfile\fR|\-e] [\fIfile\fR\&...] +.RS 4 +Enters a commit for specified files\&. Separately to each one\&. A history is created for the file if it does not already exist\&. With +\fI\-\fR, take comment text from stdin; with +\fI\-m\fR +use the following string as the comment; with +\fI\-f\fR +take from a file\&. With +\fI\-e\fR, edit even after +\fI\-\fR, +\fI\-f\fR +or +\fI\-m\fR\&. "ci" is a synonym for "commit"\&. +.RE +.PP +src amend [\-|\-m \fIstring\fR|\-f \fIfile\fR|\-e] [\fIrevision\fR] [\fIfile\fR\&...] +.RS 4 +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"\&. +.RE +.PP +src checkout [\fIrevision\fR] [\fIfile\fR\&...] +.RS 4 +Refresh the working copy of the file(s) from their history files\&. "co" is a synonym for "checkout"\&. +.RE +.PP +src cat [\fIrevision\fR] [\fIfile\fR\&...] +.RS 4 +Send the specified revision of the files to standard output\&. +.RE +.PP +src status [\-a] [\fIfile\fR\&...] +.RS 4 +"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 +\fI\-a\fR +switch or specify which files to look at\&. "st" is a synonym for "status"\&. +.RE +.PP +src tag [list|\-l|create|\-c|delete|del|\-d] [\fIname\fR] [\fIrevision\fR] [\fIfile\fR\&...] +.RS 4 +List tags, create tags, or delete tags\&. Create/delete takes a revision, defaulting to the current branch tip\&. List to all revisions\&. +.RE +.PP +src branch [list|\-l|create|\-c|delete|del|\-d] [\fIname\fR] [\fIfile\fR\&...] +.RS 4 +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\&. List defaults to all revisions, including 0 (the trunk root phantom revision)\&. +.RE +.PP +src rename [\fItag\fR|\fIbranch\fR] [\fIoldname\fR] [\fInewname\fR] [\fIfile\fR\&...] +.RS 4 +Rename a tag or branch\&. Refuses to step on an existing symbol or rename a nonexistent one\&. "rn" is a synonym for "rename"\&. +.RE +.PP +src list [(\-<n>|\-l <n>)] [\-f \fIfmt\fR] [\fIrevision\-range\fR] [\fIfile\fR\&...] +.RS 4 +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 +\fIhelp list\fR +for information about custom formats\&. Use +\fI\-<n>\fR +or +\fI\-l <n>\fR, where <n> is a number, to limit the listing length\&. Default range is the current branch, reversed\&. "li" is a synonym for "list"\&. +.RE +.PP +src log [\-v] [(\-<n>|\-l <n>)] [(\-p|\-u|\-c) [\-b|\-w]] [\fIrevision\-range\fR] [\fIfile\fR\&...] +.RS 4 +Sends log information about the specified commits to standard output\&. Use +\fI\-<n>\fR +or +\fI\-l <n>\fR, where <n> is a number, to limit the listing length\&. Default range is the current branch, reversed\&. The +\fI\-\-patch\fR, +\fI\-p\fR +or +\fI\-u\fR +option additionally sends a unified format diff listing to standard output for each revision against its immediate ancestor revision; +\fI\-c\fR +emits a context diff instead\&. When generating a diff, +\fI\-b\fR +ignores changes in whitespace, and +\fI\-w\fR +ignores all whitespace\&. Histories imported via +\fIfast\-import\fR +(when not using its +\fI\-p\fR +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 +\fIlog\fR, however, +\fI\-v\fR +shows a summarized view of important headers; +\fI\-v \-v\fR +shows all headers as\-is\&. +.RE +.PP +src diff [(\-u|\-c) [\-b|\-w]] [\fIrevision\-range\fR] [\fIfile\fR\&...] +.RS 4 +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 +\fI\-u\fR +(unified), but if you specify a +\fI\-c\fR +option after the verb a context diff will be emitted\&. +\fI\-b\fR +ignores changes in the amount of whitespace, and +\fI\-w\fR +ignores all whitespace\&. "di" is a synonym for "diff"\&. +.RE +.PP +src ls +.RS 4 +List all registered files\&. +.RE +.PP +src visualize +.RS 4 +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"\&. +.RE +.PP +src move \fIold\fR \fInew\fR +.RS 4 +Rename a workfile and its history\&. Refuses to step on existing workfiles or histories\&. "mv" is a synonym for "move"\&. +.RE +.PP +src copy \fIold\fR \fInew\fR +.RS 4 +Copy a file and its master\&. Refuses to step on existing files or masters\&. "cp" is a synonym for "copy"\&. +.RE +.PP +src fast\-export [\fIrevision\-range\fR] [\fIfile\fR\&...] +.RS 4 +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 +\fIfast\-import\fR +(if its +\fI\-p\fR +option was not used)\&. Otherwise, this information is copied from your Git configuration\&. +.RE +.PP +src fast\-import [\-p] [\fIfiles\fR\&...] +.RS 4 +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 +\fI\-p\fR +(plain) option is given, in which case this metadata is discarded\&. Give arguments to restrict the files imported\&. +.RE +.PP +src release [\fIfile\fR\&...] +.RS 4 +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\&. +.RE +.PP +src version +.RS 4 +Report the versions of SRC, the underlying Python, and the back end\&. +.RE +.sp +The omission of "src remove" is a deliberate speed bump\&. +.sp +If no files are specified, all eligible files are operated on in sequence\&. +.SH "NOISE CONTROL" +.sp +Silence is golden\&. When you have selected only one file to operate on, and the command is not a report generator (\fIstatus\fR, \fIcat\fR, \fIlog\fR, \fIlist\fR, \fIfast\-export\fR, the listing modes of \fItag\fR and \fIbranch\fR, \fIls\fR) you will see a reply only if the operation failed\&. +.sp +Other commands (\fIcommit\fR, \fIcheckout\fR, 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 \fI\-q\fR option, placed \fIbefore\fR the subcommand word\&. +.sp +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 \fIsrc status\fR \- 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 \fIsrc status *\fR will list them with status "I"\&. +.SH "BACKWARD COMPATIBILITY" +.sp +SRC history files are (normally) RCS master files\&. SRC maintains no permanent state other than these files\&. +.sp +SRC takes over the little\-used "description" field of RCS (and SCCS) master files to store some state that makes status checks faster\&. If you try to use SRC to edit a pre\-existing RCS\- or SCCS\-registered file with a non\-empty description field, SRC will refuse to step on the old description; you must clear it manually\&. +.sp +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\&. +.sp +The RCS back end will be automatically selected when there is an "\&.src" or "RCS" subdirectory\&. +.sp +You can explicitly select the RCS back end by making the first command keyword on the src command line be \fIrcs\fR\&. This should only be necessary when your working directory contains two or more of the subdirectories "\&.src", "RCS", and "SCCS"\&. +.sp +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\&. +.SH "WORKING WITH SCCS" +.sp +Using SCCS as a back end is also supported, with some limits due to missing features in SCCS: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +all commands relating to tags and branches throw an error\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +src cat does not necessarily pipe out binary data correctly\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +the exec bit is not propagated between master and workfile\&. +.RE +.sp +The SCCS back end will be automatically selected when there is an "SCCS" subdirectory and no "\&.src" or "RCS" subdirectory\&. +.sp +You can explicitly select the SCCS back end by making the first command keyword on the src command line be \fIsccs\fR\&. This should only be necessary when your working directory contains none or two or more of the subdirectories "\&.src", "RCS", and "SCCS"\&. +.sp +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\&. +.sp +Fast\-import to SCCS is not supported\&. +.sp +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 would be a better idea; in truth, the SCCS support exists mainly because it\(cqs hilarious (for obscure hacker values of \fIhilarious\fR)\&. +.SH "DEBUGGING OPTIONS" +.sp +These will be of interest mainly to developers\&. +.sp +A \fI\-d\fR (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\&. It can be repeated for higher debugging levels that expose more of src\(cqs internal computation\&. +.sp +A \fI\-S\fR (sandbox) option can be used to set the repository directory to something other than its default of "\&.src"\&. +.sp +A \fI\-T\fR option sets up an artificial clock that ticks once on each revision and fixes the user information to be used in \fIfast\-export\fR; It also attributes all commits to "J\&. Random Hacker"\&. It is for regression testing\&. +.SH "REQUIREMENTS" +.sp +SRC is written in Python and requires 2\&.7 or later; it will run under Python 3\&.x\&. +.sp +If you wish to use the RCS support, the RCS tools at version 5\&.7 or later must be installed and accessible in your path\&. +.sp +If you wish to use the SCCS support, the CSSC (Compatibly Stupid Source Control) system must be installed and accessible in your path\&. +.sp +The rcs\-fast\-import(1) tool at version 1\&.0 or later is required to support the \fIsrc fast\-import\fR command\&. +.sp +src will die gracefully with a useful error message when it fails due to a missing back end\&. +.SH "LIMITATIONS" +.sp +Branch deletions change the revision numbers of revisions downstream of the branch join\&. This behavior may change in a future release\&. +.sp +The SCCS backend has a Y2\&.1K problem that SRC cannot effectively work around and will probably not be fixed\&. +.SH "REPORTING BUGS" +.sp +Report bugs to Eric S\&. Raymond <esr@thyrsus\&.com>\&. The project page is at http://catb\&.org/~esr/src +.SH "SEE ALSO" +.sp +rcs(1), rcs\-fast\-import(1), sccs(1), svn(1), git(1), dot(1)\&. |