Merge branch 'autosync'

3 files changed, 59 insertions, 10 deletions

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 8096005ce..a0dd3d3f1 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -120,16 +120,27 @@ subdirectories).
   Use this to undo an unlock command if you don't want to modify
   the files, or have made modifications you want to discard.
 
-* sync
-
-  Use this command when you want to synchronize the local repository
-  with its default remote (typically "origin"). The sync process involves
-  first committing all local changes, then pulling and merging any changes
-  from the remote, and finally pushing the repository's state to the remote.
-  You can use standard git commands to do each of those steps by hand,
-  or if you don't want to worry about the details, you can use sync.
-
-  Note that sync does not transfer any file contents from or to the remote.
+* sync [remote ...]
+
+  Use this command when you want to synchronize the local repository with
+  one or more of its remotes. You can specifiy the remotes to sync with;
+  the default is to sync with all remotes. Or specify --fast to sync with
+  the remotes with the lowest annex-cost value.
+
+  The sync process involves first committing all local changes, then
+  fetching and merging the `synced/master` and the `git-annex` branch
+  from the remote repositories and finally pushing the changes back to
+  those branches on the remote repositories. You can use standard git
+  commands to do each of those steps by hand, or if you don't want to
+  worry about the details, you can use sync.
+
+  Note that syncing with a remote will not update the remote's working
+  tree with changes made to the local repository. However, those changes
+  are pushed to the remote, so can be merged into its working tree
+  by running "git annex sync" on the remote.
+
+  Note that sync does not transfer any file contents from or to the remote
+  repositories.
 
 * addurl [url ...]
 
diff --git a/doc/index.mdwn b/doc/index.mdwn
index 5bd42074f..e0791bf71 100644
--- a/doc/index.mdwn
+++ b/doc/index.mdwn
@@ -45,6 +45,7 @@ files with git.
 * [[git-annex man page|git-annex]]
 * [[key-value backends|backends]] for data storage
 * [[special_remotes]] (including [[special_remotes/S3]] and [[special_remotes/bup]])
+* [[sync]]
 * [[encryption]]
 * [[bare_repositories]]
 * [[internals]]
diff --git a/doc/sync.mdwn b/doc/sync.mdwn
new file mode 100644
index 000000000..765c1e43f
--- /dev/null
+++ b/doc/sync.mdwn
@@ -0,0 +1,37 @@
+The `git annex sync` command provides an easy way to keep several
+repositories in sync. 
+
+Often git is used in a centralized fashion with a central bare repositry
+which changes are pulled and pushed to using normal git commands.
+That works fine, if you don't mind having a central repository.
+
+But it can be harder to use git in a fully decentralized fashion, with no
+central repository and still keep repositories in sync with one another.
+You have to remember to pull from each remote, and merge the appopriate
+branch after pulling. It's difficult to *push* to a remote, since git does
+not allow pushes into the currently checked out branch.
+
+`git annex sync` makes it easier using a scheme devised by Joachim
+Breitner. The idea is to have a branch `synced/master` (actually,
+`synced/$currentbranch`), that is never directly checked out, and serves
+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.
+
+This way, changes propigate around between repositories as `git annex sync`
+is run on each of them. Every repository does not need to be able to talk
+to every other repository; as long as the graph of repositories is
+connected, and `git annex sync` is run from time to time on each, a given
+change, made anywhere, will eventually reach every other repository.
+
+The workflow for using `git annex sync` is simple:
+
+* Make some changes to files in the repository, using `git-annex`,
+  or anything else.
+* 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.