improve description of sync

1 files changed, 15 insertions, 12 deletions

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 3ca2ce177..acdb1313d 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.
-
-  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.
+  one or more of its remotes. You can specifiy the remotes to sync with;
+  the default is to sync with all remotes.
+
+  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.