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 records commit timestamps, but does not show
25 committer information, because the committer is always you. The command
26 set is intended to look familiar if you have ever used Subversion,
27 Mercurial, or Git.
28 SRC is lightweight and fast. It uses two small self-contained
30 executables, with no libraries and no complications.
31 SRC interprets the EDITOR variable in the usual way, using it to spawn
33 an editor instance when you perform a commit or amend. If EDITOR is not
34 set it has a fallback list of editors it looks for, beginning with
35 various ways to inoke Emacs and vi.
36 SRC is fully supported in Emacs VC mode.
38
40 A "revision" is a 1-origin integer, or a tag name designating an
41 integer revision, or a branch name designating the tip revision of its
42 branch. Revision numbers always increase in commit-date order.
43 A revision range is a single revision, or a pair of revisions "M-N"
45 (all revisions numerically from M to N) or "M..N" (all revisions that
46 are branch ancestors of N and branch successors of M).
47 If SRC complains that your revision spec looks like a nonexistent
49 filename, you can prefix it with "@" (this is always allowed). "@" by
50 itself means the current (checked-out) revision.
51 A filename can be a path. In that case SRC will behave as though it
53 were running in the lowest-level directory on the path and called with
54 the path basename.
55 Unless otherwise noted under individual commands, the default revision
57 is the tip revision on the current branch and the default range is all
58 revisions on the current branch.
59 The token "--" tells the command-line interpreter that subcommands,
61 switches, and revision-specs are done - everything after it is a
62 filename, even if it looks like a subcommand or revision number.
63 src help [command]
65 Displays help for commands.
66 src commit [-|-m string|-f file|-e|-b branch] [file...]
68 Enters a commit for specified files. Separately to each one. A
69 history is created for the file if it does not already exist. With
70 -, take comment text from stdin; with -m use the following string
71 as the comment; with -f take from a file. With -e, edit even after
72 -, -f or -m. "ci" is a synonym for "commit". With -b, set ther
73 named branch to check in to (it must exist); that branch becomes
74 the default for commits.
75 src amend [-|-m string|-f file|-e] [revision] [file...]
77 Amends the stored comment for a specified revision, defaulting to
78 the latest revision on the current branch. Flags are as for commit.
79 "am" is a synonym for "amend".
80 src checkout [revision] [file...]
82 Refresh the working copy of the file(s) from their history files.
83 "co" is a synonym for "checkout".
84 src cat [revision] [file...]
86 Send the specified revision of the files to standard output.
87 src status [-a] [file...]
89 "A" = added, "=" = unmodified, "M" = modified, "!" = missing, "?" =
90 not tracked, "I" = ignored, "L" = locked (recover with "src
91 checkout"). The "A" and "L" statuses should only occur if you have
92 used RCS directly on a file. Normally "?" and "I" files are not
93 listed; this changes if you either give the -a switch or specify
94 which files to look at. "st" is a synonym for "status".
95 src tag [list|-l|create|-c|delete|del|-d] [name] [revision] [file...]
97 List tags, create tags, or delete tags. Create/delete takes a
98 revision, defaulting to the current branch tip. List defaults to
99 all revisions.
100 src branch [list|-l|create|-c|delete|del|-d] [name] [file...]
102 List, create, or delete branches. When listing, the active branch
103 is first in the list. The default branch is "trunk". Create/delete
104 takes a singleton revision, defaulting to the current branch tip;
105 on create, the branch becomes default for future commits. List
106 defaults to all revisions, including 0 (the trunk root phantom
107 revision).
108 src rename [tag|branch] [oldname] [newname] [file...]
110 Rename a tag or branch. Refuses to step on an existing symbol or
111 rename a nonexistent one. "rn" is a synonym for "rename".
112 src list [(-<n>|-l <n>)] [-f fmt] [revision-range] [file...]
114 Sends summary information about the specified commits to standard
115 output. The summary line tagged with "*" is the state that the file
116 would return to on checkout without a revision-spec. See help list
117 for information about custom formats. Use -<n> or -l <n>, where <n>
118 is a number, to limit the listing length. Default range is the
119 current branch, reversed. "li" is a synonym for "list".
120 src log [-v] [(-<n>|-l <n>)] [(-p|-u|-c) [-b|-w]] [revision-range]
122 [file...]
123 Sends log information about the specified commits to standard
124 output. Use -<n> or -l <n>, where <n> is a number, to limit the
125 listing length. Default range is the current branch, reversed. The
126 --patch, -p or -u option additionally sends a unified format diff
127 listing to standard output for each revision against its immediate
128 ancestor revision; -c emits a context diff instead. When generating
129 a diff, -b ignores changes in whitespace, and -w ignores all
130 whitespace. Histories imported via fast-import (when not using its
131 -p option) have RFC-822-style headers inserted into the log comment
132 to preserve metadata not otherwise representable in SRC, such as
133 distinct author and committer identifications and dates. These
134 headers are normally suppressed by log, however, -v shows a
135 summarized view of important headers; -v -v shows all headers
136 as-is.
137 src diff [(-u|-c) [-b|-w]] [revision-range] [file...]
139 Sends a diff listing to standard output. With no revision spec,
140 diffs the working copy against the last version checked in. With
141 one revno, diffs the working copy against that stored revision;
142 with a range, diff between the beginning and end of the range. The
143 actual difference generation is done with diff(1). The default diff
144 format is -u (unified), but if you specify a -c option after the
145 verb a context diff will be emitted. -b ignores changes in the
146 amount of whitespace, and -w ignores all whitespace. "di" is a
147 synonym for "diff".
148 src ls
150 List all registered files.
151 src visualize
153 Emit a DOT visualization of repository structures. To use this,
154 install the graphviz package and pipe the output to something like
155 "dot -Tpng | display -". "vis" is a synonym for "visualize".
156 src move old new
158 Rename a workfile and its history. Refuses to step on existing
159 workfiles or histories. "mv" is a synonym for "move".
160 src copy old new
162 Copy a file and its master. Refuses to step on existing files or
163 masters. "cp" is a synonym for "copy".
164 src fast-export [revision-range] [file...]
166 Export one or more projects as a Git fast-import stream. For a
167 history originally imported from elsewhere, author and committer
168 identification is gleaned from the RFC-822-style headers inserted
169 into the commit comment by fast-import (if its -p option was not
170 used). Otherwise, this information is copied from your Git
171 configuration.
172 src fast-import [-p] [files...]
174 Parse a git-fast-import stream from standard input. The
175 modifications for each individual file become separate SRC
176 histories. Mark, committer and author data, and mark
177 cross-references to parent commits, are preserved in RFC-822-style
178 headers on log comments unless the -p (plain) option is given, in
179 which case this metadata is discarded. Give arguments to restrict
180 the files imported.
181 src release [file...]
183 Release locks on files. This is never necessary in a normal
184 workflow, which will be repeated edit-commit cycles, but it may be
185 handy if you have to interoperate with other tools that expect RCS
186 masters to be in their normal (unlocked) state.
187 src srcify
189 Move a directory from being RCS- or SCCS-managed to being
190 SRC-managed. That is: if the current directory contains an RCS
191 directory, rename it to .src (but leave any SCCS directory in
192 place). Then check out all masters for editing that are not already
193 checked out.
194 src version
196 Report the versions of SRC, the underlying Python, and the back
197 end.
198 The omission of "src remove" is a deliberate speed bump.
200 If no files are specified, all eligible files are operated on in
202 sequence.
203
205 Silence is golden. When you have selected only one file to operate on,
206 and the command is not a report generator (status, cat, log, list,
207 fast-export, the listing modes of tag and branch, ls) you will see a
208 reply only if the operation failed.
209 Other commands (commit, checkout, tag creation and deletion) give you a
211 success message per file when operating on multiple files, so you will
212 not be in doubt about which operation succeeded. This behavior can be
213 suppressed with the -q option, placed before the subcommand word.
214 If your directory contains a file named ".srcignore", each line that is
216 neither blank nor begins with a "#" is interpreted as an ignore
217 pattern. It is expanded with glob(3), and files in the expansion are
218 omitted from src status - unless the file is named as an argument, of
219 the status command, in which case its status is "I". Thus, for example,
220 a line reading "*.html" will cause all files with an HTML extension to
221 be omitted from the output of "src status", but the output of src
222 status * will list them with status "I".
223
225 SRC history files are (normally) RCS master files. SRC maintains no
226 permanent state other than these files.
227 SRC takes over the little-used "description" field of RCS (and SCCS)
229 master files to store some state that makes status checks faster. If
230 you try to use SRC to edit a pre-existing RCS- or SCCS-registered file
231 with a non-empty description field, SRC will refuse to step on the old
232 description; you must clear it manually.
233 In order to maintain complete backwards compatibility, one other
235 compromise was made: any commit comment containing a string exactly
236 matching an RCS log delimiter (a long string of "-" characters) will be
237 rejected as malformed.
238 The RCS back end will be automatically selected when there is an ".src"
240 or "RCS" subdirectory.
241 You can explicitly select the RCS back end by making the first command
243 keyword on the src command line be rcs. This should only be necessary
244 when your working directory contains two or more of the subdirectories
245 ".src", "RCS", and "SCCS".
246 Branch names are structure imposed by SRC using CVS-style sticky tags.
248 If you drop back to RCS, they’ll point at revisions that don’t exist.
249 By default, history files are kept in a hidden subdirectory named
251 ".src". But if you have an RCS subdirectory and no ".src", SRC will
252 quietly operate on the files in the RCS directory in a completely
253 backward-compatible way.
254
256 Using SCCS as a back end is also supported, with some limits due to
257 missing features in SCCS implementations:
258 • SCCS tags are an SRC-only extension that won’t be visible from SCCS
260 running natively.
261 • All commands relating to branches throw an error in the SCCS back
263 end.
264 • In CSSC SCCS, src cat does not necessarily pipe out binary data
266 correctly. This has been fixed in the SunOS and Schilling versions.
267 • The exec bit is not propagated between master and workfile. This
269 has been fixed in the SunOS and Schilling versions.
270 • The CSSC and SunOS SCCS backends have a Y2.1K problem that SRC
272 cannot effectively work around and will probably not be fixed. The
273 Schilling version has repaired this. To be on the safe side, do not
274 use the SCCS backend after the year 2067.
275 The SCCS back end will be automatically selected when there is an
277 "SCCS" subdirectory and no ".src" or "RCS" subdirectory.
278 You can explicitly select the SCCS back end by making the first command
280 keyword on the src command line be sccs. This should only be necessary
281 when your working directory contains none or two or more of the
282 subdirectories ".src", "RCS", and "SCCS".
283 Working with SCCS requires an "SCCS" subdirectory; SRC will quietly
285 create one, if required, then operate on the files in the "SCCS"
286 directory in a completely backward-compatible way.
287 Fast-import to SCCS is not supported.
289 The SCCS mode is not recommended unless you have a specific need to
291 work with legacy SCCS repositories. Up-converting them to something
292 less Paleolithic would be a better idea; in truth, the SCCS support
293 exists mainly because it’s hilarious (for obscure hacker values of
294 hilarious).
295
297 These will be of interest mainly to developers.
298 A -d (debug) option before the main command word turns on debugging
300 messages. Just one "-d" gives you complete visibility about what
301 commands the back end is running. It can be repeated for higher
302 debugging levels that expose more of src’s internal computation.
303 A -S (sandbox) option can be used to set the repository directory to
305 something other than its default of ".src".
306 A -T option sets up an artificial clock that ticks once on each
308 revision and fixes the user information to be used in fast-export; It
309 also attributes all commits to "J. Random Hacker". It is for regression
310 testing.
311
313 SRC is written in Python and requires 2.7 or later; it will run under
314 Python 3.x for x > 2.
315 If you wish to use the RCS support (recommended), the RCS tools at
317 version 5.7 or later must be installed and accessible in your path.
318 If you wish to use the SCCS support, some implementation of SCCS must
320 be accessible. GNU’s CSSC (Compatibly Stupid Source Control) will work;
321 so will the SunOS and Schilling forks of AT&T SCCS.
322 The rcs-fast-import(1) tool at version 1.0 or later is required to
324 support the src fast-import command.
325 src will die gracefully with a useful error message when it fails due
327 to a missing back end.
328
330 Branch deletions change the revision numbers of revisions downstream of
331 the branch join.
332 To avoid some confusing error cases, src will bail out if both .src and
334 RCS directories exist.
335 In src fast-export dumps of repositories with tags, branch labels may
337 not exactly match what git fast-export would emit.
338
340 Report bugs to Eric S. Raymond <esr@thyrsus.com>. The project page is
341 at http://catb.org/~esr/src
342
344 rcs(1), rcs-fast-import(1), sccs(1), svn(1), git(1), dot(1).
345 08/13/2023 SRC(1)