Best Practices for Managing Branches

[jeremy_sg]

Since branches appear in the same "namespace" as your other folders and files, it is important to organize your repository effectively. Most teams organize their code trees by placing distinct product into separate folders. For example, a company with three products called Gandalf, Frodo and Sauron might have a repository that looks something like this:

Code: Select all

	$/
	  Frodo/
		...
	  Sauron/
		...
	  Gandalf/
		src/
		doc/
		tests/
		

We recommend introducing one extra layer of hierarchy below each product's top-level folder, allowing you to separate your main line of development from any branches:

Code: Select all

	$/
	  Frodo/
		...
	  Sauron/
		...
	  Gandalf/
		trunk/
		  src/
		  doc/
		  tests/
		branches/
		  gratuitous_rewrite/
			src/
			doc/
			tests/
	

In the repository above, we create two subfolders under the main Gandalf project folder:
<ul>
<li>The "trunk" subfolder is where the main line of development is happening. All code changes are eventually merged into here.
<li>The "branches" subfolder is where branches are created. The "gratuitous_rewrite" folder is actually a branch which was created from $/Gandalf/trunk.
</ul>

Please note that if you use the "Snapshot" feature, we recommend creating a folder called $/Gandalf/snapshots to house your snapshots.

[lbauer]

More clarification:

Here's how the tree structure would look with a product
in development at version 4.0. Let's call it "MyApp"

Code: Select all

$\Trunk (where the development of MyApp 4.0 is progressing)

     src
     docs
     test

$\ Branches

         MyApp 1.0 (this includes labels for maintenance releases,
                          1.1, 1.2, 1.3, etc.)
                 --src
                 --docs
                 --test

         MyApp 2.0 (includes labeled maintenance releases, 2.1, etc)
                 --src
                 --docs
                 --test

         MyApp 3.0 (includes labeled maintenance releases)
                 --src
                 --docs
                 --test

Here's how it works.

You start with your development of MyApp 1.0. This is your trunk.
When you're done, you label (tag) the final code MyApp 1.0 and
create a branch, also called MyApp 1.0.

Now work on MyApp 2.0 continues in the trunk.

Meanwhile, you need to fix some bugs in MyApp 1.0. You fix them in
the MyApp 1.0 branch. The bugs are fixed, and you label the MyApp
1.0 branch with a MyApp 1.1 label. Then you merge the 1.1 changes
into the continuing development for MyApp 2.0 in the trunk.

MyApp 2.0 is done. Make a branch called MyApp 2.0. You might also want to label it the trunk at that point.

Continue work in the trunk for MyApp 3.0. If you need to do
maintenance releases for MyApp 2.0, do those in the MyApp 2.0
branch, label each, then merge them into the trunk for 3.0.

So in this model, the trunk is where current development occurs, and
the branch is for the finished version and any maintenance releases.