From 34c89dc1468a62ba4e53e935db366ad18bd0a3a4 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@kitenet.net>
Date: Fri, 30 Dec 2011 19:45:23 -0400
Subject: [PATCH] improve description of sync

---
 doc/git-annex.mdwn | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 3ca2ce1773..acdb1313da 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -120,20 +120,23 @@ 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
+* sync [remote ...]
 
   Use this command when you want to synchronize the local repository with
-  one or more other repositories. 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 these remote repositories.
+  one or more of its remotes. You can specifiy the remotes to sync with;
+  the default is to sync with all remotes.
 
-  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.
+  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.
 
-  By default, `git annex sync` will sync all remote repositories that have a
-  `synced/master` branch. If you want to include/exclude a repository from
-  this list, just create or delete this branch.
+  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.