1git-annex-import(1)         General Commands Manual        git-annex-import(1)
2
3
4

NAME

6       git-annex-import - import files from a special remote
7

SYNOPSIS

9       git annex import --from remote branch[:subdir] | [path ...]
10

DESCRIPTION

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

IMPORTING FROM A SPECIAL REMOTE

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
23       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
27       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
31       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
36       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
42       For example:
43
44        git annex import master --from myremote
45        git annex merge --allow-unrelated-histories myremote/master
46
47       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
52       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
58       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
63        git annex import master:photos --from camera
64        git merge camera/master
65
66       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
71        git config remote.myremote.annex-tracking-branch master
72        git annex sync --content
73
74       Any  files  that are gitignored will not be included in the import, but
75       will be left on the remote.
76
77       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
82       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
89       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

OPTIONS FOR IMPORTING FROM A SPECIAL REMOTE

94       --content, --no-content
95
96              Controls whether annexed content is downloaded from the  special
97              remote.
98
99              The  default  is  to download content into the git-annex reposi‐
100              tory.
101
102              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

IMPORTING FROM A DIRECTORY

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
114       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
118       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
122        git annex import /media/camera/DCIM/*
123
124       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
130       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
135       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
139       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

OPTIONS FOR IMPORTING FROM A DIRECTORY

145       --duplicate
146
147              Do not delete files from the import location.
148
149              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
153       --deduplicate
154              Only  import files that are not duplicates; duplicate files will
155              be deleted from the import location.
156
157       --skip-duplicates
158              Only import files that are not duplicates. Avoids  deleting  any
159              files from the import location.
160
161       --clean-duplicates
162              Does not import any files, but any files found in the import lo‐
163              cation that are duplicates are deleted.
164
165       --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
170       --force
171              Allow existing files to be overwritten by newly imported files.
172
173              Also, causes .gitignore to not take effect when adding files.
174
175       file matching options
176              Many of the git-annex-matching-options(1) can be used to specify
177              files to import.
178
179                   git annex import /dir --include='*.png'
180
181              ## COMMON OPTIONS
182
183       --jobs=N -JN
184              Imports multiple files in parallel. This may be faster.  For ex‐
185              ample: -J4
186
187              Setting this to "cpus" will run one job per CPU core.
188
189       --backend
190              Specifies which key-value backend to use for the imported files.
191
192       --no-check-gitignore
193              Add gitignored files.
194
195       --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
198       --json-progress
199              Include progress objects in JSON output.
200
201       --json-error-messages
202              Messages that would normally be output to standard error are in‐
203              cluded in the json instead.
204
205       Also the git-annex-common-options(1) can be used.
206

CAVEATS

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
211       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

SEE ALSO

216       git-annex(1)
217
218       git-annex-add(1)
219
220       git-annex-export(1)
221
222       git-annex-preferred-content(1)
223

AUTHOR

225       Joey Hess <id@joeyh.name>
226
227                                                           git-annex-import(1)
Impressum