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
21 reflect 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
32 importtree=yes when set up with git-annex-initremote(1). Only some
33 kinds of special remotes will let you configure them this way. A per‐
34 haps 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
38 import. 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 myremote/master
46 You could just as well use git merge myremote/master as the second
48 step, but using git-annex merge avoids a couple of gotchas. When using
49 adjusted branches, it adjusts the branch before merging from it. And it
50 avoids the merge failing on the first merge from an import due to unre‐
51 lated histories.
52 If you do use git merge, you can pass --allow-unrelated-histories the
54 first time you git merge from an import. Think of this as the remote
55 being a separate git repository with its own files. If you first git
56 annex export files to a remote, and then git annex import from it, you
57 won't need that option.
58 You can import into a subdirectory, using the "branch:subdir" syntax.
60 For example, if "camera" is a special remote that accesses a camera,
61 and you want to import those into the photos directory, rather than to
62 the root of your repository:
63 git annex import master:photos --from camera
65 git merge camera/master
66 The git annex sync --content command (and the git-annex assistant) can
68 also be used to import from a special remote. To do this, you need to
69 configure "remote.<name>.annex-tracking-branch" to tell it what branch
70 to track. For example:
71 git config remote.myremote.annex-tracking-branch master
73 git annex sync --content
74 Any files that are gitignored will not be included in the import, but
76 will be left on the remote.
77 When the special remote has a preferred content expression set by git-
79 annex-wanted(1), it will be honored when importing from it. Files that
80 are not preferred content of the remote will not be imported from it,
81 but will be left on the remote.
82 However, preferred content expressions that relate to the key can't be
84 matched when importing, because the content of the file is not known.
85 Importing will fail when such a preferred content expression is set.
86 This includes expressions containing "copies=", "metadata=", and other
87 things that depend on the key. Preferred content expressions containing
88 "include=", "exclude=" "smallerthan=", "largerthan=" will work.
89 Things in the expression like "include=" match relative to the top of
91 the tree of files on the remote, even when importing into a subdirec‐
92 tory.
93
95 --content, --no-content
96 Controls whether annexed content is downloaded from the special
98 remote.
99 The default is to download content into the git-annex reposi‐
101 tory.
102 With --no-content, git-annex keys are generated from information
104 provided by the special remote, without downloading it. Commands
105 like git-annex get can later be used to download files, as
106 desired. The --no-content option is not supported by all spe‐
107 cial remotes.
108
110 When run with a path, git annex import moves files from somewhere out‐
111 side the git working copy, and adds them to the annex.
112 This is a legacy interface. It is still supported, but please consider
114 switching to importing from a directory special remote instead, using
115 the interface documented above.
116 Individual files to import can be specified. If a directory is speci‐
118 fied, the entire directory is imported.
119 git annex import /media/camera/DCIM/*
121 When importing files, there's a possibility of importing a duplicate of
123 a file that is already known to git-annex -- its content is either
124 present in the local repository already, or git-annex knows of another
125 repository that contains it, or it was present in the annex before but
126 has been removed now.
127 By default, importing a duplicate of a known file will result in a new
129 filename being added to the repository, so the duplicate file is
130 present in the repository twice. (With all checksumming backends,
131 including the default SHA256E, only one copy of the data will be
132 stored.)
133 Several options can be used to adjust handling of duplicate files, see
135 --duplicate, --deduplicate, --skip-duplicates, --clean-duplicates, and
136 --reinject-duplicates documentation below.
137
139 --duplicate
140 Do not delete files from the import location.
142 Running with this option repeatedly can import the same files
144 into different git repositories, or branches, or different loca‐
145 tions in a git repository.
146 --deduplicate
148 Only import files that are not duplicates; duplicate files will
149 be deleted from the import location.
150 --skip-duplicates
152 Only import files that are not duplicates. Avoids deleting any
153 files from the import location.
154 --clean-duplicates
156 Does not import any files, but any files found in the import
157 location that are duplicates are deleted.
158 --reinject-duplicates
160 Imports files that are not duplicates. Files that are duplicates
161 have their content reinjected into the annex (similar to git-
162 annex-reinject(1)).
163 --force
165 Allow existing files to be overwritten by newly imported files.
166 Also, causes .gitignore to not take effect when adding files.
168 file matching options
170 Many of the git-annex-matching-options(1) can be used to specify
171 files to import.
172 git annex import /dir --include='*.png'
174 ## COMMON OPTIONS
176 --jobs=N -JN
178 Imports multiple files in parallel. This may be faster. For
179 example: -J4
180 Setting this to "cpus" will run one job per CPU core.
182 --no-check-gitignore
184 Add gitignored files.
185 --json Enable JSON output. This is intended to be parsed by programs
187 that use git-annex. Each line of output is a JSON object.
188 --json-progress
190 Include progress objects in JSON output.
191 --json-error-messages
193 Messages that would normally be output to standard error are
194 included in the json instead.
195
197 Note that using --deduplicate or --clean-duplicates with the WORM back‐
198 end does not look at file content, but filename and mtime.
199 If annex.largefiles is configured, and does not match a file, git annex
201 import will add the non-large file directly to the git repository,
202 instead of to the annex.
203
205 git-annex(1)
206 git-annex-add(1)
208 git-annex-export(1)
210 git-annex-preferred-content(1)
212
214 Joey Hess <id@joeyh.name>
215 git-annex-import(1)