git-annex/ git-annex-sync

# NAME

git-annex sync - synchronize local repository with remotes

# SYNOPSIS

git annex sync `[remote ...]`

# DESCRIPTION

This command synchronizes the local repository with its remotes.

This command first commits any local changes to files that have previously been added to the repository. Then it does the equivilant of git-annex-pull(1) followed by git-annex-push(1).

However, unlike those commands, this command does not transfer annexed content by default. That will change in a future version of git-annex, when syncing with repositories that have preferred content configured.

# OPTIONS

- `--content`, `--no-content`, `-g`

  The --content option causes the content of annexed files to also be pulled and pushed.

  The --no-content and -g options cause the content of annexed files to not be pulled and pushed.

  The `annex.synccontent` configuration can be set to true to make `--content` be enabled by default.

- `--content-of=path` `-C path`

  This option causes the content of annexed files in the given path to also be pulled and pushed.

  This option can be repeated multiple times with different paths.

  Note that this option does not prevent exporting other files to an "exporttree=yes" remote.

- `--commit`, `--no-commit`

  A commit is done by default (unless `annex.autocommit` is set to false).

  Use --no-commit to avoid committing local changes.

- `--message=msg` `-m msg`

  Use this option to specify a commit message.

  If multiple -m options are given, their values are concatenated as separate paragraphs.

- `--pull`, `--no-pull`

  Use this option to disable pulling.

  When `remote.<name>.annex-sync` is set to false, pulling is disabled for that remote, and using `--pull` will not enable it.

- `--push`, `--no-push`

  Use this option to disable pushing.

  When `remote.<name>.annex-sync` is set to false, pushing is disabled for that remote, and using `--push` will not enable it.

- Also all options supported by git-annex-pull(1) and git-annex-push(1) can be used.

- Also the git-annex-common-options(1) can be used.

# SEE ALSO

git-annex(1)

git-annex-pull(1)

git-annex-push(1)

git-annex-assist(1)

git-annex-satisfy(1)

# AUTHOR

Joey Hess id@joeyh.name

Warning: Automatically converted into a man page by mdwn2man. Edit with care.

Re: Sync to remote master?

The push to remote master will typically fail in a non-bare repository (it is possible to configure one to allow it). The push to synced/master will then succeed. Then when sync is later run in that repository, it will merge synced/master into master.

Comment by joey — Tue Jul 22 18:11:47 2025
Sync to remote master?

I'm a bit confused by what is mentioned in this page:

> To make working with such non-bare remotes easier, sync pushes not only local master to remote master, but also to remote synced/master

but just above it's explained that by default Git does not allow to push to remote master:

> Syncing with a non-bare remote will not normally update the remote's current branch with changes from the local repository.

In addition the page https://git-annex.branchable.com/sync/ doesn't mention that the remote master branch is directly synchronized:

> When you run git annex sync [...] Finally, it updates synced/master to reflect the new state of master, and pushes it out to each of the remotes.

So I was wondering about the correctness of the first cited sentence.

Comment by dud225 — Tue Jul 22 18:11:47 2025
re: comment 4

With approptiate locking to prevent concurrency problems. As is the case extensively throughout git-annex, although users seem to keep expecting that to not be the case no matter how many times I assure them it is.

Comment by joey — Tue Jul 22 18:11:47 2025
comment 4
When concurrent git-annex commands on the same repo update that repo's git-annex branch, how is that handled?
Comment by Ilya_Shlyakhter — Tue Jul 22 18:11:47 2025
comment 3
Maybe, have a config option for the number of retries or the maximum time to keep trying? An important property of git-annex-sync is that, even though it does merging, it does not normally fail. It'd be good to keep that guarantee even in the face of concurrent access to the repo. Alternately, you could push to a new branch synced/uuid/branchname, and then when git-annex-sync is later done at the target repo locally, merge from each of the synced/*/branchname .
Comment by Ilya_Shlyakhter — Tue Jul 22 18:11:47 2025
comment 2

git-annex sync pulls before pushing. If another push occurs at the same time, the push might fail, but retrying the pull will not avoid that same situation occurring again. I don't think it makes sense for git-annex sync to retry an arbitrary number of times.

Comment by joey — Tue Jul 22 18:11:47 2025
when push fails due to non-fast-forward merge, pull and retry?

When a push would result in a non-fast-forward merge, git-annex-sync currently fails. Maybe instead, pull and retry pushing? This happens in the context of several processes trying to push to the same git-annex repo.

Also, the docs mention synced/master, but it's synced/current-branch.

Comment by Ilya_Shlyakhter — Tue Jul 22 18:11:47 2025
Comments on this page are closed.