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

NAME

6       git-annex - manage files with git, without checking their contents in
7

SYNOPSIS

9       git annex command [params ...]
10

DESCRIPTION

12       git-annex  allows  managing  files  with git, without checking the file
13       contents into git. While that may seem paradoxical, it is  useful  when
14       dealing with files larger than git can currently easily handle, whether
15       due to limitations in memory, checksumming time, or disk space.
16
17       Even without file content tracking, being able  to  manage  files  with
18       git, move files around and delete files with versioned directory trees,
19       and use branches and distributed clones, are all very handy reasons  to
20       use git. And annexed files can co-exist in the same git repository with
21       regularly versioned files, which is convenient  for  maintaining  docu‐
22       ments,  Makefiles,  etc that are associated with annexed files but that
23       benefit from full revision control.
24
25       When a file is annexed, its content is moved into  a  key-value  store,
26       and  a  symlink  is made that points to the content. These symlinks are
27       checked into git and versioned like regular files. You  can  move  them
28       around,  delete them, and so on. Pushing to another git repository will
29       make git-annex there aware of the annexed file, and it can be  used  to
30       retrieve its content from the key-value store.
31

EXAMPLES

33        # git annex get video/hackity_hack_and_kaxxt.mov
34        get video/hackity_hack_and_kaxxt.mov (not available)
35          I was unable to access these remotes: server
36          Try making some of these repositories available:
37            5863d8c0-d9a9-11df-adb2-af51e6559a49  -- my home file server
38            58d84e8a-d9ae-11df-a1aa-ab9aa8c00826  -- portable USB drive
39            ca20064c-dbb5-11df-b2fe-002170d25c55  -- backup SATA drive
40        failed
41        # sudo mount /media/usb
42        # git remote add usbdrive /media/usb
43        # git annex get video/hackity_hack_and_kaxxt.mov
44        get video/hackity_hack_and_kaxxt.mov (from usbdrive...) ok
45
46        # git annex add iso
47        add iso/Debian_5.0.iso ok
48
49        # git annex drop iso/Debian_4.0.iso
50        drop iso/Debian_4.0.iso ok
51
52        # git annex move iso --to=usbdrive
53        move iso/Debian_5.0.iso (moving to usbdrive...) ok
54

COMMONLY USED COMMANDS

56       Like many git commands, git-annex can be passed a path that is either a
57       file or a directory. In the latter case it acts on all  relevant  files
58       in  the  directory.  When no path is specified, most git-annex commands
59       default to acting on all relevant files in the current  directory  (and
60       subdirectories).
61
62       help   Display built-in help.
63
64              For help on a specific command, use git annex help command
65
66       add [path ...]
67              Adds  files  in  the path to the annex. If no path is specified,
68              adds files from the current directory and below.
69
70              See git-annex-add(1) for details.
71
72       get [path ...]
73              Makes the content of annexed files available in this repository.
74
75              See git-annex-get(1) for details.
76
77       drop [path ...]
78              Drops the content of annexed files from this repository.
79
80              See git-annex-drop(1) for details.
81
82       move [path ...] [--from=remote|--to=remote]
83              Moves the content of files from or to another remote.
84
85              See git-annex-move(1) for details.
86
87       copy [path ...] [--from=remote|--to=remote]
88              Copies the content of files from or to another remote.
89
90              See git-annex-copy(1) for details.
91
92       status [path ...]
93              Similar to git status --short, displays the status of the  files
94              in the working tree.
95
96              See git-annex-status(1) for details.
97
98       unlock [path ...]
99              Unlock annexed files for modification.
100
101              See git-annex-unlock(1) for details.
102
103       edit [path ...]
104              This is an alias for the unlock command. May be easier to remem‐
105              ber, if you think of this as allowing you  to  edit  an  annexed
106              file.
107
108       lock [path ...]
109              Use  this  to undo an unlock command if you don't want to modify
110              the files, or have made modifications you want to discard.
111
112              See git-annex-lock(1) for details.
113
114       sync [remote ...]
115              Synchronize local repository with remotes.
116
117              See git-annex-sync(1) for details.
118
119       mirror [path ...] [--to=remote|--from=remote]
120              Mirror content of files to/from another repository.
121
122              See git-annex-mirror(1) for details.
123
124       addurl [url ...]
125              Downloads each url to its own file, which is added to the annex.
126
127              See git-annex-addurl(1) for details.
128
129       rmurl file url
130              Record that the file is no longer available at the url.
131
132              See git-annex-rmurl(1) for details.
133
134       import --from remote branch[:subdir] | [path ...]
135              Add a tree of files to the repository.
136
137              See git-annex-import(1) for details.
138
139       importfeed [url ...]
140              Imports the contents of podcast feeds into the annex.
141
142              See git-annex-importfeed(1) for details.
143
144       export treeish --to remote
145              Export content to a remote.
146
147              See git-annex-export(1) for details.
148
149       undo [filename|directory] ...
150              Undo last change to a file or directory.
151
152              See git-annex-undo(1) for details.
153
154       multicast
155              Multicast file distribution.
156
157              See git-annex-multicast(1) for details.
158
159       watch  Watch for changes and autocommit.
160
161              See git-annex-watch(1) for details.
162
163       assistant
164              Automatically sync folders between devices.
165
166              See git-annex-assistant(1) for details.
167
168       webapp Opens a web app, that allows easy setup of a  git-annex  reposi‐
169              tory,  and  control of the git-annex assistant. If the assistant
170              is not already running, it will be started.
171
172              See git-annex-webapp(1) for details.
173
174       remotedaemon
175              Persistant communication with remotes.
176
177              See git-annex-remotedaemon(1) for details.
178

REPOSITORY SETUP COMMANDS

180       init [description]
181
182              Until a repository (or one of its remotes) has been initialized,
183              git-annex  will  refuse  to operate on it, to avoid accidentally
184              using it in a repository that was not intended to have an annex.
185
186              See git-annex-init(1) for details.
187
188       describe repository description
189              Changes the description of a repository.
190
191              See git-annex-describe(1) for details.
192
193       initremote name type=value [param=value ...]
194              Creates a new special remote, and adds it to .git/config.
195
196              See git-annex-initremote(1) for details.
197
198       enableremote name [param=value ...]
199              Enables use of an existing special remote in the current reposi‐
200              tory.
201
202              See git-annex-enableremote(1) for details.
203
204       renameremote
205              Renames a special remote.
206
207              See git-annex-renameremote(1) for details.
208
209       enable-tor
210              Sets up tor hidden service.
211
212              See git-annex-enable-tor(1) for details.
213
214       numcopies [N]
215              Configure desired number of copies.
216
217              See git-annex-numcopies(1) for details.
218
219       trust [repository ...]
220              Records  that  a  repository is trusted to not unexpectedly lose
221              content. Use with care.
222
223              See git-annex-trust(1) for details.
224
225       untrust [repository ...]
226              Records that a repository is not trusted and could lose  content
227              at any time.
228
229              See git-annex-untrust(1) for details.
230
231       semitrust [repository ...]
232              Returns a repository to the default semi trusted state.
233
234              See git-annex-semitrust(1) for details.
235
236       group repository groupname
237              Add a repository to a group.
238
239              See git-annex-group(1) for details.
240
241       ungroup repository groupname
242              Removes a repository from a group.
243
244              See git-annex-ungroup(1) for details.
245
246       wanted repository [expression]
247              Get or set preferred content expression.
248
249              See git-annex-wanted(1) for details.
250
251       groupwanted groupname [expression]
252              Get or set groupwanted expression.
253
254              See git-annex-groupwanted(1) for details.
255
256       required repository [expression]
257              Get or set required content expression.
258
259              See git-annex-required(1) for details.
260
261       schedule repository [expression]
262              Get or set scheduled jobs.
263
264              See git-annex-schedule(1) for details.
265
266       config Get and set other configuration stored in git-annex branch.
267
268              See git-annex-config(1) for details.
269
270       vicfg  Opens EDITOR on a temp file containing most of the above config‐
271              uration settings, as well as a few others, and  when  it  exits,
272              stores any changes made back to the git-annex branch.
273
274              See git-annex-vicfg(1) for details.
275
276       adjust Switches a repository to use an adjusted branch, which can auto‐
277              matically unlock all files, etc.
278
279              See git-annex-adjust(1) for details.
280
281       direct Switches a repository to use direct mode. (deprecated)
282
283              See git-annex-direct(1) for details.
284
285       indirect
286              Switches a repository to use indirect mode. (deprecated)
287
288              See git-annex-indirect(1) for details.
289

