[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

Basic Branching and Merging

When a single development path splits into two paths, that's called a branch. Typically, a branch is followed by a merge -- adding the changes made in a branch back to the branch from which it diverged.

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.


Creating a Branch

You can create branches with the create-branch command. It leaves you with a working directory for the new branch. The sequence of commands is simply

 
      % arx create-branch OLD-REVISION NEW-BRANCH-VERSION WORKING-DIR
      [...edit log message...]
      % cd WORKING-DIR
      % arx commit

create-branch will invoke an editor (specified by my-editor) to modify the log template.

For example, to create a branch hello--experimental--1.0 from the latest revision of hello--devo--1.0, use:

 
      % arx create-branch hello--devo--1.0 \
                          hello--experimental--1.0 \
                          wd
      [...edit log message...]
      % cd wd
      % arx commit

If you make modifications to a project tree, but then decide that those modifications should go into a new branch, you can use the --in-place option to create-branch. For example,

 
      % arx get hello--devo--1.0 wd
      % cd wd
      [...edit files...]
      % arx create-branch --in-place hello--experimental--1.0
      [...edit log file...]
      % arx commit


Distributed Branches

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.

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.


whats-missing Revisited

If you have a project tree for a branch, you might want to know what has happened in the version from which you branched.

The whats-missing command is used for this. In a working directory for a branch, use:

 
      % arx whats-missing --summary ORIGINAL-VERSION

where ORIGINAL-VERSION is the version name of the version from which you branched. Actually, ORIGINAL-VERSION can be any version for which your project tree has a patch log.

The whats-missing command is explained in greater detail in the next chapter (see Patch Logs and ChangeLogs).


update and replay Revisited

Similarly, update and replay work for any version for which a project tree has a patch log, such as a version from which a branch occurred:

 
      % arx update OLD-DIR NEW-DIR [archive/]VERSION
 
      % arx replay OLD-DIR NEW-DIR [archive/]VERSION


Merging After a Branch

The simplest use of branching and merging is this: you have one development path, call it the "trunk". You form a branch from that development path, which we'll just call "the branch".

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.

As you work, you might sometimes need to "catch up" to changes made to the trunk. You can do that by using update or replay.

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.

There are more complicated and more realistic uses of branches. These are the subjects of the next several chapters.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Walter Landry on April, 30 2003 using texi2html