205 lines
7.5 KiB
Markdown
205 lines
7.5 KiB
Markdown
# NAME
|
|
|
|
git-annex sync - synchronize local repository with remotes
|
|
|
|
# SYNOPSIS
|
|
|
|
git annex sync `[remote ...]`
|
|
|
|
# DESCRIPTION
|
|
|
|
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 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
|
|
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.
|
|
|
|
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.
|
|
|
|
Some special remotes contain a tree of files that can be imported
|
|
and/or exported, and syncing with these remotes behaves differently.
|
|
See [[git-annex-import]](1) and [[git-annex-export]](1) for details
|
|
about how importing and exporting work; syncing with such a remote
|
|
is essentially an import followed by an export. In many cases,
|
|
importing needs to download content from the remote, and so sync will
|
|
only import when the --content option is used. (And exporting only
|
|
ever happens when --content is used.) The remote's
|
|
`remote.<name>.annex-tracking-branch` also must be configured, and
|
|
have the same value as the currently checked out branch.
|
|
|
|
When [[git-annex-adjust]](1) has been used to check out an adjusted branch,
|
|
running sync will propagate changes that have been made back to the
|
|
parent branch, without propagating the adjustments.
|
|
|
|
# OPTIONS
|
|
|
|
* `[remote]`
|
|
|
|
By default, all remotes are synced, except for remotes that have
|
|
`remote.<name>.annex-sync` set to false. By specifying the names
|
|
of remotes (or remote groups), you can control which ones to sync with.
|
|
|
|
* `--fast`
|
|
|
|
Only sync with the remotes with the lowest annex-cost value configured.
|
|
|
|
When a list of remotes (or remote groups) is provided, it picks from
|
|
amoung those, otherwise it picks from amoung all remotes.
|
|
|
|
* `--only-annex` `-a`, `--not-only-annex`
|
|
|
|
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.
|
|
|
|
The `annex.synconlyannex` configuration can be set to true to make
|
|
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).
|
|
|
|
Use --no-commit to avoid committing local changes.
|
|
|
|
* `--message=msg`
|
|
|
|
Use this option to specify a commit message.
|
|
|
|
* `--pull`, `--no-pull`
|
|
|
|
By default, syncing pulls from remotes and imports from some special
|
|
remotes. Use --no-pull to disable all pulling.
|
|
|
|
When `remote.<name>.annex-pull` or `remote.<name>.annex-sync`
|
|
are set to false, pulling is disabled for those remotes, and using
|
|
`--pull` will not enable it.
|
|
|
|
* `--push`, `--no-push`
|
|
|
|
By default, syncing pushes changes to remotes and exports to some
|
|
special remotes. Use --no-push to disable all pushing.
|
|
|
|
When `remote.<name>.annex-push` or `remote.<name>.annex-sync` are
|
|
set to false, or `remote.<name>.annex-readonly` is set to true,
|
|
pushing is disabled for those remotes, and using `--push` will not enable
|
|
it.
|
|
|
|
* `--content`, `--no-content`
|
|
|
|
Normally, syncing does not transfer the contents of annexed files.
|
|
The --content option causes the content of annexed files
|
|
to also be uploaded and downloaded as necessary, to sync the content
|
|
between the repository and its remotes.
|
|
|
|
The `annex.synccontent` configuration can be set to true to make content
|
|
be synced by default.
|
|
|
|
Normally this tries to get each annexed file that is in the working tree
|
|
and whose content the local repository does not yet have, from any remote
|
|
that it's syncing with that has a copy, and then copies each file to
|
|
every remote that it is syncing with. This behavior can be overridden by
|
|
configuring the preferred content of repositories. See
|
|
[[git-annex-preferred-content]](1).
|
|
|
|
* `--content-of=path` `-C path`
|
|
|
|
While --content operates on all annexed files,
|
|
--content-of allows limiting the transferred files to ones in a given
|
|
location.
|
|
|
|
This option can be repeated multiple times with different paths.
|
|
|
|
* `--all` `-A`
|
|
|
|
This option, when combined with `--content`, makes all available versions
|
|
of all files be synced, when preferred content settings allow.
|
|
|
|
Note that preferred content settings that use `include=` or `exclude=`
|
|
will only match the version of files currently in the work tree, but not
|
|
past versions of files.
|
|
|
|
* `--jobs=N` `-JN`
|
|
|
|
Enables parallel syncing with up to the specified number of jobs
|
|
running at once. For example: `-J10`
|
|
|
|
Setting this to "cpus" will run one job per CPU core.
|
|
|
|
When there are multiple git remotes, pushes will be made to them in
|
|
parallel. Pulls are not done in parallel because that tends to be
|
|
less efficient. When --content is synced, the files are processed
|
|
in parallel as well.
|
|
|
|
* `--allow-unrelated-histories`, `--no-allow-unrelated-histories`
|
|
|
|
Passed on to `git merge`, to control whether or not to merge
|
|
histories that do not share a common ancestor.
|
|
|
|
* `--resolvemerge`, `--no-resolvemerge`
|
|
|
|
By default, merge conflicts are automatically handled by sync. When two
|
|
conflicting versions of a file have been committed, both will be added
|
|
to the tree, under different filenames. For example, file "foo"
|
|
would be replaced with "foo.variant-A" and "foo.variant-B". (See
|
|
[[git-annex-resolvemerge]](1) for details.)
|
|
|
|
Use `--no-resolvemerge` to disable this automatic merge conflict
|
|
resolution. It can also be disabled by setting `annex.resolvemerge`
|
|
to false.
|
|
|
|
* `--backend`
|
|
|
|
Specifies which key-value backend to use when adding files,
|
|
or when importing from a special remote.
|
|
|
|
* `--cleanup`
|
|
|
|
Removes the local and remote `synced/` branches, which were created
|
|
and pushed by `git-annex sync`. This option prevents all other syncing
|
|
activities.
|
|
|
|
This can come in handy when you've synced a change to remotes and now
|
|
want to reset your master branch back before that change. So you
|
|
run `git reset` and force-push the master branch to remotes, only
|
|
to find that the next `git annex merge` or `git annex sync` brings the
|
|
changes back. Why? Because the `synced/master` branch is hanging
|
|
around and still has the change in it. Cleaning up the `synced/` branches
|
|
prevents that problem.
|
|
|
|
* Also the [[git-annex-common-options]](1) can be used.
|
|
|
|
# SEE ALSO
|
|
|
|
[[git-annex]](1)
|
|
|
|
[[git-annex-preferred-content]](1)
|
|
|
|
# AUTHOR
|
|
|
|
Joey Hess <id@joeyh.name>
|
|
|
|
Warning: Automatically converted into a man page by mdwn2man. Edit with care.
|