REPOSITORY MAINTENANCE COMMANDS

291       fsck [path ...]
292
293              Checks the annex consistency, and warns about or fixes any prob‐
294              lems found.  This is a good complement to git fsck.
295
296              See git-annex-fsck(1) for details.
297
298       expire [repository:]time ...
299              Expires  repositories that have not recently performed an activ‐
300              ity (such as a fsck).
301
302              See git-annex-expire(1) for details.
303
304       unused Checks the annex for data that does not correspond to any  files
305              present  in any tag or branch, and prints a numbered list of the
306              data.
307
308              See git-annex-unused(1) for details.
309
310       dropunused [number|range ...]
311              Drops the data corresponding to the numbers, as  listed  by  the
312              last git annex unused
313
314              See git-annex-dropunused(1) for details.
315
316       addunused [number|range ...]
317              Adds  back files for the content corresponding to the numbers or
318              ranges, as listed by the last git annex unused.
319
320              See git-annex-addunused(1) for details.
321
322       fix [path ...]
323              Fixes up symlinks that have become  broken  to  again  point  to
324              annexed content.
325
326              See git-annex-fix(1) for details.
327
328       merge  Automatically merge changes from remotes.
329
330              See git-annex-merge(1) for details.
331
332       upgrade
333              Upgrades the repository.
334
335              See git-annex-upgrade(1) for details.
336
337       dead [repository ...] [--key key]
338              Indicates  that a repository or a single key has been irretriev‐
339              ably lost.
340
341              See git-annex-dead(1) for details.
342
343       forget Causes the git-annex branch to be rewritten, throwing away  his‐
344              torical data about past locations of files.
345
346              See git-annex-forget(1) for details.
347
348       repair This  can repair many of the problems with git repositories that
349              git fsck detects, but does not itself  fix.  It's  useful  if  a
350              repository  has become badly damaged. One way this can happen is
351              if a repository used by git-annex is on a removable  drive  that
352              gets unplugged at the wrong time.
353
354              See git-annex-repair(1) for details.
355
356       p2p    Configure peer-2-Peer links between repositories.
357
358              See git-annex-p2p(1) for details.
359

QUERY COMMANDS

361       find [path ...]
362
363              Outputs  a  list of annexed files in the specified path. With no
364              path, finds files in the current directory and  its  subdirecto‐
365              ries.
366
367              See git-annex-find(1) for details.
368
369       whereis [path ...]
370              Displays  information  about  where  the  contents  of files are
371              located.
372
373              See git-annex-whereis(1) for details.
374
375       list [path ...]
376              Displays a table of remotes that contain  the  contents  of  the
377              specified  files.  This is similar to whereis but a more compact
378              display.
379
380              See git-annex-list(1) for details.
381
382       log [path ...]
383              Displays the location log for the specified file or files, show‐
384              ing  each  repository  they were added to ("+") and removed from
385              ("-").
386
387              See git-annex-log(1) for details.
388
389       info [directory|file|remote|uuid ...]
390              Displays statistics and  other  information  for  the  specified
391              item,  which  can be a directory, or a file, or a remote, or the
392              uuid of a repository.
393
394              When no item is specified, displays statistics  and  information
395              for the repository as a whole.
396
397              See git-annex-info(1) for details.
398
399       version
400              Shows  the  version  of git-annex, as well as repository version
401              information.
402
403              See git-annex-version(1) for details.
404
405       map    Generate map of repositories.
406
407              See git-annex-map(1) for details.
408
409       inprogress
410              Access files while they're being downloaded.
411
412              See git-annex-inprogress(1) for details.
413

METADATA COMMANDS

415       metadata [path ...]
416
417              The content of an annexed file can have any number  of  metadata
418              fields attached to it to describe it. Each metadata field can in
419              turn have any number of values.
420
421              This command can be used to set metadata, or show the  currently
422              set metadata.
423
424              See git-annex-metadata(1) for details.
425
426       view   [tag   ...]   [field=value  ...]  [field=glob  ...]  [!tag  ...]
427       [field!=value ...]
428              Uses metadata to build a view branch of the files in the current
429              branch,  and  checks out the view branch. Only files in the cur‐
430              rent branch whose metadata matches all the specified field  val‐
431              ues and tags will be shown in the view.
432
433              See git-annex-view(1) for details.
434
435       vpop [N]
436              Switches  from  the  currently  active view back to the previous
437              view.  Or, from the first view back to original branch.
438
439              See git-annex-vpop(1) for details.
440
441       vfilter [tag ...] [field=value ...] [!tag ...] [field!=value ...]
442              Filters the current view to only the files that have the  speci‐
443              fied field values and tags.
444
445              See git-annex-vfilter(1) for details.
446
447       vadd [field=glob ...] [field=value ...] [tag ...]
448              Changes the current view, adding an additional level of directo‐
449              ries to categorize the files.
450
451              See git-annex-vfilter(1) for details.
452
453       vcycle When a view involves  nested  subdirectories,  this  cycles  the
454              order.
455
456              See git-annex-vcycle(1) for details.
457

UTILITY COMMANDS

459       migrate [path ...]
460
461              Changes the specified annexed files to use a different key-value
462              backend.
463
464              See git-annex-migrate(1) for details.
465
466       reinject src dest
467              Moves the src file into the annex as the  content  of  the  dest
468              file.   This can be useful if you have obtained the content of a
469              file from elsewhere and want to put it in the local annex.
470
471              See git-annex-reinject(1) for details.
472
473       unannex [path ...]
474              Use this to undo an accidental git annex add  command.  It  puts
475              the file back how it was before the add.
476
477              See git-annex-unannex(1) for details.
478
479       uninit De-initialize git-annex and clean out repository.
480
481              See git-annex-uninit(1) for details.
482
483       reinit uuid|description
484              Initialize repository, reusing old UUID.
485
486              See git-annex-reinit(1) for details.
487

PLUMBING COMMANDS

