Synchronizing Changes in Stacked Branches

When working with stacked branches in Graphite, keeping your changes synchronized across your team is essential. This section covers how to manage synchronization of your stacked branches using Tower's Graphite integration.

Graphite provides powerful synchronization capabilities that Tower makes easily accessible, including keeping branches up-to-date with remote changes, submitting pull requests, and merging your work.

Graphite Toolbar Integration
When you check out a Graphite branch, the standard Pull and Push toolbar items will be replaced with Graphite's equivalents: Sync and Submit. This ensures that you're using the appropriate Graphite actions for synchronizing your stacked branches instead of the standard Git operations. This is indicated by a small Graphite badge icon on the toolbar items.

Sync

The Sync action in Graphite (equivalent to gt get in the Graphite CLI) synchronizes your branches with the remote repository. You can access this action through the Workflow toolbar button, the branch's context menu, or the Workflow main menu after selecting a branch to sync.

When you use the Sync action, the following actions will be performed:

Fetch the latest changes from the remote repository
Update your local branch with those changes
Automatically restack any child branches (unless there are conflicts)

When syncing, Tower will restack from the trunk branch up to your selected branch by default. For a more comprehensive update, you can choose the Sync Full Stack option, which will also restack all child branches below your selected branch.

Handling Conflicts
During sync operations, the command will only restack branches that won't result in conflicts. If you notice that some branches in your stack haven't been updated after a sync, you may need to manually restack them and resolve any conflicts that arise.

The Sync action is comparable to a Pull operation in Git, which is why the toolbar Pull action is replaced with Sync when working with Graphite branches.

Submit

The Submit action in Graphite (equivalent to gt submit in the Graphite CLI) creates or updates pull requests for your stacked branches. You can access this action through the Workflow toolbar button, the branch's context menu, or the Workflow main menu after selecting a branch to submit.

When you use the Submit action, the following actions will be performed:

Create a new pull request if one doesn't exist
Update an existing pull request if one already exists
Push your local changes to the remote repository

Graphite ensures that pull requests maintain the proper dependencies, so reviewers understand the relationship between different changes.

The Submit action is comparable to a Push operation in Git, which is why the toolbar Push action is replaced with Submit when working with Graphite branches.

Merge

The Merge action in Graphite (equivalent to gt merge in the Graphite CLI) submits a branch's pull request for merging. This action is labeled as Add to Merge Queue in Tower. You can access this action through the Workflow toolbar button, the branch's context menu, or the Workflow main menu after selecting a branch to merge.

When you use the Merge action, the following actions will be performed:

Submit the pull request for merging
Update the status of the pull request

Graphite ensures that branches are merged in the correct order, respecting the dependencies between branches in the stack.

Important
The Merge action only submits the branch for merging on the Graphite backend. Once the branch has been actually merged (which may require approval from reviewers or passing CI checks), you will need to perform a manual Sync to refresh your local branches and update your repository state.

Fetching a Stack from Remote

Tower makes it easy to collaborate on stacked branches by allowing you to fetch an entire stack from a remote repository. This is particularly useful when you want to work on or review changes that were created by another team member.

To fetch a stack from remote:

In the sidebar, locate the remote branch you want to fetch in the "Remotes" section
Right-click on the remote branch to open the context menu
Select Fetch Stack for "BRANCH"...

This action will create local branches for the selected branch and all missing branches down to the trunk branch. Tower will automatically establish the proper parent-child relationships between these branches, ensuring that the stack structure is preserved.

The "Fetch Stack" option is only available in the context menu of a remote branch.

After fetching a stack, you can check out any of the branches and work with them as you would with any other Graphite stacked branch. This makes it seamless to collaborate on complex changes across your team.