File: basic-branching-and-merging.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 (427 lines) | stat: -rw-r--r-- 8,367 bytes
<html>
<head>
<title>Basic Branching and Merging</title>
</head>
<body>

<a name="Basic_Branching_and_Merging"></a>

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

<h2 align=center>Basic Branching and Merging</h2>




<small>
<b>up: </b><a href="arch.html#arch">arch</a></br>
<b>next: </b><a href="patch-logs.html#Patch_Logs_and_ChangeLogs">Patch Logs and ChangeLogs</a></br>

<b>prev: </b><a href="basic-rc.html#Basic_Revision_Control">Basic Revision Control</a></br>

</small>
<br>






<p>When a single development path splits into two paths, that's called a
<em>
<a name="index-pt:0"></a>

branch
</em>
.  Typically, a branch is followed by a <em>
<a name="index-pt:1"></a>

merge
</em>
 -- adding the
changes made in a branch back to the branch from which it diverged.
</p><p>This chapter explains how to create a branch and the simplest way to
merge changes from two branches.  Later chapters will explain fancier
techniques, useful in more complex situations.
</p>
<a name="Tagging"></a>



<h3 align=center>Tagging</h3>










<p><a name="index-pt:2"></a>

</p><p>In <code>arch</code>
, branches are &quot;tags&quot;.
</p><p>A <em>
<a name="index-pt:3"></a>

tag
</em>
 is an alternative name for some revision.  For example, one
could use the tag <code>release-candidate</code>
 to name whatever revision people
should download for testing purposes, regardless of what branch,
version, or patch level the release candidate happens to be on.
</p><p>In <code>arch</code>
, tags are revisions on ordinary branches.  For example,
suppose we are developing <code>arch--devo--0.5</code>
 and want to create a tag
<code>release-candidate</code>
 to mark revisions which &quot;early adopters&quot;
should test.  First, create a development path for the tag:
</p><pre>
      % larch make-branch arch--release-candidate
      % larch make-version arch--release-candidate--0.5

</pre>
<p>To tag a specific revision, use the command:
</p><pre>
      % larch tag SOURCE-REVISION TAG-REVISION

</pre>
<p>Note that <code>source-revision</code>
 and <code>tag-revision</code>
 may be abbreviated.
For example, to tag the most recent revision of <code>arch--devo</code>
:
</p><pre>
      % larch tag arch--devo arch--release-candidate

</pre>
<p>or 
</p><pre>
      % larch tag arch--devo--0.5 arch--release-candidate--0.5

</pre>
<p>or 
</p><pre>
      % larch tag arch--devo--0.5--patch-37 \
                 arch--release-candidate--0.5

</pre>
<p>After such a command, you can retrieve the tagged revision in the
ordinary way:
</p><pre>
      % larch get arch--release-candidate--0.5

</pre>
<p>Note that when you <code>get</code>
 a tag that way, the default version of the
resulting project tree is the tag's version, not the tagged version
(see <a href="project-names.html#Labelling_Project_Trees">Labelling Project Trees</a>).
</p><p>You can always update a tag, making it point to a later revision,
again using the <code>tag</code>
 command:
</p><pre>
      % larch tag arch--devo--0.5--patch-53 \
                 arch--release-candidate--0.5

</pre>
<p>You can see the history of a tag in the usual way, too:
</p><pre>
      % larch revisions --summary arch--release-candidate--0.5
      base-0
          tag of joe.hacker@gnu.org--arch/arch--devo--0.5--patch-37
      patch-1
          tag of joe.hacker@gnu.org--arch/arch--devo--0.5--patch-53

</pre>












<a name="Creating_a_Branch"></a>



<h3 align=center>Creating a Branch</h3>










<p>There is another way to create a branch.  This technique is slower,
but has the side effect of leaving you with a working directory for
the new branch.  The effect on the repository is the same as when
using the <code>tag</code>
 command.
</p><p>Creating a new branch from an existing branch can be accomplished by
this sequence of commands:
</p><pre>
      % larch prepare-branch OLD-REVISION NEW-BRANCH-VERSION WORKING-DIR
      % cd WORKING-DIR
      [...edit log message...]
      % larch finish-branch

