== Sync Extension ==

'''This extension is not distributed with Mercurial.'''

''Author: Graham Helliwell''

Repository: https://bitbucket.org/GrahamHelliwell/hg-sync

=== Overview ===

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.

=== Configuration ===
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):
{{{
[extensions]
sync=path/to/sync.py

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

[tortoisehg-tools]
#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.

 * Fetch is designed as an atomic operation. It either succeeds or changes nothing.
 * Sync is designed from a user workflow perspective. It was intended to be a "do the right thing" button, and as such is not an atomic operation.

For example - you have uncommitted changes:

 * Fetch will immediately bail out, changing nothing.
 * Sync will pull changes from the remote repository, then bail out, having achieved as much as it can without user intervention.

Another example - the user ends up updated to something other than tip
 * Fetch will bail out telling them to hg update. So they need to know something extra, how to update.
 * Sync automatically does the update.

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.

=== Bugs ===
All bugs and features requests should be posted on the [[https://bitbucket.org/GrahamHelliwell/hg-sync/issues?status=new&status=open|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.

=== Credit ===
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.
----
CategoryExtensionsByOthers