489       pre-commit [path ...]
490
491              This is meant to be called from git's pre-commit hook. git annex
492              init automatically creates a pre-commit hook using this.
493
494              See git-annex-pre-commit(1) for details.
495
496       post-receive
497              This is meant to be called from  git's  post-receive  hook.  git
498              annex init automatically creates a post-receive hook using this.
499
500              See git-annex-post-receive(1) for details.
501
502       lookupkey [file ...]
503              Looks up key used for file.
504
505              See git-annex-lookupkey(1) for details.
506
507       calckey [file ...]
508              Calculates the key that would be used to refer to a file.
509
510              See git-annex-calckey(1) for details.
511
512       contentlocation [key ..]
513              Looks up location of annexed content for a key.
514
515              See git-annex-contentlocation(1) for details.
516
517       examinekey [key ...]
518              Print  information  that  can be determined purely by looking at
519              the key.
520
521              See git-annex-examinekey(1) for details.
522
523       matchexpression
524              Checks if a preferred content expression matches provided data.
525
526              See git-annex-matchexpression(1) for details.
527
528       fromkey [key file]
529              Manually set up a file in the git repository to link to a speci‐
530              fied key.
531
532              See git-annex-fromkey(1) for details.
533
534       registerurl [key url]
535              Registers an url for a key.
536
537              See git-annex-registerurl(1) for details.
538
539       setkey key file
540              Moves a file into the annex as the content of a key.
541
542              See git-annex-setkey(1) for details.
543
544       dropkey [key ...]
545              Drops annexed content for specified keys.
546
547              See git-annex-dropkey(1) for details.
548
549       transferkey key [--from=remote|--to=remote]
550              Transfers a key from or to a remote.
551
552              See git-annex-transferkey(1) for details.
553
554       transferkeys
555              Used internally by the assistant.
556
557              See git-annex-transferkey(1) for details.
558
559       setpresentkey key uuid [1|0]
560              This  plumbing-level  command  changes git-annex's records about
561              whether the specified key's content is present in a remote  with
562              the specified uuid.
563
564              See git-annex-setpresentkey(1) for details.
565
566       readpresentkey key uuid
567              Read records of where key is present.
568
569              See git-annex-readpresentkey(1) for details.
570
571       checkpresentkey key remote
572              Check if key is present in remote.
573
574              See git-annex-checkpresentkey(1) for details.
575
576       rekey [file key ...]
577              Change keys used for files.
578
579              See git-annex-rekey(1) for details.
580
581       resolvemerge
582              Resolves a conflicted merge, by adding both conflicting versions
583              of the file to the tree, using variants of their filename.  This
584              is  done  automatically  when  using git annex sync or git annex
585              merge.
586
587              See git-annex-resolvemerge(1) for details.
588
589       diffdriver
590              This can be used to make git diff use an  external  diff  driver
591              with annexed files.
592
593              See git-annex-diffdriver(1) for details.
594
595       smudge This  command  lets  git-annex  be  used as a git filter driver,
596              allowing annexed files in the git repository to be  unlocked  at
597              all times, instead of being symlinks.
598
599              See git-annex-smudge(1) for details.
600
601       findref [ref]
602              Lists files in a git ref. (deprecated)
603
604              See git-annex-findref(1) for details.
605
606       proxy -- git cmd [options]
607              Bypass direct mode guard. (deprecated)
608
609              See git-annex-proxy(1) for details.
610

TESTING COMMANDS

612       test
613
614              This runs git-annex's built-in test suite.
615
616              See git-annex-test(1) for details.
617
618       testremote remote
619              This  tests a remote by generating some random objects and send‐
620              ing them to the remote, then redownloading them,  removing  them
621              from the remote, etc.
622
623              It's  safe to run in an existing repository (the repository con‐
624              tents are not altered), although it may perform  expensive  data
625              transfers.
626
627              See git-annex-testremote(1) for details.
628
629       fuzztest
630              Generates random changes to files in the current repository, for
631              use in testing the assistant.
632
633              See git-annex-fuzztest(1) for details.
634
635       benchmark
636              This runs git-annex's built-in benchmarks, if it was built  with
637              benchmarking support.
638
639              See git-annex-benchmark(1) for details.
640

COMMON OPTIONS

642       These  common  options  are accepted by all git-annex commands, and may
643       not be explicitly listed on their individual man pages.  (Many commands
644       also accept the git-annex-matching-options(1).)
645
646       --force
647              Force  unsafe actions, such as dropping a file's content when no
648              other source of it can be verified to  still  exist,  or  adding
649              ignored files.  Use with care.
650
651       --fast Enable  less  expensive, but also less thorough versions of some
652              commands.  What is avoided depends on the command.
653
654       --quiet
655              Avoid the default verbose display of what  is  done;  only  show
656              errors.
657
658       --verbose
659              Enable verbose display.
660
661       --debug
662              Show debug messages.
663
664       --no-debug
665              Disable debug messages.
666
667       --numcopies=n
668              Overrides the numcopies setting, forcing git-annex to ensure the
669              specified number of copies exist.
670
671              Note that setting numcopies to 0 is very unsafe.
672
673       --time-limit=time
674              Limits how long a git-annex command runs. The time can be  some‐
675              thing like "5h", or "30m" or even "45s" or "10d".
676
677              Note that git-annex may continue running a little past the spec‐
678              ified time limit, in order to finish processing a file.
679
680              Also, note that if the time limit prevents git-annex from  doing
681              all it was asked to, it will exit with a special code, 101.
682
683       --trust=repository
684
685       --semitrust=repository
686
687       --untrust=repository
688              Overrides trust settings for a repository. May be specified more
689              than once.
690
691              The repository should be specified using the name of  a  config‐
692              ured remote, or the UUID or description of a repository.
693
694       --trust-glacier
695              Amazon  Glacier  inventories take hours to retrieve, and may not
696              represent the current state of a repository. So  git-annex  does
697              not  trust  that  files that the inventory claims are in Glacier
698              are really there.  This switch can be used to allow it to  trust
699              the inventory.
700
701              Be  careful  using this, especially if you or someone else might
702              have recently removed a file from Glacier. If you  try  to  drop
703              the only other copy of the file, and this switch is enabled, you
704              could lose data!
705
706       --backend=name
707              Specifies which key-value backend to use. This can be used  when
708              adding  a file to the annex, or migrating a file. Once files are
709              in the annex, their backend is known and this option is not nec‐
710              essary.
711
712       --user-agent=value
713              Overrides  the User-Agent to use when downloading files from the
714              web.
715
716       --notify-finish
717              Caused a desktop notification to be displayed  after  each  suc‐
718              cessful file download and upload.
719
720              (Only supported on some platforms, e.g. Linux with dbus. A no-op
721              when not supported.)
722
723       --notify-start
724              Caused a desktop notification to be displayed when a file upload
725              or download has started, or when a file is dropped.
726
727       -c name=value
728              Overrides  git configuration settings. May be specified multiple
729              times.
730

CONFIGURATION

