To access a project branch, the project name has the branch appended, separated by a dot or a hyphen. For example: branch 1 of project "aegis" is referred to as "aegis.1". To reference changes on this branch, use this compound project name wherever you would normally use a project name.

Traditional 2-level project release names are obtained by using a further level of branching. For example: by creating branch 0 of project "aegis.1", there would be a branch accessed as project "aegis.1.0".

By default, these two level of project branching are created automatically when the aenpr(1) command is used. You need to use the -VERSion option to make this deeper or shallower, or have different numbering.

The last is a special case, to enable a project to be created with no default branches (it's also hard to get the empty string past the alias).

To add branching and release level management to an existing project on uses the aenbr(1) command at any level. Say we already have foo.1.0, which represents version 1.0 of our software. One method of release level management would be to integrate foo.1.0 into its parent foo.1 and then do aenbr -p foo.1 would create foo.1.1 representing version 1.1. Eventually we might want to make a major version release and would integrate foo.1 into its parent foo and then do aenbr -p foo, which would create foo.2. Then if we do aenbr -p foo.2 we create foo.2.0, for development of version 2.0 of our software.

To convert a project from the old-style to the new branching style, use the aenrls(1) command.

If you give no second project name, the new name is generated by removing the numeric suffixes. If you did not give a -VERSion option, the numeric suffixes will be used to determine the next version, by adding one to the previous minor version number. The new project is then created rather like the aenpr(1) command.

The files of the old project are copied across as an implicit change on the newly created branch within the new project. If the new project name already exists, and is a new-style project, the aenrls(1) command will attempt to make the appropriate numbered branches. If the new project already exists and is an old-style project, or it exists and the branch number(s) are already in use, aenrls(1) will emit an error and fail. The aenrls(1) command only works on old-style projects, and always converts them to new style projects.

Planning you branch numbers is essential. If you want to use 3-level branch numbers (e.g. "aegis.2.3.1") at some time in the future, then you must use 3-level version numbers all the way through (e.g. "aegis.2.3.0"). This is because change numbers and branch numbers come from the same common pool of numbers. Once change one has been used (e.g. "aegis.2.3.C001"), then branch one is no longer available (e.g. "aegis.2.3.1.C042" conflicts).

From time to time you will want to merge the changes from one branch into a change. This may be done using a cross-branch merge. This is done by specifying the -BRanch option to the aegis -diff -merge-only command.

The most common cross branch merge is when the project's files are out-of-date. Because it is not possible to use aegis -diff -merge-only directly on the branch, this must be in a change on the branch. As a short-cut, the branch may be specified using the -grandparent option.

It is very common for a bug fix to need to be applied to more than one branch at once. The change could be applied to the common ancestor branch, however this may not be effective in the branch immediately. An alternative is to use the aegis -clone command, which can be used to identically reproduce a change on another branch.

It would be nice if there was some way to use one project as a sort of "super change" to a "super project", so that large teams (say 1000 people) could work as lots of small teams (say 100 people). As a small team gets their chunk ready, using the facilities provided to-date by Aegis, the small team's baseline is treated as a change to be made to the large team baseline.

This idea can be extended quite naturally to any depth of layering.

After reading Transaction Oriented Configuration Management: A Case Study Peter Fieler, Grace Downey, CMU/SEI-90-TR-23, this is not a new idea. It also provides some ideas for how to do branching sensibly, and was influential in the design of Aegis' branching.

% aenpr gizmo.0.1
project "gizmo": created
project "gizmo.0": created
project "gizmo.0.1": created
%

aenbr -p gizmo.0.1 1 # the foo project
aenbr -p gizmo.0.1 2 # the bar project
aenbr -p gizmo.0.1 3 # the baz project

aenbr -p gizmo.0.2 1 # the foo project
aenbr -p gizmo.0.2 2 # the bar project
aenbr -p gizmo.0.2 3 # the baz project

A development directory becomes out of date, compared to the project, when another change is integrated which has a file in common. This situation is detected automatically by aede(1) and you resolve it using aed(1), usually with something like the --merge-only option. Additionally, you can see if you have an out-of-date file from the change files listing, because it will show you the current baseline version in parentheses if you are out-of-date.

Aegis implements branches as very long changes, with sub-changes. A side effect of this is that a branch can become out-of-date in the same way that a development director becomes out of date. When it comes time to aede(1) the branch, you will be told if there are any out-of-date files. Additionally, the project files listing will show out of date files in exactly the same way that the change file listing does.

“OK, I give up. I do not understand the ending of branches.”

Usually, you end development of a branch the same way you end development of a simple change. In this example, branch example.1.42 will be ended:

% aede -p example 1 -c 42


aegis: project "example.1": change 42:
file "fubar" in the baseline
has changed since the last
'aegis -DIFFerence' command, you
need to do a merge

%

Oops. Something went wrong. Don't panic!

I'm going to assume, for the purposes of explanation, that there have been changes in one of the ancestor branches, and thus require a merge, just like file fubar, above.

You need to bring file fubar up-to-date. How? You do it in a change set, like everything else.

At his point you need to do 5 things: (1) create a new change on example.1.42, (2) copy fubar into it, (3) merge fubar with branch "example.1" (4) end development of the change and integrate it, and (5) now you can end example.1.42

The -GrandParent option is a special case of the -BRanch option. You are actually doing a cross-branch merge, just up-and-down rather than sideways.

% aem -gp fubar
%

And manually fix any conflicts... naturally.

At this point, have a look at the file listing, it will show you something you have never seen before - it will show you what it is going to set the branch's edit_number_origin to for each file, at aeipass.

% ael cf
Type   Action Edit        File Name
------ ------ -------     -----------
source modify 1.3         fubar
              {cross 1.2}

Now finish the change as usual... aeb, aed, aede, aerpass, aeib, ..., aeipass nothing special here.

One small tip: merge the files one at a time. It makes keeping track of where you are up to much easier.

Now you can end development of the branch, because all of the files are up-to-date.

In some cases, Aegis has detected a logical conflict where you, the human, know there is none. Remember that the aem command saves the old version of the file with a ,B suffix (`B' for backup). If you have a file like this, just use

% mv fubar,B fubar
%

to discard everything from the ancestor branch, and use the current branch.