Working with Stacked Branches

With the help of Branch Dependencies, you can easily create multiple branches depending on each other.

This is useful if you develop a series of features depending on each other or if you want to split feature development into a smaller set of changes, for example when using the “Stacked Pull Requests” workflow, where each logical change is represented by its own branch so it can be reviewed and merged individually.

As these branches depend on each other, the challenge is to keep later changes in parent branches (e.g. during code reviews) in sync with the child branches. Tower will automatically detect changes in parent branches and offer to synchronize all changes using the “Restack“ action.

Restacking Branches

Restacking becomes necessary if any of the parent branches has introduced changes. Our child branch might directly depend on those changes or we simply want to ensure that we have all the latest changes from the parents to work with in order to avoid conflicts.

If Tower detects a change in a branch that has child branches, it will mark them as “needs restacking”. This state is represented by a special icon in the sidebar and the child branch's history will also offer a hint that this branch needs to be restacked.

You can also run the Restack action from a child branch's context menu in the sidebar.

Restacking brings all changes in line by subsequently rebasing each child branch onto its parent branch up to the “trunk” branch (usually the “main” branch in a repository).

Viewing Stacked Branches

In Tower's settings, under the “General“ tab, you can enable the option “Stack branches under parent branches” to display child branches underneath their parent.
If the parent branch is one of the typical base branches in a repository (like “main” or “master”), any child branches will not be grouped under those branches as almost every stacked branch group starts from such a branch.

Grouping Stacked Branches
If you group refs in the sidebar, this will also take precedence over the branch's dependency. This allows you to logically group multiple branches for the same feature together while it depends on a different feature branch.