File: introduction.html

package info (click to toggle)
arch 1.0pre15-1
links: PTS
area: main
in suites: woody
size: 20,180 kB
ctags: 4,560
sloc: ansic: 64,410; sh: 29,168; lisp: 1,896; awk: 1,044; makefile: 484; sed: 26
file content (759 lines) | stat: -rw-r--r-- 21,497 bytes
<html>
<head>
<title>Introducing arch</title>
</head>
<body>

<a name="Introducing_arch"></a>

<a href="http://www.regexps.com">The Hackerlab at <code>regexps.com</code></a>

<h2 align=center>Introducing arch</h2>




<small>
<b>up: </b><a href="arch.html#arch">arch</a></br>
<b>next: </b><a href="system-requirements.html#System_Requirements">System Requirements</a></br>


</small>
<br>






<p><code>arch</code>
 is a source code management, revision control, and
configuration management tool.
</p>
<a name="Advantages_of_arch"></a>



<h3 align=center>Advantages of arch</h3>










<p>What makes <code>arch</code>
 better than other revision control systems?
</p><p>There are minor advantages, and a a few major advantages.
</p><p>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.
</p><p>There are at least six major advantages to arch: <em>
<a name="index-pt:0"></a>

a file tree library
of revisions
</em>
, <em>
<a name="index-pt:1"></a>

renaming
</em>
, <em>
<a name="index-pt:2"></a>

distributed repositories
</em>
, <em>
<a name="index-pt:3"></a>

robust and
easy operation
</em>
, <em>
<a name="index-pt:4"></a>

configurations
</em>
, and <em>
<a name="index-pt:5"></a>

sophisticated branching and
merging
</em>
.
</p><p>&quot;a file tree library of revisions&quot; 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 <code>diff</code>
, <code>find</code>
, and
<code>grep</code>
 to explore past revisions and revisions on other branches.
</p><p>&quot;renaming&quot; means that you can rename files and directories and
<code>arch</code>
 keeps up just fine: it rearranges the patches between revisions
in the corresponding way.  And it's convenient: you can use <code>arch</code>
 in a
mode that doesn't require you to run <code>add</code>
, <code>remove</code>
, or <code>move</code>

commands every time you add, delete, or rename a file or directory.
</p><p>&quot;robust and easy operation&quot; means that <code>arch</code>
 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 <code>arch</code>
 never
become permanently wedged (requiring by-hand repair): they can be
broken remotely to recover from interrupted commands.
</p><p>&quot;Distributed repositories&quot; 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 <code>arch</code>
 is concerned, there is exactly one repository
database for the entire world -- we all share it.
</p><p>&quot;configurations&quot; are a mechanism for defining &quot;meta-projects&quot; that
are a combination of multiple &quot;sub-projects&quot;.  For every
meta-project, you need to be able to define <em>configuration rules</em>,
which explain which revisions from what branches to check out to get a
particular revision of the meta-project.  <code>arch</code>
 provides a flexible
mechanism for that, allowing you to pick and choose pieces from
various branches and repositories with varying degrees of specificity.
</p><p>&quot;Sophisticated branching and merging&quot; has to do with arch's support
for asynchronous development on branches, coordinated by a shared
trunk.  Commonly, people arrange branches in a &quot;star topology&quot;.
There is a trunk in the middle, surrounded by branches, as in this
(hypothetical) example:
</p><pre>
        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)

</pre>
<p>And we might imagine many more branches than are actually drawn here.
</p><p>Ideally, each of the surrounding branches will sometimes be merged
into <code>gcc-main</code>
.  And as <code>gcc-main</code>
 changes, it wll sometimes be 
merged back into the surrounding branches.
</p><p>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 <a href="star-topology.html#Star_Topology_Branching_and_Merging">Star Topology Branching and Merging</a>.)
</p><p>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.
</p><p>In <code>arch</code>
, history sensitivity is taken to the next level.  <code>arch</code>

knows how handle back-and-forth merging in a star topology
automatically.
</p><p>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.
</p><p><code>arch</code>
 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.
</p><p><code>arch</code>
 automates the merge operation (with the <code>larch star-merge</code>
)
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 <code>update</code>

command.
</p><p>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.
</p><p>In addition to star topology merging, <code>arch</code>
 provides some other fancy
merging options too (e.g. see <a href="reconciling.html#Multi-Branch_Merging_--_The_reconcile_Command">Multi-Branch Merging -- The reconcile Command</a>.)
</p>











<a name="Global_Revision_Control_Done_Right"></a>



<h3 align=center>Global Revision Control Done Right</h3>










<p>The foundation of <code>arch</code>
 is two commands: <code>mkpatch</code>
 and <code>dopatch</code>
.
</p><p><code>mkpatch</code>
 computes a patch set describing the difference between two
trees.  <code>dopatch</code>
 applies a patch set to a tree, gracefully handling
the cases when a patch doesn't apply cleanly.
</p><p>Conceptually, <code>mkpatch</code>
 is similar to <code>diff -r</code>
 and <code>dopatch</code>
 is similar
to <code>patch</code>
.  Unlike <code>diff</code>
 and <code>patch</code>