732       Like other git commands, git-annex is configured via .git/config.
733
734       annex.uuid
735              A unique UUID for this repository (automatically set).
736
737       annex.backend
738              Name of the default key-value backend to  use  when  adding  new
739              files to the repository.
740
741              This  is  overridden by annex annex.backend configuration in the
742              .gitattributes files, and by the --backend option.
743
744              (This used to be named annex.backends, and that  will  still  be
745              used if set.)
746
747       annex.securehashesonly
748              Set  to  true  to  indicate  that the repository should only use
749              cryptographically secure hashes (SHA2, SHA3)  and  not  insecure
750              hashes (MD5, SHA1) for content.
751
752              When  this is set, the contents of files using cryptographically
753              insecure hashes will not be allowed to be added to  the  reposi‐
754              tory.
755
756              Also,  git-annex  fsck  will complain about any files present in
757              the repository that use insecure hashes.
758
759              To configure the behavior in new clones of the repository,  this
760              can be set using git-annex-config.
761
762       annex.maxextensionlength
763              Maximum  length,  in  bytes,  of  what  is considered a filename
764              extension when adding a file to a backend that  preserves  file‐
765              name  extensions.  The  default length is 4, which allows exten‐
766              sions like "jpeg". The dot before the extension is  not  counted
767              part of its length. At most two extensions at the end of a file‐
768              name will be preserved, e.g. .gz or .tar.gz .
769
770       annex.diskreserve
771              Amount of disk space to reserve.  Disk  space  is  checked  when
772              transferring  content  to avoid running out, and additional free
773              space can be reserved via this option, to make  space  for  more
774              important  content  (such  as git commit logs). Can be specified
775              with any commonly used units, for example, "0.5 gb", "500M",  or
776              "100 KiloBytes"
777
778              The default reserve is 1 megabyte.
779
780       annex.largefiles
781              Used  to  configure  which files are large enough to be added to
782              the annex.  It is an expression that matches the large files, eg
783              "include=*.mp3   or   largerthan(500kb)"   See  git-annex-match‐
784              ing-expression(1) for details on the syntax.
785
786              Overrides  any  annex.largefiles  attributes  in  .gitattributes
787              files.
788
789              To  configure  a  default annex.largefiles for all clones of the
790              repository, this can be set in git-annex-config(1).
791
792              This configures the behavior of  both  git-annex  and  git  when
793              adding  files  to the repository. By default, git-annex add adds
794              all files to the annex (except dotfiles), and git add adds files
795              to  git  (unless they were added to the annex previously).  When
796              annex.largefiles is configured, both git annex add and  git  add
797              will  add matching large files to the annex, and the other files
798              to git.
799
800              Other git-annex commands also honor annex.largefiles,  including
801              git annex import, git annex addurl, git annex importfeed and the
802              assistant.
803
804       annex.dotfiles
805              Normally, dotfiles are assumed  to  be  files  like  .gitignore,
806              whose  content  should  always be part of the git repository, so
807              they will not be added to the annex. Setting  annex.dotfiles  to
808              true  makes dotfiles be added to the annex the same as any other
809              file.
810
811              To annex only some dotfiles, set this and configure annex.large‐
812              files  to  match  the  ones you want. For example, to match only
813              dotfiles ending in ".big"
814
815               git     config     annex.largefiles     "(include=.*.big     or
816              include=*/.*.big) or (exclude=.* and exclude=*/.*)"
817               git config annex.dotfiles true
818
819              To  configure  a  default  annex.dotfiles  for all clones of the
820              repository, this can be set in git-annex-config(1).
821
822       annex.gitaddtoannex
823              Setting this to false will prevent git add from adding files  to
824              the annex, despite the annex.largefiles configuration.
825
826       annex.addsmallfiles
827              Controls  whether  small  files  (not matching annex.largefiles)
828              should be checked into git by git annex add. Defaults  to  true;
829              set to false to instead make small files be skipped.
830
831       annex.addunlocked
832              Commands  like  git-annex  add  default  to  adding files to the
833              repository in locked form. This can make them add the  files  in
834              unlocked  form,  the  same as if git-annex-unlock(1) were run on
835              the files.
836
837              This can be set to "true" to add everything unlocked, or it  can
838              be  a  more  complicated  expression that matches files by name,
839              size,  or  content.  See  git-annex-matching-expression(1)   for
840              details.
841
842              To  configure  a default annex.addunlocked for all clones of the
843              repository, this can be set in git-annex-config(1).
844
845              (Using git add always adds files in unlocked form and it is  not
846              affected by this setting.)
847
848              When  a  repository  has  core.symlinks  set to false, or has an
849              adjusted unlocked branch checked out, this setting  is  ignored,
850              and files are always added to the repository in unlocked form.
851
852       annex.numcopies
853              This  is  a  deprecated  setting. You should instead use the git
854              annex numcopies command to configure how many  copies  of  files
855              are kept across all repositories, or the annex.numcopies .gitat‐
856              tributes setting.
857
858              This config setting is only looked at when git  annex  numcopies
859              has  never  been configured, and when there's no annex.numcopies
860              setting in the .gitattributes file.
861
862              Note that setting numcopies to 0 is very unsafe.
863
864       annex.genmetadata
865              Set this to true to make git-annex automatically  generate  some
866              metadata when adding files to the repository.
867
868              In particular, it stores year, month, and day metadata, from the
869              file's modification date.
870
871              When importfeed is used, it stores additional metadata from  the
872              feed, such as the author, title, etc.
873
874       annex.used-refspec
875              This  controls which refs git-annex unused considers to be used.
876              See REFSPEC FORMAT in git-annex-unused(1) for details.
877
878       annex.jobs
879              Configure the number of concurrent jobs to run. Default is 1.
880
881              Only git-annex commands that support the --jobs option will  use
882              this.
883
884              Setting this to "cpus" will run one job per CPU core.
885
886       annex.queuesize
887              git-annex  builds  a  queue of git commands, in order to combine
888              similar commands for speed. By default the size of the queue  is
889              limited  to 10240 commands; this can be used to change the size.
890              If you have plenty of memory and are  working  with  very  large
891              numbers of files, increasing the queue size can speed it up.
892
893       annex.bloomcapacity
894              The git annex unused and git annex sync --content commands use a
895              bloom filter to determine what files are present in eg, the work
896              tree.   The default bloom filter is sized to handle up to 500000
897              files. If your  repository  is  larger  than  that,  you  should
898              increase  this  value.  Larger values will make git-annex unused
899              and git annex sync --content consume more memory; run git  annex
900              info for memory usage numbers.
901
902       annex.bloomaccuracy
903              Adjusts  the  accuracy  of  the  bloom  filter used by git annex
904              unused and git annex sync --content.  The  default  accuracy  is
905              10000000  -- 1 unused file out of 10000000 will be missed by git
906              annex unused. Increasing the accuracy will make git annex unused
907              consume  more  memory;  run git annex info for memory usage num‐
908              bers.
909
910       annex.sshcaching
911              By default, git-annex caches ssh connections  using  ssh's  Con‐
912              trolMaster  and  ControlPersist  settings  (if built using a new
913              enough ssh). To disable this, set to false.
914
915       annex.alwayscommit
916              By default, git-annex automatically commits  data  to  the  git-
917              annex  branch after each command is run. If you have a series of
918              commands that you want to make a single commit, you can run  the
919              commands  with -c annex.alwayscommit=false. You can later commit
920              the data by running git annex merge (or by automatic merges)  or
921              git annex sync.
922
923              You  should beware running git gc when using this configuration,
924              since it could garbage collect objects that are staged  in  git-
925              annex's index but not yet committed.
926
927       annex.commitmessage
928              When git-annex updates the git-annex branch, it usually makes up
929              its own commit message ("update"), since users rarely look at or
930              care about changes to that branch. If you do care, you can spec‐
931              ify this setting by running commands  with  -c  annex.commitmes‐
932              sage=whatever
933
934              This works well in combination with annex.alwayscommit=false, to
935              gather up a set of changes and commit them with  a  message  you
936              specify.
937
938       annex.allowsign
939              By  default  git-annex  avoids gpg signing commits that it makes
940              when they're not the purpose of  a  command,  but  only  a  side
941              effect.   That  default avoids lots of gpg password prompts when
942              commit.gpgSign is set. A command like  git  annex  sync  or  git
943              annex  merge  will  gpg  sign its commit, but a command like git
944              annex get, that updates the  git-annex  branch,  will  not.  The
945              assistant also avoids signing commits.
946
947              Setting  annex.allowsign  to true lets all commits be signed, as
948              controlled by commit.gpgSign and other git configuration.
949
950       annex.merge-annex-branches
951              By default,  git-annex  branches  that  have  been  pulled  from
952              remotes  are  automatically  merged  into  the  local  git-annex
953              branch, so that  git-annex  has  the  most  up-to-date  possible
954              knowledge.
955
956              To  avoid  that merging, set this to "false". This can be useful
957              particularly when you don't have write permission to the reposi‐
958              tory.
959
960       annex.hardlink
961              Set  this  to  true to make file contents be hard linked between
962              the repository and its remotes when possible, instead of a  more
963              expensive copy.
964
965              Use  with  caution  --  This  can invalidate numcopies counting,
966              since with hard links, fewer copies of a file can exist. So,  it
967              is  a  good  idea  to  mark  a  repository using this setting as
968              untrusted.
969
970              When a repository is set up using git clone --shared,  git-annex
971              init  will automatically set annex.hardlink and mark the reposi‐
972              tory as untrusted.
973
974       annex.thin
975              Set this to true to make unlocked files be a hard link to  their
976              content  in  the annex, rather than a second copy. This can save
977              considerable disk space, but when a modification is  made  to  a
978              file,  you  will  lose the local (and possibly only) copy of the
979              old version. So, enable with care.
980
981              After setting (or unsetting) this, you should run git annex  fix
982              to  fix  up  the annexed files in the work tree to be hard links
983              (or copies).
984
985              Note that this has no effect when the filesystem does  not  sup‐
986              port  hard links.  And when multiple files in the work tree have
987              the same content, only one of  them  gets  hard  linked  to  the
988              annex.
989
990       annex.resolvemerge
991              Set  to  false  to  prevent  merge  conflicts in the checked out
992              branch being automatically resolved by the  git-annex  assitant,
993              git-annex  sync, git-annex merge, and the git-annex post-receive
994              hook.
995
996              To configure the behavior in all clones of the repository,  this
997              can be set in git-annex-config(1).
998
999       annex.synccontent
1000              Set  to  true  to make git-annex sync default to syncing annexed
1001              content.
1002
1003              To configure the behavior in all clones of the repository,  this
1004              can be set in git-annex-config(1).
1005
1006       annex.synconlyannex
1007              Set  to  true to make git-annex sync default to only sincing the
1008              git-annex branch and annexed content.
1009
1010              To configure the behavior in all clones of the repository,  this
1011              can be set in git-annex-config(1).
1012
1013       annex.debug
1014              Set to true to enable debug logging by default.
1015
1016       annex.version
1017              The  current  version of the git-annex repository. This is main‐
1018              tained by git-annex and should never be manually changed.
1019
1020       annex.autoupgraderepository
1021              When an old git-annex repository version has become  deprecated,
1022              git-annex  will normally automatically upgrade the repository to
1023              the new version.
1024
1025              If this is set to false, git-annex won't  automatically  upgrade
1026              the  repository. Instead it will exit with an error message. You
1027              can run git annex upgrade yourself when you are ready to upgrade
1028              the repository.
1029
1030       annex.crippledfilesystem
1031              Set  to true if the repository is on a crippled filesystem, such
1032              as FAT, which does not support symbolic links, or hard links, or
1033              unix  permissions.   This  is automatically probed by "git annex
1034              init".
1035
1036       annex.pidlock
1037              Normally, git-annex uses fine-grained lock files to allow multi‐
1038              ple  processes  to run concurrently without getting in each oth‐
1039              ers' way.  That works great, unless you are using git-annex on a
1040              filesystem  that  does  not  support  POSIX fcntl locks. This is
1041              sometimes the case when using NFS or Lustre filesystems.
1042
1043              To support such situations, you can set annex.pidlock  to  true,
1044              and it will fall back to a single top-level pid file lock.
1045
1046              Although,  often,  you'd  really  be better off fixing your net‐
1047              worked filesystem configuration to support  POSIX  locks..  And,
1048              some  networked  filesystems  are  so inconsistent that one node
1049              can't reliably tell when the other node is holding a  pid  lock.
1050              Caveat emptor.
1051
1052       annex.pidlocktimeout
1053              When  using  pid lock files, it's possible for a stale lock file
1054              to get left behind by previous run of git-annex that crashed  or
1055              was  interrupted.   This  is mostly avoided, but can occur espe‐
1056              cially when using a network file system.
1057
1058              git-annex will wait up to this many seconds  for  the  pid  lock
1059              file  to  go  away,  and  will then abort if it cannot continue.
1060              Default: 300
1061
1062       annex.cachecreds
1063              When "true" (the default), git-annex will cache credentials used
1064              to  access  special  remotes  in files in .git/annex/creds/ that
1065              only you can read. To disable that caching, set to "false",  and
1066              credentials  will  only be read from the environment, or if they
1067              have been embedded in encrypted form in the git repository, will
1068              be  extracted  and decrypted each time git-annex needs to access
1069              the remote.
1070
1071       annex.secure-erase-command
1072              This can be set to a command that should be  run  whenever  git-
1073              annex removes the content of a file from the repository.
1074
1075              In the command line, %file is replaced with the file that should
1076              be erased.
1077
1078              For example, to use the wipe command, set it to wipe -f %file.
1079
1080       annex.tune.objecthash1, annex.tune.objecthashlower,  annex.tune.branch‐
1081       hash1
1082              These  can  be  passed to git annex init to tune the repository.
1083              They cannot be safely changed in a running repository and should
1084              never  be  set  in  global  git configuration.  For details, see
1085              <https://git-annex.branchable.com/tuning/>.
1086

