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 myremote/master
46
47       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
53       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
59       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
64        git annex import master:photos --from camera
65        git merge camera/master
66
67       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
72        git config remote.myremote.annex-tracking-branch master
73        git annex sync --content
74
75       Any files that are gitignored will not be included in the  import,  but
76       will be left on the remote.
77
78       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
83       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
90       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

OPTIONS FOR IMPORTING FROM A SPECIAL REMOTE

95       --content, --no-content
96
97              Controls  whether annexed content is downloaded from the special
98              remote.
99
100              The default is to download content into  the  git-annex  reposi‐
101              tory.
102
103              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 de‐
106              sired.  The --no-content option is not supported by all  special
107              remotes.
108

IMPORTING FROM A DIRECTORY

110       When  run  with a path, git annex import **moves** files from somewhere
111       outside the git working copy, and adds them to the annex.  In  contrast
112       to  importing  from  a  special  directory  remote,  imported files are
113       **deleted from the given path**.
114
115       This is a legacy interface. It is still supported, but please  consider
116       switching  to  importing from a directory special remote instead, using
117       the interface documented above.
118
119       Individual files to import can be specified. If a directory  is  speci‐
120       fied,  the entire directory is imported. Please note that the following
121       instruction will **delete all files from the source directory**.
122
123        git annex import /media/camera/DCIM/*
124
125       When importing files, there's a possibility of importing a duplicate of
126       a  file  that  is  already  known to git-annex -- its content is either
127       present in the local repository already, or git-annex knows of  another
128       repository  that contains it, or it was present in the annex before but
129       has been removed now.
130
131       By default, importing a duplicate of a known file will result in a  new
132       filename  being  added  to  the  repository,  so  the duplicate file is
133       present in the repository twice. (With all checksumming  backends,  in‐
134       cluding the default SHA256E, only one copy of the data will be stored.)
135
136       Several  options can be used to adjust handling of duplicate files, see
137       --duplicate, --deduplicate, --skip-duplicates, --clean-duplicates,  and
138       --reinject-duplicates documentation below.
139

OPTIONS FOR IMPORTING FROM A DIRECTORY

141       --duplicate
142
143              Do not delete files from the import location.
144
145              Running  with  this  option repeatedly can import the same files
146              into different git repositories, or branches, or different loca‐
147              tions in a git repository.
148
149       --deduplicate
150              Only  import files that are not duplicates; duplicate files will
151              be deleted from the import location.
152
153       --skip-duplicates
154              Only import files that are not duplicates. Avoids  deleting  any
155              files from the import location.
156
157       --clean-duplicates
158              Does not import any files, but any files found in the import lo‐
159              cation that are duplicates are deleted.
160
161       --reinject-duplicates
162              Imports files that are not duplicates. Files that are duplicates
163              have their content reinjected into the annex (similar to git-an‐
164              nex-reinject(1)).
165
166       --force
167              Allow existing files to be overwritten by newly imported files.
168
169              Also, causes .gitignore to not take effect when adding files.
170
171       file matching options
172              Many of the git-annex-matching-options(1) can be used to specify
173              files to import.
174
175                   git annex import /dir --include='*.png'
176
177              ## COMMON OPTIONS
178
179       --jobs=N -JN
180              Imports multiple files in parallel. This may be faster.  For ex‐
181              ample: -J4
182
183              Setting this to "cpus" will run one job per CPU core.
184
185       --no-check-gitignore
186              Add gitignored files.
187
188       --json Enable JSON output. This is intended to be  parsed  by  programs
189              that use git-annex. Each line of output is a JSON object.
190
191       --json-progress
192              Include progress objects in JSON output.
193
194       --json-error-messages
195              Messages that would normally be output to standard error are in‐
196              cluded in the json instead.
197

CAVEATS

199       Note that using --deduplicate or --clean-duplicates with the WORM back‐
200       end does not look at file content, but filename and mtime.
201
202       If annex.largefiles is configured, and does not match a file, git annex
203       import will add the non-large file directly to the git repository,  in‐
204       stead of to the annex.
205

SEE ALSO

207       git-annex(1)
208
209       git-annex-add(1)
210
211       git-annex-export(1)
212
213       git-annex-preferred-content(1)
214

AUTHOR

216       Joey Hess <id@joeyh.name>
217
218                                                           git-annex-import(1)
Impressum