, though, <code>mkpatch</code>
 and
<code>dopatch</code>
 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.
</p><p>An <code>arch</code>
 <em>repository</em> 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.
</p><p><code>arch</code>
 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, <code>arch</code>
 provides a global namespace for revisions.
</p><p>On the basis of that global namespace, branches and merge operations
can span repository boundaries.  As far as <code>arch</code>
 is concerned, all of
the repositories you can access over the Internet are integrated into
one gigantic repository -- seemlessly integrated.
</p><p>In <code>arch</code>
, there is no such thing as a &quot;working directory&quot;.  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.
<code>arch</code>
 is happy to work with both.
</p><p>Every tree that <code>arch</code>
 works with has a &quot;patch log&quot; -- 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 <code>arch</code>
, 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.
</p><p><code>arch</code>
 is agile and flexible at handling patch sets.  It provides
<code>update</code>
 -- a patch set manipulation operation that is logically
equivalent to the traditional <code>update</code>
 operation of <code>CVS</code>
; it provides
<code>replay</code>
 -- a history-sensative merge operation equivalent to the
<code>update</code>
 operation of <code>Subversion</code>
 (as documented in the <code>Subversion</code>

manual); <code>arch</code>
 also provides two rather more sophisticated merge
operations -- <code>reconcile</code>
 and <code>i-merge</code>
 -- which handle very complex
(yet quite realistic) branching and merging scenarios gracefully.
</p><p>In general, the design philosophy of <code>arch</code>
 is to be a very good
librarian for whole-tree patch sets, and a very good mechanic for
manipulating whole-tree patch sets.  <code>arch</code>
 is designed to stay out of
your way while you hack, but come to your aid when you <code>commit</code>
,
review, <code>update</code>
, or merge.  The aim is simplicity, clarity of
function, and flexibility.
</p>











<a name="Introducing_arch_Project_Trees"></a>



<h3 align=center>Introducing arch Project Trees</h3>










<p><code>arch</code>
 manages &quot;project trees&quot;.  A project tree is a file
system tree, usually containing the source code for a project.
</p><p>What distinguishes a project tree from an ordinary tree is the
presence of &quot;arch control files&quot;, primarilly stored in a top-level
subdirectory called <code>{arch}</code>
.
</p><p>The control files include information needed to keep an inventory of
the tree, a &quot;patch log&quot; documenting the history of the tree, various
default values for <code>arch</code>
 commands applied to the tree, and a local
cache of information to speed up some <code>arch</code>
 commands.
