--- /dev/null
+= SRC FAQ =
+
+== Why SRC instead of $VCS? ==
+
+Most version control systems today are ostensibly multi-user,
+multi-file, and multi-fork oriented. These are all good features and
+properties to have, but it neglects 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 criteria, 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 nice 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 had spawned the development of SRC was that it would
+have four 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 à 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 by large are used 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 of 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 serious 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.
+
projects / src.git / commitdiff