Git Branches for Multi-root Projects

Sometimes there is a need to have multiple Git repositories within a single project. Since long ago IntelliJ IDEA is able to execute many Git operations on all roots at once: Commit, Update Project, Push. Now multi-repository support has come to branches.

In IntelliJ IDEA 11.1 we have implemented two different approaches for multi-root branches.

Most people who use multi-root setup probably have a single repository for project development and several repositories for libraries. They may be included as submodules or just as nested roots, it doesn’t matter for now. For these everything is simple. When you invoke Git Branches popup, you see all branches in the current repository. Other repositories are accessible from the popup as sub-popups with all branches listed there for each repository, with all usual branch actions available for them.

What is the current repository? If you have explicitly selected a file or folder in the Project View or elsewhere, we take the root under which the file is located. Otherwise (if you clicked on the status bar widget or from the main menu) we take the root of the file currently open in the editor.

Synchronous branch control

There is also another case: when users have several repositories in one project that are connected. We at Jetbrains have a configuration like this in one of our projects. There are 3 repositories in a single project, and these repositories are controlled synchronously, i.e. we commit, push and apply other operations to all 3 repositories at once. For such projects IntelliJ IDEA allows to control branches synchronously. It means performing all branch operations on several repositories simultaneously, as it would be a single repository.

When you invoke Git Branches for the first time, IDEA looks at the repositories registered in the project, and if they all are on branches with same names, proposes to control branches synchronously.

If you don’t need it, you may disable it right away or later in the Settings | Version Control | Git | Control branches from different roots synchronously.

If the setting is enabled, all operations on Git branches will be executed for all repositories at once. On the root level of Git Branches popup there will be listed only those local and remote branches which are common for all repositories in the project. Creating new branch from the popup will create it on all repositories, checking out a branch will checkout it on all repositories, etc. This applies to all actions including checkout, merge and delete. Compare just shows the standard dialog with additional selector to choose the root.

You may still control branches individually for each root by using repository selector in the popup. If you happen to checkout a branch only on one of the roots, you’ll get the warning that branches have diverged. Of course, you won’t get this warning if you have disabled synchronous branch control.


There is one more nice feature for synchronous branch management. If you decided to checkout a branch on several roots, and checkout failed for some of them, but has already succeeded for others, you’re in the situation when branches diverge: for example, you are on master in one repository and on feature branch in the other.

To prevent this, the IDE offers to rollback successful checkout. Rollback checkout means just checkout back to the previous branch.

Rollback is offered for checkout, merge and other branch actions.

That’s all about Git branches for today.

We are looking forward for your feedback about the Git branch control interface in IntelliJ IDEA. Your suggestions are welcome. Please submit bug reports directly to our issue tracker.

Discover more