CONFIGURATION OF REMOTES

1088       Remotes are configured using these settings in .git/config.
1089
1090       remote.<name>.annex-cost
1091              When determining which repository to transfer annexed files from
1092              or to, ones with lower costs are preferred.  The default cost is
1093              100 for local repositories, and 200 for remote repositories.
1094
1095       remote.<name>.annex-cost-command
1096              If set, the command is run, and the number it outputs is used as
1097              the  cost.  This allows varying the cost based on e.g., the cur‐
1098              rent network.
1099
1100       remote.<name>.annex-start-command
1101              A command to run when git-annex begins to use the  remote.  This
1102              can  be used to, for example, mount the directory containing the
1103              remote.
1104
1105              The command may be run repeatedly when multiple  git-annex  pro‐
1106              cesses are running concurrently.
1107
1108       remote.<name>.annex-stop-command
1109              A command to run when git-annex is done using the remote.
1110
1111              The  command  will only be run once *all* running git-annex pro‐
1112              cesses are finished using the remote.
1113
1114       remote.<name>.annex-shell
1115              Specify an alternative git-annex-shell executable on the  remote
1116              instead of looking for "git-annex-shell" on the PATH.
1117
1118              This  is  useful  if  the git-annex-shell program is outside the
1119              PATH or has a non-standard name.
1120
1121       remote.<name>.annex-ignore
1122              If set to true, prevents git-annex from storing file contents on
1123              this  remote  by  default.  (You can still request it be used by
1124              the --from and --to options.)
1125
1126              This is, for example, useful if the remote is located  somewhere
1127              without  git-annex-shell. (For example, if it's on GitHub).  Or,
1128              it could be used if the network connection between two reposito‐
1129              ries is too slow to be used normally.
1130
1131              This  does  not  prevent git-annex sync (or the git-annex assis‐
1132              tant) from syncing the git repository to the remote.
1133
1134       remote.<name>.annex-ignore-command
1135              If set, the command is run, and if it exits nonzero, that's  the
1136              same  as  setting  annex-ignore to true. This allows controlling
1137              behavior based on e.g., the current network.
1138
1139       remote.<name>.annex-sync
1140              If set to false, prevents  git-annex  sync  (and  the  git-annex
1141              assistant)  from  syncing  with this remote by default. However,
1142              git annex sync <name> can still be used to sync with the remote.
1143
1144       remote.<name>.annex-sync-command
1145              If set, the command is run, and if it exits nonzero, that's  the
1146              same  as  setting  annex-sync  to false. This allows controlling
1147              behavior based on e.g., the current network.
1148
1149       remote.<name>.annex-pull
1150              If set to false, prevents  git-annex  sync  (and  the  git-annex
1151              assistant etc) from ever pulling (or fetching) from the remote.
1152
1153       remote.<name>.annex-push
1154              If  set  to  false,  prevents  git-annex sync (and the git-annex
1155              assistant etc) from ever pushing to the remote.
1156
1157       remote.<name>.annex-readonly
1158              If set to true, prevents git-annex  from  making  changes  to  a
1159              remote.  This both prevents git-annex sync from pushing changes,
1160              and prevents storing or removing files from read-only remote.
1161
1162       remote.<name>.annex-verify, annex.verify
1163              By default, git-annex will verify the checksums of objects down‐
1164              loaded  from  remotes.  If you trust a remote and don't want the
1165              overhead of these checksums, you can set this to false.
1166
1167              Note that even when this is set to false, git-annex does verifi‐
1168              cation  in  some  edge cases, where it's likely the case than an
1169              object was downloaded incorrectly, or when needed for security.
1170
1171       remote.<name>.annex-tracking-branch
1172              This is for use with special remotes that  support  exports  and
1173              imports.
1174
1175              When set to eg, "master", this tells git-annex that you want the
1176              special remote to track that branch.
1177
1178              When set to eg, "master:subdir", the special remote tracks  only
1179              the subdirectory of that branch.
1180
1181              git-annex sync --content will import changes from the remote and
1182              merge them into  the  annex-tracking-branch.  They  also  export
1183              changes made to the branch to the remote.
1184
1185       remote.<name>.annex-export-tracking
1186              Deprecated  name  for  remote.<name>.annex-tracking-branch. Will
1187              still be used if it's configured and  remote.<name>.annex-track‐
1188              ing-branch is not.
1189
1190       remote.<name>.annexUrl
1191              Can  be  used  to  specify  a  different  url  than  the regular
1192              remote.<name>.url for git-annex to use  when  talking  with  the
1193              remote. Similar to the pushUrl used by git-push.
1194
1195       remote.<name>.annex-uuid
1196              git-annex caches UUIDs of remote repositories here.
1197
1198       remote.<name>.annex-config-uuid
1199              Used  for  some  special  remotes, points to a different special
1200              remote configuration to use.
1201
1202       remote.<name>.annex-retry, annex.retry
1203              Configure retries of failed transfers on a per-remote  and  gen‐
1204              eral  basis,  respectively.  The  value is the number of retries
1205              that can be made of the same transfer. (default 0)
1206
1207       remote.<name>.annex-retry-delay, annex.retry-delay
1208              Number of seconds to delay before the first retry of a transfer.
1209              When  making  multiple  retries  of the same transfer, the delay
1210              doubles after each retry. (default 1)
1211
1212       remote.<name>.annex-checkuuid
1213              This only affects remotes that have  their  url  pointing  to  a
1214              directory on the same system. git-annex normally checks the uuid
1215              of such remotes each time it's run, which lets it  transparently
1216              deal with different drives being mounted to the location at dif‐
1217              ferent times.
1218
1219              Setting annex-checkuuid to false will prevent it  from  checking
1220              the  uuid at startup (although the uuid is still verified before
1221              making any changes to the remote repository). This may be useful
1222              to set to prevent unncessary spin-up or automounting of a drive.
1223
1224       remote.<name>.annex-trustlevel
1225              Configures  a  local  trust level for the remote. This overrides
1226              the value configured by the  trust  and  untrust  commands.  The
1227              value can be any of "trusted", "semitrusted" or "untrusted".
1228
1229       remote.<name>.annex-availability
1230              Can  be used to tell git-annex whether a remote is LocallyAvail‐
1231              able or GloballyAvailable. Normally, git-annex  determines  this
1232              automatically.
1233
1234       remote.<name>.annex-speculate-present
1235              Set  to  "true" to make git-annex speculate that this remote may
1236              contain the content of any file, even though its normal location
1237              tracking  does  not  indicate that it does. This will cause git-
1238              annex to try to get all file contents from the  remote.  Can  be
1239              useful in setting up a caching remote.
1240
1241       remote.<name>.annex-bare
1242              Can  be  used to tell git-annex if a remote is a bare repository
1243              or not. Normally, git-annex determines this automatically.
1244
1245       remote.<name>.annex-ssh-options
1246              Options to use when using ssh to talk to this remote.
1247
1248       remote.<name>.annex-rsync-options
1249              Options to use when using rsync to  or  from  this  remote.  For
1250              example,  to  force IPv6, and limit the bandwidth to 100Kbyte/s,
1251              set it to -6 --bwlimit 100
1252
1253              Note that git-annex-shell  has  a  whitelist  of  allowed  rsync
1254              options,  and  others will not be be passed to the remote rsync.
1255              So using some options may break the  communication  between  the
1256              local and remote rsyncs.
1257
1258       remote.<name>.annex-rsync-upload-options
1259              Options to use when using rsync to upload a file to a remote.
1260
1261              These  options  are passed after other applicable rsync options,
1262              so can be used to override them. For example,  to  limit  upload
1263              bandwidth to 10Kbyte/s, set --bwlimit 10.
1264
1265       remote.<name>.annex-rsync-download-options
1266              Options  to  use  when  using  rsync  to  download a file from a
1267              remote.
1268
1269              These options are passed after other applicable  rsync  options,
1270              so can be used to override them.
1271
1272       remote.<name>.annex-rsync-transport
1273              The remote shell to use to connect to the rsync remote. Possible
1274              values are ssh (the default) and rsh, together with their  argu‐
1275              ments,  for  instance  ssh  -p  2222  -c blowfish; Note that the
1276              remote hostname  should  not  appear  there,  see  rsync(1)  for
1277              details.   When the transport used is ssh, connections are auto‐
1278              matically cached unless annex.sshcaching is unset.
1279
1280       remote.<name>.annex-bup-split-options
1281              Options to pass to  bup  split  when  storing  content  in  this
1282              remote.   For example, to limit the bandwidth to 100Kbyte/s, set
1283              it to --bwlimit 100k (There is no corresponding option  for  bup
1284              join.)
1285
1286       remote.<name>.annex-gnupg-options
1287              Options  to  pass  to  GnuPG  when  it's  encrypting  data.  For
1288              instance, to use the AES cipher with a 256 bits key and  disable
1289              compression,  set  it  to  --cipher-algo  AES256 --compress-algo
1290              none. (These options take precedence over the default GnuPG con‐
1291              figuration, which is otherwise used.)
1292
1293       remote.<name>.annex-gnupg-decrypt-options
1294              Options  to  pass  to  GnuPG  when  it's decrypting data. (These
1295              options take precedence over the  default  GnuPG  configuration,
1296              which is otherwise used.)
1297
1298       annex.ssh-options, annex.rsync-options,
1299              annex.rsync-upload-options,        annex.rsync-download-options,
1300              annex.bup-split-options,                    annex.gnupg-options,
1301              annex.gnupg-decrypt-options
1302
1303              Default  options  to use if a remote does not have more specific
1304              options as described above.
1305
1306       remote.<name>.annex-rsyncurl
1307              Used by rsync special remotes, this configures the  location  of
1308              the  rsync repository to use. Normally this is automatically set
1309              up by git annex initremote, but you can change it if needed.
1310
1311       remote.<name>.annex-buprepo
1312              Used by bup special remotes, this configures the location of the
1313              bup  repository to use. Normally this is automatically set up by
1314              git annex initremote, but you can change it if needed.
1315
1316       remote.<name>.annex-ddarrepo
1317              Used by ddar special remotes, this configures  the  location  of
1318              the  ddar  repository to use. Normally this is automatically set
1319              up by git annex initremote, but you can change it if needed.
1320
1321       remote.<name>.annex-directory
1322              Used by directory special remotes, this configures the  location
1323              of the directory where annexed files are stored for this remote.
1324              Normally this is automatically set up by git  annex  initremote,
1325              but you can change it if needed.
1326
1327       remote.<name>.annex-adb
1328              Used  to  identify  remotes on Android devices accessed via adb.
1329              Normally this is automatically set up by git annex initremote.
1330
1331       remote.<name>.annex-androiddirectory
1332              Used by adb special  remotes,  this  is  the  directory  on  the
1333              Android  device where files are stored for this remote. Normally
1334              this is automatically set up by git annex  initremote,  but  you
1335              can change it if needed.
1336
1337       remote.<name>.annex-androidserial
1338              Used  by  adb  special remotes, this is the serial number of the
1339              Android device used by the remote. Normally  this  is  automati‐
1340              cally  set  up by git annex initremote, but you can change it if
1341              needed, eg when upgrading to a new Android device.
1342
1343       remote.<name>.annex-s3
1344              Used to identify Amazon S3 special remotes.   Normally  this  is
1345              automatically set up by git annex initremote.
1346
1347       remote.<name>.annex-glacier
1348              Used  to identify Amazon Glacier special remotes.  Normally this
1349              is automatically set up by git annex initremote.
1350
1351       remote.<name>.annex-webdav
1352              Used to identify webdav special remotes.  Normally this is auto‐
1353              matically set up by git annex initremote.
1354
1355       remote.<name>.annex-tahoe
1356              Used  to identify tahoe special remotes.  Points to the configu‐
1357              ration directory for tahoe.
1358
1359       remote.<name>.annex-gcrypt
1360              Used to identify gcrypt special remotes.  Normally this is auto‐
1361              matically set up by git annex initremote.
1362
1363              It  is  set to "true" if this is a gcrypt remote.  If the gcrypt
1364              remote is accessible over ssh and has git-annex-shell  available
1365              to manage it, it's set to "shell".
1366
1367       remote.<name>.annex-git-lfs
1368              Used  to  identify  git-lfs  special  remotes.  Normally this is
1369              automatically set up by git annex initremote.
1370
1371              It is set to "true" if this is a git-lfs remote.
1372
1373       remote.<name>.annex-hooktype, remote.<name>.annex-externaltype
1374              Used by hook special remotes and  external  special  remotes  to
1375              record the type of the remote.
1376
1377       annex.web-options
1378              Options  to pass to curl when git-annex uses it to download urls
1379              (rather than the default built-in url downloader).
1380
1381              For example, to force IPv4 only, set it to  "-4".   Or  to  make
1382              curl use your ~/.netrc file, set it to "--netrc".
1383
1384              Setting  this  option  makes  git-annex  use curl, but only when
1385              annex.security.allowed-ip-addresses is configured in a  specific
1386              way. See its documentation.
1387
1388       annex.youtube-dl-options
1389              Options  to  pass to youtube-dl when using it to find the url to
1390              download for a video.
1391
1392              Some options may break git-annex's integration with  youtube-dl.
1393              For  example,  the --output option could cause it to store files
1394              somewhere git-annex won't find them. Avoid setting  here  or  in
1395              the  youtube-dl config file any options that cause youtube-dl to
1396              download more than one file, or to store the file anywhere other
1397              than the current working directory.
1398
1399       annex.aria-torrent-options
1400              Options to pass to aria2c when using it to download a torrent.
1401
1402       annex.http-headers
1403              HTTP  headers  to  send  when downloading from the web. Multiple
1404              lines of this option can be set, one per header.
1405
1406       annex.http-headers-command
1407              If set, the command is run and each line of its output  is  used
1408              as a HTTP header. This overrides annex.http-headers.
1409
1410       annex.security.allowed-url-schemes
1411              List  of  URL schemes that git-annex is allowed to download con‐
1412              tent from.  The default is "http https ftp".
1413
1414              Think very carefully before changing this;  there  are  security
1415              implications. For example, if it's changed to allow "file" URLs,
1416              then anyone who can get a commit into your git-annex  repository
1417              could  git-annex addurl a pointer to a private file located out‐
1418              side that repository, possibly causing it to be copied into your
1419              repository  and  transferred  on  to other remotes, exposing its
1420              content.
1421
1422              Some special  remotes  support  their  own  domain-specific  URL
1423              schemes; those are not affected by this configuration setting.
1424
1425       annex.security.allowed-ip-addresses
1426              By  default,  git-annex  only  makes  connections  to  public IP
1427              addresses; it will refuse to  use  HTTP  and  other  servers  on
1428              localhost or on a private network.
1429
1430              This setting can override that behavior, allowing access to par‐
1431              ticular IP addresses that would normally be blocked. For example
1432              "127.0.0.1 ::1" allows access to localhost (both IPV4 and IPV6).
1433              To allow access to all IP addresses, use "all"
1434
1435              Think very carefully before changing this;  there  are  security
1436              implications.  Anyone  who  can get a commit into your git-annex
1437              repository could git annex addurl an url on  a  private  server,
1438              possibly  causing  it  to be downloaded into your repository and
1439              transferred to other remotes, exposing its content.
1440
1441              Note that, since the interfaces of curl and  youtube-dl  do  not
1442              allow  these  IP  address  restrictions to be enforced, curl and
1443              youtube-dl   will   never    be    used    unless    annex.secu‐
1444              rity.allowed-ip-addresses=all.
1445
1446              To  allow  accessing  local or private IP addresses on only spe‐
1447              cific  ports,  use  the  syntax  "[addr]:port".   For   example,
1448              "[127.0.0.1]:80   [127.0.0.1]:443   [::1]:80  [::1]:443"  allows
1449              localhost on the http ports only.
1450
1451       annex.security.allowed-http-addresses
1452              Old name for annex.security.allowed-ip-addresses.  If set,  this
1453              is     treated     the     same     as     having    annex.secu‐
1454              rity.allowed-ip-addresses set.
1455
1456       annex.security.allow-unverified-downloads
1457              For security reasons, git-annex refuses to download content from
1458              most  special remotes when it cannot check a hash to verify that
1459              the correct content was downloaded.  This  particularly  impacts
1460              downloading the content of URL or WORM keys, which lack hashes.
1461
1462              The  best  way to avoid problems due to this is to migrate files
1463              away from such keys, before  their  content  reaches  a  special
1464              remote.  See git-annex-migrate(1).
1465
1466              When  the  content  is only available from a special remote, you
1467              can use this configuration to force git-annex  to  download  it.
1468              But you do so at your own risk, and it's very important you read
1469              and understand the information below first!
1470
1471              Downloading unverified content from encrypted special remotes is
1472              prevented,  because  the  special  remote  could send some other
1473              encrypted content than what you  expect,  causing  git-annex  to
1474              decrypt  data that you never checked into git-annex, and risking
1475              exposing the decrypted data to  any  non-encrypted  remotes  you
1476              send content to.
1477
1478              Downloading  unverified  content  from  (non-encrypted) external
1479              special remotes is prevented, because  they  could  follow  http
1480              redirects  to  web servers on localhost or on a private network,
1481              or in some cases to a file:/// url.
1482
1483              If you decide to bypass this security check, the best  thing  to
1484              do  is to only set it temporarily while running the command that
1485              gets the file.  The value to set the config  to  is  "ACKTHPPT".
1486              For example:
1487
1488               git -c annex.security.allow-unverified-downloads=ACKTHPPT annex
1489              get myfile
1490
1491              It would be a good idea to check that it downloaded the file you
1492              expected, too.
1493
1494       remote.<name>.annex-security-allow-unverified-downloads
1495              Per-remote    configuration    of   annex.security.allow-unveri‐
1496              fied-downloads.
1497

