PhpStorm 2016.2 Help

Git Branches in Multirooted Projects

On this page:


Sometimes you may need to have several local Git repositories within a single project. Such multirooted project can be set up in the following ways:

  • The repositories are independent, they can be included in the project just as nested roots. One of these repositories can be intended for the project development itself while the others store the libraries used.

    Such repositories are controlled asynchronously, that is, commit, push, and other operations can be applied to them independently, just as it is done in projects with one Git repository.

  • The repositories are mutually connected. Such repositories most often need to be controlled synchronously, that is, commit, push, and other operations should be applied to all these repositories at once. For such projects PhpStorm also allows you to control branches synchronously. This means that all branch operations on several repositories are performed simultaneously as if it were a single repository. In case an operation fails in at least one of the repositories, PhpStorm rolls it back in the repositories where the operation has passed successfully.

Asynchronous branch control

Asynchronous control is applied to the branches in a multirooted project when all local Git repositories in the project are independent. Commit, push, and other operations to the branches in the repositories are applied independently, just as it is done in projects with one Git repository.

To apply a Git operation to a branch asynchronously (in one of the repositories)

  1. Open the Git Branches popup menu.
  2. In the Git Branches popup menu that opens, choose the branch to apply the required action to. The popup menu shows a list of branches in the current repository and a list of all the repositories in the project.

    The current repository is detected in the following ways:

    • If you have explicitly selected a file or a folder in the Project tool window or elsewhere, PhpStorm treats the root under which the file is located as current repository.
    • If you used the VCS | Git | Git Branches command on the main menu, PhpStorm treats the root of the file currently opened in the editor as current repository.

    Do one of the following:

    • To update a branch in the current repository, select the branch in the list.
    • To access another repository, select it under the Repositories group, and then select the relevant branch in the subordinate popup menu that opens.
  3. Click the branch and choose the required action from the popup menu that opens.

Synchronous branch control

In a multirooted project when several mutually connected repositories, it is often helpful to apply synchronous branch control, which involves the following:

  • All branch operations on several repositories are performed simultaneously as if it were a single repository. This applies to all actions including checkout, merge, and delete. If you invoke the compare action, PhpStorm shows a dialog box where you are asked to choose the repository to compare the branch with.
  • The Git Branches popup lists only those local and remote branches that are common for all the repositories in the project.
  • Creating a new branch from the popup will create it on all the repositories.
  • You may still control branches individually for each repository by using the repository selector in the Git Branches popup menu. If you happen to checkout a branch only in one of the repositories, you’ll get the warning that branches have diverged:

To disable synchronous branch control, do one of the following

When you invoke the Git Branches popup menu for the first time, PhpStorm examines the repositories registered in the project. If they all are on branches with same names, PhpStorm displays a popup menu that proposes to control branches synchronously.

To enable synchronous branch control

Rolling back a successful operation if it fails in some of the repositories

If you checkout a branch on several roots and the operation fails for some of the roots but has already succeeded for the others, the branches diverge. For example, the master branch is checked out in one repository while the feature branch is checked out in the other.

To prevent this, PhpStorm offers to rollback the successful checkout operation, so the previous checked out branch is checked out again.


Besides checkout, PhpStorm suggests to rollback merge and other branch operations.

See Also

Last modified: 24 November 2016