mention automatic merge conflict resolution

1 files changed, 20 insertions, 0 deletions

diff --git a/doc/sync.mdwn b/doc/sync.mdwn
index 540e64545..52beddf9a 100644
--- a/doc/sync.mdwn
+++ b/doc/sync.mdwn
@@ -35,3 +35,23 @@ The workflow for using `git annex sync` is simple:
 * Run `git annex sync` to save the changes.
 * Next time you're working on a different clone of that repository,
   run `git annex sync` to update it.
+
+## automatic merge conflict resolution
+
+The sync process involves merging a branch into your currently checked out
+branch. This could lead to a merge conflict, perhaps because the same file
+got changed in two different ways. An extra feature of `git annex sync` is
+that it automatically resolves these merge conflicts, rather than leaving
+git in the middle of a conflicted merge.
+
+If this occurs, there will be several messages printed about the merge
+conflict, and the file that has the merge conflict will be renamed, with
+".variant-XXX" tacked onto it. So if there are two versions of file foo,
+you might end up with "foo.variant-AAA" and "foo.variant-BBB". It's then
+up to you to decide what to do with these two files. Perhaps you can
+manually combine them back into a single file. Or perhaps you choose to
+rename them to better names and keep two versions, or delete one version
+you don't want.
+
+The "AAA" and "BBB" in the above example are essentially arbitrary
+(technically they are the MD5 checksum of the key).