1git-annex-import(1) General Commands Manual git-annex-import(1)
2
6 git-annex-import - import files from a special remote
7
9 git annex import --from remote branch[:subdir] | [path ...]
10
12 This command is a way to import a tree of files from elsewhere into
13 your git-annex repository. It can import files from a git-annex special
14 remote, or from a directory.
15
17 Importing from a special remote first downloads or hashes all new con‐
18 tent from it, and then constructs a git commit that reflects files that
19 have changed on the special remote since the last time git-annex looked
20 at it. Merging that commit into your repository will update it to re‐
21 flect changes made on the special remote.
22 This way, something can be using the special remote for file storage,
24 adding files, modifying files, and deleting files, and you can track
25 those changes using git-annex.
26 You can combine using git annex import to fetch changes from a special
28 remote with git annex export to send your local changes to the special
29 remote.
30 You can only import from special remotes that were configured with im‐
32 porttree=yes when set up with git-annex-initremote(1). Only some kinds
33 of special remotes will let you configure them this way. A perhaps
34 non-exhaustive list is the directory, s3, and adb special remotes.
35 To import from a special remote, you must specify the name of a branch.
37 A corresponding remote tracking branch will be updated by git annex im‐
38 port. After that point, it's the same as if you had run a git fetch
39 from a regular git remote; you can merge the changes into your cur‐
40 rently checked out branch.
41 For example:
43 git annex import master --from myremote
45 git annex merge --allow-unrelated-histories myremote/master
46 You could just as well use git merge --allow-unrelated-histories myre‐
48 mote/master as the second step, but using git-annex merge avoids a cou‐
49 ple of gotchas. When using adjusted branches, it adjusts the branch
50 before merging from it.
51 The --allow-unrelated-histories option is needed for at least the first
53 merge of an imported remote tracking branch, since the branch's history
54 is not connected. Think of this as the remote being a separate git
55 repository with its own files. If you first git annex export files to a
56 remote, and then git annex import from it, you won't need that option.
57 You can import into a subdirectory, using the "branch:subdir" syntax.
59 For example, if "camera" is a special remote that accesses a camera,
60 and you want to import those into the photos directory, rather than to
61 the root of your repository:
62 git annex import master:photos --from camera
64 git merge camera/master
65 The git annex sync --content command (and the git-annex assistant) can
67 also be used to import from a special remote. To do this, you need to
68 configure "remote.<name>.annex-tracking-branch" to tell it what branch
69 to track. For example:
70 git config remote.myremote.annex-tracking-branch master
72 git annex sync --content
73 Any files that are gitignored will not be included in the import, but
75 will be left on the remote.
76 When the special remote has a preferred content expression set by git-
78 annex-wanted(1), it will be honored when importing from it. Files that
79 are not preferred content of the remote will not be imported from it,
80 but will be left on the remote.
81 However, preferred content expressions that relate to the key can't be
83 matched when importing, because the content of the file is not known.
84 Importing will fail when such a preferred content expression is set.
85 This includes expressions containing "copies=", "metadata=", and other
86 things that depend on the key. Preferred content expressions containing
87 "include=", "exclude=" "smallerthan=", "largerthan=" will work.
88 Things in the expression like "include=" match relative to the top of
90 the tree of files on the remote, even when importing into a subdirec‐
91 tory.
92
94 --content, --no-content
95 Controls whether annexed content is downloaded from the special
97 remote.
98 The default is to download content into the git-annex reposi‐
100 tory.
101 With --no-content, git-annex keys are generated from information
103 provided by the special remote, without downloading it. Commands
104 like git-annex get can later be used to download files, as de‐
105 sired. The --no-content option is not supported by all special
106 remotes.
107
109 When run with a path, git annex import **moves** files from somewhere
110 outside the git working copy, and adds them to the annex. In contrast
111 to importing from a special directory remote, imported files are
112 **deleted from the given path**.
113 This is a legacy interface. It is still supported, but please consider
115 switching to importing from a directory special remote instead, using
116 the interface documented above.
117 Individual files to import can be specified. If a directory is speci‐
119 fied, the entire directory is imported. Please note that the following
120 instruction will **delete all files from the source directory**.
121 git annex import /media/camera/DCIM/*
123 When importing files, there's a possibility of importing a duplicate of
125 a file that is already known to git-annex -- its content is either
126 present in the local repository already, or git-annex knows of another
127 repository that contains it, or it was present in the annex before but
128 has been removed now.
129 By default, importing a duplicate of a known file will result in a new
131 filename being added to the repository, so the duplicate file is
132 present in the repository twice. (With all checksumming backends, in‐
133 cluding the default SHA256E, only one copy of the data will be stored.)
134 Several options can be used to adjust handling of duplicate files, see
136 --duplicate, --deduplicate, --skip-duplicates, --clean-duplicates, and
137 --reinject-duplicates documentation below.
138 symbolic links in the directory being imported are skipped to avoid ac‐
140 cidentially importing things outside the directory that import was ran
141 on. The directory that import is run on can, however inself be a sym‐
142 bolic link, and that symbolic link will be followed.
143
145 --duplicate
146 Do not delete files from the import location.
148 Running with this option repeatedly can import the same files
150 into different git repositories, or branches, or different loca‐
151 tions in a git repository.
152 --deduplicate
154 Only import files that are not duplicates; duplicate files will
155 be deleted from the import location.
156 --skip-duplicates
158 Only import files that are not duplicates. Avoids deleting any
159 files from the import location.
160 --clean-duplicates
162 Does not import any files, but any files found in the import lo‐
163 cation that are duplicates are deleted.
164 --reinject-duplicates
166 Imports files that are not duplicates. Files that are duplicates
167 have their content reinjected into the annex (similar to git-an‐
168 nex-reinject(1)).
169 --force
171 Allow existing files to be overwritten by newly imported files.
172 Also, causes .gitignore to not take effect when adding files.
174 file matching options
176 Many of the git-annex-matching-options(1) can be used to specify
177 files to import.
178 git annex import /dir --include='*.png'
180
182 --jobs=N -JN
183 Imports multiple files in parallel. This may be faster. For ex‐
185 ample: -J4
186 Setting this to "cpus" will run one job per CPU core.
188 --backend
190 Specifies which key-value backend to use for the imported files.
191 --no-check-gitignore
193 Add gitignored files.
194 --json Enable JSON output. This is intended to be parsed by programs
196 that use git-annex. Each line of output is a JSON object.
197 --json-progress
199 Include progress objects in JSON output.
200 --json-error-messages
202 Messages that would normally be output to standard error are in‐
203 cluded in the JSON instead.
204 Also the git-annex-common-options(1) can be used.
206
208 Note that using --deduplicate or --clean-duplicates with the WORM back‐
209 end does not look at file content, but filename and mtime.
210 If annex.largefiles is configured, and does not match a file, git annex
212 import will add the non-large file directly to the git repository, in‐
213 stead of to the annex.
214
216 git-annex(1)
217 git-annex-add(1)
219 git-annex-export(1)
221 git-annex-preferred-content(1)
223
225 Joey Hess <id@joeyh.name>
226 git-annex-import(1)