</pre>
<p>but it is worth deeply understanding that <code>prepare-branch</code>
 is
equivalent to:
</p><pre>
      # This command gets the source tree for the revision we
      # are branching from:
      # 
      % larch get OLD-REVISION WORKING-DIR

</pre>
<pre>
      # These commands switch the working directory to the
      # new branch:
      # 
      % cd WORKING-DIR
      % larch add-log NEW-BRANCH-VERSION
      % larch set-tree-version NEW-BRANCH-VERSION

</pre>
<pre>
      # These commands create a &quot;continuation&quot; base-revision
      # for the new branch:
      # 
      % larch make-log

</pre>
<p>and that <code>finish-branch</code>
 is the same as:
</p><pre>
      % larch make-branch NEW-BRANCH
      % larch make-version NEW-BRANCH-VERSION
      % larch commit --continuation OLD-REVISION

</pre>
<p>For example, to create a branch <code>hello--experimental--1.0</code>
 from the
latest revision of <code>hello--devo--1.0</code>
, use:
</p><pre>
      % larch prepare-branch hello--devo--1.0 \
                            hello--experimental--1.0 \
                            wd

</pre>
<pre>
      % cd wd

</pre>
<pre>
      [...edit log message...]

</pre>
<pre>
      % larch finish-branch

</pre>












<a name="Distributed_Branches"></a>



<h3 align=center>Distributed Branches</h3>










<p>There is no requirement that a branch be stored in the same archive as
the revision from which it branched.  For example, you can create a
private archive, and store some branches there -- only merging those
changes back into the shared archive when they are ready.
</p><p>Here's a tip: make your private archive your default archive.  Use
fully-qualified version and revision names when getting or committing
revisions in the shared archive.  This makes it less likely that
you'll accidently make unintended changes to the shared archive.
</p>











<a name="whats-missing_Revisited"></a>



<h3 align=center>whats-missing Revisited</h3>










<p><a name="index-pt:4"></a>

</p><p>If you have a project tree for a branch, you might want to know what
has happened in the version from which you branched.
</p><p>The <code>whats-missing</code>
 is used for this.  In a working directory for a
branch, use:
</p><pre>
      % larch whats-missing --summary ORIGINAL-VERSION

</pre>
<p>where <code>ORIGINAL-VERSION</code>
 is the version name of the version from which
you branched.  Actually, <code>ORIGINAL-VERSION</code>
 can be any version for
which your project tree has a patch log.
</p><p>The <code>whats-missing</code>
 command is explained in greater detail in the next
chapter (see <a href="patch-logs.html#Patch_Logs_and_ChangeLogs">Patch Logs and ChangeLogs</a>).
</p>











<a name="update_and_replay_Revisited"></a>



<h3 align=center>update and replay Revisited</h3>










<p>Similarly, <code>update</code>
 and <code>replay</code>
 work for any version for which a
project tree has a patch log, such as a version from which a branch
occurred:
</p><pre>
      % larch update OLD-DIR NEW-DIR [archive/]VERSION

</pre>
<pre>
      % larch replay OLD-DIR NEW-DIR [archive/]VERSION

</pre>












<a name="Merging_After_a_Branch"></a>



<h3 align=center>Merging After a Branch</h3>










<p>The simplest use of branching and merging is this: you have one
development path, call it the &quot;trunk&quot;.  You form a branch from that
development path, which we'll just call &quot;the branch&quot;.
</p><p>To make some changes, you do your work on the branch:  check out the
latest revision from the branch, make changes, commit, make more
changes, commit again, etc.
</p><p>As you work, you might sometimes need to &quot;catch up&quot; to changes made
to the trunk.  You can do that by using <code>update</code>
 or <code>replay</code>
.
</p><p>When you're done, and the branch is fully up-to-date with the trunk,
you can check out the latest branch revision, then commit that version
to the trunk.   All of the changes that you made on the branch will be
summarized into a single patch.
</p><p>There are more complicated and more realistic uses of branches.  These
are the subjects of the next several chapters.
</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>