1SRC(1)                                                                  SRC(1)
2
3
4

NAME

6       src - simple revision control
7

SYNOPSIS

9       src [command] [revision-spec] [file...]
10

DESCRIPTION

12       SRC (or src) is simple revision control, a version-control system for
13       single-file projects by solo developers and authors. It modernizes the
14       venerable RCS, hence the anagrammatic acronym. The design is tuned for
15       use cases like all those little scripts in your "~/bin" directory, or a
16       directory full of single-file HOWTOs.
17
18       SRC revision histories are single, human-readable files beneath a
19       hidden ".src" subdirectory in the directory where they live. There may
20       be multiple histories under one directory; SRC treats them as separate
21       projects, and history files can be moved elsewhere at any time.
22
23       SRC gives you simple, consecutive integer revision numbers. It supports
24       tags and branching. It does not show committer information, because the
25       committer is always you. The command set is intended to look familiar
26       if you have ever used Subversion, Mercurial, or Git.
27
28       SRC is lightweight and fast. It uses two small self-contained
29       executables, with no libraries and no complications.
30
31       SRC interprets the EDITOR variable in the usual way, using it to spawn
32       an editor instance when you perform a commit or amend.
33
34       SRC is fully supported in Emacs VC mode.
35

COMMAND SUMMARY

