PyCharm 2017.3 Help

Managing Mercurial Branches and Bookmarks

With PyCharm, you can use both named branches and light-weight branches (bookmarks). PyCharm provides interface for creating, merging, and switching between branches and bookmarks, see Switching Between Working Directories. You can also run commands in the embedded Terminal, see Working with Embedded Local Terminal.

On this page:

For information about switching between branches and bookmarks, see Switching Between Working Directories.

Opening the Branches pop-up list

Most of the operations with branches and bookmarks are invoked from the Branches pop-up list.

mercurialBranchesPopUp

The list shows all the Mercurial repositories under the project root, all the named branches, and all the bookmarks in them. The current repository and the current bookmark are marked with a tick. The name of the current named branch is shown in the dedicated hg area on the Status bar:

mercurialStatusBar

To open the Branches pop-up list, do one of the following:

  • On the Status bar, click the name of the current named branch in the dedicated hg area.
    mercurialStatusBar
  • On the main menu, choose VCS | Mercurial | Branches.
  • On the context menu of the Editor or Version Control tool window, choose Mercurial | Branches.

Creating a named branch

The new branch immediately becomes active and its name is shown on the Status bar in the hg area.

  1. In the Branches pop-up list, click New Branch.
  2. In the Create New Branch dialog box that opens, specify the name of the new branch.

Creating a bookmark

  1. In the Branches pop-up list, click New Bookmark.
  2. In the Bookmarks dialog box that opens, specify the name of the bookmark to be created.
  3. Specify, whether you want to switch to the new bookmark immediately or not.
    • To activate the new bookmark and thus enable tracking and updating the light-weight branch the bookmarks identifies, leave the Inactive checkbox cleared. The new bookmark immediately becomes active and its name is marked with a tick in the Branches pop-up list.
    • To have an inactive bookmark created, that is, to remain in the current light-weight branch (bookmark) or named branch and switch to the new bookmark later, select the Inactive checkbox.

Closing a branch

According to Mercurial workflows, when you are done with a feature development and do not expect any further changes, you close the corresponding branch. A closed branch is not displayed among active branches, in the Log view, etc. To close a branch, do the following:

  1. In the Branches popup, click Close branch. The Commit changes dialog will be displayed.
  2. Click Commit and Close. All changes will be committed and the current branch will be closed.

Note that if you have several repositories listed in the Repositories section, the corresponding menu option will toggle to Close branches and the close operation will be applied to all of them.

Merging named branches and bookmarks

You can merge a named branch or a bookmark with another named branch, another bookmark, or a specific changeset identified by a tag or a revision number.

  • Merging a named branch or a bookmark with another named branch or bookmark means merging with its head.

    Merging with named branches and bookmarks can be invoked through the menu item VCS | Mercurial | Merge, which opens the Mercurial-specific Merge dialog box of from the Branches pop-up list.

    mercurialInvokeMergeFromBranchesPopup

  • Merging a named branch or a bookmark with a changeset means merging the branch head with the specified changeset. A changeset can be identified either by a revision number or a tag, see https://www.mercurial-scm.org/wiki/Tag.

    Merging a named branch or a bookmark with a specific changeset can be invoked only through VCS | Mercurial | Merge.

For definitions and Mercurial-specific details regarding the merge operation itself, see https://www.mercurial-scm.org/wiki/Merge.

By default, Mercurial requires that before merge the current working directory should be clean, that is, it should not contain any uncommitted changes. Otherwise the merge operation fails and PyCharm shows the corresponding error message. The message also recommends that you clean the current working directory by running the hg merge <target branch, bookmark, or changeset> -C to discard the uncommitted changes.

If your current working copy is not clean, you can either commit the changes or shelve them as described in Shelving and Unshelving Changes.

Merging a named branch or bookmark with another named branch or bookmark

Merging a named branch or a bookmark with another named branch or bookmark means merging with its head.

  1. Make sure, your current working directory is clean, that is, it does not contain any uncommitted changes. Commit or shelve the changes, if any.
  2. Invoke merge by doing one of the following:
    • In the Branches pop-up list, click the name of the branch or bookmark to merge with, then choose Merge on the pop-up menu:
    • Choose VCS | Mercurial | Merge on the main menu or Mercurial | Merge on the context menu of the Editor.

      In the Merge dialog box that opens:

      1. Choose the target repository from the Repository drop-down list which shows all the Mercurial repositories available under the current project root.
      2. Choose the Branch or Bookmark option and choose the named branch or bookmark to merge the current working directory with.

  3. Resolve conflicts. As soon as a conflict takes place, the Files Merged with Conflicts dialog box opens with a list of conflicting files. Use the controls of the dialog box to resolve the problems:
    • To have the version of the current working directory preserved, click Accept Yours.
    • To have the version of the branch you are merging with preserved, click Accept Theirs.
    • To resolve the conflicts manually, click Merge and use the Conflict Resolution Tool, as described in Resolving Conflicts.

    If no conflicts arise during merge, the operation passes silently and the merge log is shown in the Version Control tool window.

Merging a named branch or bookmark with a changeset

Merging a named branch or a bookmark with a changeset means merging the branch head with the specified changeset. A changeset can be identified either by a revision number or a tag, see https://www.mercurial-scm.org/wiki/Tag.

  1. Make sure, your current working directory is clean, that is, it does not contain any uncommitted changes. Commit or shelve the changes, if any.
  2. Choose VCS | Mercurial | Merge on the main menu or Mercurial | Merge on the context menu of the Editor.
  3. In the Merge dialog box that opens:
    1. Choose the target repository from the Repository drop-down list which shows all the Mercurial repositories available under the current project root.
    2. Choose the Tag or Revision option and choose the tag or specify the hash or revision number to merge the current working directory with. To copy a hash, open the Log tab of the Version Control tool window, select the relevant branch and revision, and then choose Copy Hash on the context menu of the selection.
  4. Resolve conflicts. As soon as a conflict takes place, the Files Merged with Conflicts dialog box opens with a list of conflicting files. Use the controls of the dialog box to resolve the problems:
    • To have the version of the current working directory preserved, click Accept Yours.
    • To have the version of the branch you are merging with preserved, click Accept Theirs.
    • To resolve the conflicts manually, click Merge and use the Conflict Resolution Tool, as described in Resolving Conflicts.

    If no conflicts arise during merge, the operation passes silently and the merge log is shown in the Version Control tool window.

Last modified: 28 March 2018

See Also