1SRC(1) SRC(1)
2
6 src - simple revision control
7
9 src [command] [revision-spec] [file...]
10
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 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 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 SRC is lightweight and fast. It uses two small self-contained
29 executables, with no libraries and no complications.
30 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 SRC is fully supported in Emacs VC mode.
35
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 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 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 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 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 src help [command]
58 Displays help for commands.
59 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 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 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 src cat [revision] [file...]
77 Send the specified revision of the files to standard output.
78 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 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 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 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 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 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 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 src ls
140 List all registered files.
141 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 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 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 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 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 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 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 src version
185 Report the versions of SRC, the underlying Python, and the back
186 end.
187 The omission of "src remove" is a deliberate speed bump.
189 If no files are specified, all eligible files are operated on in
191 sequence.
192
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 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 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
214 SRC history files are (normally) RCS master files. SRC maintains no
215 permanent state other than these files.
216 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 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 The RCS back end will be automatically selected when there is an ".src"
229 or "RCS" subdirectory.
230 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 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
242 Using SCCS as a back end is also supported, with some limits due to
243 missing features in SCCS implementations:
244 • SCCS tags are an SRC-only extension that won’t be visible from SCCS
246 running natively.
247 • All commands relating to branches throw an error in the SCCS back
249 end.
250 • 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 • The exec bit is not propagated between master and workfile. This
255 has been fixed in the SunOS and Schilling versions.
256 • 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 The SCCS back end will be automatically selected when there is an
262 "SCCS" subdirectory and no ".src" or "RCS" subdirectory.
263 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 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 Fast-import to SCCS is not supported.
274 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
282 These will be of interest mainly to developers.
283 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 A -S (sandbox) option can be used to set the repository directory to
290 something other than its default of ".src".
291 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
298 SRC is written in Python and requires 2.7 or later; it will run under
299 Python 3.x for x > 2.
300 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 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 The rcs-fast-import(1) tool at version 1.0 or later is required to
309 support the src fast-import command.
310 src will die gracefully with a useful error message when it fails due
312 to a missing back end.
313
315 Branch deletions change the revision numbers of revisions downstream of
316 the branch join.
317 To avoid some confusing error cases, src will bail out if both .src and
319 RCS directories exist.
320 In src fast-export dumps of repositories with tags, branch labels may
322 not exactly match what git fast-export would emit.
323
325 Report bugs to Eric S. Raymond <esr@thyrsus.com>. The project page is
326 at http://catb.org/~esr/src
327
329 rcs(1), rcs-fast-import(1), sccs(1), svn(1), git(1), dot(1).
330 11/29/2022 SRC(1)