1git-annex-export(1) General Commands Manual git-annex-export(1)
2
6 git-annex-export - export content to a remote
7
9 git annex export treeish --to remote
10
12 Use this command to export a tree of files from a git-annex repository.
13 Normally files are stored on a git-annex special remote named by their
15 keys. That is great for reliable data storage, but your filenames are
16 obscured. Exporting replicates the tree to the special remote as-is.
17 Mixing key/value storage and exports in the same remote would be a mess
19 and so is not allowed. You have to configure a special remote with
20 exporttree=yes when initially setting it up with git-annex-ini‐
21 tremote(1).
22 The treeish to export can be the name of a git branch, or a tag, or any
24 other treeish accepted by git, including eg master:subdir to only
25 export a subdirectory from a branch.
26 When the remote has a preferred content setting, the treeish is fil‐
28 tered through it, excluding files it does not want from being exported
29 to it.
30 Repeated exports are done efficiently, by diffing the old and new tree,
32 and transferring only the changed files, and renaming files as neces‐
33 sary.
34 Exports can be interrupted and resumed. However, partially uploaded
36 files will be re-started from the beginning in most cases.
37 Once content has been exported to a remote, commands like git annex get
39 can download content from there the same as from other remotes. How‐
40 ever, since an export is not a key/value store, git-annex has to do
41 more verification of content downloaded from an export. Some types of
42 keys, that are not based on checksums, cannot be downloaded from an
43 export. And, git-annex will never trust an export to retain the con‐
44 tent of a key.
45 However, some special remotes, notably S3, support keeping track of old
47 versions of files stored in them. If a special remote is set up to do
48 that, it can be used as a key/value store and the limitations in the
49 above paragraph do not apply. Note that dropping content from such a
50 remote is not supported. See individual special remotes' documentation
51 for details of how to enable such versioning.
52 The git annex sync --content command (and the git-annex assistant) can
54 also be used to export a branch to a special remote, updating the spe‐
55 cial remote whenever the branch is changed. To do this, you need to
56 configure "remote.<name>.annex-tracking-branch" to tell it what branch
57 to track. For example:
58 git config remote.myremote.annex-tracking-branch master
60 git annex sync --content
61 You can combine using git annex export to send changes to a special
63 remote with git annex import to fetch changes from a special remote.
64 When a file on a special remote has been modified by software other
65 than git-annex, exporting to it will not overwrite the modified file,
66 and the export will not succeed. You can resolve this conflict by using
67 git annex import.
68 (Some types of special remotes such as S3 with versioning may instead
70 let an export overwrite the modified file; then git annex import will
71 create a sequence of commits that includes the modified file, so the
72 overwritten modification is not lost.)
73
75 --to=remote
76 Specify the special remote to export to.
78 --tracking
80 This is a deprecated way to set "remote.<name>.annex-track‐
81 ing-branch". Instead of using this option, you should just set
82 the git configuration yourself.
83 --fast This sets up an export of a tree, but avoids any expensive file
85 uploads to the remote. You can later run git annex sync --con‐
86 tent to upload the files to the export.
87
89 git annex initremote myremote type=directory directory=/mnt/myremote
90 exporttree=yes encryption=none
91 git annex export master --to myremote
92 After that, /mnt/myremote will contain the same tree of files as the
94 master branch does.
95 git mv myfile subdir/myfile
97 git commit -m renamed
98 git annex export master --to myremote
99 That updates /mnt/myremote to reflect the renamed file.
101 git annex export master:subdir --to myremote
103 That updates /mnt/myremote, to contain only the files in the "subdir"
105 directory of the master branch.
106
108 If two different git-annex repositories are both exporting different
109 trees to the same special remote, it's possible for an export conflict
110 to occur. This leaves the special remote with some files from one
111 tree, and some files from the other. Files in the special remote may
112 have entirely the wrong content as well.
113 It's not possible for git-annex to detect when making an export will
115 result in an export conflict. The best way to avoid export conflicts is
116 to either only ever export to a special remote from a single reposi‐
117 tory, or to have a rule about the tree that you export to the special
118 remote. For example, if you always export origin/master after pushing
119 to origin, then an export conflict can't happen.
120 An export conflict can only be detected after the two git repositories
122 that produced it get back in sync. Then the next time you run git annex
123 export, it will detect the export conflict, and resolve it.
124
126 git-annex(1)
127 git-annex-initremote(1)
129 git-annex-import(1)
131 git-annex-sync(1)
133 git-annex-preferred-content(1)
135
137 The export command was introduced in git-annex version 6.20170925.
138
140 Joey Hess <id@joeyh.name>
141 git-annex-export(1)