PhpStorm 2021.2 Help

Manage Mercurial branches and bookmarks

With PhpStorm, you can use both named branches and light-weight branches (bookmarks). PhpStorm provides interface for creating, merging, and switching between branches and bookmarks, see Switch between Mercurial working directories. You can also run commands in the Terminal.

For information about switching between branches and bookmarks, see Switch between Mercurial working directories.

Opening the Branches list

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

Mercurial branches popup

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:

Mercurial status bar

To open the Branches list, do one of the following:

  • On the Status bar, click the name of the current named branch in the dedicated hg area.

    Mercurial status bar
  • From the main menu, choose VCS | Mercurial | Branches.

  • From the context menu of the Editor or Mercurial 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 list, click New Branch.

  2. In the Create New Branch dialog that opens, specify the name of the new branch.

Creating a bookmark

  1. In the Branches list, click New Bookmark.

  2. In the New Bookmark dialog 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 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, and so on. 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 of from the Branches list.

    Merge from branches

  • 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 PhpStorm 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 Shelve and unshelve 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 list, click the name of the branch or bookmark to merge with, then choose Merge from the list:

    • Choose VCS | Mercurial | Merge on the main menu or Mercurial | Merge from the context menu of the Editor.

      In the Merge dialog that opens:

      1. Choose the target repository from the Repository 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 Conflicts dialog opens with a list of conflicting files. Use the controls of the dialog 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 Resolve conflicts.

    If no conflicts arise during merge, the operation passes silently and the merge log is shown in the Mercurial 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 From the context menu or Mercurial | Merge from the context menu of the Editor.

  3. In the Merge dialog that opens:

    1. Choose the target repository from the Repository 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 Mercurial tool window Alt+9, select the relevant branch and revision, and then choose Copy Hash from the context menu.

  4. Resolve conflicts. As soon as a conflict takes place, the Conflicts dialog opens with a list of conflicting files. Use the controls of the dialog 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 Resolve conflicts.

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

Last modified: 11 November 2021