1git-annex-export(1) General Commands Manual git-annex-export(1)
2
6 git-annex-export - export a tree of files to a special 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 ex‐
20 porttree=yes when initially setting it up with git-annex-initremote(1).
21 The treeish to export can be the name of a git branch, or a tag, or any
23 other treeish accepted by git, including eg master:subdir to only ex‐
24 port a subdirectory from a branch.
25 When the remote has a preferred content expression set by git-an‐
27 nex-wanted(1), the treeish is filtered through it, excluding annexed
28 files it does not want from being exported to it. (Note that things in
29 the expression like "include=" match relative to the top of the treeish
30 being exported.)
31 Any files in the treeish that are stored on git will also be exported
33 to the special remote.
34 Repeated exports are done efficiently, by diffing the old and new tree,
36 and transferring only the changed files, and renaming files as neces‐
37 sary.
38 Exports can be interrupted and resumed. However, partially uploaded
40 files will be re-started from the beginning in most cases.
41 Once content has been exported to a remote, commands like git annex get
43 can download content from there the same as from other remotes. How‐
44 ever, since an export is not a key/value store, git-annex has to do
45 more verification of content downloaded from an export. Some types of
46 keys, that are not based on checksums, cannot be downloaded from an ex‐
47 port. And, git-annex will never trust an export to retain the content
48 of a key.
49 However, some special remotes, notably S3, support keeping track of old
51 versions of files stored in them. If a special remote is set up to do
52 that, it can be used as a key/value store and the limitations in the
53 above paragraph do not apply. Note that dropping content from such a
54 remote is not supported. See individual special remotes' documentation
55 for details of how to enable such versioning.
56 Commands like git-annex push can also be used to export a branch to a
58 special remote, updating the special remote whenever the branch is
59 changed. To do this, you need to configure "remote.<name>.annex-track‐
60 ing-branch" to tell it what branch to track. For example:
61 git config remote.myremote.annex-tracking-branch master
63 git annex push myremote
64 You can combine using git annex export to send changes to a special re‐
66 mote with git annex import to fetch changes from a special remote.
67 When a file on a special remote has been modified by software other
68 than git-annex, exporting to it will not overwrite the modified file,
69 and the export will not succeed. You can resolve this conflict by using
70 git annex import.
71 (Some types of special remotes such as S3 with versioning may instead
73 let an export overwrite the modified file; then git annex import will
74 create a sequence of commits that includes the modified file, so the
75 overwritten modification is not lost.)
76
78 --to=remote
79 Specify the special remote to export to.
81 --tracking
83 This is a deprecated way to set "remote.<name>.annex-track‐
84 ing-branch". Instead of using this option, you should just set
85 the git configuration yourself.
86 --fast This sets up an export of a tree, but avoids any expensive file
88 uploads to the remote. You can later run git annex push to up‐
89 load the files to the export.
90 --jobs=N -JN
92 Exports multiple files in parallel. This may be faster. For ex‐
93 ample: -J4
94 Setting this to "cpus" will run one job per CPU core.
96 --json Enable JSON output. This is intended to be parsed by programs
98 that use git-annex. Each line of output is a JSON object.
99 --json-progress
101 Include progress objects in JSON output.
102 --json-error-messages
104 Messages that would normally be output to standard error are in‐
105 cluded in the JSON instead.
106 Also the git-annex-common-options(1) can be used.
108
110 git annex initremote myremote type=directory directory=/mnt/myremote
111 exporttree=yes encryption=none
112 git annex export master --to myremote
113 After that, /mnt/myremote will contain the same tree of files as the
115 master branch does.
116 git mv myfile subdir/myfile
118 git commit -m renamed
119 git annex export master --to myremote
120 That updates /mnt/myremote to reflect the renamed file.
122 git annex export master:subdir --to myremote
124 That updates /mnt/myremote, to contain only the files in the "subdir"
126 directory of the master branch.
127
129 If two different git-annex repositories are both exporting different
130 trees to the same special remote, it's possible for an export conflict
131 to occur. This leaves the special remote with some files from one
132 tree, and some files from the other. Files in the special remote may
133 have entirely the wrong content as well.
134 It's not possible for git-annex to detect when making an export will
136 result in an export conflict. The best way to avoid export conflicts is
137 to either only ever export to a special remote from a single reposi‐
138 tory, or to have a rule about the tree that you export to the special
139 remote. For example, if you always export origin/master after pushing
140 to origin, then an export conflict can't happen.
141 An export conflict can only be detected after the two git repositories
143 that produced it get back in sync. Then the next time you run git annex
144 export, it will detect the export conflict, and resolve it.
145
147 git-annex(1)
148 git-annex-initremote(1)
150 git-annex-import(1)
152 git-annex-push(1)
154 git-annex-preferred-content(1)
156
158 The export command was introduced in git-annex version 6.20170925.
159
161 Joey Hess <id@joeyh.name>
162 git-annex-export(1)