= SRC FAQ =
version 1.0
+[[why]]
== Why SRC instead of $VCS? ==
Most version control systems today are multi-user,
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.
+programs and scripts. Do you presently keep your `~/bin` contents under
+version control? If not, consider using SRC for them.
+[[another-vcs]]
== $VCS 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.
+and RCS being some of the earliest examples dating back to the 1970s
+and 1980s. While SCCS died off due to its proprietary nature,
+https://www.gnu.org/software/rcs[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:
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.
+the _very_ least will fail criteria #3 and #5, and often #4 as well.
+[[dvcs-obsoletion]]
== 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
+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.
+named like `.hg` or `.git`). Scripts to impose a single-file concept
+on top of these systems do not go <<another-vcs,far enough>> with
+respect to the reasons SRC exists.
+[[beginners-vcs]]
== Is SRC a good system on which to learn about version control? ==
+=======
-YES! SRC is explicitly designed to have the bare-bones features and
+*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
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.
+case. http://mercurial.selenic.com/[Mercurial] and
+http://git-scm.com/[Git] are the most common, which means they are
+also easy to find help for.
+[[keywords]]
== Does SRC have keyword expansion? ==
-No. When SRC commits a file with RCS on the backend, it uses -kb which
+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.
+[[missing-features]]
== Does SRC have $FEATURE? ==
-If you don’t see it in the "src help" listing, probably not. You are
+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.
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.
+too many can easily creep over into ``too complicated'' territory.
+[[network]]
== How well does SRC handle files over the network? ==
-The answer is either “completely fine” or “not at all”, depending on
+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
other kind of networking file system. As long as the directory tree is
mounted on your system, SRC should be able to handle it.
+[[status-inconsistency]]
== 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.
+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
needs to settle on its own definitions that may differ from what you
are used to.
+[[not-a-joke]]
== Um. This is a joke, right? ==
No, though the author admits he did laugh a lot while roughing out the
SCCS. It won't be difficult, that whole end of the interface is
encapsulated in a class...
+[[ack]]
== Acknowledgments ==
-Nearly all of this FAQ, except "This is a joke, right?", was written
-by Mike Swanson, aka chungy.
-
+Nearly all of this FAQ, except <<not-a-joke,This is a joke, right?>>,
+was written by Mike Swanson, aka chungy.
projects / src.git / commitdiff