CONFIGURATION OF ASSISTANT

1499       annex.delayadd
1500
1501              Makes the watch and assistant commands delay for  the  specified
1502              number  of  seconds  before  adding  a newly created file to the
1503              annex. Normally this is not needed, because  they  already  wait
1504              for all writers of the file to close it.
1505
1506       annex.expireunused
1507              Controls what the assistant does about unused file contents that
1508              are stored in the repository.
1509
1510              The default is false, which causes all old and unused file  con‐
1511              tents  to be retained, unless the assistant is able to move them
1512              to some other repository (such as a backup repository).
1513
1514              Can be set to a time specification, like "7d" or "1m", and  then
1515              file  contents that have been known to be unused for a week or a
1516              month will be deleted.
1517
1518       annex.fscknudge
1519              When set to false, prevents the webapp from reminding  you  when
1520              using repositories that lack consistency checks.
1521
1522       annex.autoupgrade
1523              When  set  to  ask  (the default), the webapp will check for new
1524              versions and prompt if they should be upgraded to. When  set  to
1525              true,  automatically  upgrades  without  prompting (on some sup‐
1526              ported platforms). When  set  to  false,  disables  any  upgrade
1527              checking.
1528
1529              Note  that  upgrade  checking  is  only  done  when git-annex is
1530              installed from one of the prebuilt images from its website. This
1531              does  not  bypass  e.g., a Linux distribution's own upgrade han‐
1532              dling code.
1533
1534              This setting also controls  whether  to  restart  the  git-annex
1535              assistant when the git-annex binary is detected to have changed.
1536              That is useful no matter how you installed git-annex.
1537
1538       annex.autocommit
1539              Set to false to prevent the git-annex  assistant  and  git-annex
1540              sync  from  automatically  committing  changes  to  files in the
1541              repository.
1542
1543              To configure the behavior in all clones of the repository,  this
1544              can be set in git-annex-config(1).
1545
1546       annex.startupscan
1547              Set  to  false  to prevent the git-annex assistant from scanning
1548              the repository for new and changed files on startup.  This  will
1549              prevent it from noticing changes that were made while it was not
1550              running, but can be a  useful  performance  tweak  for  a  large
1551              repository.
1552
1553       annex.listen
1554              Configures  which  address the webapp listens on. The default is
1555              localhost.  Can be either an IP  address,  or  a  hostname  that
1556              resolves to the desired address.
1557

