Sync Extension

This extension is not distributed with Mercurial.

Author: Graham Helliwell



The sync extension provides a useful option for users making changes unlikely to conflict with other repository users, for example Technical Authors and Graphical Designers in an otherwise developer-only project. The intended workflow with the tool is: sync, change, commit, sync.

If the command completes, the local and remote repositories will contain the same changesets (except those marked as secret).

The sync command is composed of 3 actions each of which is atomic and dependent on the previous: pull, update/merge, push.


To install the extension, first download from the site above, and extract it to a folder where you prefer to keep extensions (e.g. $HOME/hgext) or clone it.

To use this extension with hg, you need to edit the hg configuration file in: %USERPROFILE%\mercurial.ini or $HOME/.hgrc

Enable the extension in Mercurial by adding the following lines (replacing path/to with the appropriate path in both cases):


#The following line is a list of toolbar tool names separated by spaces.
workbench.custom-toolbar = sync

#Define the sync tool in thg 2.5+
sync.icon = path/to/hg-sync.svg
sync.command = hg sync
sync.label = sync
sync.showoutput = True
sync.tooltip = Pull incoming changes, update/merge and push outgoing changes

Difference from fetch extension

In terms of functionality, sync is similar to fetch followed by a push. However there are some small but important differences.

For example - you have uncommitted changes:

Another example - the user ends up updated to something other than tip

In summary, the extensions are extremely similar, but are suited for slightly different situations. It is hoped that the sync extension will be particularly helpful for users who are not used to DVCS.

Technical Details

The sync command pulls from remote. If there are local-only committed changes, they are merged (and the merge is committed). Then a push is performed. This is a non-atomic command such that pulled changes remain if later parts fail, but any merge attempt is rolled back if the user cancels.


All bugs and features requests should be posted on the bug tracker. When considering whether something should be included in the extension. Ask yourself whether the result is 99% likely to be what the user wanted to happen in that circumstance.


Thanks to Chris Moore for his help during Down Tools Week. Thanks to Vadim Gelfer for the fetch extension on which this extension is based.


SyncExtension (last edited 2012-10-02 22:40:37 by cpc21-cmbg15-2-0-cust35)