</p><p>When you distribute a tree, usually you will <em>include</em> all of the arch
control files -- they are useful to others.
</p><p><code>arch</code>
 has no special concept of a &quot;working copy&quot; (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 <code>arch</code>
 control files can be used as a
&quot;working copy&quot;.  If you download a distribution for a project
managed with <code>arch</code>
 and unpack that distribution -- you have a working
copy.
</p><p>For more information, see <a href="project-trees.html#arch_Project_Trees">arch Project Trees</a>.
</p>











<a name="Introducing_arch_Inventories"></a>



<h3 align=center>Introducing arch Inventories</h3>










<p><code>arch</code>
 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:
</p><pre>
        % larch inventory --source

</pre>
<p>prints an inventory of files in a tree.
</p><p>Every file has two names: its &quot;location&quot; (a path relative to the root of
the tree) and its &quot;tag&quot; (a logical, location-independent name for
the file).  The command:
</p><pre>
        % larch inventory --source --tags

</pre>
<p>prints an inventory of files in a tree, showing the logical name of
each file.
</p><p><code>arch</code>
 uses tags to keep track, for example, of when files are
renamed.
</p><p>If you are being extra careful, you can use the command:
</p><pre>
        % larch set-manifest

</pre>
<p>to record a list of all the files that are <em>supposed</em> to be in a tree
and the command:
</p><pre>
        % larch check-manifest

</pre>
<p>to see if any unexpected files have been added, or expected files
removed.
</p><p>For more information, see <a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a>.
</p>











<a name="Introducing_arch_Patch_Sets"></a>



<h3 align=center>Introducing arch Patch Sets</h3>










<p>Experienced programmers should be familiar with the standard command
<code>diff -c -r</code>
, used to create a (standard) &quot;patch set&quot; describing the
changes made between two copies of a tree.   And they are familiar
with the standard command <code>patch</code>
 -- used to modify a tree according
to the description of changes in a patch set.
</p><p>Standard patch sets have limitations: they do not cleanly handle file
or directory additions, removals, or renames, symbolic links, file
permissions, or binary files.
</p><p><code>arch</code>
 provides <code>mkpatch</code>
 and <code>dopatch</code>
, similar to <code>diff -r</code>
 and
<code>patch</code>
, but without the limitations.  
</p><p>For more information, see <a href="patches.html#arch_Patch_Sets">arch Patch Sets</a>.
</p>











<a name="Global_Namespaces"></a>



<h3 align=center>Global Namespaces</h3>










<p><code>arch</code>
 implements a global namespace of projects, taking into account
the organization publishing a project, branching of projects, and
versioning of branches.
</p><p><code>arch</code>
 implements a global namespace of patch sets, building on the
global namespace of projects.
</p><p>Those namespaces give rise to the idea of a &quot;development path&quot;.
For example, the very first revision of the project <code>arch</code>
, might be
called:
</p><pre>
        lord@regexps.com--arch/arch--0.1--base-0

</pre>
<p>The next three revisions might be called:
</p><pre>
        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

</pre>
<p>Each of those revision names is the name of a patch set that describes
what changed in that revision, compared to the previous revision.
</p><p>If <code>arch</code>
 forked into a separate development paths, say &quot;intl&quot; (for
internationalizing the code), there might be revisions such as:
</p><pre>
        lord@regexps.com--arch/arch--intl--0.1--patch-1
        lord@regexps.com--arch/arch--intl--0.1--patch-2

</pre>
<p><code>arch</code>
 implements a global namespace of all user's of <code>arch</code>
 (layered
on top of email addresses).  Every patch set has an associated log
entry, with a <code>Creator:</code>
 line that contains a user's <code>arch</code>
 id.
</p><p>For more information, see <a href="user-names.html#The_arch_Global_Name-space_of_Users">The arch Global Name-space of Users</a>,
<a href="project-names.html#The_arch_Global_Name-space_of_Projects">The arch Global Name-space of Projects</a>, and <a href="basic-rc.html#Basic_Revision_Control">Basic Revision Control</a>.
</p>











<a name="Introducing_arch_Archives"></a>



<h3 align=center>Introducing arch Archives</h3>










<p><code>arch</code>
 can manage repositories of revisions, storing those revisions as
compressed tar files of patch sets or compressed tar files of complete
trees.
</p><p><code>arch</code>
 archives can be used remotely if they are made accessible by an
ordinary FTP server (there is no need for a special <code>arch</code>
-specific
server).
</p><p>You can (safely, atomically) add a new revision to a repository (<code>larch
import</code>
 or <code>larch commit</code>
).  You can reconstruct an arbitrary revision
from the files in a repository (<code>larch get</code>
).  You can &quot;branch&quot; a
development path to create a new, related development path (<code>larch
tag</code>
).  Branches can cross repository boundaries, and to the user,
<code>arch</code>
 appears to integrate the two repositories into one.
</p><p>Repositories can be migrated and, for read-only access, replicated.
</p><p><code>arch</code>
 repositories have an easy-to-understand format, amendable to
browsing by hand or with special-purpose interface programs.
</p><p>For more information, see <a href="archives.html#Archives">Archives</a>.
</p>











<a name="Introducing_arch_Patch_Logs"></a>



<h3 align=center>Introducing arch Patch Logs</h3>










<p>In every project tree, <code>arch</code>
 keeps a detailed &quot;patch log&quot;: 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).
</p><p><code>arch</code>
 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.
</p><p><code>arch</code>
 can automatically generate and maintain a GNU-style ChangeLog
from its patch log.
</p><p>When you &quot;merge&quot; two branches (combine the changes made in those
branches), <code>arch</code>
 uses the information in the patch log to avoid
redundantly applying patches.
</p><p>For more information, see <a href="patch-logs.html#Patch_Logs_and_ChangeLogs">Patch Logs and ChangeLogs</a>.
</p>











<a name="Cheap_Branching_and_Smart_Merging"></a>



<h3 align=center>Cheap Branching and Smart Merging</h3>










<p>Creating a branch in <code>arch</code>
 is inexpensive in both space and time.
</p><p>The <code>arch</code>
 commands for merging have many subtle features to help a
merge go smoothly.
</p><p>For more information, see <a href="basic-branching-and-merging.html#Basic_Branching_and_Merging">Basic Branching and Merging</a>,
<a href="reconciling.html#Multi-Branch_Merging_--_The_reconcile_Command">Multi-Branch Merging -- The reconcile Command</a>, and
<a href="idempotent-merging.html#Idempotent_Merging">Idempotent Merging</a>.
</p>











<a name="What_Does_It_All_Mean?"></a>



<h3 align=center>What Does It All Mean?</h3>










<p>Putting all those features together, <code>arch</code>
 is an elegant and more
featureful replacement for older systems like <code>CVS</code>
.
</p><p>For example, using <code>arch</code>
, every programmer can conveniently have a
private repository for day-to-day work rather than burdening a shared
repository with per-user branches.
</p><p>A project can be &quot;multi-homed&quot; -- stored in multiple repositories --
with different branches in each repository.
</p><p>It is easy and convenient, when using <code>arch</code>
, to improve and clean-up
projects by reorganizing the files and directories they contain:
something that is quite awkward with <code>CVS</code>
.
</p><p>The fancy branching and merging commands of <code>arch</code>
 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.
</p><p><code>arch</code>
 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.
<code>arch</code>
 is an excellent foundation for process automation and for
layering under fancy graphical interfaces.  <code>arch</code>
 is self-documenting
and extensible.
</p>


















<small><i>arch: The arch Revision Control System

</i></small><br>


<a href="http://www.regexps.com">The Hackerlab at <code>regexps.com</code></a>

</body>