1git-annex-import(1) General Commands Manual git-annex-import(1)
2
6 git-annex-import - add files from a non-versioned directory or a spe‐
7 cial remote
8
10 git annex import [path ...] | git annex import --from remote
11 branch[:subdir]
12
14 This command is a way to import files from elsewhere into your git-
15 annex repository. It can import files from a directory into your repos‐
16 itory, or it can import files from a git-annex special remote.
17
19 Importing from a special remote first downloads all new content from
20 it, and then constructs a git commit that reflects files that have
21 changed on the special remote since the last time git-annex looked at
22 it. Merging that commit into your repository will update it to reflect
23 changes made on the special remote.
24 This way, something can be using the special remote for file storage,
26 adding files, modifying files, and deleting files, and you can track
27 those changes using git-annex.
28 You can combine using git annex import to fetch changes from a special
30 remote with git annex export to send your local changes to the special
31 remote.
32 You can only import from special remotes that were configured with
34 importtree=yes when set up with git-annex-initremote(1). Only some
35 kinds of special remotes will let you configure them this way.
36 To import from a special remote, you must specify the name of a branch.
38 A corresponding remote tracking branch will be updated by git annex
39 import. After that point, it's the same as if you had run a git fetch
40 from a regular git remote; you can merge the changes into your cur‐
41 rently checked out branch.
42 For example:
44 git annex import master --from myremote
46 git annex merge myremote/master
47 You could just as well use git merge myremote/master as the second
49 step, but using git-annex merge avoids a couple of gotchas. When using
50 adjusted branches, it adjusts the branch before merging from it. And it
51 avoids the merge failing on the first merge from an import due to unre‐
52 lated histories.
53 If you do use git merge, you can pass --allow-unrelated-histories the
55 first time you git merge from an import. Think of this as the remote
56 being a separate git repository with its own files. If you first git
57 annex export files to a remote, and then git annex import from it, you
58 won't need that option.
59 You can import into a subdirectory, using the "branch:subdir" syntax.
61 For example, if "camera" is a special remote that accesses a camera,
62 and you want to import those into the photos directory, rather than to
63 the root of your repository:
64 git annex import master:photos --from camera
66 git merge camera/master
67 The git annex sync --content command (and the git-annex assistant) can
69 also be used to import from a special remote. To do this, you need to
70 configure "remote.<name>.annex-tracking-branch" to tell it what branch
71 to track. For example:
72 git config remote.myremote.annex-tracking-branch master
74 git annex sync --content
75 If a preferred content expression is configured for the special remote,
77 it will be honored when importing from it. Files that are not preferred
78 content of the remote will not be imported from it, but will be left on
79 the remote.
80 However, preferred content expressions that relate to the key can't be
82 matched when importing, because the content of the file is not known.
83 Importing will fail when such a preferred content expression is set.
84 This includes expressions containing "copies=", "metadata=", and other
85 things that depend on the key. Preferred content expressions containing
86 "include=", "exclude=" "smallerthan=", "largerthan=" will work.
87
89 When run with a path, git annex import moves files from somewhere out‐
90 side the git working copy, and adds them to the annex.
91 Individual files to import can be specified. If a directory is speci‐
93 fied, the entire directory is imported.
94 git annex import /media/camera/DCIM/*
96 When importing files, there's a possibility of importing a duplicate of
98 a file that is already known to git-annex -- its content is either
99 present in the local repository already, or git-annex knows of another
100 repository that contains it, or it was present in the annex before but
101 has been removed now.
102 By default, importing a duplicate of a known file will result in a new
104 filename being added to the repository, so the duplicate file is
105 present in the repository twice. (With all checksumming backends,
106 including the default SHA256E, only one copy of the data will be
107 stored.)
108 Several options can be used to adjust handling of duplicate files, see
110 --duplicate, --deduplicate, --skip-duplicates, --clean-duplicates, and
111 --reinject-duplicates documentation below.
112
114 --duplicate
115 Do not delete files from the import location.
117 Running with this option repeatedly can import the same files
119 into different git repositories, or branches, or different loca‐
120 tions in a git repository.
121 --deduplicate
123 Only import files that are not duplicates; duplicate files will
124 be deleted from the import location.
125 --skip-duplicates
127 Only import files that are not duplicates. Avoids deleting any
128 files from the import location.
129 --clean-duplicates
131 Does not import any files, but any files found in the import
132 location that are duplicates are deleted.
133 --reinject-duplicates
135 Imports files that are not duplicates. Files that are duplicates
136 have their content reinjected into the annex (similar to git-
137 annex-reinject(1)).
138 --force
140 Allow existing files to be overwritten by newly imported files.
141 Also, causes .gitignore to not take effect when adding files.
143 file matching options
145 Many of the git-annex-matching-options(1) can be used to specify
146 files to import.
147 git annex import /dir --include='*.png'
149 ## COMMON OPTIONS
151 --jobs=N -JN
153 Imports multiple files in parallel. This may be faster. For
154 example: -J4
155 Setting this to "cpus" will run one job per CPU core.
157 --json Enable JSON output. This is intended to be parsed by programs
159 that use git-annex. Each line of output is a JSON object.
160 --json-error-messages
162 Messages that would normally be output to standard error are
163 included in the json instead.
164
166 Note that using --deduplicate or --clean-duplicates with the WORM back‐
167 end does not look at file content, but filename and mtime.
168 If annex.largefiles is configured, and does not match a file, git annex
170 import will add the non-large file directly to the git repository,
171 instead of to the annex.
172
174 git-annex(1)
175 git-annex-add(1)
177 git-annex-export(1)
179 git-annex-preferred-content(1)
181
183 Joey Hess <id@joeyh.name>
184 git-annex-import(1)