1git-annex(1) General Commands Manual git-annex(1)
2
6 git-annex - manage files with git, without checking their contents in
7
9 git annex command [params ...]
10
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 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 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
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 # git annex add iso
47 add iso/Debian_5.0.iso ok
48 # git annex drop iso/Debian_4.0.iso
50 drop iso/Debian_4.0.iso ok
51 # git annex move iso --to=usbdrive
53 move iso/Debian_5.0.iso (moving to usbdrive...) ok
54
56 help
57 Display built-in help.
59 For help on a specific command, use git annex help command
61 add [path ...]
63 Adds files to the annex.
64 See git-annex-add(1) for details.
66 get [path ...]
68 Makes the content of annexed files available in this repository.
69 See git-annex-get(1) for details.
71 drop [path ...]
73 Drops the content of annexed files from this repository.
74 See git-annex-drop(1) for details.
76 move [path ...] [--from=remote|--to=remote]
78 Moves the content of files from or to another remote.
79 See git-annex-move(1) for details.
81 copy [path ...] [--from=remote|--to=remote]
83 Copies the content of files from or to another remote.
84 See git-annex-copy(1) for details.
86 status [path ...]
88 Show the working tree status. (deprecated)
89 See git-annex-status(1) for details.
91 unlock [path ...]
93 Unlock annexed files for modification.
94 See git-annex-unlock(1) for details.
96 edit [path ...]
98 This is an alias for the unlock command. May be easier to remem‐
99 ber, if you think of this as allowing you to edit an annexed
100 file.
101 lock [path ...]
103 Use this to undo an unlock command if you don't want to modify
104 the files, or have made modifications you want to discard.
105 See git-annex-lock(1) for details.
107 pull [remote ...]
109 Pull content from remotes.
110 See git-annex-pull(1) for details.
112 push [remote ...]
114 Push content to remotes.
115 See git-annex-push(1) for details.
117 sync [remote ...]
119 Synchronize local repository with remotes.
120 See git-annex-sync(1) for details.
122 assist [remote ...]
124 Add files and sync changes with remotes.
125 See git-annex-assist(1) for details.
127 mirror [path ...] [--to=remote|--from=remote]
129 Mirror content of files to/from another repository.
130 See git-annex-mirror(1) for details.
132 addurl [url ...]
134 Downloads each url to its own file, which is added to the annex.
135 See git-annex-addurl(1) for details.
137 rmurl file url
139 Record that the file is no longer available at the url.
140 See git-annex-rmurl(1) for details.
142 import --from remote branch[:subdir] | [path ...]
144 Add a tree of files to the repository.
145 See git-annex-import(1) for details.
147 importfeed [url ...]
149 Imports the contents of podcast feeds into the annex.
150 See git-annex-importfeed(1) for details.
152 export treeish --to remote
154 Export content to a remote.
155 See git-annex-export(1) for details.
157 undo [filename|directory] ...
159 Undo last change to a file or directory.
160 See git-annex-undo(1) for details.
162 multicast
164 Multicast file distribution.
165 See git-annex-multicast(1) for details.
167 watch Daemon to watch for changes and autocommit.
169 See git-annex-watch(1) for details.
171 assistant
173 Daemon to automatically sync changes.
174 See git-annex-assistant(1) for details.
176 webapp Opens a web app, that allows easy setup of a git-annex reposi‐
178 tory, and control of the git-annex assistant. If the assistant
179 is not already running, it will be started.
180 See git-annex-webapp(1) for details.
182 remotedaemon
184 Persistant communication with remotes.
185 See git-annex-remotedaemon(1) for details.
187
189 init [description]
190 Until a repository (or one of its remotes) has been initialized,
192 git-annex will refuse to operate on it, to avoid accidentally
193 using it in a repository that was not intended to have an annex.
194 See git-annex-init(1) for details.
196 describe repository description
198 Changes the description of a repository.
199 See git-annex-describe(1) for details.
201 initremote name type=value [param=value ...]
203 Creates a new special remote, and adds it to .git/config.
204 See git-annex-initremote(1) for details.
206 enableremote name [param=value ...]
208 Enables use of an existing special remote in the current reposi‐
209 tory.
210 See git-annex-enableremote(1) for details.
212 configremote name [param=value ...]
214 Changes configuration of an existing special remote.
215 See git-annex-configremote(1) for details.
217 renameremote
219 Renames a special remote.
220 See git-annex-renameremote(1) for details.
222 enable-tor
224 Sets up tor hidden service.
225 See git-annex-enable-tor(1) for details.
227 numcopies [N]
229 Configure desired number of copies.
230 See git-annex-numcopies(1) for details.
232 mincopies [N]
234 Configure minimum number of copies.
235 See git-annex-mincopies(1) for details.
237 trust [repository ...]
239 Records that a repository is trusted to not unexpectedly lose
240 content. Use with care.
241 See git-annex-trust(1) for details.
243 untrust [repository ...]
245 Records that a repository is not trusted and could lose content
246 at any time.
247 See git-annex-untrust(1) for details.
249 semitrust [repository ...]
251 Returns a repository to the default semi trusted state.
252 See git-annex-semitrust(1) for details.
254 group repository groupname
256 Add a repository to a group.
257 See git-annex-group(1) for details.
259 ungroup repository groupname
261 Removes a repository from a group.
262 See git-annex-ungroup(1) for details.
264 wanted repository [expression]
266 Get or set preferred content expression.
267 See git-annex-wanted(1) for details.
269 groupwanted groupname [expression]
271 Get or set groupwanted expression.
272 See git-annex-groupwanted(1) for details.
274 required repository [expression]
276 Get or set required content expression.
277 See git-annex-required(1) for details.
279 schedule repository [expression]
281 Get or set scheduled jobs.
282 See git-annex-schedule(1) for details.
284 config Get and set other configuration stored in git-annex branch.
286 See git-annex-config(1) for details.
288 vicfg Opens EDITOR on a temp file containing most of the above config‐
290 uration settings, as well as a few others, and when it exits,
291 stores any changes made back to the git-annex branch.
292 See git-annex-vicfg(1) for details.
294 adjust Switches a repository to use an adjusted branch, which can auto‐
296 matically unlock all files, etc.
297 See git-annex-adjust(1) for details.
299 direct Switches a repository to use direct mode. (deprecated)
301 See git-annex-direct(1) for details.
303 indirect
305 Switches a repository to use indirect mode. (deprecated)
306 See git-annex-indirect(1) for details.
308
310 fsck [path ...]
311 Checks the annex consistency, and warns about or fixes any prob‐
313 lems found. This is a good complement to git fsck.
314 See git-annex-fsck(1) for details.
316 expire [repository:]time ...
318 Expires repositories that have not recently performed an activ‐
319 ity (such as a fsck).
320 See git-annex-expire(1) for details.
322 unused Checks the annex for data that does not correspond to any files
324 present in any tag or branch, and prints a numbered list of the
325 data.
326 See git-annex-unused(1) for details.
328 dropunused [number|range ...]
330 Drops the data corresponding to the numbers, as listed by the
331 last git annex unused
332 See git-annex-dropunused(1) for details.
334 addunused [number|range ...]
336 Adds back files for the content corresponding to the numbers or
337 ranges, as listed by the last git annex unused.
338 See git-annex-addunused(1) for details.
340 fix [path ...]
342 Fixes up symlinks that have become broken to again point to an‐
343 nexed content.
344 See git-annex-fix(1) for details.
346 merge Automatically merge changes from remotes.
348 See git-annex-merge(1) for details.
350 upgrade
352 Upgrades the repository.
353 See git-annex-upgrade(1) for details.
355 dead [repository ...] [--key key]
357 Indicates that a repository or a single key has been irretriev‐
358 ably lost.
359 See git-annex-dead(1) for details.
361 forget Causes the git-annex branch to be rewritten, throwing away his‐
363 torical data about past locations of files.
364 See git-annex-forget(1) for details.
366 filter-branch
368 Produces a filtered version of the git-annex branch.
369 See git-annex-filter-branch(1) for details.
371 repair This can repair many of the problems with git repositories that
373 git fsck detects, but does not itself fix. It's useful if a
374 repository has become badly damaged. One way this can happen is
375 if a repository used by git-annex is on a removable drive that
376 gets unplugged at the wrong time.
377 See git-annex-repair(1) for details.
379 p2p Configure peer-2-Peer links between repositories.
381 See git-annex-p2p(1) for details.
383
385 find [path ...]
386 Outputs a list of annexed files in the specified path. With no
388 path, finds files in the current directory and its subdirecto‐
389 ries.
390 See git-annex-find(1) for details.
392 whereis [path ...]
394 Displays information about where the contents of files are lo‐
395 cated.
396 See git-annex-whereis(1) for details.
398 list [path ...]
400 Displays a table of remotes that contain the contents of the
401 specified files. This is similar to whereis but a more compact
402 display.
403 See git-annex-list(1) for details.
405 whereused
407 Finds what files use or used a key.
408 log [path ...]
410 Displays the location log for the specified file or files, show‐
411 ing each repository they were added to ("+") and removed from
412 ("-").
413 See git-annex-log(1) for details.
415 info [directory|file|remote|uuid ...]
417 Displays statistics and other information for the specified
418 item, which can be a directory, or a file, or a remote, or the
419 uuid of a repository.
420 When no item is specified, displays statistics and information
422 for the repository as a whole.
423 See git-annex-info(1) for details.
425 version
427 Shows the version of git-annex, as well as repository version
428 information.
429 See git-annex-version(1) for details.
431 map Generate map of repositories.
433 See git-annex-map(1) for details.
435 inprogress
437 Access files while they're being downloaded.
438 See git-annex-inprogress(1) for details.
440 findkeys
442 Similar to git-annex find, but operating on keys.
443 See git-annex-findkeys(1) for details.
445
447 metadata [path ...]
448 The content of an annexed file can have any number of metadata
450 fields attached to it to describe it. Each metadata field can in
451 turn have any number of values.
452 This command can be used to set metadata, or show the currently
454 set metadata.
455 See git-annex-metadata(1) for details.
457 view [tag ...] [field=value ...] [field=glob ...] [?tag ...]
459 [field?=glob] [!tag ...] [field!=value ...]
460 Uses metadata to build a view branch of the files in the current
461 branch, and checks out the view branch. Only files in the cur‐
462 rent branch whose metadata matches all the specified field val‐
463 ues and tags will be shown in the view.
464 See git-annex-view(1) for details.
466 vpop [N]
468 Switches from the currently active view back to the previous
469 view. Or, from the first view back to original branch.
470 See git-annex-vpop(1) for details.
472 vfilter [tag ...] [field=value ...] [!tag ...] [field!=value ...]
474 Filters the current view to only the files that have the speci‐
475 fied field values and tags.
476 See git-annex-vfilter(1) for details.
478 vadd [field=glob ...] [field=value ...] [tag ...]
480 Changes the current view, adding an additional level of directo‐
481 ries to categorize the files.
482 See git-annex-vfilter(1) for details.
484 vcycle When a view involves nested subdirectories, this cycles the or‐
486 der.
487 See git-annex-vcycle(1) for details.
489
491 migrate [path ...]
492 Changes the specified annexed files to use a different key-value
494 backend.
495 See git-annex-migrate(1) for details.
497 reinject src dest
499 Moves the src file into the annex as the content of the dest
500 file. This can be useful if you have obtained the content of a
501 file from elsewhere and want to put it in the local annex.
502 See git-annex-reinject(1) for details.
504 unannex [path ...]
506 Use this to undo an accidental git annex add command. It puts
507 the file back how it was before the add.
508 See git-annex-unannex(1) for details.
510 uninit De-initialize git-annex and clean out repository.
512 See git-annex-uninit(1) for details.
514 reinit uuid|description
516 Initialize repository, reusing old UUID.
517 See git-annex-reinit(1) for details.
519
521 pre-commit [path ...]
522 This is meant to be called from git's pre-commit hook. git annex
524 init automatically creates a pre-commit hook using this.
525 See git-annex-pre-commit(1) for details.
527 post-receive
529 This is meant to be called from git's post-receive hook. git an‐
530 nex init automatically creates a post-receive hook using this.
531 See git-annex-post-receive(1) for details.
533 lookupkey [file ...]
535 Looks up key used for file.
536 See git-annex-lookupkey(1) for details.
538 calckey [file ...]
540 Calculates the key that would be used to refer to a file.
541 See git-annex-calckey(1) for details.
543 contentlocation [key ..]
545 Looks up location of annexed content for a key.
546 See git-annex-contentlocation(1) for details.
548 examinekey [key ...]
550 Print information that can be determined purely by looking at
551 the key.
552 See git-annex-examinekey(1) for details.
554 matchexpression
556 Checks if a preferred content expression matches provided data.
557 See git-annex-matchexpression(1) for details.
559 fromkey [key file]
561 Manually set up a file in the git repository to link to a speci‐
562 fied key.
563 See git-annex-fromkey(1) for details.
565 registerurl [key url]
567 Registers an url for a key.
568 See git-annex-registerurl(1) for details.
570 unregisterurl [key url]
572 Unregisters an url for a key.
573 See git-annex-unregisterurl(1) for details.
575 setkey key file
577 Moves a file into the annex as the content of a key.
578 See git-annex-setkey(1) for details.
580 dropkey [key ...]
582 Drops annexed content for specified keys.
583 See git-annex-dropkey(1) for details.
585 transferkey key [--from=remote|--to=remote]
587 Transfers a key from or to a remote.
588 See git-annex-transferkey(1) for details.
590 transferrer
592 Used internally by git-annex to transfer content.
593 See git-annex-transferrer(1) for details.
595 transferkeys
597 Used internally by old versions of the assistant.
598 See git-annex-transferkey(1) for details.
600 setpresentkey key uuid [1|0]
602 This plumbing-level command changes git-annex's records about
603 whether the specified key's content is present in a remote with
604 the specified uuid.
605 See git-annex-setpresentkey(1) for details.
607 readpresentkey key uuid
609 Read records of where key is present.
610 See git-annex-readpresentkey(1) for details.
612 checkpresentkey key remote
614 Check if key is present in remote.
615 See git-annex-checkpresentkey(1) for details.
617 rekey [file key ...]
619 Change keys used for files.
620 See git-annex-rekey(1) for details.
622 resolvemerge
624 Resolves a conflicted merge, by adding both conflicting versions
625 of the file to the tree, using variants of their filename. This
626 is done automatically when using git annex sync or git-annex
627 pull or git annex merge.
628 See git-annex-resolvemerge(1) for details.
630 diffdriver
632 This can be used to make git diff use an external diff driver
633 with annexed files.
634 See git-annex-diffdriver(1) for details.
636 smudge This command lets git-annex be used as a git filter driver, al‐
638 lowing annexed files in the git repository to be unlocked regu‐
639 lar files instead of symlinks.
640 See git-annex-smudge(1) for details.
642 filter-process
644 An alternative implementation of a git filter driver, that is
645 faster in some situations and slower in others than git-annex
646 smudge.
647 See git-annex-filter-process(1) for details.
649 restage
651 Restages unlocked files in the git index.
652 See git-annex-restage(1) for details.
654 findref [ref]
656 Lists files in a git ref. (deprecated)
657 See git-annex-findref(1) for details.
659 proxy -- git cmd [options]
661 Bypass direct mode guard. (deprecated)
662 See git-annex-proxy(1) for details.
664
666 test
667 This runs git-annex's built-in test suite.
669 See git-annex-test(1) for details.
671 testremote remote
673 This tests a remote by generating some random objects and send‐
674 ing them to the remote, then redownloading them, removing them
675 from the remote, etc.
676 It's safe to run in an existing repository (the repository con‐
678 tents are not altered), although it may perform expensive data
679 transfers.
680 See git-annex-testremote(1) for details.
682 fuzztest
684 Generates random changes to files in the current repository, for
685 use in testing the assistant.
686 See git-annex-fuzztest(1) for details.
688 benchmark
690 This runs git-annex's built-in benchmarks, if it was built with
691 benchmarking support.
692 See git-annex-benchmark(1) for details.
694
696 In addition to all the commands listed above, more commands can be
697 added to git-annex by dropping commands named like "git-annex-foo" into
698 a directory in the PATH.
699
701 Like other git commands, git-annex is configured via .git/config.
702 These settings, as well as relevant git config settings, are the ones
703 git-annex uses.
704 (Some of these settings can also be set, across all clones of the
706 repository, using git-annex-config. See its man page for a list.)
707 annex.uuid
709 A unique UUID for this repository (automatically set).
710 annex.backend
712 Name of the default key-value backend to use when adding new
713 files to the repository. See git-annex-backends(1) for informa‐
714 tion about available backends.
715 This is overridden by annex annex.backend configuration in the
717 .gitattributes files, and by the --backend option.
718 (This used to be named annex.backends, and that will still be
720 used if set.)
721 annex.securehashesonly
723 Set to true to indicate that the repository should only use
724 cryptographically secure hashes (SHA2, SHA3) and not insecure
725 hashes (MD5, SHA1) for content.
726 When this is set, the contents of files using cryptographically
728 insecure hashes will not be allowed to be added to the reposi‐
729 tory.
730 Also, git-annex fsck will complain about any files present in
732 the repository that use insecure hashes. And, git-annex import
733 --no-content will refuse to import files from special remotes
734 using insecure hashes.
735 To configure the behavior in new clones of the repository, this
737 can be set using git-annex-config.
738 annex.maxextensionlength
740 Maximum length, in bytes, of what is considered a filename ex‐
741 tension. This is used when adding a file to a backend that pre‐
742 serves filename extensions, and also when generating a view
743 branch.
744 The default length is 4, which allows extensions like "jpeg".
746 The dot before the extension is not counted part of its length.
747 At most two extensions at the end of a filename will be pre‐
748 served, e.g. .gz or .tar.gz .
749 annex.diskreserve
751 Amount of disk space to reserve. Disk space is checked when
752 transferring annexed content to avoid running out, and addi‐
753 tional free space can be reserved via this option, to make space
754 for other data (such as git commit logs). Can be specified with
755 any commonly used units, for example, "0.5 gb", "500M", or "100
756 KiloBytes"
757 The default reserve is 100 megabytes.
759 annex.skipunknown
761 Set to true to make commands like "git-annex get" silently skip
762 over items that are listed in the command line, but are not
763 checked into git.
764 Set to false to make it an error for commands like "git-annex
766 get" to be asked to operate on files that are not checked into
767 git. (This is the default in recent versions of git-annex.)
768 Note that, when annex.skipunknown is false, a command like "git-
770 annex get ." will fail if no files in the current directory are
771 checked into git, but a command like "git-annex get" will not
772 fail, because the current directory is not listed, but is im‐
773 plicit. Commands like "git-annex get foo/" will fail if no files
774 in the directory are checked into git, but if at least one file
775 is, it will ignore other files that are not. This is all the
776 same as the behavior of "git-ls files --error-unmatch".
777 Also note that git-annex skips files that are checked into git,
779 but are not annexed files, this setting does not affect that.
780 annex.largefiles
782 Used to configure which files are large enough to be added to
783 the annex. It is an expression that matches the large files, eg
784 "include=*.mp3 or largerthan=500kb" See git-annex-matching-ex‐
785 pression(1) for details on the syntax.
786 Overrides any annex.largefiles attributes in .gitattributes
788 files.
789 To configure a default annex.largefiles for all clones of the
791 repository, this can be set in git-annex-config(1).
792 This configures the behavior of both git-annex and git when
794 adding files to the repository. By default, git-annex add adds
795 all files to the annex (except dotfiles), and git add adds files
796 to git (unless they were added to the annex previously). When
797 annex.largefiles is configured, both git annex add and git add
798 will add matching large files to the annex, and the other files
799 to git.
800 Other git-annex commands also honor annex.largefiles, including
802 git annex import, git annex addurl, git annex importfeed, git-
803 annex assist, and the git-annex assistant.
804 annex.dotfiles
806 Normally, dotfiles are assumed to be files like .gitignore,
807 whose content should always be part of the git repository, so
808 they will not be added to the annex. Setting annex.dotfiles to
809 true makes dotfiles be added to the annex the same as any other
810 file.
811 To annex only some dotfiles, set this and configure annex.large‐
813 files to match the ones you want. For example, to match only
814 dotfiles ending in ".big"
815 git config annex.largefiles "(include=.*.big or in‐
817 clude=*/.*.big) or (exclude=.* and exclude=*/.*)"
818 git config annex.dotfiles true
819 To configure a default annex.dotfiles for all clones of the
821 repository, this can be set in git-annex-config(1).
822 annex.gitaddtoannex
824 Setting this to false will prevent git add from adding files to
825 the annex, despite the annex.largefiles configuration.
826 annex.addsmallfiles
828 Controls whether small files (not matching annex.largefiles)
829 should be checked into git by git annex add. Defaults to true;
830 set to false to instead make small files be skipped.
831 annex.addunlocked
833 Commands like git-annex add default to adding files to the
834 repository in locked form. This can make them add the files in
835 unlocked form, the same as if git-annex-unlock(1) were run on
836 the files.
837 This can be set to "true" to add everything unlocked, or it can
839 be a more complicated expression that matches files by name,
840 size, or content. See git-annex-matching-expression(1) for de‐
841 tails.
842 To configure a default annex.addunlocked for all clones of the
844 repository, this can be set in git-annex-config(1).
845 (Using git add always adds files in unlocked form and it is not
847 affected by this setting.)
848 When a repository has core.symlinks set to false, or has an ad‐
850 justed unlocked branch checked out, this setting is ignored, and
851 files are always added to the repository in unlocked form.
852 annex.numcopies
854 This is a deprecated setting. You should instead use the git an‐
855 nex numcopies command to configure how many copies of files are
856 kept across all repositories, or the annex.numcopies .gitat‐
857 tributes setting.
858 This config setting is only looked at when git annex numcopies
860 has never been configured, and when there's no annex.numcopies
861 setting in the .gitattributes file.
862 annex.genmetadata
864 Set this to true to make git-annex automatically generate some
865 metadata when adding files to the repository.
866 In particular, it stores year, month, and day metadata, from the
868 file's modification date.
869 When importfeed is used, it stores additional metadata from the
871 feed, such as the author, title, etc.
872 annex.used-refspec
874 This controls which refs git-annex unused considers to be used.
875 See REFSPEC FORMAT in git-annex-unused(1) for details.
876 annex.jobs
878 Configure the number of concurrent jobs to run. Default is 1.
879 Only git-annex commands that support the --jobs option will use
881 this.
882 Setting this to "cpus" will run one job per CPU core.
884 When the --batch option is used, this configuration is ignored.
886 annex.adjustedbranchrefresh
888 When git-annex-adjust(1) is used to set up an adjusted branch
889 that needs to be refreshed after getting or dropping files, this
890 config controls how frequently the branch is refreshed.
891 Refreshing the branch takes some time, so doing it after every
893 file can be too slow. (It also can generate a lot of dangling
894 git objects.) The default value is 0 (or false), which does not
895 refresh the branch. Setting 1 (or true) will refresh only once,
896 after git-annex has made other changes. Setting 2 refreshes af‐
897 ter every file, 3 after every other file, and so on; setting 100
898 refreshes after every 99 files.
899 (If git-annex gets faster in the future, refresh rates will in‐
901 crease proportional to the speed improvements.)
902 annex.queuesize
904 git-annex builds a queue of git commands, in order to combine
905 similar commands for speed. By default the size of the queue is
906 limited to 10240 commands; this can be used to change the size.
907 If you have plenty of memory and are working with very large
908 numbers of files, increasing the queue size can speed it up.
909 annex.bloomcapacity
911 The git annex unused and git annex sync --content commands use a
912 bloom filter to determine what files are present in eg, the work
913 tree. The default bloom filter is sized to handle up to 500000
914 files. If your repository is larger than that, you should in‐
915 crease this value. Larger values will make git-annex unused and
916 git annex sync --content consume more memory; run git annex info
917 for memory usage numbers.
918 annex.bloomaccuracy
920 Adjusts the accuracy of the bloom filter used by git annex un‐
921 used and git annex sync --content. The default accuracy is
922 10000000 -- 1 unused file out of 10000000 will be missed by git
923 annex unused. Increasing the accuracy will make git annex unused
924 consume more memory; run git annex info for memory usage num‐
925 bers.
926 annex.sshcaching
928 By default, git-annex caches ssh connections using ssh's Con‐
929 trolMaster and ControlPersist settings (if built using a new
930 enough ssh). To disable this, set to false.
931 annex.adviceNoSshCaching
933 When git-annex is unable to use ssh connection caching, or has
934 been configured not to, and concurrency is enabled, it will warn
935 that this might result in multiple ssh processes prompting for
936 passwords at the same time. To disable that warning, eg if you
937 have configured ssh connection caching yourself, or have ssh
938 agent caching passwords, set this to false.
939 annex.alwayscommit
941 By default, git-annex automatically commits data to the git-an‐
942 nex branch after each command is run. If you have a series of
943 commands that you want to make a single commit, you can run the
944 commands with -c annex.alwayscommit=false. You can later commit
945 the data by running git annex merge (or by automatic merges) or
946 git annex sync.
947 annex.commitmessage
949 When git-annex updates the git-annex branch, it usually makes up
950 its own commit message (eg "update"), since users rarely look at
951 or care about changes to that branch. If you do care, you can
952 specify this setting by running commands with -c annex.com‐
953 mitmessage=whatever
954 This works well in combination with annex.alwayscommit=false, to
956 gather up a set of changes and commit them with a message you
957 specify.
958 annex.alwayscompact
960 By default, git-annex compacts data it records in the git-annex
961 branch. Setting this to false avoids doing that compaction in
962 some cases, which can speed up operations that populate the git-
963 annex branch with a lot of data. However, when used with opera‐
964 tions that overwrite old values in the git-annex branch, that
965 may cause the git-annex branch to use more disk space, and so
966 slow down reading data from it.
967 An example of a command that can be sped up by using -c an‐
969 nex.alwayscompact=false is git-annex registerurl --batch, when
970 adding a large number of urls to the same key.
971 This option was first supported by git-annex version
973 10.20220724. It is not entirely safe to set this option in a
974 repository that may also be used by an older version of git-an‐
975 nex at the same time as a version that supports this option.
976 annex.allowsign
978 By default git-annex avoids gpg signing commits that it makes
979 when they're not the purpose of a command, but only a side ef‐
980 fect. That default avoids lots of gpg password prompts when
981 commit.gpgSign is set. A command like git annex sync or git an‐
982 nex merge will gpg sign its commit, but a command like git annex
983 get, that updates the git-annex branch, will not. The assistant
984 also avoids signing commits.
985 Setting annex.allowsign to true lets all commits be signed, as
987 controlled by commit.gpgSign and other git configuration.
988 annex.merge-annex-branches
990 By default, git-annex branches that have been pulled from re‐
991 motes are automatically merged into the local git-annex branch,
992 so that git-annex has the most up-to-date possible knowledge.
993 To avoid that merging, set this to "false".
995 This can be useful particularly when you don't have write per‐
997 mission to the repository. While git-annex is mostly able to
998 work in a read-only repository with unmerged git-annex branches,
999 some things do not work, and when it does work it will be slower
1000 due to needing to look at each of the unmerged branches.
1001 annex.private
1003 When this is set to true, no information about the repository
1004 will be recorded in the git-annex branch.
1005 For example, to make a repository without any mention of it ever
1007 appearing in the git-annex branch:
1008 git init myprivate
1010 cd myprivaterepo
1011 git config annex.private true
1012 git annex init
1013 annex.hardlink
1015 Set this to true to make file contents be hard linked between
1016 the repository and its remotes when possible, instead of a more
1017 expensive copy.
1018 Use with caution -- This can invalidate numcopies counting,
1020 since with hard links, fewer copies of a file can exist. So, it
1021 is a good idea to mark a repository using this setting as un‐
1022 trusted.
1023 When a repository is set up using git clone --shared, git-annex
1025 init will automatically set annex.hardlink and mark the reposi‐
1026 tory as untrusted.
1027 When annex.thin is also set, setting annex.hardlink has no ef‐
1029 fect.
1030 annex.thin
1032 Set this to true to make unlocked files be a hard link to their
1033 content in the annex, rather than a second copy. This can save
1034 considerable disk space, but when a modification is made to a
1035 file, you will lose the local (and possibly only) copy of the
1036 old version. Any other, locked files in the repository that
1037 pointed to that content will get broken as well (git-annex fsck
1038 will detect and clean up after that). So, enable this with
1039 care.
1040 After setting (or unsetting) this, you should run git annex fix
1042 to fix up the annexed files in the work tree to be hard links
1043 (or copies).
1044 Note that this has no effect when the filesystem does not sup‐
1046 port hard links. And when multiple files in the work tree have
1047 the same content, only one of them gets hard linked to the an‐
1048 nex.
1049 annex.supportunlocked
1051 By default git-annex supports unlocked files as well as locked
1052 files, so this defaults to true. If set to false, git-annex will
1053 only support locked files. That will avoid doing the work needed
1054 to support unlocked files.
1055 Note that setting this to false does not prevent a repository
1057 from having unlocked files added to it, and in that case the
1058 content of the files will not be accessible until they are
1059 locked.
1060 After changing this config, you need to re-run git-annex init
1062 for it to take effect.
1063 annex.resolvemerge
1065 Set to false to prevent merge conflicts in the checked out
1066 branch being automatically resolved by the git-annex assitant,
1067 git-annex assist, git-annex sync, git-annex pull, git-annex
1068 merge, and the git-annex post-receive hook.
1069 To configure the behavior in all clones of the repository, this
1071 can be set in git-annex-config(1).
1072 annex.synccontent
1074 Set to true to make git-annex sync default to transferring an‐
1075 nexed content.
1076 Set to false to prevent git-annex assist, git-annex pull and
1078 git-annex push from transferring annexed content.
1079 To configure the behavior in all clones of the repository, this
1081 can be set in git-annex-config(1).
1082 annex.synconlyannex
1084 Set to true to make git-annex assist, git-annex sync, git-annex
1085 pull, and git-annex push default to only operating on the git-
1086 annex branch and annexed content.
1087 To configure the behavior in all clones of the repository, this
1089 can be set in git-annex-config(1).
1090 annex.viewunsetdirectory
1092 This configures the name of a directory that is used in a view
1093 to contain files that do not have metadata set. The default name
1094 for the directory is "_". See git-annex-view(1) for details.
1095 annex.debug
1097 Set to true to enable debug logging by default.
1098 annex.debugfilter
1100 Set to configure which debug messages to display (when debug
1101 message display has been enabled by annex.debug or --debug). The
1102 value is one or more module names, separated by commas.
1103 annex.version
1105 The current version of the git-annex repository. This is main‐
1106 tained by git-annex and should never be manually changed.
1107 annex.autoupgraderepository
1109 When an old git-annex repository version is no longer supported,
1110 git-annex will normally automatically upgrade the repository to
1111 the new version. It may also sometimes upgrade from an old
1112 repository version that is still supported but that is not as
1113 good as a later version.
1114 If this is set to false, git-annex won't automatically upgrade
1116 the repository. If the repository version is not supported, git-
1117 annex will instead exit with an error message. If it is still
1118 supported, git-annex will continue to work.
1119 You can run git annex upgrade yourself when you are ready to up‐
1121 grade the repository.
1122 annex.crippledfilesystem
1124 Set to true if the repository is on a crippled filesystem, such
1125 as FAT, which does not support symbolic links, or hard links, or
1126 unix permissions. This is automatically probed by "git annex
1127 init".
1128 annex.pidlock
1130 Normally, git-annex uses fine-grained lock files to allow multi‐
1131 ple processes to run concurrently without getting in each oth‐
1132 ers' way. That works great, unless you are using git-annex on a
1133 filesystem that does not support POSIX fcntl locks. This is
1134 sometimes the case when using NFS or Lustre filesystems.
1135 To support such situations, you can set annex.pidlock to true,
1137 and it will fall back to a single top-level pid file lock.
1138 Although, often, you'd really be better off fixing your net‐
1140 worked filesystem configuration to support POSIX locks.. And,
1141 some networked filesystems are so inconsistent that one node
1142 can't reliably tell when the other node is holding a pid lock.
1143 Caveat emptor.
1144 annex.pidlocktimeout
1146 git-annex will wait up to this many seconds for the pid lock
1147 file to go away, and will then abort if it cannot continue. De‐
1148 fault: 300
1149 When using pid lock files, it's possible for a stale lock file
1151 to get left behind by previous run of git-annex that crashed or
1152 was interrupted. This is mostly avoided, but can occur espe‐
1153 cially when using a network file system. This timeout prevents
1154 git-annex waiting forever in such a situation.
1155 annex.dbdir
1157 The directory where git-annex should store its sqlite databases.
1158 The default location is inside .git/annex/.
1159 Certian filesystems, such as cifs, may not support locking oper‐
1161 ations that sqlite needs, and setting this to a directory on an‐
1162 other filesystem can work around such a problem.
1163 This can safely be set to the same directory in the configura‐
1165 tion of multiple repositories; each repository will use a subdi‐
1166 rectory for its sqlite database.
1167 annex.cachecreds
1169 When "true" (the default), git-annex will cache credentials used
1170 to access special remotes in files in .git/annex/creds/ that
1171 only you can read. To disable that caching, set to "false", and
1172 credentials will only be read from the environment, or if they
1173 have been embedded in encrypted form in the git repository, will
1174 be extracted and decrypted each time git-annex needs to access
1175 the remote.
1176 annex.secure-erase-command
1178 This can be set to a command that should be run whenever git-an‐
1179 nex removes the content of a file from the repository.
1180 In the command line, %file is replaced with the file that should
1182 be erased.
1183 For example, to use the wipe command, set it to wipe -f %file.
1185 annex.freezecontent-command, annex.thawcontent-command
1187 Usually the write permission bits are unset to protect annexed
1188 objects from being modified or deleted. The freezecontent-com‐
1189 mand is run after git-annex has removed (or attempted to remove)
1190 the write bit, and can be used to prevent writing in some other
1191 way. The thawcontent-command should undo its effect, and is run
1192 before git-annex restores the write bit.
1193 In the command line, %path is replaced with the file or direc‐
1195 tory to operate on.
1196 (When annex.crippledfilesystem is set, git-annex will not try to
1198 remove/restore the write bit, but it will still run these
1199 hooks.)
1200 annex.tune.objecthash1, annex.tune.objecthashlower, annex.tune.branch‐
1202 hash1
1203 These can be passed to git annex init to tune the repository.
1204 They cannot be safely changed in a running repository and should
1205 never be set in global git configuration. For details, see
1206 <https://git-annex.branchable.com/tuning/>.
1207
1209 Remotes are configured using these settings in .git/config.
1210 remote.<name>.annex-cost
1212 When determining which repository to transfer annexed files from
1213 or to, ones with lower costs are preferred. The default cost is
1214 100 for local repositories, and 200 for remote repositories.
1215 remote.<name>.annex-cost-command
1217 If set, the command is run, and the number it outputs is used as
1218 the cost. This allows varying the cost based on e.g., the cur‐
1219 rent network.
1220 remote.<name>.annex-start-command
1222 A command to run when git-annex begins to use the remote. This
1223 can be used to, for example, mount the directory containing the
1224 remote.
1225 The command may be run repeatedly when multiple git-annex pro‐
1227 cesses are running concurrently.
1228 remote.<name>.annex-stop-command
1230 A command to run when git-annex is done using the remote.
1231 The command will only be run once *all* running git-annex pro‐
1233 cesses are finished using the remote.
1234 remote.<name>.annex-shell
1236 Specify an alternative git-annex-shell executable on the remote
1237 instead of looking for "git-annex-shell" on the PATH.
1238 This is useful if the git-annex-shell program is outside the
1240 PATH or has a non-standard name.
1241 remote.<name>.annex-ignore
1243 If set to true, prevents git-annex from storing annexed file
1244 contents on this remote by default. (You can still request it
1245 be used by the --from and --to options.)
1246 This is, for example, useful if the remote is located somewhere
1248 without git-annex-shell. (For example, if it's on GitHub). Or,
1249 it could be used if the network connection between two reposito‐
1250 ries is too slow to be used normally.
1251 This does not prevent git-annex sync, git-annex pull, git-annex
1253 push, git-annex assist or the git-annex assistant from operating
1254 on the git repository.
1255 remote.<name>.annex-ignore-command
1257 If set, the command is run, and if it exits nonzero, that's the
1258 same as setting annex-ignore to true. This allows controlling
1259 behavior based on e.g., the current network.
1260 remote.<name>.annex-sync
1262 If set to false, prevents git-annex sync (and git-annex pull,
1263 git-annex push, git-annex assist, and the git-annex assistant)
1264 from operating on this remote by default.
1265 remote.<name>.annex-sync-command
1267 If set, the command is run, and if it exits nonzero, that's the
1268 same as setting annex-sync to false. This allows controlling be‐
1269 havior based on e.g., the current network.
1270 remote.<name>.annex-pull
1272 If set to false, prevents git-annex pull, git-annex sync, git-
1273 annex assist and the git-annex assistant from ever pulling (or
1274 fetching) from the remote.
1275 remote.<name>.annex-push
1277 If set to false, prevents git-annex push, git-annex sync, git-
1278 annex assist and the git-annex assistant from ever pushing to
1279 the remote.
1280 remote.<name>.annex-readonly
1282 If set to true, prevents git-annex from making changes to a re‐
1283 mote. This prevents git-annex sync and git-annex assist from
1284 pushing changes to a git repository. And it prevents storing or
1285 removing files from read-only remote.
1286 remote.<name>.annex-verify, annex.verify
1288 By default, git-annex will verify the checksums of objects down‐
1289 loaded from remotes. If you trust a remote and don't want the
1290 overhead of these checksums, you can set this to false.
1291 Note that even when this is set to false, git-annex does verifi‐
1293 cation in some edge cases, where it's likely the case than an
1294 object was downloaded incorrectly, or when needed for security.
1295 remote.<name>.annex-tracking-branch
1297 This is for use with special remotes that support exports and
1298 imports.
1299 When set to eg, "master", this tells git-annex that you want the
1301 special remote to track that branch.
1302 When set to eg, "master:subdir", the special remote tracks only
1304 the subdirectory of that branch.
1305 Setting this enables some other command to work with these spe‐
1307 cial remotes: git-annex pull will import changes from the remote
1308 and merge them into the annex-tracking-branch. And git-annex
1309 push will export changes to the remote. Higher-level commands
1310 git-annex sync --content and git-annex assist both import and
1311 export.
1312 remote.<name>.annex-export-tracking
1314 Deprecated name for remote.<name>.annex-tracking-branch. Will
1315 still be used if it's configured and remote.<name>.annex-track‐
1316 ing-branch is not.
1317 remote.<name>.annexUrl
1319 Can be used to specify a different url than the regular re‐
1320 mote.<name>.url for git-annex to use when talking with the re‐
1321 mote. Similar to the pushUrl used by git-push.
1322 remote.<name>.annex-uuid
1324 git-annex caches UUIDs of remote repositories here.
1325 remote.<name>.annex-config-uuid
1327 Used for some special remotes, points to a different special re‐
1328 mote configuration to use.
1329 remote.<name>.annex-retry, annex.retry
1331 Number of times a transfer that fails can be retried. (default
1332 0)
1333 remote.<name>.annex-forward-retry, annex.forward-retry
1335 If a transfer made some forward progress before failing, this
1336 allows it to be retried even when annex.retry does not. The
1337 value is the maximum number of times to do that. (default 5)
1338 When both annex.retry and this are set, the maximum number of
1340 retries is the larger of the two.
1341 remote.<name>.annex-retry-delay, annex.retry-delay
1343 Number of seconds to delay before the first retry of a transfer.
1344 When making multiple retries of the same transfer, the delay
1345 doubles after each retry. (default 1)
1346 remote.<name>.annex-bwlimit, annex.bwlimit
1348 This can be used to limit how much bandwidth is used for a
1349 transfer from or to a remote.
1350 For example, to limit transfers to 1 mebibyte per second: git
1352 config annex.bwlimit "1MiB"
1353 This will work with many remotes, including git remotes, but not
1355 for remotes where the transfer is run by a separate program than
1356 git-annex.
1357 remote.<name>.annex-stalldetecton, annex.stalldetection
1359 Configuring this lets stalled or too-slow transfers be detected,
1360 and dealt with, so rather than getting stuck, git-annex will
1361 cancel the stalled operation. The transfer will be considered to
1362 have failed, so settings like annex.retry will control what it
1363 does next.
1364 By default, git-annex detects transfers that have probably
1366 stalled, and suggests configuring this. If it is incorrectly de‐
1367 tecting stalls, setting this to "false" will avoid that.
1368 Set to "true" to enable automatic stall detection. If a remote
1370 does not update its progress consistently, no automatic stall
1371 detection will be done. And it may take a while for git-annex to
1372 decide a remote is really stalled when using automatic stall de‐
1373 tection, since it needs to be conservative about what looks like
1374 a stall.
1375 For more fine control over what constitutes a stall, set to a
1377 value in the form "$amount/$timeperiod" to specify how much data
1378 git-annex should expect to see flowing, minimum, over a given
1379 period of time.
1380 For example, to detect outright stalls where no data has been
1382 transferred after 30 seconds: git config annex.stalldetection
1383 "1KB/30s"
1384 Or, if you have a remote on a USB drive that is normally capable
1386 of several megabytes per second, but has bad sectors where it
1387 gets stuck for a long time, you could use: git config remote.us‐
1388 bdrive.annex-stalldetection "1MB/1m"
1389 This is not enabled by default, because it can make git-annex
1391 use more resources. To be able to cancel stalls, git-annex has
1392 to run transfers in separate processes (one per concurrent job).
1393 So it may need to open more connections to a remote than usual,
1394 or the communication with those processes may make it a bit
1395 slower.
1396 remote.<name>.annex-checkuuid
1398 This only affects remotes that have their url pointing to a di‐
1399 rectory on the same system. git-annex normally checks the uuid
1400 of such remotes each time it's run, which lets it transparently
1401 deal with different drives being mounted to the location at dif‐
1402 ferent times.
1403 Setting annex-checkuuid to false will prevent it from checking
1405 the uuid at startup (although the uuid is still verified before
1406 making any changes to the remote repository). This may be useful
1407 to set to prevent unnecessary spin-up or automounting of a
1408 drive.
1409 remote.<name>.annex-trustlevel
1411 Configures a local trust level for the remote. This overrides
1412 the value configured by the trust and untrust commands. The
1413 value can be any of "trusted", "semitrusted" or "untrusted".
1414 remote.<name>.annex-availability
1416 Can be used to tell git-annex whether a remote is LocallyAvail‐
1417 able or GloballyAvailable. Normally, git-annex determines this
1418 automatically.
1419 remote.<name>.annex-speculate-present
1421 Set to "true" to make git-annex speculate that this remote may
1422 contain the content of any file, even though its normal location
1423 tracking does not indicate that it does. This will cause git-an‐
1424 nex to try to get all file contents from the remote. Can be use‐
1425 ful in setting up a caching remote.
1426 remote.<name>.annex-private
1428 When this is set to true, no information about the remote will
1429 be recorded in the git-annex branch. This is mostly useful for
1430 special remotes, and is set when using git-annex-initremote(1)
1431 with the --private option.
1432 remote.<name>.annex-bare
1434 Can be used to tell git-annex if a remote is a bare repository
1435 or not. Normally, git-annex determines this automatically.
1436 remote.<name>.annex-ssh-options
1438 Options to use when using ssh to talk to this remote.
1439 remote.<name>.annex-rsync-options
1441 Options to use when using rsync to or from this remote. For ex‐
1442 ample, to force IPv6, and limit the bandwidth to 100Kbyte/s, set
1443 it to -6 --bwlimit 100
1444 Note that git-annex-shell has a whitelist of allowed rsync op‐
1446 tions, and others will not be be passed to the remote rsync. So
1447 using some options may break the communication between the local
1448 and remote rsyncs.
1449 remote.<name>.annex-rsync-upload-options
1451 Options to use when using rsync to upload a file to a remote.
1452 These options are passed after other applicable rsync options,
1454 so can be used to override them. For example, to limit upload
1455 bandwidth to 10Kbyte/s, set --bwlimit 10.
1456 remote.<name>.annex-rsync-download-options
1458 Options to use when using rsync to download a file from a re‐
1459 mote.
1460 These options are passed after other applicable rsync options,
1462 so can be used to override them.
1463 remote.<name>.annex-rsync-transport
1465 The remote shell to use to connect to the rsync remote. Possible
1466 values are ssh (the default) and rsh, together with their argu‐
1467 ments, for instance ssh -p 2222 -c blowfish; Note that the re‐
1468 mote hostname should not appear there, see rsync(1) for details.
1469 When the transport used is ssh, connections are automatically
1470 cached unless annex.sshcaching is unset.
1471 remote.<name>.annex-bup-split-options
1473 Options to pass to bup split when storing content in this re‐
1474 mote. For example, to limit the bandwidth to 100Kbyte/s, set it
1475 to --bwlimit 100k (There is no corresponding option for bup
1476 join.)
1477 remote.<name>.annex-gnupg-options
1479 Options to pass to GnuPG when it's encrypting data. For in‐
1480 stance, to use the AES cipher with a 256 bits key and disable
1481 compression, set it to --cipher-algo AES256 --compress-algo
1482 none. (These options take precedence over the default GnuPG con‐
1483 figuration, which is otherwise used.)
1484 remote.<name>.annex-gnupg-decrypt-options
1486 Options to pass to GnuPG when it's decrypting data. (These op‐
1487 tions take precedence over the default GnuPG configuration,
1488 which is otherwise used.)
1489 annex.ssh-options, annex.rsync-options,
1491 annex.rsync-upload-options, annex.rsync-download-options, an‐
1492 nex.bup-split-options, annex.gnupg-options, annex.gnupg-de‐
1493 crypt-options
1494 Default options to use if a remote does not have more specific
1496 options as described above.
1497 remote.<name>.annex-rsyncurl
1499 Used by rsync special remotes, this configures the location of
1500 the rsync repository to use. Normally this is automatically set
1501 up by git annex initremote, but you can change it if needed.
1502 remote.<name>.annex-buprepo
1504 Used by bup special remotes, this configures the location of the
1505 bup repository to use. Normally this is automatically set up by
1506 git annex initremote, but you can change it if needed.
1507 remote.<name>.annex-borgrepo
1509 Used by borg special remotes, this configures the location of
1510 the borg repository to use. Normally this is automatically set
1511 up by git annex initremote, but you can change it if needed.
1512 remote.<name>.annex-ddarrepo
1514 Used by ddar special remotes, this configures the location of
1515 the ddar repository to use. Normally this is automatically set
1516 up by git annex initremote, but you can change it if needed.
1517 remote.<name>.annex-directory
1519 Used by directory special remotes, this configures the location
1520 of the directory where annexed files are stored for this remote.
1521 Normally this is automatically set up by git annex initremote,
1522 but you can change it if needed.
1523 remote.<name>.annex-adb
1525 Used to identify remotes on Android devices accessed via adb.
1526 Normally this is automatically set up by git annex initremote.
1527 remote.<name>.annex-androiddirectory
1529 Used by adb special remotes, this is the directory on the An‐
1530 droid device where files are stored for this remote. Normally
1531 this is automatically set up by git annex initremote, but you
1532 can change it if needed.
1533 remote.<name>.annex-androidserial
1535 Used by adb special remotes, this is the serial number of the
1536 Android device used by the remote. Normally this is automati‐
1537 cally set up by git annex initremote, but you can change it if
1538 needed, eg when upgrading to a new Android device.
1539 remote.<name>.annex-s3
1541 Used to identify Amazon S3 special remotes. Normally this is
1542 automatically set up by git annex initremote.
1543 remote.<name>.annex-glacier
1545 Used to identify Amazon Glacier special remotes. Normally this
1546 is automatically set up by git annex initremote.
1547 remote.<name>.annex-web
1549 Used to identify web special remotes. Normally this is automat‐
1550 ically set up by git annex initremote.
1551 remote.<name>.annex-webdav
1553 Used to identify webdav special remotes. Normally this is auto‐
1554 matically set up by git annex initremote.
1555 remote.<name>.annex-tahoe
1557 Used to identify tahoe special remotes. Points to the configu‐
1558 ration directory for tahoe.
1559 remote.<name>.annex-gcrypt
1561 Used to identify gcrypt special remotes. Normally this is auto‐
1562 matically set up by git annex initremote.
1563 It is set to "true" if this is a gcrypt remote. If the gcrypt
1565 remote is accessible over ssh and has git-annex-shell available
1566 to manage it, it's set to "shell".
1567 remote.<name>.annex-git-lfs
1569 Used to identify git-lfs special remotes. Normally this is au‐
1570 tomatically set up by git annex initremote.
1571 It is set to "true" if this is a git-lfs remote.
1573 remote.<name>.annex-httpalso
1575 Used to identify httpalso special remotes. Normally this is au‐
1576 tomatically set up by git annex initremote.
1577 remote.<name>.annex-externaltype
1579 Used external special remotes to record the type of the remote.
1580 Eg, if this is set to "foo", git-annex will run a "git-annex-re‐
1582 mote-foo" program to communicate with the external special re‐
1583 mote.
1584 If this is set to "readonly", then git-annex will not run any
1586 external special remote program, but will try to access things
1587 stored in the remote using http. That only works for some exter‐
1588 nal special remotes, so consult the documentation of the one you
1589 are using.
1590 remote.<name>.annex-hooktype
1592 Used by hook special remotes to record the type of the remote.
1593 annex.web-options
1595 Options to pass to curl when git-annex uses it to download urls
1596 (rather than the default built-in url downloader).
1597 For example, to force IPv4 only, set it to "-4".
1599 Setting this option makes git-annex use curl, but only when an‐
1601 nex.security.allowed-ip-addresses is configured in a specific
1602 way. See its documentation.
1603 Setting this option prevents git-annex from using git-credential
1605 for prompting for http passwords. Instead, you can include
1606 "--netrc" to make curl use your ~/.netrc file and record the
1607 passwords there.
1608 annex.youtube-dl-options
1610 Options to pass to yt-dlp (or deprecated youtube-dl) when using
1611 it to find the url to download for a video.
1612 Some options may break git-annex's integration with yt-dlp. For
1614 example, the --output option could cause it to store files some‐
1615 where git-annex won't find them. Avoid setting here or in the
1616 yt-dlp config file any options that cause it to download more
1617 than one file, or to store the file anywhere other than the cur‐
1618 rent working directory.
1619 annex.youtube-dl-command
1621 Default is to use "yt-dlp" or if that is not available in the
1622 PATH, to use "youtube-dl".
1623 annex.aria-torrent-options
1625 Options to pass to aria2c when using it to download a torrent.
1626 annex.http-headers
1628 HTTP headers to send when downloading from the web. Multiple
1629 lines of this option can be set, one per header.
1630 annex.http-headers-command
1632 If set, the command is run and each line of its output is used
1633 as a HTTP header. This overrides annex.http-headers.
1634 annex.security.allowed-url-schemes
1636 List of URL schemes that git-annex is allowed to download con‐
1637 tent from. The default is "http https ftp".
1638 Think very carefully before changing this; there are security
1640 implications. For example, if it's changed to allow "file" URLs,
1641 then anyone who can get a commit into your git-annex repository
1642 could git-annex addurl a pointer to a private file located out‐
1643 side that repository, possibly causing it to be copied into your
1644 repository and transferred on to other remotes, exposing its
1645 content.
1646 Any url schemes supported by curl can be listed here, but you
1648 will also need to configure annex.allowed-ip-addresses to allow
1649 using curl.
1650 Some special remotes support their own domain-specific URL
1652 schemes; those are not affected by this configuration setting.
1653 annex.security.allowed-ip-addresses
1655 By default, git-annex only makes connections to public IP ad‐
1656 dresses; it will refuse to use HTTP and other servers on local‐
1657 host or on a private network.
1658 This setting can override that behavior, allowing access to par‐
1660 ticular IP addresses that would normally be blocked. For example
1661 "127.0.0.1 ::1" allows access to localhost (both IPV4 and IPV6).
1662 To allow access to all IP addresses, use "all"
1663 Think very carefully before changing this; there are security
1665 implications. Anyone who can get a commit into your git-annex
1666 repository could git annex addurl an url on a private server,
1667 possibly causing it to be downloaded into your repository and
1668 transferred to other remotes, exposing its content.
1669 Note that, since the interfaces of curl and yt-dlp do not allow
1671 these IP address restrictions to be enforced, curl and yt-dlp
1672 will never be used unless annex.security.allowed-ip-ad‐
1673 dresses=all.
1674 To allow accessing local or private IP addresses on only spe‐
1676 cific ports, use the syntax "[addr]:port". For example,
1677 "[127.0.0.1]:80 [127.0.0.1]:443 [::1]:80 [::1]:443" allows lo‐
1678 calhost on the http ports only.
1679 annex.security.allowed-http-addresses
1681 Old name for annex.security.allowed-ip-addresses. If set, this
1682 is treated the same as having annex.security.allowed-ip-ad‐
1683 dresses set.
1684 annex.security.allow-unverified-downloads
1686 For security reasons, git-annex refuses to download content from
1687 most special remotes when it cannot check a hash to verify that
1688 the correct content was downloaded. This particularly impacts
1689 downloading the content of URL or WORM keys, which lack hashes.
1690 The best way to avoid problems due to this is to migrate files
1692 away from such keys, before their content reaches a special re‐
1693 mote. See git-annex-migrate(1).
1694 When the content is only available from a special remote, you
1696 can use this configuration to force git-annex to download it.
1697 But you do so at your own risk, and it's very important you read
1698 and understand the information below first!
1699 Downloading unverified content from encrypted special remotes is
1701 prevented, because the special remote could send some other en‐
1702 crypted content than what you expect, causing git-annex to de‐
1703 crypt data that you never checked into git-annex, and risking
1704 exposing the decrypted data to any non-encrypted remotes you
1705 send content to.
1706 Downloading unverified content from (non-encrypted) external
1708 special remotes is prevented, because they could follow http
1709 redirects to web servers on localhost or on a private network,
1710 or in some cases to a file:/// url.
1711 If you decide to bypass this security check, the best thing to
1713 do is to only set it temporarily while running the command that
1714 gets the file. The value to set the config to is "ACKTHPPT".
1715 For example:
1716 git -c annex.security.allow-unverified-downloads=ACKTHPPT annex
1718 get myfile
1719 It would be a good idea to check that it downloaded the file you
1721 expected, too.
1722 remote.<name>.annex-security-allow-unverified-downloads
1724 Per-remote configuration of annex.security.allow-unveri‐
1725 fied-downloads.
1726
1728 annex.delayadd
1729 Makes the watch and assistant commands delay for the specified
1731 number of seconds before adding a newly created file to the an‐
1732 nex. Normally this is not needed, because they already wait for
1733 all writers of the file to close it.
1734 Note that this only delays adding files created while the daemon
1736 is running. Changes made when it is not running will be added
1737 immediately the next time it is started up.
1738 annex.expireunused
1740 Controls what the assistant does about unused file contents that
1741 are stored in the repository.
1742 The default is false, which causes all old and unused file con‐
1744 tents to be retained, unless the assistant is able to move them
1745 to some other repository (such as a backup repository).
1746 Can be set to a time specification, like "7d" or "1m", and then
1748 file contents that have been known to be unused for a week or a
1749 month will be deleted.
1750 annex.fscknudge
1752 When set to false, prevents the webapp from reminding you when
1753 using repositories that lack consistency checks.
1754 annex.autoupgrade
1756 When set to ask (the default), the webapp will check for new
1757 versions and prompt if they should be upgraded to. When set to
1758 true, automatically upgrades without prompting (on some sup‐
1759 ported platforms). When set to false, disables any upgrade
1760 checking.
1761 Note that upgrade checking is only done when git-annex is in‐
1763 stalled from one of the prebuilt images from its website. This
1764 does not bypass e.g., a Linux distribution's own upgrade han‐
1765 dling code.
1766 This setting also controls whether to restart the git-annex as‐
1768 sistant when the git-annex binary is detected to have changed.
1769 That is useful no matter how you installed git-annex.
1770 annex.autocommit
1772 Set to false to prevent the git-annex assistant, git-annex as‐
1773 sist, and git-annex sync from automatically committing changes
1774 to files in the repository.
1775 To configure the behavior in all clones of the repository, this
1777 can be set in git-annex-config(1).
1778 annex.startupscan
1780 Set to false to prevent the git-annex assistant from scanning
1781 the repository for new and changed files on startup. This will
1782 prevent it from noticing changes that were made while it was not
1783 running, but can be a useful performance tweak for a large
1784 repository.
1785 annex.listen
1787 Configures which address the webapp listens on. The default is
1788 localhost. Can be either an IP address, or a hostname that re‐
1789 solves to the desired address.
1790
1792 The key-value backend used when adding a new file to the annex can be
1793 configured on a per-file-type basis via .gitattributes files. In the
1794 file, the annex.backend attribute can be set to the name of the backend
1795 to use. (See git-annex-backends(1) for information about available
1796 backends.) For example, this here's how to use the WORM backend by de‐
1797 fault, but the SHA256E backend for ogg files:
1798 * annex.backend=WORM
1800 *.ogg annex.backend=SHA256E
1801 There is a annex.largefiles attribute, which is used to configure which
1803 files are large enough to be added to the annex. Since attributes can‐
1804 not contain spaces, it is difficult to use for more complex an‐
1805 nex.largefiles settings. Setting annex.largefiles in git-annex-con‐
1806 fig(1) is an easier way to configure it across all clones of the repos‐
1807 itory. See git-annex-matching-expression(1) for details on the syntax.
1808 The numcopies and mincopies settings can also be configured on a
1810 per-file-type basis via the annex.numcopies and annex.mincopies at‐
1811 tributes in .gitattributes files. This overrides other settings. For
1812 example, this makes two copies be needed for wav files and 3 copies for
1813 flac files:
1814 *.wav annex.numcopies=2
1816 *.flac annex.numcopies=3
1817 These settings are honored by git-annex whenever it's operating on a
1819 matching file. However, when using --all, --unused, or --key to specify
1820 keys to operate on, git-annex is operating on keys and not files, so
1821 will not honor the settings from .gitattributes. For this reason, the
1822 git annex numcopies and git annex mincopies commands are useful to con‐
1823 figure a global default.
1824 Also note that when using views, only the toplevel .gitattributes file
1826 is preserved in the view, so other settings in other files won't have
1827 any effect.
1828
1830 git-annex itself will exit 0 on success and 1 on failure, unless the
1831 --size-limit or --time-limit option is hit, in which case it exits 101.
1832 A few git-annex subcommands have other exit statuses used to indicate
1834 specific problems, which are documented on their individual man pages.
1835
1837 These environment variables are used by git-annex when set:
1838 GIT_WORK_TREE, GIT_DIR
1840 Handled the same as they are by git, see git(1)
1841 GIT_SSH, GIT_SSH_COMMAND
1843 Handled similarly to the same as described in git(1). The one
1844 difference is that git-annex will sometimes pass an additional
1845 "-n" parameter to these, as the first parameter, to prevent ssh
1846 from reading from stdin. Since that can break existing uses of
1847 these environment variables that don't expect the extra parame‐
1848 ter, you will need to set GIT_ANNEX_USE_GIT_SSH=1 to make git-
1849 annex support these.
1850 Note that setting either of these environment variables prevents
1852 git-annex from automatically enabling ssh connection caching
1853 (see annex.sshcaching), so it will slow down some operations
1854 with remotes over ssh. It's up to you to enable ssh connection
1855 caching if you need it; see ssh's documentation.
1856 Also, annex.ssh-options and remote.<name>.annex-ssh-options
1858 won't have any effect when these envionment variables are set.
1859 Usually it's better to configure any desired options through
1861 your ~/.ssh/config file, or by setting annex.ssh-options.
1862 GIT_ANNEX_VECTOR_CLOCK
1864 Normally git-annex timestamps lines in the log files committed
1865 to the git-annex branch. Setting this environment variable to a
1866 number will make git-annex use that (or a larger number) rather
1867 than the current number of seconds since the UNIX epoch. Note
1868 that decimal seconds are supported.
1869 This is only provided for advanced users who either have a bet‐
1871 ter way to tell which commit is current than the local clock, or
1872 who need to avoid embedding timestamps for policy reasons.
1873 Some special remotes use additional environment variables
1875 for authentication etc. For example, AWS_ACCESS_KEY_ID and
1876 GIT_ANNEX_P2P_AUTHTOKEN. See special remote documentation.
1877
1879 These files are used by git-annex:
1880 .git/annex/objects/ in your git repository contains the annexed file
1882 contents that are currently available. Annexed files in your git repos‐
1883 itory symlink to that content.
1884 .git/annex/ in your git repository contains other run-time information
1886 used by git-annex.
1887 ~/.config/git-annex/autostart is a list of git repositories to start
1889 the git-annex assistant in.
1890 .git/hooks/pre-commit-annex in your git repository will be run whenever
1892 a commit is made to the HEAD branch, either by git commit, git-annex
1893 sync, or the git-annex assistant.
1894 .git/hooks/post-update-annex in your git repository will be run when‐
1896 ever the git-annex branch is updated. You can make this hook run git
1897 update-server-info when publishing a git-annex repository by http.
1898
1900 More git-annex documentation is available on its web site,
1901 <https://git-annex.branchable.com/>
1902 If git-annex is installed from a package, a copy of its documentation
1904 should be included, in, for example, /usr/share/doc/git-annex/.
1905
1907 Joey Hess <id@joeyh.name>
1908 <https://git-annex.branchable.com/>
1910 git-annex(1)