break out a page

2 files changed, 28 insertions, 24 deletions

diff --git a/doc/automatic_conflict_resolution.mdwn b/doc/automatic_conflict_resolution.mdwn
new file mode 100644
index 000000000..f20138b19
--- /dev/null
+++ b/doc/automatic_conflict_resolution.mdwn
@@ -0,0 +1,23 @@
+Running `git annex sync` or using the [[assistant]] involves merging
+changes from elsewhere into your repository's currently checked out branch.
+This could lead to a merge conflict, perhaps because the same file
+got changed in two different ways. A nice feature is that these
+merge conflicts are automatically resolved, rather than leaving
+git in the middle of a conflicted merge, which would prevent further
+syncing from happening.
+
+When a conflict 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). The automatic merge
+conflict resoltuion is designed so that if two or more repositories both get
+a merge conflict, and resolve it, the resolved repositories will not
+themselves conflict. This is why it doesn't use something nicer, like
+perhaps the name of the remote that the file came from.
diff --git a/doc/sync.mdwn b/doc/sync.mdwn
index 52beddf9a..ade34d48d 100644
--- a/doc/sync.mdwn
+++ b/doc/sync.mdwn
@@ -17,10 +17,11 @@ Breitner. The idea is to have a branch `synced/master` (actually,
 as a drop-point for other repositories to use to push changes.
 
 When you run `git annex sync`, it merges the `synced/master` branch
-into `master`, receiving anything that's been pushed to it. Then it
-fetches from each remote, and merges in any changes that have been made
-to the remotes too. Finally, it updates `synced/master` to reflect the new
-state of `master`, and pushes it out to each of the remotes.
+into `master`, receiving anything that's been pushed to it. (If there is a
+conflict in this merge, [[automatic_conflict_resolution]] is used to
+resolve it). Then it fetches from each remote, and merges in any changes that
+have been made to the remotes too. Finally, it updates `synced/master`
+to reflect the new state of `master`, and pushes it out to each of the remotes.
 
 This way, changes propagate around between repositories as `git annex sync`
 is run on each of them. Every repository does not need to be able to talk
@@ -35,23 +36,3 @@ 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).