PhpStorm 2020.2 Help

Manage Git branches

In Git, branching is a powerful mechanism that allows you to diverge from the main development line, for example, when you need to work on a feature, or freeze a certain state of a code base for a release, and so on.

In PhpStorm, all operations with branches are performed in the Git Branches popup: To invoke it, click the Git widget in the Status bar (it shows the name of the branch that is currently checked out):

Git widget

You can also manage branches and perform batch operations with multiple branches in the Branches pane of the Git tool window.

Branches pane

Mark branches as favorites

If you have many branches, you may want to see only your favorite ones. The master branch is marked as a favorite by default. Favorite branches are always displayed at the top of the Branches popup and in the Branches pane of the Git tool window .

  • To mark a branch as a favorite, in the Branches popup, hover the mouse cursor over the branch name, and click the star outline that appears on the left:

    favourite branch

    You can also select a branch in the Branches pane of the Git tool window and click the Star icon on the toolbar.

  • To hide non-favorite branches, click Show Only Favorites at the bottom of the Branches popup.

Create new branch

Create a new branch from current branch

  1. In the Branches popup, choose New Branch or right-click the current branch in the Branches pane of the Git tool window tool window and choose New Branch.

  2. In the dialog that opens, specify the branch name, and make sure the Checkout branch option is selected if you want to switch to that branch.

    The new branch will start from the current branch HEAD.

Create a new branch from selected branch

  1. In the Branches popup or in the Branches pane of the Git tool window select a local or a remote branch that you want to start a new branch from and choose New Branch from Selected.

  2. In the dialog that opens, specify the branch name, and make sure the Checkout branch option is selected if you want to switch to that branch.

Create a new branch from selected commit

  1. In the Log view, select the commit that you want to act as a starting point for the new branch and choose New Branch from the context menu.

  2. In the dialog that opens, specify the branch name, and make sure the Checkout branch option is selected if you want to switch to that branch.

Check out branches (git-checkout)

Check out a branch as a new local branch

If you want to work on a branch created by someone else, you need to check it out to create a local copy of that branch.

To make sure you have a full list of remote branches, click Fetch icons.actions.refresh.svg in the branches popup:

the Fetch icon
  1. In the Branches popup or in the Branches pane of the Git tool window , select a branch that you want to check out locally from Remote Branches, or Common Remote Branches if your project has several roots and synchronous branch control is enabled, or from Repositories | Remote Branches if it is disabled.

  2. Choose Checkout from the list of actions.

  3. Enter a new name for this branch if necessary, or leave the default name that corresponds to the remote branch, and click OK.

    The new local branch will be set to track the origin remote branch.

Switch between branches

When multitasking, you often need to jump between branches to commit unrelated changes.

  1. In the Branches popup or in the Branches pane of the Git tool window , select the branch that you want to switch to under Local Branches and choose Checkout from the list of available operations.

  2. What happens next depends on whether there are conflicts between your local changes that you have not committed yet, and the branch that you are going to check out:

    • If your working tree is clean (that means you have no uncommitted changes), or your local changes do not conflict with the specified branch, this branch will be checked out (a notification will pop up in the bottom-right corner of the PhpStorm window).

    • If your local changes are going to be overwritten by checkout, PhpStorm displays a list of files that prevent you from checking out the selected branch, and suggests choosing between Force Checkout and Smart Checkout.

      If you click Force Checkout, your local uncommitted changes will be overwritten, and you will lose them.

      If you click Smart Checkout, PhpStorm will shelve uncommitted changes, check out the selected branch, and then unshelve the changes. If a conflict occurs during the unshelve operation, you will be prompted to merge the changes. For details, see Resolve conflicts.

Compare branches

Compare a branch with the current branch

If you want to check how a branch has diverged from the current branch, you can compare them.

  1. From the Branches popup or from theBranches pane of the Git tool window , select the branch that you want to compare with the current branch, and choose Compare with Current.

    A new tab will be added to the Git tool window listing all commits that exist in the selected branch and do not exist in the current branch.

    You can click the Swap Branches link to change which branch is considered as a base against which you are comparing the other branch.

  2. To see a list of all files that are different in the two branches, click Ctrl+A: the Changed Files pane will list all files that contain differences.

Compare a branch with the working tree

Apart from comparing a branch with the current branch, you can compare it against the local state of the current branch. This is useful if you have local uncommited changes.

  • From the Branches popup or from theBranches pane of the Git tool window , select the branch that you want to compare with the local working tree, and choose Show Diff with Working Tree.

    A list of all files that are different in the selected branch and in the local state of the current branch will be displayed in a separate window.

    You can click the Swap Branches link to change which branch is considered as a base against which you are comparing the other branch.

Compare any two branches

Apart from comparing a branch with the current branch or its local state, you can compare any two branches to see which commits or files exist in one branch and don't exist in the other.

  1. In the Branches pane of the Git tool window select two branches that you want to compare (Ctrl+Click) and choose Compare Branches from the context menu.

    A new editor tab till open showing all commits that exist in one branch and don't exist in the other, and vice versa.

  2. To see a list of all files that are different in the two branches, click Ctrl+A: the Changed Files pane will list all files that contain differences.

Delete branches

After you have integrated the changes from a feature branch into the main line of development, you can delete the branch you do not need anymore.

  1. Check out a branch that you are going to use for further work.

  2. In the Branches popup or from the Branches pane of the Git tool window , select the branch you want to delete and choose Delete.

After you have deleted a branch, a notification will be displayed in the bottom-right corner from which you can restore the deleted branch:

deleted branch notification

If the branch contained commits that have not yet been merged to its upstream branch or to the current branch, it will still be deleted immediately (equivalent to the git branch --D or git branch --delete --force command), but the notification will also contain a link allowing you to view the unmerged commits.

If the deleted branch was tracking a remote branch, there will also be a link in this notification to remove the remote branch.

Configure synchronous branch control

If you have a multi-rooted repository, you can configure PhpStorm to perform all branch operations (such as checkout, merge, delete, and so on) simultaneously on all roots as if it were a single repository. If an operation fails at least in one of the repositories, PhpStorm prevents branches from diverging by suggesting you to roll back this operation in the repositories where it was successful.

  1. In the Settings/Preferences dialog Ctrl+Alt+S select Version Control | Git.

  2. Select the Execute branch operations on all roots option (note that this option is only available if your project has multiple roots).

Last modified: 21 September 2020