.\"
.\"	aegis - project change supervisor
.\"	Copyright (C) 1995, 1998, 1999, 2001 Peter Miller;
.\"	All rights reserved.
.\"
.\"	This program is free software; you can redistribute it and/or modify
.\"	it under the terms of the GNU General Public License as published by
.\"	the Free Software Foundation; either version 2 of the License, or
.\"	(at your option) any later version.
.\"
.\"	This program is distributed in the hope that it will be useful,
.\"	but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"	GNU General Public License for more details.
.\"
.\"	You should have received a copy of the GNU General Public License
.\"	along with this program; if not, write to the Free Software
.\"	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
.\"
.\" MANIFEST: User Guide, Branching
.\"
.bp
.if t .2C
.nh 1 "Branching"
.LP
This chapter describes the concept of branching
implemented by Aegis.
The process described in previous chapters makes changes to a project's
master source.
.PS
line from (0,0) to (2.5,0) "" "Baseline"
L1: line from (0.25,0) to (0.375,0.125) to (0.625,0.125) to (0.75,0)
"1" above at (0.5,0.125)
L2: line from (1,0) to (1.125,0.125) to (1.375,0.125) to (1.5,0)
"2" above at (1.25,0.125)
L3: line from (1.75,0) to (1.875,0.125) to (2.125,0.125) to (2.25,0)
"3" above at (2.0,0.125)
.PE
.LP
Branching generalizes this change model,
by allowing the baseline to be treated as a change,
or the ability to treat a change as a baseline.
.PS
line from (0,0) to (2.5,0) "" "Baseline"
L1: line from (0.25,0) to (0.375,0.125) to (2.125,0.125) to (2.25,0)
"Branch 1" above at (0.5,0.125)
L2: line from (0.875,0.125) to (1,0.25) to (1.25,0.25) to (1.375,0.125)
"1.1" above at (1.125,0.25)
L3: line from (1.5,0.125) to (1.625,0.25) to (1.875,0.25) to (2,0.125)
"1.2" above at (1.75,0.25)
.PE
.LP
A significant feature of Aegis branches is that, because they are
an extension of the
.I change
concept,
they are expected to end,
and be integrated back into
.I their
baseline in time.
.LP
The commonest case of this is in project releases.
.LP
A branch in the
.I "being developed"
state may have changes made to it,
deeper branches.
This may recurse to any level.
Once a branch is complete,
no further deeper branches may be created from that branch.
.nh 2 "How To Use Branching"
.LP
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 a "aegis.1".
To reference changes on this branch,
use this compound project name wherever you would normally use a project name.
.LP
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".
.LP
By default,
these two level of project branching are created automatically when
the \fIaenpr\fP(1) command is used.
You need to use the
.B -VERSion
option to make this deeper or shallower, or have different numbering.
.TS
box,center,tab(;);
lw(1i)|lw(1i).
Command;Branches Created
_
aenpr foo;T{
foo, foo.1, foo.1.0
T}
T{
aenpr foo -vers 2.4.1
T};T{
foo, foo.2, foo.2.4, foo.2.4.1
T}
aenpr foo.7;T{
foo, foo.7
T}
T{
aegis -npr foo -vers -
T};foo
.TE
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).
.nh 2 "Transition Using aenrls"
.LP
To convert a project from the old-style to the new branching style,
use the \fIaenrls\fP(1) command.
.LP
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 \fIaenpr\fP(1) command.
.LP
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 \fIaenrls\fP(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 then branch number(s) are already in use,
\fIaenrls\fP(1) will emit an error and fail.
The \fIaenrls\fP(1) command only works on old-style projects,
and always converts them to new style projects.
.LP
Planning you branch numbers is essential.
If you want to use 3-level branch numbers (e.g. "aegis.2.3.1")
at time 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).
.nh 2 "Cross Branch Merge"
.LP
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 \fB\-BRanch\fP option to the \fIaegis -diff
-merge-only\fP command.
.LP
The most common cross branch merge is when the project's files
are out-of-date.  Because it is not possible to use \fIaegis -diff
-merge-only\fP directly on the branch, this must be in a change on
the branch.  As a short-cut, the branch may be specified using the
\fI\-grandparent\fP option.
.nh 2 "Multiple Branch Development"
.LP
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 \fIaegis -clone\fP command, which can be
used to identically reproduce a change on another branch.
.so c9.1.so
.so c9.2.so
.so c9.3.so