SRC FAQ

Most version control systems today are multi-user, multi-file, and multi-branch oriented. These are all good features and properties to have, but they neglect the occasional need to maintain simple single-file documents, such as HOWTOs and FAQs, much like the very file you are reading now. There is even a good use-case for small programs and scripts. Do you presently keep your ~/bin contents under version control? If not, consider using SRC for them.

It is true, other VCSes already fulfill this simple criterion, SCCS and RCS being some of the earliest examples dating back to the 1970s and 1980s. While SCCS died off due to its proprietary nature, RCS has kept a niche for itself precisely for single-file projects. In fact, SRC is built on top of RCS, rather than reimplementing all of the gritty master file details.

The idea that spawned the development of SRC was that it would have these five properties:

Notably, RCS itself fails on the latter two criteria. Designed both as an early attempt at VCS and for multi-user environments, the commands are awkward to deal with and it requires complicated processes of locking and unlocking files in order to edit and commit them. None of this is appropriate anymore. Modern DVCSes with a non-locking model have proven more effective even for multi-user projects, let alone single-user ones that will never have contention issues.

Other projects to mold Mercurial and Git for a single-file purpose will at the very least fail criteria #3 and #5, and often #4 as well.

Absolutely not! SRC and DVCSes serve entirely opposite needs. SRC’s strength is precisely when there is neither need nor desire for collaboration or publishing features, when there is only a single file and a single author for a file. In fact, if your script grows into a full project in its own right, SRC has a src fast-export command that can be used to jump-start a DVCS repository with the entire existing history intact.

SRC might make certain uses of DVCS obsolete, such as keeping individual documents tucked away in their own directories so that the DVCS (which usually has a special repository directory named like .hg or .git) can operate. Scripts to impose a single-file concept on top of these systems do not go far enough with respect to the reasons SRC exists.

No. That would be silly. SRC is a real software project, with several files that do, and should, have joint history. It has a public Git repository.

SRC has had real users (that is, other than the author) since day two after it was announced, but not for projects like itself.

Because process friction matters, even to hackers as ancient as you and the author of SRC. Bare RCS’s interface is pretty awful; a competently-designed UI can reduce that friction considerably. Try it and see.

If you use RCS through Emacs’s VC mode, you already have a pretty good wrapper around it…​which, as it happens, the author of SRC also wrote. SRC has a couple of advantages over VC-RCS - running lockless, better scriptability, and ditching RCS’s ugly revision numbering are the main ones.

SRC is now a fully-supported VC-mode system in Emacs, so you can run SRC through Emacs and get the lockless operation and Subversion-style revision numbers.

YES! SRC is explicitly designed to have the bare-bones features and commands of a modern version control system. Keep in mind that SRC’s strength is single-file documents and projects. If you have loose scripts and documents not presently under any version control, SRC is a good candidate for playing around with them.

If instead you have a large multi-file project, ease yourself into using a DVCS with simple commands, possibly even using SRC’s command set as a guideline for which ones to learn first. You will appreciate having actual changesets that span multiple files in this use case. Mercurial and Git are the most common, which means they are also easy to find help for.

No. When SRC commits a file with RCS on the backend, it uses -kb which explicitly disables all kind of expansion, and also allows arbitrary binary files to be stored. The SCCS backend always checks out files with -e, implying -k and no keyword expansion.

Keyword expansion has, in general, not been well-accepted in the VCS world, most modern VCSes do not support it at all, and the author of SRC thinks it was a terrible idea. Do not even suggest this feature, it will not be implemented.

If you don’t see it in the src help listing, probably not. You are certainly free to suggest features, but SRC is developed with extreme conservatism as to what features to implement or not. Remember, single-file, single-user, private VCS.

Before requesting a feature, ask yourself whether it makes SRC more complicated, whether it really helps a single author or developer, and whether it really makes sense to deploy SRC for your use-case instead of a DVCS. These can all be hard questions, and if you are in doubt, you may go forth with your request, others may share their own opinions.

SRC shines in its simplicity. Any individual feature is not necessarily against this, but too many can easily creep over into 'too complicated' territory.

The answer is either “completely fine” or “not at all”, depending on what is being asked. :-)

SRC makes no special provisions, it operates in the current working directory whether that is local storage, NFS, CIFS, sshfs, or any other kind of networking file system. As long as the directory tree is mounted on your system, SRC should be able to handle it.

Ah, yes, everybody’s favorite bikeshedding topic.

Consistency with other version control systems is an important way to reduce any kind of surprises while using SRC. Unfortunately, the single-letter codes used for statuses are not identical between VCSes and often conflict with each other over specific meanings. For example, D means 'deleted' in Subversion and Git, but Mercurial uses R for that same meaning. Git uses R to mean 'renamed', while Subversion uses it to mean 'replaced'.

It is an unfortunate state of affairs. The development philosophy behind SRC is to keep it as un-innovative and unsurprising as possible, but since multiple VCSes in widespread use have not converged on the same meanings for single-letter status codes, SRC needs to settle on its own definitions that may differ from what you are used to.

Because some hacks that are useless or marginal are way too funny not to do anyway. This one was hilarious…​if you have a hacker’s sense of humor. If you don’t, never mind.

No, though the author admits he did laugh a lot while roughing out the original design. Resurrect RCS? Wrap it in a decent UI? Really?

There’s a significant amount of ha-ha-only-serious here. Laugh, but treat SRC as a lesson in several things. Unix minimalism. The virtue of re-use, even of technology as old as RCS. The effectiveness of a carefully crafted UI. The value of a conservative design with no surprises and no undue cleverness.

This isn’t really a FAQ, as nobody has asked it frequently enough; SRC is simple, carefully-tested code and bugs in it have been rare. Still…​

The first thing to do is pull the tip version from the project repository and verify that it still exhibits the bug. If it doesn’t, you need read no further.

When you have a bug persists with the repository tip version, the author needs three things:

Points for style if you send a tarball that unpacks into a directory containing relevant workfiles, their .src/RCS/SCCS subdirectory, a file of SRC commands to reproduce the bug (named 'tickleme' or 'fooup' or something distinctive), and a README listing the “src version” output and circumstances.

If you can supply all this information, expect bug resolution to be very rapid.

Most of this FAQ was originally written by Mike Swanson, aka chungy.