regexps.com
arch
is a source code management, revision control, and
configuration management tool.
What makes arch
better than other revision control systems?
There are minor advantages, and a a few major advantages.
The minor advantages are things like: regular, clean, interfaces; small code size; on-line help; automated ChangeLog generation; features for browsing change sets with a web browser; software tools architecture. Some of these are arguably matters of taste -- worth mentioning but not arguing for.
There are at least six major advantages to arch: a file tree library of revisions , renaming , distributed repositories , robust and easy operation , configurations , and sophisticated branching and merging .
"a file tree library of revisions" means that all revisions can be
made accessible in a (space efficient) library of revision trees.
That means that you can use ordinary tools like diff
, find
, and
grep
to explore past revisions and revisions on other branches.
"renaming" means that you can rename files and directories and
arch
keeps up just fine: it rearranges the patches between revisions
in the corresponding way. And it's convenient: you can use arch
in a
mode that doesn't require you to run add
, remove
, or move
commands every time you add, delete, or rename a file or directory.
"robust and easy operation" means that arch
repository
transactions have ACID properties and repositories are stored as
ordinary unix files. Commits may be concurrent with reads and are
atomic. There is no overhead from having to administer a relational
or hash-table database. The transient locks held by arch
never
become permanently wedged (requiring by-hand repair): they can be
broken remotely to recover from interrupted commands.
"Distributed repositories" means that you never need write access to
a repository in order to start branches from projects stored in that
repository. You can store branches in any repository. That means
every programmer can have private repositories for day-to-day work or
as scratch areas for working out complex merges. Every sub-group
working on a project can have their own repository. If two groups
want to fork a project, but still loosely cooperate, they can each
have their own trunk in their own repository -- selectively merging
changes between the two trunks. Without wishing to put too much hype
on it, as far as arch
is concerned, there is exactly one repository
database for the entire world -- we all share it.
"configurations" are a mechanism for defining "meta-projects" that
are a combination of multiple "sub-projects". For every
meta-project, you need to be able to define configuration rules,
which explain which revisions from what branches to check out to get a
particular revision of the meta-project. arch
provides a flexible
mechanism for that, allowing you to pick and choose pieces from
various branches and repositories with varying degrees of specificity.
"Sophisticated branching and merging" has to do with arch's support for asynchronous development on branches, coordinated by a shared trunk. Commonly, people arrange branches in a "star topology". There is a trunk in the middle, surrounded by branches, as in this (hypothetical) example:
patch-reviewer A patch-reviewer B (who merges patches (another patch reviewer) contributed by people / who don't have write-access / to gcc-main) / \ / \ / gcc-main (the trunk) / \ / \ / \ C 99 team Fortran team (who work on features (who work on fortran) required by the new standard)
And we might imagine many more branches than are actually drawn here.
Ideally, each of the surrounding branches will sometimes be merged
into gcc-main
. And as gcc-main
changes, it wll sometimes be
merged back into the surrounding branches.
When two versions each merge with the other repeatedly, forming a merge without creating spurious conflicts is a tricky problem. (For a more detailed description of the problem, see Star Topology Branching and Merging.)
In CVS, the problem is solved by using tags and not generating conflicts for changes that appear to be redundant. Unfortunately, tags are expensive, work only within one repository, and worst of all, are complicated to use correctly. If you forget to create a tag at the right time (or worse, if your tagging operation is interleaved with other operations) you're hosed.
In arch
, history sensitivity is taken to the next level. arch
knows how handle back-and-forth merging in a star topology
automatically.
This is an advance in revision control similar to the invention of lockless operation in CVS. With lockless operation, you have a star topology with an archived development path in the middle, surrounded not by branches, but by working copies. Programmers can commit from the working copies to the trunk or merge from the trunk into working copies repeatedly, and everything works beautifully. The trunk is used to syncronize the multiple working copies.
arch
takes the next step. It allows those satellite working copies
to be archived as long-lived branches. The trunk is used to
syncronize the surrounding branches.
arch
automates the merge operation (with the larch star-merge
)
command and gives you control over the precedence-ordering of change
sets (which branch takes priority, and which has changes that are
rejected if they conflict). You don't have to use tags, and you don't
have to figure out the right revision arguments to pass to an update
command.
Each satellite has its own log history. Each can be used for progress tracking. A satellite can be used to maintain an alternative distribution that tracks the trunk, but sometimes takes the lead with additional features.
In addition to star topology merging, arch
provides some other fancy
merging options too (e.g. see Multi-Branch Merging -- The reconcile Command.)
The foundation of arch
is two commands: mkpatch
and dopatch
.
mkpatch
computes a patch set describing the difference between two
trees. dopatch
applies a patch set to a tree, gracefully handling
the cases when a patch doesn't apply cleanly.
Conceptually, mkpatch
is similar to diff -r
and dopatch
is similar
to patch
. Unlike diff
and patch
, though, mkpatch
and
dopatch
can handle the addition or removal of files and directories,
the renaming of files and directories, files which are symbolic links,
changes to file permissions, and binary files.
An arch
repository is a collection of full-source revisions, and
patch sets. Brand new trees are represented as full-source revisions.
Modified trees are stored as patch sets. Any revision can be
reconstructed by retrieving a full-source revision, intermediate patch
sets, and applying those patches.
arch
repositories have globally unique names and every revision in a
repository has an easy to understand, easy to type name. Putting the
two names together, arch
provides a global namespace for revisions.
On the basis of that global namespace, branches and merge operations
can span repository boundaries. As far as arch
is concerned, all of
the repositories you can access over the Internet are integrated into
one gigantic repository -- seemlessly integrated.
In arch
, there is no such thing as a "working directory". That is
to say, there is no distinction between a tree that you download as a
source distribution, and a tree that you check out from a repository.
arch
is happy to work with both.
Every tree that arch
works with has a "patch log" -- a record of all
of the patches (in the global namespace) that have ever been applied
to the tree, along with a record of the full-source revision that the
tree started from. In arch
, a tree never belongs to a specific
branch in some specific repository -- instead: a source tree is
considered to be a part of every branch in every repository for which
it has a patch log. At any time, any tree can join any branch with
which it has a common ancestor.
arch
is agile and flexible at handling patch sets. It provides
update
-- a patch set manipulation operation that is logically
equivalent to the traditional update
operation of CVS
; it provides
replay
-- a history-sensative merge operation equivalent to the
update
operation of Subversion
(as documented in the Subversion
manual); arch
also provides two rather more sophisticated merge
operations -- reconcile
and i-merge
-- which handle very complex
(yet quite realistic) branching and merging scenarios gracefully.
In general, the design philosophy of arch
is to be a very good
librarian for whole-tree patch sets, and a very good mechanic for
manipulating whole-tree patch sets. arch
is designed to stay out of
your way while you hack, but come to your aid when you commit
,
review, update
, or merge. The aim is simplicity, clarity of
function, and flexibility.
arch
manages "project trees". A project tree is a file
system tree, usually containing the source code for a project.
What distinguishes a project tree from an ordinary tree is the
presence of "arch control files", primarilly stored in a top-level
subdirectory called {arch}
.
The control files include information needed to keep an inventory of
the tree, a "patch log" documenting the history of the tree, various
default values for arch
commands applied to the tree, and a local
cache of information to speed up some arch
commands.
When you distribute a tree, usually you will include all of the arch control files -- they are useful to others.
arch
has no special concept of a "working copy" (in other revision
control systems, a working copy is a tree checked out from the
revision control database, as contrasted with a tree from any other
source). Any tree that contains arch
control files can be used as a
"working copy". If you download a distribution for a project
managed with arch
and unpack that distribution -- you have a working
copy.
For more information, see arch Project Trees.
arch
keeps track of an inventory of the files in a project tree.
For example, it can distinguish the files that are officially part of
the tree from other files, such as scratch files or editor back-up
files. The command:
% larch inventory --source
prints an inventory of files in a tree.
Every file has two names: its "location" (a path relative to the root of the tree) and its "tag" (a logical, location-independent name for the file). The command:
% larch inventory --source --tags
prints an inventory of files in a tree, showing the logical name of each file.
arch
uses tags to keep track, for example, of when files are
renamed.
If you are being extra careful, you can use the command:
% larch set-manifest
to record a list of all the files that are supposed to be in a tree and the command:
% larch check-manifest
to see if any unexpected files have been added, or expected files removed.
For more information, see arch Project Inventories.
Experienced programmers should be familiar with the standard command
diff -c -r
, used to create a (standard) "patch set" describing the
changes made between two copies of a tree. And they are familiar
with the standard command patch
-- used to modify a tree according
to the description of changes in a patch set.
Standard patch sets have limitations: they do not cleanly handle file or directory additions, removals, or renames, symbolic links, file permissions, or binary files.
arch
provides mkpatch
and dopatch
, similar to diff -r
and
patch
, but without the limitations.
For more information, see arch Patch Sets.
arch
implements a global namespace of projects, taking into account
the organization publishing a project, branching of projects, and
versioning of branches.
arch
implements a global namespace of patch sets, building on the
global namespace of projects.
Those namespaces give rise to the idea of a "development path".
For example, the very first revision of the project arch
, might be
called:
lord@regexps.com--arch/arch--0.1--base-0
The next three revisions might be called:
lord@regexps.com--arch/arch--0.1--patch-1 lord@regexps.com--arch/arch--0.1--patch-2 lord@regexps.com--arch/arch--0.1--patch-3
Each of those revision names is the name of a patch set that describes what changed in that revision, compared to the previous revision.
If arch
forked into a separate development paths, say "intl" (for
internationalizing the code), there might be revisions such as:
lord@regexps.com--arch/arch--intl--0.1--patch-1 lord@regexps.com--arch/arch--intl--0.1--patch-2
arch
implements a global namespace of all user's of arch
(layered
on top of email addresses). Every patch set has an associated log
entry, with a Creator:
line that contains a user's arch
id.
For more information, see The arch Global Name-space of Users, The arch Global Name-space of Projects, and Basic Revision Control.
arch
can manage repositories of revisions, storing those revisions as
compressed tar files of patch sets or compressed tar files of complete
trees.
arch
archives can be used remotely if they are made accessible by an
ordinary FTP server (there is no need for a special arch
-specific
server).
You can (safely, atomically) add a new revision to a repository (larch
import
or larch commit
). You can reconstruct an arbitrary revision
from the files in a repository (larch get
). You can "branch" a
development path to create a new, related development path (larch
tag
). Branches can cross repository boundaries, and to the user,
arch
appears to integrate the two repositories into one.
Repositories can be migrated and, for read-only access, replicated.
arch
repositories have an easy-to-understand format, amendable to
browsing by hand or with special-purpose interface programs.
For more information, see Archives.
In every project tree, arch
keeps a detailed "patch log": a record
of what the original source tree was, along with a record for every
patch applied to the tree (regardless of what branch the patch came
from).
arch
log entries use RFC822-style formatting. Automatically
generated headers record what files were changed by each patch, what
repository the patch came from, what user created the patch, etc. The
patch log is a very useful source of information for programmers.
arch
can automatically generate and maintain a GNU-style ChangeLog
from its patch log.
When you "merge" two branches (combine the changes made in those
branches), arch
uses the information in the patch log to avoid
redundantly applying patches.
For more information, see Patch Logs and ChangeLogs.
Creating a branch in arch
is inexpensive in both space and time.
The arch
commands for merging have many subtle features to help a
merge go smoothly.
For more information, see Basic Branching and Merging, Multi-Branch Merging -- The reconcile Command, and Idempotent Merging.
Putting all those features together, arch
is an elegant and more
featureful replacement for older systems like CVS
.
For example, using arch
, every programmer can conveniently have a
private repository for day-to-day work rather than burdening a shared
repository with per-user branches.
A project can be "multi-homed" -- stored in multiple repositories -- with different branches in each repository.
It is easy and convenient, when using arch
, to improve and clean-up
projects by reorganizing the files and directories they contain:
something that is quite awkward with CVS
.
The fancy branching and merging commands of arch
make it convenient
to do more development than ever in feature-specific branches, merging
features as they are completed, generating a clean, complete, and
isolated patch set for each new feature.
arch
is written in a software-tools style: it is made up of many
small programs, each of which does one job well. The commands have
very regular option and argument syntax and input and output formats.
arch
is an excellent foundation for process automation and for
layering under fancy graphical interfaces. arch
is self-documenting
and extensible.
regexps.com