PhpStorm 2022.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.

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

The popup 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 check mark. The name of the current named branch is shown in the Status bar.

Mercurial status bar

Open the Branches popup

  • In the Status bar, click the Mercurial Branch widget.

    Mercurial widget in Status bar
  • From the main menu, choose Hg | Mercurial | Branches.

  • From the context menu of the editor or the Mercurial tool window, choose Mercurial | Branches.

Branches

Create a named branch

The new branch immediately becomes active and its name is shown on the Mercurial Branches widget in the Status bar.

  1. Click the Mercurial Branches widget in the status bar to open the Branches popup and click New Branch.

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

Close 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. Click the Mercurial Branches widget in the status bar to open the Branches popup and click Close Branch.

  2. In the Branches popup, click Close branch. The Commit changes dialog will be displayed.

  3. 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.

Bookmarks

Create a bookmark

  1. Click the Mercurial Branches widget in the status bar to open the Branches popup and click New Bookmark.

  2. In the New Bookmark dialog that opens, name the new bookmark.

  3. Select the Inactive option to remain in the current light-weight branch (bookmark) or named branch and switch to the new bookmark late.

    Disable the option to activate the new bookmark and enable tracking and updating the light-weight branch.

Merge 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.

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.

Merge a named branch or bookmark with another 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. From the main menu, select Hg | Mercurial | Branches.

  3. In the Merge dialog that opens, choose the target repository from the Repository list which shows all the Mercurial repositories available under the current project root.

  4. Choose the Branch or Bookmark option and choose the named branch or bookmark to merge the current working directory with.

  5. To prevent failures during update if the current working directory is not clean, select the Overwrite locally modified files (no backup) checkbox. The uncommitted changes will be discarded.

  6. 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.

Merge 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.

  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. From the main menu, select Hg | Mercurial | Branches.

  3. In the Merge dialog that opens, choose the target repository from the Repository list which shows all the Mercurial repositories available under the current project root.

  4. 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.

  5. 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: 01 August 2022