From f1a1669224c7cc5a433978fd0e07ace4dd36d23c Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Tue, 18 Feb 2020 12:42:44 -0400 Subject: [PATCH] clarify description of synced/ branches --- doc/git-annex-sync.mdwn | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/doc/git-annex-sync.mdwn b/doc/git-annex-sync.mdwn index 73129086b6..e4cf8d0803 100644 --- a/doc/git-annex-sync.mdwn +++ b/doc/git-annex-sync.mdwn @@ -12,7 +12,7 @@ This command synchronizes the local repository with its remotes. The sync process involves first committing any local changes to files that have previously been added to the repository, -then fetching and merging the `synced/master` and the `git-annex` branch +then fetching and merging the current branch 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 @@ -21,11 +21,18 @@ worry about the details, you can use sync. The content of annexed objects is not synced by default, but the --content option (see below) can make that also be synchronized. -Note that syncing with a remote will not normally update the remote's working -tree with changes made to the local repository. (Unless it's configured -with receive.denyCurrentBranch=updateInstead.) However, those changes -are pushed to the remote, so they can be merged into its working tree -by running "git annex sync" on the remote. +When using git-annex, often remotes are not bare repositories, because +it's helpful to add remotes for nearby machines that you want +to access the same annexed content. Syncing with a non-bare remote will +not normally update the remote's current branch with changes from the local +repository. (Unless the remote is configured with +receive.denyCurrentBranch=updateInstead.) + +To make working with such non-bare remotes easier, sync pushes not only +local `master` to remote `master`, but also to remote `synced/master` (and +similar with other branches). When `git-annex sync` is later run on the +remote, it will merge the `synced/` branches that the repository has +received. # OPTIONS @@ -41,7 +48,8 @@ by running "git annex sync" on the remote. * `--only-annex` `-a`, `--not-only-annex` - Only get sync the git-annex branch and annexed content with remotes. + Only sync the git-annex branch and annexed content with remotes, + not other git branches. This avoids pulling and pushing other branches, and it avoids committing any local changes. It's up to you to use regular git commands to do that. @@ -50,6 +58,9 @@ by running "git annex sync" on the remote. this be the default behavior of `git-annex sync`. To override such a setting, use `--not-only-annex`. + When this is combined with --no-content, only the git-annex branch + will be synced. + * `--commit`, `--no-commit` A commit is done by default (unless `annex.autocommit` is set to false).