Working in parallel

Branching and merging

You want to work on a project with your team, but you don’t want to step on each other’s toes. No worries! There’s a way to work on your project in parallel without interfering with each other’s work, and then recombine it all together when you’re done. It’s called branching and merging.

Branching

You can think of a branch as a separate version of your project. When you create a branch, you’re creating a copy of your project at that point in time.

Creating a new branch

In the Desktop App:

1. Click the 'New Branch' button

   This is in your workspace view.

   
2. Choose a branch name

   Give your branch a name that describes what you’re working on. Also, pay attention to the commit you’re branching from - this will be the base for our new branch. You can automatically switch to the new branch after creating it by leaving the checkbox checked, it’s checked by default.

   
3. Click Create

Via the CLI, see the branch command for creating branches and more options.

Switching branches

In the Desktop App, the branch dropdown in the header shows your current branch. Click it to see all branches in the repository. Clicking on another branch lets you view it in read-only mode without switching. To switch, click the menu for the branch you want and select “Switch to branch”.

If you have any changes in your workspace that you haven’t committed, you can choose to discard them, shelve them for later, or take them with you to the new branch, if possible (see Merge conflicts below).

Via the CLI, see the checkout command for switching branches.

Switching a branch changes the files on your computer. For some game engines, like Unreal Engine, you might need to restart the editor to see the changes.

Branch graph

You can see a visual graph of all your branches and commits in the Desktop App.

1. Open the branch graph

   Click the Timeline icon in the top bar of your workspace.

   
2. Navigate the graph

   The graph shows an interactive visualization of all branches and commits. You can pan and zoom to navigate around the graph.

   
3. Access actions from the graph

   Right-click on any commit or branch in the graph to open its context menu. From here you can access the same actions available elsewhere — create a branch, cherry-pick a commit, merge, and more.

   

If you have a lot of branches, this is a great way to understand how they relate to each other.

Important things to remember

1. Working on any branch is just like working on your main branch. Making changes, committing, syncing - it’s all the same.
2. Branches are visible to anyone in your repo, and anyone can switch to any branch.
3. The committed changes on the branch are only available to team members who are on the same branch.
4. There is no need to pull or fetch. When a teammate commits to a branch you’re on, your workspace is updated automatically. See syncing for more details on how auto-update works and how to control it.

Managing branches

Delete a branch

If you no longer need a branch, you can delete it. Note that you cannot delete the default branch.

In the Desktop App, in the branch list, right-click (or click the menu icon) on the branch you want to delete and select “Delete”.

What happens when you delete the branch you’re currently on? If you delete the branch you are currently viewing, you will be redirected to the repository’s main page. Any workspaces that were checked out to the deleted branch will remain in a detached state — they keep their current files and uncommitted changes, but are no longer associated with any branch. To continue working, switch to another branch from the workspace.

Via the CLI, see the branch command for deleting branches and more options.

Rename a branch

You can rename a branch from the Desktop App. This is not supported for repositories synced with Git.

In the branch list, right-click (or click the menu icon) on the branch you want to rename and select “Rename”. Type the new name and click “Rename”.

Via the CLI, see the branch command for renaming branches.

Set the default branch

The default branch is the branch that new workspaces are based on when they are created. Only admins can change the default branch, and this option is only available in the Desktop App.

In the branch list, right-click (or click the menu icon) on the branch you want to set as default and select “Set as default branch”. This option is only visible if you are an admin of the repository.

There is no CLI equivalent for this action.

Merging

When you’re done working on your branch, you can merge it back into your main branch. Merging takes all of the changes from one branch and applies them to another.

How to merge

In the Desktop App, go to the workspace view, choose the branch you want to merge, and select the merge option from the menu.

If there are no conflicts, you should see a new merge commit in your branch history.

Via the CLI, see the merge command for merging branches.

Merge conflicts

Sometimes, the changes you made on your branch conflict with the changes someone else made on another branch. When you try to merge these branches together, you’ll have to decide how to handle these conflicting changes.

In the Desktop App, if you have conflicting changes and follow the steps in How to merge, you’ll see a screen that shows you the conflicting files instead of the successful merge commit.

The conflict window has 4 parts:

1. A list of files with conflicting changes.
2. For each file on the list:
   1. The incoming file. This is a readonly version of the file that’s on the branch you’re trying to merge from.
   2. The current file. This is a readonly version of the file that’s on the branch you’re trying to merge into.
   3. The outcome file. This is what the file will look like after you resolve the conflict. This is editable.

To resolve a conflict, you need to decide which changes to keep and which to discard. You can choose either the incoming version, the current version, or a combination of both. And, as mentioned above, you can edit the outcome file directly.

If you want to make the same choice for many files, you can select them using their checkboxes and use the buttons at the bottom.

When you’re done, type a commit message and hit ‘Commit’.

For resolving merge conflicts via the CLI, see Handling Merge Conflicts (CLI).

Merging non-text files

Non-text files, like images, 3d models, spritesheets, animations, etc., can’t be merged. This merge process works because text files are human-readable and can be compared line by line. If you have a merge conflict with a non-text file you have 2 options:

1. If you have a specific tool that can merge these files, you can use it to resolve the conflict. One example is Unreal Engine’s built-in merge tool which you can use if you have our plugin.
2. Choose one version to keep and discard the other.

Merge conflict warning

Diversion has a feature that warns you about files that are being edited by other team members, and might cause a merge conflict. If you see the merge warning icon on a file, you can click on it and get info about who’s editing the file. Be sure to communicate before working on it to prevent merge conflicts. As mentioned above, this is crucial when working on non-text files.