git-annex/doc/git-annex-export.mdwn

# NAME

git-annex export - export content to a remote

# SYNOPSIS

git annex export `treeish --to remote`

# DESCRIPTION

Use this command to export a tree of files from a git-annex repository.

Normally files are stored on a git-annex special remote named by their
keys. That is great for reliable data storage, but your filenames are
obscured. Exporting replicates the tree to the special remote as-is.

Mixing key/value storage and exports in the same remote would be a mess and
so is not allowed. You have to configure a remote with `exporttree=yes`
when initially setting it up with [[git-annex-initremote]](1).

Repeated exports are done efficiently, by diffing the old and new tree,
and transferring only the changed files.

Exports can be interrupted and resumed. However, partially uploaded files
will be re-started from the beginning.

Once content has been exported to a remote, commands like `git annex get`
can download content from there the same as from other remotes. However,
since an export is not a key/value store, git-annex has to do more
verification of content downloaded from an export. Some types of keys,
that are not based on checksums, cannot be downloaded from an export.
And, git-annex will never trust an export to retain the content of a key.

# EXPORT CONFLICTS

If two different git-annex repositories are both exporting different trees
to the same special remote, it's possible for an export conflict to occur.
This leaves the special remote with some files from one tree, and some
files from the other. Files in the special remote may have entirely the
wrong content as well.

It's not possible for git-annex to detect when making an export will result
in an export conflict. The best way to avoid export conflicts is to either
only ever export to a special remote from a single repository, or to have a
rule about the tree that you export to the special remote. For example, if
you always export origin/master after pushing to origin, then an export
conflict can't happen.

An export conflict can only be detected after the two git repositories
that produced it get back in sync. Then the next time you run `git annex
export`, it will detect the export conflict, and resolve it.

# SEE ALSO

[[git-annex]](1)

[[git-annex-export]](1)

# AUTHOR

Joey Hess <id@joeyh.name>

Warning: Automatically converted into a man page by mdwn2man. Edit with care.
documentation for export This commit was sponsored by Ole-Morten Duesund on Patreon. 2017-08-29 17:25:48 +00:00			`# NAME`

			`git-annex export - export content to a remote`

			`# SYNOPSIS`

			git annex export `treeish --to remote`

			`# DESCRIPTION`

			`Use this command to export a tree of files from a git-annex repository.`

			`Normally files are stored on a git-annex special remote named by their`
git annex get from exports Straightforward enough, except for the needed belt-and-suspenders sanity checks to avoid foot shooting due to exports not being key/value stores. * Even when annex.verify=false, always verify from exports. * Only get files from exports that use a backend that supports checksum verification. * Never trust exports, even if the user says to, because then `git annex drop` would drop content if the export seemed to contain a copy. This commit was supported by the NSF-funded DataLad project. 2017-09-04 20:39:56 +00:00			`keys. That is great for reliable data storage, but your filenames are`
			`obscured. Exporting replicates the tree to the special remote as-is.`
documentation for export This commit was sponsored by Ole-Morten Duesund on Patreon. 2017-08-29 17:25:48 +00:00
git annex get from exports Straightforward enough, except for the needed belt-and-suspenders sanity checks to avoid foot shooting due to exports not being key/value stores. * Even when annex.verify=false, always verify from exports. * Only get files from exports that use a backend that supports checksum verification. * Never trust exports, even if the user says to, because then `git annex drop` would drop content if the export seemed to contain a copy. This commit was supported by the NSF-funded DataLad project. 2017-09-04 20:39:56 +00:00			`Mixing key/value storage and exports in the same remote would be a mess and`
			so is not allowed. You have to configure a remote with `exporttree=yes`
documentation for export This commit was sponsored by Ole-Morten Duesund on Patreon. 2017-08-29 17:25:48 +00:00			`when initially setting it up with [[git-annex-initremote]](1).`

			`Repeated exports are done efficiently, by diffing the old and new tree,`
			`and transferring only the changed files.`

			`Exports can be interrupted and resumed. However, partially uploaded files`
			`will be re-started from the beginning.`

git annex get from exports Straightforward enough, except for the needed belt-and-suspenders sanity checks to avoid foot shooting due to exports not being key/value stores. * Even when annex.verify=false, always verify from exports. * Only get files from exports that use a backend that supports checksum verification. * Never trust exports, even if the user says to, because then `git annex drop` would drop content if the export seemed to contain a copy. This commit was supported by the NSF-funded DataLad project. 2017-09-04 20:39:56 +00:00			Once content has been exported to a remote, commands like `git annex get`
			`can download content from there the same as from other remotes. However,`
			`since an export is not a key/value store, git-annex has to do more`
			`verification of content downloaded from an export. Some types of keys,`
			`that are not based on checksums, cannot be downloaded from an export.`
			`And, git-annex will never trust an export to retain the content of a key.`

export file renaming This is seriously super hairy. It has to handle interrupted exports, which may be resumed with the same or a different tree. It also has to recover from export conflicts, which could cause the wrong content to be renamed to a file. I think this works, or is close to working. See the update to the design for how it works. This is definitely not optimal, in that it does more renames than are necessary. It would probably be worth finding the keys that are really renamed and only renaming those. But let's get the "simple" approach to work first.. This commit was supported by the NSF-funded DataLad project. 2017-09-06 19:33:40 +00:00			`# EXPORT CONFLICTS`

			`If two different git-annex repositories are both exporting different trees`
			`to the same special remote, it's possible for an export conflict to occur.`
			`This leaves the special remote with some files from one tree, and some`
			`files from the other. Files in the special remote may have entirely the`
			`wrong content as well.`

			`It's not possible for git-annex to detect when making an export will result`
			`in an export conflict. The best way to avoid export conflicts is to either`
			`only ever export to a special remote from a single repository, or to have a`
			`rule about the tree that you export to the special remote. For example, if`
			`you always export origin/master after pushing to origin, then an export`
			`conflict can't happen.`

			`An export conflict can only be detected after the two git repositories`
			that produced it get back in sync. Then the next time you run `git annex
			export`, it will detect the export conflict, and resolve it.

documentation for export This commit was sponsored by Ole-Morten Duesund on Patreon. 2017-08-29 17:25:48 +00:00			`# SEE ALSO`

			`[[git-annex]](1)`

			`[[git-annex-export]](1)`

			`# AUTHOR`

			`Joey Hess <id@joeyh.name>`

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