SRC FAQ

A&D regular Mike Swanson did such a nice job on this that I want you all to see it.

SRC FAQ

version 1.0

Why SRC instead of $VCS?

Most version control systems today are multi-user, multi-file, and multi-fork oriented. These are all good features and properties to have, but they neglect the 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.

XYZ already does single-file version control, why another one?

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 five properties characterizing it:

  • Only deals with single files. Use for HOWTOs, memoranda, etc.
  • Allows multiple histories to live in the same directory without entanglement.
  • Has a human-readable master-file representation – no binary blobs.
  • Modern CLI user-interface. Commands familiar to Subversion, Hg, Git users.
  • Integer sequential revision numbers a la Subversion.

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 even 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 for multi-user projects and wide coordination.

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

Does SRC mean that $DVCS is obsolete?

Absolutely not! SRC and DVCSes serve entirely opposite needs. SRC’s strength is precisely when there is no 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 can operate (which usually have a special repository directed named like .hg or .git). Scripts to impose a single-file concept on top of these systems do not go far enough with respect to the reasons SRC exists.

Is SRC a good system to learn about version control?

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.

Does SRC have keyword expansion?

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. Keyword expansion has, in general, not been well-accepted in the VCS world and most modern VCSes do not support it at all. Do not even suggest this feature, it will not be implemented.

Does SRC have $FEATURE?

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. Extra features is not against this, but too many can easily creep over into “too complicated” territory.

How well does SRC handle files over the network?

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.

Why doesn’t src status display show the same letters as $VCS?

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.

Um. This is a joke, right?

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 value of a carefully designed UI. The value of a conservative design with no surprises and no undue cleverness.

What will be funny is when we implement the back end to talk to SCCS. It won’t be difficult, that whole end of the interface is encapsulated in a class…

Acknowledgments

Nearly all of this FAQ, except “This is a joke, right?”, was written by Mike Swanson, aka chungy.

Published
Categorized as General

22 comments

  1. @esr, @chungy –

    > What will be funny is when we implement the back end to talk to SCCS. It won’t be difficult, that whole end of the interface is encapsulated in a class…

    Except then you will fail Criterion 3. This might not be fatal, except you seem to have treated it as a fundamental design property, yes?

    1. >Except then you will fail Criterion 3.

      SCCS files were human-readable last time I looked at one. Has something changed?

  2. SCCS uses ^A for control codes. It’s not really so bad as a full binary-packed format when it comes to readability.

  3. @esr –

    > SCCS files were human-readable last time I looked at one. Has something changed?

    I was remembering the control-A hack for “control lines’. This isn’t exactly a show-stopper for programs like “less”, “more”, “ed”, etc. But it is not strictly non-binary, I would argue (not very strenuously).

  4. @esr: “SCCS files were human-readable last time I looked at one. Has something changed?”

    When was the last time *anyone* looked at an SCCS file? I don’t think I’ve had cause to do so for over 25 years.

    1. >I guess I’m just quibbling.

      I had forgotten the SOH characters. Even then I was using Emacs, which makes them visible, so it was easy to think of them as an odd kind of visible delimiter.

  5. Nice piece of documentation: short, clear, and with some humor. :-)

    @ Mike Swanson: You clearly know the ins and outs of SRC. As usual, I’m curious: did you participate in its coding? At the very least, you were an early tester, right?

    @ ESR: I’d read in your Google+ that Emacs development would fully switch to git by November 11th. Today’s 12th, but Emacs’ Savannah page still says they use Bazaar for the main source. What’s happened? (Since this thread is about version control and you mentioned Emacs in a comment, I trust this question is on-topic, if only tenuously. :-P)

    1. >At the very least, you were an early tester, right?

      Mike was in the original design discussion on #reposurgeon. He has since been doing good work on testing the alpha releases.

      >What’s happened

      The old repo was locked until it got cleared by a Savannah admin while I was sleeping. The big push is happening now. I wouldn’t hold my breath waiting for the web page to change, alas.

  6. > I wouldn’t hold my breath waiting for the web page to change, alas.

    No, but I’m sure the info page will be up to date!

  7. Perhaps a nit:

    The bulleted list of five characteristics is then referred to by number. Please change the bulleted list to an enumerated list.

    1. >Please change the bulleted list to an enumerated list.

      Maybe. I need to think about whether I want to imply a priority order there.

  8. >>Please change the bulleted list to an enumerated list.

    >Maybe. I need to think about whether I want to imply a priority order there.

    If technically possible, you can always use alphabetical enumeration (a., b., c., d., e.) or roman numbers (i., ii., iii., iv., v.) to be able to reference points without implying priority order.

  9. If technically possible, you can always use alphabetical enumeration (a., b., c., d., e.) or roman numbers (i., ii., iii., iv., v.) to be able to reference points without implying priority order.

    Like this?

  10. > Like this?

    Yes, assuming it is to be read as plain ASCII, or it renders correctly (if it is Markdown or sth).

  11. It’s AsciiDoc, it renders out to HTML :) Although, there’s nothing really wrong with reading it as plain text.

    Personally I much prefer AsciiDoc to Markdown. Never heard of sth…

  12. Thanks. I nearly made+uploaded a package right when 0.1 was released, but it was just a bit too early and unsuitable for real packaging yet… 0.2 was much much better and that became the first on AUR :-)

Leave a comment

Your email address will not be published. Required fields are marked *