CONFIGURATION VIA .gitattributes

1559       The  key-value  backend used when adding a new file to the annex can be
1560       configured on a per-file-type basis via .gitattributes  files.  In  the
1561       file, the annex.backend attribute can be set to the name of the backend
1562       to use. For example, this  here's  how  to  use  the  WORM  backend  by
1563       default, but the SHA256E backend for ogg files:
1564
1565        * annex.backend=WORM
1566        *.ogg annex.backend=SHA256E
1567
1568       There is a annex.largefiles attribute, which is used to configure which
1569       files are large enough to be added to the annex. Since attributes  can‐
1570       not   contain   spaces,  it  is  difficult  to  use  for  more  complex
1571       annex.largefiles settings. Setting annex.largefiles  in  git-annex-con‐
1572       fig(1) is an easier way to configure it across all clones of the repos‐
1573       itory.  See git-annex-matching-expression(1) for details on the syntax.
1574
1575       The numcopies setting can also be configured on a  per-file-type  basis
1576       via  the  annex.numcopies attribute in .gitattributes files. This over‐
1577       rides other numcopies settings.  For example, this makes two copies  be
1578       needed for wav files and 3 copies for flac files:
1579
1580        *.wav annex.numcopies=2
1581        *.flac annex.numcopies=3
1582
1583       Note that setting numcopies to 0 is very unsafe.
1584
1585       These  settings  are  honored by git-annex whenever it's operating on a
1586       matching file. However, when using --all, --unused, or --key to specify
1587       keys  to  operate  on, git-annex is operating on keys and not files, so
1588       will not honor the settings from .gitattributes. For this  reason,  the
1589       git annex numcopies command is useful to configure a global default for
1590       numcopies.
1591
1592       Also note that when using views, only the toplevel .gitattributes  file
1593       is  preserved  in the view, so other settings in other files won't have
1594       any effect.
1595

