mirrors/git-annex
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
git-annex/doc/git-annex-pull.mdwn

146 lines
4.6 KiB
Text
Raw Normal View History

git-annex pull and push Split out two new commands, git-annex pull and git-annex push. Those plus a git commit are equivilant to git-annex sync. In a sense, git-annex sync conflates 3 things, and it would have been better to have push and pull from the beginning and not sync. Although note that git-annex sync --content is faster than a pull followed by a push, because it only has to walk the tree once, look at preferred content once, etc. So there is some value in git-annex sync in speed, as well as user convenience. And it would be hard to split out pull and push from sync, as far as the implementaton goes. The implementation inside sync was easy, just adjust SyncOptions so it does the right thing. Note that the new commands default to syncing content, unless annex.synccontent is explicitly set to false. I'd like sync to also do that, but that's a hard transition to make. As a start to that transition, I added a note to git-annex-sync.mdwn that it may start to do so in a future version of git-annex. But a real transition would necessarily involve displaying warnings when sync is used without --content, and time. Sponsored-by: Kevin Mueller on Patreon
2023-05-16 20:37:30 +00:00
# NAME
git-annex pull - pull content from remotes
# SYNOPSIS
git annex pull `[remote ...]`
# DESCRIPTION
This command pulls content from remotes. It downloads
both git repository content, and the content of annexed files.
Like `git pull`, it merges changes into the current branch.
You can use `git pull` and `git-annex get` by hand to do the same thing as
this command, but this command handles several details, including making
sure that the git-annex branch is fetched from the remote.
Some special remotes contain a tree of files that can be imported,
and this command can be used to pull from those remotes as
well as regular git remotes. See [[git-annex-import]](1) for details
about how those special remotes work. In order for this command to import
from a special remote, `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,
this command will also pull changes from the parent branch.
When [[git-annex-view]](1) has been used to check out a view branch,
this command will update the view branch to reflect any changes
to the parent branch or metadata.
Normally this tries to download the content of each annexed file,
from any remote that it's pulling from that has a copy.
To control which files it downloads, configure the preferred
added git-annex satisfy This ended up having an interface like sync, rather than like get/copy/drop. That let it be implemented in terms of sync, which took a lot less code. Also, it lets it handle many of the edge cases that sync does, such as getting files that are not visible in a --hide-missing branch, and sending files to exporttree remotes. As well as being easier to implement, `git-annex satisfy myremote` makes sense as it satisfies the preferred content settings of the remote. `git-annex satisfy somefile` does not form a sentence that makes sense. So while -C can be a little bit annoying, it still makes sense to have this syntax. Note that, while I initially thought this would also satisfy numcopies, it does not. Arguably it ought to. But, sync does not send files in order to satisfy numcopies, it only sends files to satisfy preferred content. And it's important that this transfer the same files as sync does, because it will probably be used in a workflow where the user sometimes syncs and sometimes satisfies, and does not expect satisfy to do things that sync would not do. (Also opened a new bug that also affects sync et all, not only this command.) Sponsored-by: Nicholas Golder-Manning on Patreon
2023-06-29 19:34:53 +00:00
content of the local repository. It will also drop files from a
git-annex pull and push Split out two new commands, git-annex pull and git-annex push. Those plus a git commit are equivilant to git-annex sync. In a sense, git-annex sync conflates 3 things, and it would have been better to have push and pull from the beginning and not sync. Although note that git-annex sync --content is faster than a pull followed by a push, because it only has to walk the tree once, look at preferred content once, etc. So there is some value in git-annex sync in speed, as well as user convenience. And it would be hard to split out pull and push from sync, as far as the implementaton goes. The implementation inside sync was easy, just adjust SyncOptions so it does the right thing. Note that the new commands default to syncing content, unless annex.synccontent is explicitly set to false. I'd like sync to also do that, but that's a hard transition to make. As a start to that transition, I added a note to git-annex-sync.mdwn that it may start to do so in a future version of git-annex. But a real transition would necessarily involve displaying warnings when sync is used without --content, and time. Sponsored-by: Kevin Mueller on Patreon
2023-05-16 20:37:30 +00:00
remote that are not preferred content of the remote.
See [[git-annex-preferred-content]](1).
# OPTIONS
* `[remote]`
mention that the default is only available remotes
2023-08-16 20:03:05 +00:00
By default this command pulls from all available remotes, except for remotes
git-annex pull and push Split out two new commands, git-annex pull and git-annex push. Those plus a git commit are equivilant to git-annex sync. In a sense, git-annex sync conflates 3 things, and it would have been better to have push and pull from the beginning and not sync. Although note that git-annex sync --content is faster than a pull followed by a push, because it only has to walk the tree once, look at preferred content once, etc. So there is some value in git-annex sync in speed, as well as user convenience. And it would be hard to split out pull and push from sync, as far as the implementaton goes. The implementation inside sync was easy, just adjust SyncOptions so it does the right thing. Note that the new commands default to syncing content, unless annex.synccontent is explicitly set to false. I'd like sync to also do that, but that's a hard transition to make. As a start to that transition, I added a note to git-annex-sync.mdwn that it may start to do so in a future version of git-annex. But a real transition would necessarily involve displaying warnings when sync is used without --content, and time. Sponsored-by: Kevin Mueller on Patreon
2023-05-16 20:37:30 +00:00
that have `remote.<name>.annex-pull` (or `remote.<name>.annex-sync`)
set to false.
By specifying the names of remotes (or remote groups), you can control
which ones to pull from.
* `--fast`
Only pull 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 pull the git-annex branch and annexed content from remotes,
not other git branches.
The `annex.synconlyannex` configuration can be set to true to make
this be the default behavior. To override such a setting, use
`--not-only-annex`.
When this is combined with --no-content, only the git-annex branch
will be pulled.
sync: Added -g as a short option for --no-content I anticipate that if sync is transitioned to syncing content by default, people will want a short option. And in repositories where annex.synccontent = true, they already would. And pull and push sync content by default, so a short option is useful with them too. Mnemonic: -g makes only git data be synced Also, -a makes only annex data be synced. Would have preferred -c, which would complement -C, but it was already taken to set git configs. Sponsored-by: Noam Kremen on Patreon
2023-05-17 16:33:57 +00:00
* `--no-content, `-g`, `--content`
git-annex pull and push Split out two new commands, git-annex pull and git-annex push. Those plus a git commit are equivilant to git-annex sync. In a sense, git-annex sync conflates 3 things, and it would have been better to have push and pull from the beginning and not sync. Although note that git-annex sync --content is faster than a pull followed by a push, because it only has to walk the tree once, look at preferred content once, etc. So there is some value in git-annex sync in speed, as well as user convenience. And it would be hard to split out pull and push from sync, as far as the implementaton goes. The implementation inside sync was easy, just adjust SyncOptions so it does the right thing. Note that the new commands default to syncing content, unless annex.synccontent is explicitly set to false. I'd like sync to also do that, but that's a hard transition to make. As a start to that transition, I added a note to git-annex-sync.mdwn that it may start to do so in a future version of git-annex. But a real transition would necessarily involve displaying warnings when sync is used without --content, and time. Sponsored-by: Kevin Mueller on Patreon
2023-05-16 20:37:30 +00:00
sync: Added -g as a short option for --no-content I anticipate that if sync is transitioned to syncing content by default, people will want a short option. And in repositories where annex.synccontent = true, they already would. And pull and push sync content by default, so a short option is useful with them too. Mnemonic: -g makes only git data be synced Also, -a makes only annex data be synced. Would have preferred -c, which would complement -C, but it was already taken to set git configs. Sponsored-by: Noam Kremen on Patreon
2023-05-17 16:33:57 +00:00
Use `--no-content` or `-g` to avoid downloading (and dropping)
git-annex pull and push Split out two new commands, git-annex pull and git-annex push. Those plus a git commit are equivilant to git-annex sync. In a sense, git-annex sync conflates 3 things, and it would have been better to have push and pull from the beginning and not sync. Although note that git-annex sync --content is faster than a pull followed by a push, because it only has to walk the tree once, look at preferred content once, etc. So there is some value in git-annex sync in speed, as well as user convenience. And it would be hard to split out pull and push from sync, as far as the implementaton goes. The implementation inside sync was easy, just adjust SyncOptions so it does the right thing. Note that the new commands default to syncing content, unless annex.synccontent is explicitly set to false. I'd like sync to also do that, but that's a hard transition to make. As a start to that transition, I added a note to git-annex-sync.mdwn that it may start to do so in a future version of git-annex. But a real transition would necessarily involve displaying warnings when sync is used without --content, and time. Sponsored-by: Kevin Mueller on Patreon
2023-05-16 20:37:30 +00:00
the content of annexed files.
If you often use `--no-content`, you can set the `annex.synccontent`
configuration to false to prevent downloading content by default.
The `--content` option overrides that configuration.
* `--content-of=path` `-C path`
Only download (and drop) annexed files in the given path.
This option can be repeated multiple times with different paths.
* `--all` `-A`
Usually this command operates on annexed files in the current branch.
This option makes it operate on all available versions of all annexed files
(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 pulling 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.
(Note that git pulls are not done in parallel because that tends to be
less efficient.)
* `--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 this command.
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 importing from a
special remote.
* Also the [[git-annex-common-options]](1) can be used.
# SEE ALSO
[[git-annex]](1)
[[git-annex-push]](1)
[[git-annex-sync]](1)
[[git-annex-preferred-content]](1)
document git-annex satisfy
2023-06-29 18:15:01 +00:00
[[git-annex-satisfy]](1)
git-annex pull and push Split out two new commands, git-annex pull and git-annex push. Those plus a git commit are equivilant to git-annex sync. In a sense, git-annex sync conflates 3 things, and it would have been better to have push and pull from the beginning and not sync. Although note that git-annex sync --content is faster than a pull followed by a push, because it only has to walk the tree once, look at preferred content once, etc. So there is some value in git-annex sync in speed, as well as user convenience. And it would be hard to split out pull and push from sync, as far as the implementaton goes. The implementation inside sync was easy, just adjust SyncOptions so it does the right thing. Note that the new commands default to syncing content, unless annex.synccontent is explicitly set to false. I'd like sync to also do that, but that's a hard transition to make. As a start to that transition, I added a note to git-annex-sync.mdwn that it may start to do so in a future version of git-annex. But a real transition would necessarily involve displaying warnings when sync is used without --content, and time. Sponsored-by: Kevin Mueller on Patreon
2023-05-16 20:37:30 +00:00
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.
Reference in a new issue Copy permalink