2.3. Pushing / Pulling

Pushing and pulling is how you get commits to and from remote repositories, respectively. This is mostly covered in the Mercurial tutorials & documentation. This section is concerned with the recommended approach to common issues.

This is very easy to do, you can use hg outgoing and hg push (or the GUI equivalent) to send the changesets (commits) you’ve already made to the master.


By default the target of push and pull is where you cloned the repository from. If you make a local clone of your repository, remember that the default push/pull location will be the local origin, not the master. Edit .hg/hgrc to change where the default points to (or to add aliases).

However, a common occurrence is that you try to push your commits to the master, but find that you get an error saying:

abort: push creates new remote heads!
(did you forget to merge? use push -f to force)

This is a bit of a confusing message, but the most common reason is that someone else pushed their commits before you did, and you’re not allowed to push your changes until you’ve resolved this. The new remote heads refers to the fact that you would effectively create 2 different parallel streams of development on the branch in question, and you can’t (or rather, shouldn’t) push that, although you might do it locally.

The advice "(did you forget to merge? use push -f to force)" is not a great tip either. You almost never want to use push -f, and actually in the most common case of being out of date with upstream changes, there’s a better option than merging - see Section 2.3.2, “Pulling Changesets” below for details.

If you’ve actually created multiple heads for a branch locally - which you may have done deliberately by committing 2 sets of parallel changes from the same base, or because you’ve pulled or imported someone elses changes which were based on an earlier revision, your choices are how to unify those before pushing. See Parallel Development for more details.

Pulling changesets from the master (usually the default) or other repositories is easy to do (hg incoming to preview, hg pull to do it), but it’s important to understand the effects of parallel development.

For now, let’s just say that you always want to use the rebase extension when you pull from the master:

hg pull --rebase

If you forget to use --rebase, it’s no big deal because you can rebase later too, but definitely try to remember to use it because it’s simpler. In TortoiseHg you can set is as the default option, see TortoiseHg config options for details.


There are special occasions where you would not want to use --rebase (or the GUI option equivalent), and this is mainly when pulling changes from very large, long-running forks of the project for re-integration (for example, Google Summer of Code or other long-running experimental forks). These are the minority case so it’s still worth setting rebase as your default behaviour, but just bear in mind that very occasionally you might want to change this.

For more on rebasing and merging, see Parallel Development.