EXIT STATUS

1597       git-annex, when called as a git subcommand, may return exit codes 0  or
1598       1 for success or failures, or, more rarely, 127 or 128 for certain very
1599       specific failures.  git-annex itself should return 0 on success  and  1
1600       on  failure,  unless the --time-limit=time option is hit, in which case
1601       it returns with exit code 101.
1602

ENVIRONMENT

1604       These environment variables are used by git-annex when set:
1605
1606       GIT_WORK_TREE, GIT_DIR
1607              Handled the same as they are by git, see git(1)
1608
1609       GIT_SSH, GIT_SSH_COMMAND
1610              Handled similarly to the same as described in git(1).   The  one
1611              difference  is  that git-annex will sometimes pass an additional
1612              "-n" parameter to these, as the first parameter, to prevent  ssh
1613              from  reading  from stdin. Since that can break existing uses of
1614              these environment variables that don't expect the extra  parame‐
1615              ter,  you  will need to set GIT_ANNEX_USE_GIT_SSH=1 to make git-
1616              annex support these.
1617
1618              Note that setting either of these environment variables prevents
1619              git-annex  from  automatically  enabling  ssh connection caching
1620              (see annex.sshcaching), so it will  slow  down  some  operations
1621              with  remotes  over ssh. It's up to you to enable ssh connection
1622              caching if you need it; see ssh's documentation.
1623
1624              Also,  annex.ssh-options   and   remote.<name>.annex-ssh-options
1625              won't have any effect when these envionment variables are set.
1626
1627              Usually  it's  better  to  configure any desired options through
1628              your ~/.ssh/config file, or by setting annex.ssh-options.
1629
1630       GIT_ANNEX_VECTOR_CLOCK
1631              Normally git-annex timestamps lines in the log  files  committed
1632              to  the git-annex branch. Setting this environment variable to a
1633              number will make git-annex use that rather than the current num‐
1634              ber  of  seconds since the UNIX epoch. Note that decimal seconds
1635              are supported.
1636
1637              This is only provided for advanced users who either have a  bet‐
1638              ter way to tell which commit is current than the local clock, or
1639              who need to avoid embedding timestamps for policy reasons.  Mis‐
1640              use   of  this  environment  variable  can  confuse  git-annex's
1641              book-keeping, sometimes in ways that git annex fsck is unable to
1642              repair.
1643
1644              Some  special  remotes  use additional environment variables for
1645              authentication   etc.   For   example,   AWS_ACCESS_KEY_ID   and
1646              GIT_ANNEX_P2P_AUTHTOKEN. See special remote documentation.
1647

FILES

1649       These files are used by git-annex:
1650
1651       .git/annex/objects/  in  your  git repository contains the annexed file
1652       contents that are currently available. Annexed files in your git repos‐
1653       itory symlink to that content.
1654
1655       .git/annex/  in your git repository contains other run-time information
1656       used by git-annex.
1657
1658       ~/.config/git-annex/autostart is a list of git  repositories  to  start
1659       the git-annex assistant in.
1660
1661       .git/hooks/pre-commit-annex in your git repository will be run whenever
1662       a commit is made to the HEAD branch, either by  git  commit,  git-annex
1663       sync, or the git-annex assistant.
1664
1665       .git/hooks/post-update-annex  in  your git repository will be run when‐
1666       ever the git-annex branch is updated. You can make this  hook  run  git
1667       update-server-info when publishing a git-annex repository by http.
1668

SEE ALSO

1670       More   git-annex   documentation   is   available   on  its  web  site,
1671       <https://git-annex.branchable.com/>
1672
1673       If git-annex is installed from a package, a copy of  its  documentation
1674       should be included, in, for example, /usr/share/doc/git-annex/.
1675

AUTHOR

1677       Joey Hess <id@joeyh.name>
1678
1679       <https://git-annex.branchable.com/>
1680
1681                                                                  git-annex(1)
Impressum