37       A "revision" is a 1-origin integer, or a tag name designating an
38       integer revision, or a branch name designating the tip revision of its
39       branch. Revision numbers always increase in commit-date order.
40
41       A revision range is a single revision, or a pair of revisions "M-N"
42       (all revisions numerically from M to N) or "M..N" (all revisions that
43       are branch ancestors of N and branch successors of M).
44
45       If SRC complains that your revision spec looks like a nonexistent
46       filename, you can prefix it with "@" (this is always allowed). "@" by
47       itself means the current (checked-out) revision.
48
49       Unless otherwise noted under individual commands, the default revision
50       is the tip revision on the current branch and the default range is all
51       revisions on the current branch.
52
53       The token "--" tells the command-line interpreter that subcommands,
54       switches, and revision-specs are done - everything after it is a
55       filename, even if it looks like a subcommand or revision number.
56
57       src help [command]
58           Displays help for commands.
59
60       src commit [-|-m string|-f file|-e] [file...]
61           Enters a commit for specified files. Separately to each one. A
62           history is created for the file if it does not already exist. With
63           -, take comment text from stdin; with -m use the following string
64           as the comment; with -f take from a file. With -e, edit even after
65           -, -f or -m. "ci" is a synonym for "commit".
66
67       src amend [-|-m string|-f file|-e] [revision] [file...]
68           Amends the stored comment for a specified revision, defaulting to
69           the latest revision on the current branch. Flags are as for commit.
70           "am" is a synonym for "amend".
71
72       src checkout [revision] [file...]
73           Refresh the working copy of the file(s) from their history files.
74           "co" is a synonym for "checkout".
75
76       src cat [revision] [file...]
77           Send the specified revision of the files to standard output.
78
79       src status [-a] [file...]
80           "A" = added, "=" = unmodified, "M" = modified, "!" = missing, "?" =
81           not tracked, "I" = ignored, "L" = locked (recover with "src
82           checkout"). The "A" and "L" statuses should only occur if you have
83           used RCS directly on a file. Normally "?" and "I" files are not
84           listed; this changes if you either give the -a switch or specify
85           which files to look at. "st" is a synonym for "status".
86
87       src tag [list|-l|create|-c|delete|del|-d] [name] [revision] [file...]
88           List tags, create tags, or delete tags. Create/delete takes a
89           revision, defaulting to the current branch tip. List defaults to
90           all revisions.
91
92       src branch [list|-l|create|-c|delete|del|-d] [name] [file...]
93           List, create, or delete branches. When listing, the active branch
94           is first in the list. The default branch is "trunk". Create/delete
95           takes a singleton revision, defaulting to the current branch tip.
96           List defaults to all revisions, including 0 (the trunk root phantom
97           revision).
98
99       src rename [tag|branch] [oldname] [newname] [file...]
100           Rename a tag or branch. Refuses to step on an existing symbol or
101           rename a nonexistent one. "rn" is a synonym for "rename".
102
103       src list [(-<n>|-l <n>)] [-f fmt] [revision-range] [file...]
104           Sends summary information about the specified commits to standard
105           output. The summary line tagged with "*" is the state that the file
106           would return to on checkout without a revision-spec. See help list
107           for information about custom formats. Use -<n> or -l <n>, where <n>
108           is a number, to limit the listing length. Default range is the
109           current branch, reversed. "li" is a synonym for "list".
110
111       src log [-v] [(-<n>|-l <n>)] [(-p|-u|-c) [-b|-w]] [revision-range]
112       [file...]
113           Sends log information about the specified commits to standard
114           output. Use -<n> or -l <n>, where <n> is a number, to limit the
115           listing length. Default range is the current branch, reversed. The
116           --patch, -p or -u option additionally sends a unified format diff
117           listing to standard output for each revision against its immediate
118           ancestor revision; -c emits a context diff instead. When generating
119           a diff, -b ignores changes in whitespace, and -w ignores all
120           whitespace. Histories imported via fast-import (when not using its
121           -p option) have RFC-822-style headers inserted into the log comment
122           to preserve metadata not otherwise representable in SRC, such as
123           distinct author and committer identifications and dates. These
124           headers are normally suppressed by log, however, -v shows a
125           summarized view of important headers; -v -v shows all headers
126           as-is.
127
128       src diff [(-u|-c) [-b|-w]] [revision-range] [file...]
129           Sends a diff listing to standard output. With no revision spec,
130           diffs the working copy against the last version checked in. With
131           one revno, diffs the working copy against that stored revision;
132           with a range, diff between the beginning and end of the range. The
133           actual difference generation is done with diff(1). The default diff
134           format is -u (unified), but if you specify a -c option after the
135           verb a context diff will be emitted.  -b ignores changes in the
136           amount of whitespace, and -w ignores all whitespace. "di" is a
137           synonym for "diff".
138
139       src ls
140           List all registered files.
141
142       src visualize
143           Emit a DOT visualization of repository structures. To use this,
144           install the graphviz package and pipe the output to something like
145           "dot -Tpng | display -". "vis" is a synonym for "visualize".
146
147       src move old new
148           Rename a workfile and its history. Refuses to step on existing
149           workfiles or histories. "mv" is a synonym for "move".
150
151       src copy old new
152           Copy a file and its master. Refuses to step on existing files or
153           masters. "cp" is a synonym for "copy".
154
155       src fast-export [revision-range] [file...]
156           Export one or more projects as a Git fast-import stream. For a
157           history originally imported from elsewhere, author and committer
158           identification is gleaned from the RFC-822-style headers inserted
159           into the commit comment by fast-import (if its -p option was not
160           used). Otherwise, this information is copied from your Git
161           configuration.
162
163       src fast-import [-p] [files...]
164           Parse a git-fast-import stream from standard input. The
165           modifications for each individual file become separate SRC
166           histories. Mark, committer and author data, and mark
167           cross-references to parent commits, are preserved in RFC-822-style
168           headers on log comments unless the -p (plain) option is given, in
169           which case this metadata is discarded. Give arguments to restrict
170           the files imported.
171
172       src release [file...]
173           Release locks on files. This is never necessary in a normal
174           workflow, which will be repeated edit-commit cycles, but it may be
175           handy if you have to interoperate with other tools that expect RCS
176           masters to be in their normal (unlocked) state.
177
178       src srcify Move a directory from being RCS- or SCCS-managed to being
179       SRC-managed. That is: if the current directory contains an RCS
180       directory, rename it to .src (but leave any SCCS directory in place).
181       Then check out all masters for editing that are not already checked
182       out.
183
184       src version
185           Report the versions of SRC, the underlying Python, and the back
186           end.
187
188       The omission of "src remove" is a deliberate speed bump.
189
190       If no files are specified, all eligible files are operated on in
191       sequence.
192

NOISE CONTROL

194       Silence is golden. When you have selected only one file to operate on,
195       and the command is not a report generator (status, cat, log, list,
196       fast-export, the listing modes of tag and branch, ls) you will see a
197       reply only if the operation failed.
198
199       Other commands (commit, checkout, tag creation and deletion) give you a
200       success message per file when operating on multiple files, so you will
201       not be in doubt about which operation succeeded. This behavior can be
202       suppressed with the -q option, placed before the subcommand word.
203
204       If your directory contains a file named ".srcignore", each line that is
205       neither blank nor begins with a "#" is interpreted as an ignore
206       pattern. It is expanded with glob(3), and files in the expansion are
207       omitted from src status - unless the file is named as an argument, of
208       the status command, in which case its status is "I". Thus, for example,
209       a line reading "*.html" will cause all files with an HTML extension to
210       be omitted from the output of "src status", but the output of src
211       status * will list them with status "I".
212

BACKWARD COMPATIBILITY

214       SRC history files are (normally) RCS master files. SRC maintains no
215       permanent state other than these files.
216
217       SRC takes over the little-used "description" field of RCS (and SCCS)
218       master files to store some state that makes status checks faster. If
219       you try to use SRC to edit a pre-existing RCS- or SCCS-registered file
220       with a non-empty description field, SRC will refuse to step on the old
221       description; you must clear it manually.
222
223       In order to maintain complete backwards compatibility, one other
224       compromise was made: any commit comment containing a string exactly
225       matching an RCS log delimiter (a long string of "-" characters) will be
226       rejected as malformed.
227
228       The RCS back end will be automatically selected when there is an ".src"
229       or "RCS" subdirectory.
230
231       You can explicitly select the RCS back end by making the first command
232       keyword on the src command line be rcs. This should only be necessary
233       when your working directory contains two or more of the subdirectories
234       ".src", "RCS", and "SCCS".
235
236       By default, history files are kept in a hidden subdirectory named
237       ".src". But if you have an RCS subdirectory and no ".src", SRC will
238       quietly operate on the files in the RCS directory in a completely
239       backward-compatible way.
240

WORKING WITH SCCS

242       Using SCCS as a back end is also supported, with some limits due to
243       missing features in SCCS implementations:
244
245       •   SCCS tags are an SRC-only extension that won’t be visible from SCCS
246           running natively.
247
248       •   All commands relating to branches throw an error in the SCCS back
249           end.
250
251       •   In CSSC SCCS, src cat does not necessarily pipe out binary data
252           correctly. This has been fixed in the SunOS and Schilling versions.
253
254       •   The exec bit is not propagated between master and workfile. This
255           has been fixed in the SunOS and Schilling versions.
256
257       •   The CSSC and SunOS SCCS backends have a Y2.1K problem that SRC
258           cannot effectively work around and will probably not be fixed. The
259           Schilling version has repaired this.
260
261       The SCCS back end will be automatically selected when there is an
262       "SCCS" subdirectory and no ".src" or "RCS" subdirectory.
263
264       You can explicitly select the SCCS back end by making the first command
265       keyword on the src command line be sccs. This should only be necessary
266       when your working directory contains none or two or more of the
267       subdirectories ".src", "RCS", and "SCCS".
268
269       Working with SCCS requires an "SCCS" subdirectory; SRC will quietly
270       create one, if required, then operate on the files in the "SCCS"
271       directory in a completely backward-compatible way.
272
273       Fast-import to SCCS is not supported.
274
275       The SCCS mode is not recommended unless you have a specific need to
276       work with legacy SCCS repositories. Up-converting them to something
277       less Paleolithic would be a better idea; in truth, the SCCS support
278       exists mainly because it’s hilarious (for obscure hacker values of
279       hilarious).
280

DEBUGGING OPTIONS

282       These will be of interest mainly to developers.
283
284       A -d (debug) option before the main command word turns on debugging
285       messages. Just one "-d" gives you complete visibility about what
286       commands the back end is running. It can be repeated for higher
287       debugging levels that expose more of src’s internal computation.
288
289       A -S (sandbox) option can be used to set the repository directory to
290       something other than its default of ".src".
291
292       A -T option sets up an artificial clock that ticks once on each
293       revision and fixes the user information to be used in fast-export; It
294       also attributes all commits to "J. Random Hacker". It is for regression
295       testing.
296

REQUIREMENTS

298       SRC is written in Python and requires 2.7 or later; it will run under
299       Python 3.x for x > 2.
300
301       If you wish to use the RCS support (recommended), the RCS tools at
302       version 5.7 or later must be installed and accessible in your path.
303
304       If you wish to use the SCCS support, some implementation of SCCS must
305       be accessible. GNU’s CSSC (Compatibly Stupid Source Control) will work;
306       so will the SunOS and Schilling forks of AT&T SCCS.
307
308       The rcs-fast-import(1) tool at version 1.0 or later is required to
309       support the src fast-import command.
310
311       src will die gracefully with a useful error message when it fails due
312       to a missing back end.
313

LIMITATIONS

315       Branch deletions change the revision numbers of revisions downstream of
316       the branch join.
317
318       To avoid some confusing error cases, src will bail out if both .src and
319       RCS directories exist.
320
321       In src fast-export dumps of repositories with tags, branch labels may
322       not exactly match what git fast-export would emit.
323

REPORTING BUGS

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

SEE ALSO

329       rcs(1), rcs-fast-import(1), sccs(1), svn(1), git(1), dot(1).
330
331
332
333                                  01/22/2022                            SRC(1)
Impressum