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, etc.
In PyCharm, all operations with branches are performed in the Git Branches popup. To invoke it, do one of the following:
- Click the Git widget in the Status bar:
- Invoke the VCS Operations popup by choosing VCS Operations Popup from the main menu, or press Alt+Back Quote and select Branches there.
- From the main menu, choose VCS | Git | Branches.
- Right-click any file in the editor, and in the context menu choose Git | Repository | Branches.
If you have many branches, you can choose whether you want to display all of them in the Branches popup, or just the favorites. To do this, toggle the Show Only Favorites and the Show x More commands at the bottom of the Branches popup.
To mark a branch as a favorite, hover the mouse cursor over the branch name, and click the star outline that appears on the left: . The
master branch is marked as a favorite by default.
The name of the branch that is currently checked out is displayed in the Git widget in the Status bar.
If you have a multi-rooted repository, you can enable synchronous branch control, which means that all branch operations (such as checkout, merge, delete, etc.) will be performed simultaneously as if it were a single repository. If an operation fails at least in one of the repositories, PyCharm prevents branches from diverging by suggesting you to roll back this operation in the repositories where it was successful. You can enable synchronous branch control in the Settings/Preferences dialog (Ctrl+Alt+S) under Version Control | Git.
Create a new branch
If you want to create a new branch, for example to work on a new feature, do the following
- In the Branches popup, choose New Branch.
- 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 HEAD. If you want to start a branch from a previous commit instead of the current branch HEAD, select this commit in the Log and select New Branch from the context menu.
Checkout a branch as a new local branch
If you want to work in a branch created by someone else, you need to check it out to create a local copy of that branch:
- In the Branches popup, 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, and choose Checkout as new local branch from the list of available operations.
- Enter a new name for this branch if necessary, or leave the default name that corresponds to the remote branch, and click OK.
Switch between branches
When multitasking, you often need to jump between branches to commit unrelated changes. To switch to a different branch, in the Branches popup, select the branch that you want to switch to under Local Branches and choose Checkout from the list of available operations. 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 (i.e. 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 PyCharm window).
- If your local changes will be overwritten by checkout, PyCharm displays a list of files that prevent you from checking out the selected branch, and suggests to choose 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, PyCharm will stash uncommitted changes, check out the selected branch, and then unstash the changes. If a conflict occurs during the unstash operation, you will be prompted to merge the changes. For details, see Resolve conflicts.
If you want to check how two branches have diverged from each other, you can compare them. To do this, from the Branches popup select the branch that you want to compare with the current branch, and choose Compare from the list of available operations.
In the dialog that opens, the Log tab shows a list of all commits that exist in one branch and do not exist in the other. When you select a commit, the right pane displays a list of files that were affected by this commit. You can click the Show Diff icon on the toolbar to see how exactly the selected file was changed in this commit.
The Files tab shows a list of all files that have diverged between the two branches. Clicking shows the differences between the selected file in the current branch and in the branch you are comparing it with.
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:
- Invoke the branches popup and select the branch you want to delete.
- Choose Delete from the submenu.
After you have deleted a branch, a notification will be displayed in the bottom-right corner from which you can restore the deleted branch:
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, you will also be able to remove the remote branch from this notification.