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 Similar to git status --short, displays the status of the files
89 in the working tree.
90 See git-annex-status(1) for details.
92 unlock [path ...]
94 Unlock annexed files for modification.
95 See git-annex-unlock(1) for details.
97 edit [path ...]
99 This is an alias for the unlock command. May be easier to remem‐
100 ber, if you think of this as allowing you to edit an annexed
101 file.
102 lock [path ...]
104 Use this to undo an unlock command if you don't want to modify
105 the files, or have made modifications you want to discard.
106 See git-annex-lock(1) for details.
108 sync [remote ...]
110 Synchronize local repository with remotes.
111 See git-annex-sync(1) for details.
113 mirror [path ...] [--to=remote|--from=remote]
115 Mirror content of files to/from another repository.
116 See git-annex-mirror(1) for details.
118 addurl [url ...]
120 Downloads each url to its own file, which is added to the annex.
121 See git-annex-addurl(1) for details.
123 rmurl file url
125 Record that the file is no longer available at the url.
126 See git-annex-rmurl(1) for details.
128 import --from remote branch[:subdir] | [path ...]
130 Add a tree of files to the repository.
131 See git-annex-import(1) for details.
133 importfeed [url ...]
135 Imports the contents of podcast feeds into the annex.
136 See git-annex-importfeed(1) for details.
138 export treeish --to remote
140 Export content to a remote.
141 See git-annex-export(1) for details.
143 undo [filename|directory] ...
145 Undo last change to a file or directory.
146 See git-annex-undo(1) for details.
148 multicast
150 Multicast file distribution.
151 See git-annex-multicast(1) for details.
153 watch Watch for changes and autocommit.
155 See git-annex-watch(1) for details.
157 assistant
159 Automatically sync folders between devices.
160 See git-annex-assistant(1) for details.
162 webapp Opens a web app, that allows easy setup of a git-annex reposi‐
164 tory, and control of the git-annex assistant. If the assistant
165 is not already running, it will be started.
166 See git-annex-webapp(1) for details.
168 remotedaemon
170 Persistant communication with remotes.
171 See git-annex-remotedaemon(1) for details.
173
175 init [description]
176 Until a repository (or one of its remotes) has been initialized,
178 git-annex will refuse to operate on it, to avoid accidentally
179 using it in a repository that was not intended to have an annex.
180 See git-annex-init(1) for details.
182 describe repository description
184 Changes the description of a repository.
185 See git-annex-describe(1) for details.
187 initremote name type=value [param=value ...]
189 Creates a new special remote, and adds it to .git/config.
190 See git-annex-initremote(1) for details.
192 enableremote name [param=value ...]
194 Enables use of an existing special remote in the current reposi‐
195 tory.
196 See git-annex-enableremote(1) for details.
198 renameremote
200 Renames a special remote.
201 See git-annex-renameremote(1) for details.
203 enable-tor
205 Sets up tor hidden service.
206 See git-annex-enable-tor(1) for details.
208 numcopies [N]
210 Configure desired number of copies.
211 See git-annex-numcopies(1) for details.
213 mincopies [N]
215 Configure minimum number of copies.
216 See git-annex-mincopies(1) for details.
218 trust [repository ...]
220 Records that a repository is trusted to not unexpectedly lose
221 content. Use with care.
222 See git-annex-trust(1) for details.
224 untrust [repository ...]
226 Records that a repository is not trusted and could lose content
227 at any time.
228 See git-annex-untrust(1) for details.
230 semitrust [repository ...]
232 Returns a repository to the default semi trusted state.
233 See git-annex-semitrust(1) for details.
235 group repository groupname
237 Add a repository to a group.
238 See git-annex-group(1) for details.
240 ungroup repository groupname
242 Removes a repository from a group.
243 See git-annex-ungroup(1) for details.
245 wanted repository [expression]
247 Get or set preferred content expression.
248 See git-annex-wanted(1) for details.
250 groupwanted groupname [expression]
252 Get or set groupwanted expression.
253 See git-annex-groupwanted(1) for details.
255 required repository [expression]
257 Get or set required content expression.
258 See git-annex-required(1) for details.
260 schedule repository [expression]
262 Get or set scheduled jobs.
263 See git-annex-schedule(1) for details.
265 config Get and set other configuration stored in git-annex branch.
267 See git-annex-config(1) for details.
269 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 See git-annex-vicfg(1) for details.
275 adjust Switches a repository to use an adjusted branch, which can auto‐
277 matically unlock all files, etc.
278 See git-annex-adjust(1) for details.
280 direct Switches a repository to use direct mode. (deprecated)
282 See git-annex-direct(1) for details.
284 indirect
286 Switches a repository to use indirect mode. (deprecated)
287 See git-annex-indirect(1) for details.
289
291 fsck [path ...]
292 Checks the annex consistency, and warns about or fixes any prob‐
294 lems found. This is a good complement to git fsck.
295 See git-annex-fsck(1) for details.
297 expire [repository:]time ...
299 Expires repositories that have not recently performed an activ‐
300 ity (such as a fsck).
301 See git-annex-expire(1) for details.
303 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 See git-annex-unused(1) for details.
309 dropunused [number|range ...]
311 Drops the data corresponding to the numbers, as listed by the
312 last git annex unused
313 See git-annex-dropunused(1) for details.
315 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 See git-annex-addunused(1) for details.
321 fix [path ...]
323 Fixes up symlinks that have become broken to again point to an‐
324 nexed content.
325 See git-annex-fix(1) for details.
327 merge Automatically merge changes from remotes.
329 See git-annex-merge(1) for details.
331 upgrade
333 Upgrades the repository.
334 See git-annex-upgrade(1) for details.
336 dead [repository ...] [--key key]
338 Indicates that a repository or a single key has been irretriev‐
339 ably lost.
340 See git-annex-dead(1) for details.
342 forget Causes the git-annex branch to be rewritten, throwing away his‐
344 torical data about past locations of files.
345 See git-annex-forget(1) for details.
347 filter-branch
349 Produces a filtered version of the git-annex branch.
350 See git-annex-filter-branch(1) for details.
352 repair This can repair many of the problems with git repositories that
354 git fsck detects, but does not itself fix. It's useful if a
355 repository has become badly damaged. One way this can happen is
356 if a repository used by git-annex is on a removable drive that
357 gets unplugged at the wrong time.
358 See git-annex-repair(1) for details.
360 p2p Configure peer-2-Peer links between repositories.
362 See git-annex-p2p(1) for details.
364
366 find [path ...]
367 Outputs a list of annexed files in the specified path. With no
369 path, finds files in the current directory and its subdirecto‐
370 ries.
371 See git-annex-find(1) for details.
373 whereis [path ...]
375 Displays information about where the contents of files are lo‐
376 cated.
377 See git-annex-whereis(1) for details.
379 list [path ...]
381 Displays a table of remotes that contain the contents of the
382 specified files. This is similar to whereis but a more compact
383 display.
384 See git-annex-list(1) for details.
386 whereused
388 Finds what files use or used a key.
389 log [path ...]
391 Displays the location log for the specified file or files, show‐
392 ing each repository they were added to ("+") and removed from
393 ("-").
394 See git-annex-log(1) for details.
396 info [directory|file|remote|uuid ...]
398 Displays statistics and other information for the specified
399 item, which can be a directory, or a file, or a remote, or the
400 uuid of a repository.
401 When no item is specified, displays statistics and information
403 for the repository as a whole.
404 See git-annex-info(1) for details.
406 version
408 Shows the version of git-annex, as well as repository version
409 information.
410 See git-annex-version(1) for details.
412 map Generate map of repositories.
414 See git-annex-map(1) for details.
416 inprogress
418 Access files while they're being downloaded.
419 See git-annex-inprogress(1) for details.
421
423 metadata [path ...]
424 The content of an annexed file can have any number of metadata
426 fields attached to it to describe it. Each metadata field can in
427 turn have any number of values.
428 This command can be used to set metadata, or show the currently
430 set metadata.
431 See git-annex-metadata(1) for details.
433 view [tag ...] [field=value ...] [field=glob ...] [!tag ...]
435 [field!=value ...]
436 Uses metadata to build a view branch of the files in the current
437 branch, and checks out the view branch. Only files in the cur‐
438 rent branch whose metadata matches all the specified field val‐
439 ues and tags will be shown in the view.
440 See git-annex-view(1) for details.
442 vpop [N]
444 Switches from the currently active view back to the previous
445 view. Or, from the first view back to original branch.
446 See git-annex-vpop(1) for details.
448 vfilter [tag ...] [field=value ...] [!tag ...] [field!=value ...]
450 Filters the current view to only the files that have the speci‐
451 fied field values and tags.
452 See git-annex-vfilter(1) for details.
454 vadd [field=glob ...] [field=value ...] [tag ...]
456 Changes the current view, adding an additional level of directo‐
457 ries to categorize the files.
458 See git-annex-vfilter(1) for details.
460 vcycle When a view involves nested subdirectories, this cycles the or‐
462 der.
463 See git-annex-vcycle(1) for details.
465
467 migrate [path ...]
468 Changes the specified annexed files to use a different key-value
470 backend.
471 See git-annex-migrate(1) for details.
473 reinject src dest
475 Moves the src file into the annex as the content of the dest
476 file. This can be useful if you have obtained the content of a
477 file from elsewhere and want to put it in the local annex.
478 See git-annex-reinject(1) for details.
480 unannex [path ...]
482 Use this to undo an accidental git annex add command. It puts
483 the file back how it was before the add.
484 See git-annex-unannex(1) for details.
486 uninit De-initialize git-annex and clean out repository.
488 See git-annex-uninit(1) for details.
490 reinit uuid|description
492 Initialize repository, reusing old UUID.
493 See git-annex-reinit(1) for details.
495
497 pre-commit [path ...]
498 This is meant to be called from git's pre-commit hook. git annex
500 init automatically creates a pre-commit hook using this.
501 See git-annex-pre-commit(1) for details.
503 post-receive
505 This is meant to be called from git's post-receive hook. git an‐
506 nex init automatically creates a post-receive hook using this.
507 See git-annex-post-receive(1) for details.
509 lookupkey [file ...]
511 Looks up key used for file.
512 See git-annex-lookupkey(1) for details.
514 calckey [file ...]
516 Calculates the key that would be used to refer to a file.
517 See git-annex-calckey(1) for details.
519 contentlocation [key ..]
521 Looks up location of annexed content for a key.
522 See git-annex-contentlocation(1) for details.
524 examinekey [key ...]
526 Print information that can be determined purely by looking at
527 the key.
528 See git-annex-examinekey(1) for details.
530 matchexpression
532 Checks if a preferred content expression matches provided data.
533 See git-annex-matchexpression(1) for details.
535 fromkey [key file]
537 Manually set up a file in the git repository to link to a speci‐
538 fied key.
539 See git-annex-fromkey(1) for details.
541 registerurl [key url]
543 Registers an url for a key.
544 See git-annex-registerurl(1) for details.
546 unregisterurl [key url]
548 Unregisters an url for a key.
549 See git-annex-unregisterurl(1) for details.
551 setkey key file
553 Moves a file into the annex as the content of a key.
554 See git-annex-setkey(1) for details.
556 dropkey [key ...]
558 Drops annexed content for specified keys.
559 See git-annex-dropkey(1) for details.
561 transferkey key [--from=remote|--to=remote]
563 Transfers a key from or to a remote.
564 See git-annex-transferkey(1) for details.
566 transferrer
568 Used internally by git-annex to transfer content.
569 See git-annex-transferrer(1) for details.
571 transferkeys
573 Used internally by old versions of the assistant.
574 See git-annex-transferkey(1) for details.
576 setpresentkey key uuid [1|0]
578 This plumbing-level command changes git-annex's records about
579 whether the specified key's content is present in a remote with
580 the specified uuid.
581 See git-annex-setpresentkey(1) for details.
583 readpresentkey key uuid
585 Read records of where key is present.
586 See git-annex-readpresentkey(1) for details.
588 checkpresentkey key remote
590 Check if key is present in remote.
591 See git-annex-checkpresentkey(1) for details.
593 rekey [file key ...]
595 Change keys used for files.
596 See git-annex-rekey(1) for details.
598 resolvemerge
600 Resolves a conflicted merge, by adding both conflicting versions
601 of the file to the tree, using variants of their filename. This
602 is done automatically when using git annex sync or git annex
603 merge.
604 See git-annex-resolvemerge(1) for details.
606 diffdriver
608 This can be used to make git diff use an external diff driver
609 with annexed files.
610 See git-annex-diffdriver(1) for details.
612 smudge This command lets git-annex be used as a git filter driver, al‐
614 lowing annexed files in the git repository to be unlocked at all
615 times, instead of being symlinks.
616 See git-annex-smudge(1) for details.
618 filter-process
620 An alternative implementation of a git filter driver, that is
621 faster in some situations and slower in others than git-annex
622 smudge.
623 See git-annex-filter-process(1) for details.
625 findref [ref]
627 Lists files in a git ref. (deprecated)
628 See git-annex-findref(1) for details.
630 proxy -- git cmd [options]
632 Bypass direct mode guard. (deprecated)
633 See git-annex-proxy(1) for details.
635
637 test
638 This runs git-annex's built-in test suite.
640 See git-annex-test(1) for details.
642 testremote remote
644 This tests a remote by generating some random objects and send‐
645 ing them to the remote, then redownloading them, removing them
646 from the remote, etc.
647 It's safe to run in an existing repository (the repository con‐
649 tents are not altered), although it may perform expensive data
650 transfers.
651 See git-annex-testremote(1) for details.
653 fuzztest
655 Generates random changes to files in the current repository, for
656 use in testing the assistant.
657 See git-annex-fuzztest(1) for details.
659 benchmark
661 This runs git-annex's built-in benchmarks, if it was built with
662 benchmarking support.
663 See git-annex-benchmark(1) for details.
665
667 In addition to all the commands listed above, more commands can be
668 added to git-annex by dropping commands named like "git-annex-foo" into
669 a directory in the PATH.
670
672 Like other git commands, git-annex is configured via .git/config.
673 These settings, as well as relevant git config settings, are the ones
674 git-annex uses.
675 (Some of these settings can also be set, across all clones of the
677 repository, using git-annex-config. See its man page for a list.)
678 annex.uuid
680 A unique UUID for this repository (automatically set).
681 annex.backend
683 Name of the default key-value backend to use when adding new
684 files to the repository.
685 This is overridden by annex annex.backend configuration in the
687 .gitattributes files, and by the --backend option.
688 (This used to be named annex.backends, and that will still be
690 used if set.)
691 annex.securehashesonly
693 Set to true to indicate that the repository should only use
694 cryptographically secure hashes (SHA2, SHA3) and not insecure
695 hashes (MD5, SHA1) for content.
696 When this is set, the contents of files using cryptographically
698 insecure hashes will not be allowed to be added to the reposi‐
699 tory.
700 Also, git-annex fsck will complain about any files present in
702 the repository that use insecure hashes. And, git-annex import
703 --no-content will refuse to import files from special remotes
704 using insecure hashes.
705 To configure the behavior in new clones of the repository, this
707 can be set using git-annex-config.
708 annex.maxextensionlength
710 Maximum length, in bytes, of what is considered a filename ex‐
711 tension when adding a file to a backend that preserves filename
712 extensions. The default length is 4, which allows extensions
713 like "jpeg". The dot before the extension is not counted part of
714 its length. At most two extensions at the end of a filename will
715 be preserved, e.g. .gz or .tar.gz .
716 annex.diskreserve
718 Amount of disk space to reserve. Disk space is checked when
719 transferring content to avoid running out, and additional free
720 space can be reserved via this option, to make space for more
721 important content (such as git commit logs). Can be specified
722 with any commonly used units, for example, "0.5 gb", "500M", or
723 "100 KiloBytes"
724 The default reserve is 1 megabyte.
726 annex.skipunknown
728 Set to true to make commands like "git-annex get" silently skip
729 over items that are listed in the command line, but are not
730 checked into git.
731 Set to false to make it an error for commands like "git-annex
733 get" to be asked to operate on files that are not checked into
734 git.
735 The default is currently true, but is planned to change to false
737 in a release in 2022.
738 Note that, when annex.skipunknown is false, a command like "git-
740 annex get ." will fail if no files in the current directory are
741 checked into git, but a command like "git-annex get" will not
742 fail, because the current directory is not listed, but is im‐
743 plicit. Commands like "git-annex get foo/" will fail if no files
744 in the directory are checked into git, but if at least one file
745 is, it will ignore other files that are not. This is all the
746 same as the behavior of "git-ls files --error-unmatch".
747 Also note that git-annex skips files that are checked into git,
749 but are not annexed files, this setting does not affect that.
750 annex.largefiles
752 Used to configure which files are large enough to be added to
753 the annex. It is an expression that matches the large files, eg
754 "include=*.mp3 or largerthan=500kb" See git-annex-matching-ex‐
755 pression(1) for details on the syntax.
756 Overrides any annex.largefiles attributes in .gitattributes
758 files.
759 To configure a default annex.largefiles for all clones of the
761 repository, this can be set in git-annex-config(1).
762 This configures the behavior of both git-annex and git when
764 adding files to the repository. By default, git-annex add adds
765 all files to the annex (except dotfiles), and git add adds files
766 to git (unless they were added to the annex previously). When
767 annex.largefiles is configured, both git annex add and git add
768 will add matching large files to the annex, and the other files
769 to git.
770 Other git-annex commands also honor annex.largefiles, including
772 git annex import, git annex addurl, git annex importfeed and the
773 assistant.
774 annex.dotfiles
776 Normally, dotfiles are assumed to be files like .gitignore,
777 whose content should always be part of the git repository, so
778 they will not be added to the annex. Setting annex.dotfiles to
779 true makes dotfiles be added to the annex the same as any other
780 file.
781 To annex only some dotfiles, set this and configure annex.large‐
783 files to match the ones you want. For example, to match only
784 dotfiles ending in ".big"
785 git config annex.largefiles "(include=.*.big or in‐
787 clude=*/.*.big) or (exclude=.* and exclude=*/.*)"
788 git config annex.dotfiles true
789 To configure a default annex.dotfiles for all clones of the
791 repository, this can be set in git-annex-config(1).
792 annex.gitaddtoannex
794 Setting this to false will prevent git add from adding files to
795 the annex, despite the annex.largefiles configuration.
796 annex.addsmallfiles
798 Controls whether small files (not matching annex.largefiles)
799 should be checked into git by git annex add. Defaults to true;
800 set to false to instead make small files be skipped.
801 annex.addunlocked
803 Commands like git-annex add default to adding files to the
804 repository in locked form. This can make them add the files in
805 unlocked form, the same as if git-annex-unlock(1) were run on
806 the files.
807 This can be set to "true" to add everything unlocked, or it can
809 be a more complicated expression that matches files by name,
810 size, or content. See git-annex-matching-expression(1) for de‐
811 tails.
812 To configure a default annex.addunlocked for all clones of the
814 repository, this can be set in git-annex-config(1).
815 (Using git add always adds files in unlocked form and it is not
817 affected by this setting.)
818 When a repository has core.symlinks set to false, or has an ad‐
820 justed unlocked branch checked out, this setting is ignored, and
821 files are always added to the repository in unlocked form.
822 annex.numcopies
824 This is a deprecated setting. You should instead use the git an‐
825 nex numcopies command to configure how many copies of files are
826 kept across all repositories, or the annex.numcopies .gitat‐
827 tributes setting.
828 This config setting is only looked at when git annex numcopies
830 has never been configured, and when there's no annex.numcopies
831 setting in the .gitattributes file.
832 Note that setting numcopies to 0 is very unsafe.
834 annex.genmetadata
836 Set this to true to make git-annex automatically generate some
837 metadata when adding files to the repository.
838 In particular, it stores year, month, and day metadata, from the
840 file's modification date.
841 When importfeed is used, it stores additional metadata from the
843 feed, such as the author, title, etc.
844 annex.used-refspec
846 This controls which refs git-annex unused considers to be used.
847 See REFSPEC FORMAT in git-annex-unused(1) for details.
848 annex.jobs
850 Configure the number of concurrent jobs to run. Default is 1.
851 Only git-annex commands that support the --jobs option will use
853 this.
854 Setting this to "cpus" will run one job per CPU core.
856 When the --batch option is used, this configuration is ignored.
858 annex.adjustedbranchrefresh
860 When git-annex-adjust(1) is used to set up an adjusted branch
861 that needs to be refreshed after getting or dropping files, this
862 config controls how frequently the branch is refreshed.
863 Refreshing the branch takes some time, so doing it after every
865 file can be too slow. (It also can generate a lot of dangling
866 git objects.) The default value is 0 (or false), which does not
867 refresh the branch. Setting 1 (or true) will refresh only once,
868 after git-annex has made other changes. Setting 2 refreshes af‐
869 ter every file, 3 after every other file, and so on; setting 100
870 refreshes after every 99 files.
871 (If git-annex gets faster in the future, refresh rates will in‐
873 crease proportional to the speed improvements.)
874 annex.queuesize
876 git-annex builds a queue of git commands, in order to combine
877 similar commands for speed. By default the size of the queue is
878 limited to 10240 commands; this can be used to change the size.
879 If you have plenty of memory and are working with very large
880 numbers of files, increasing the queue size can speed it up.
881 annex.bloomcapacity
883 The git annex unused and git annex sync --content commands use a
884 bloom filter to determine what files are present in eg, the work
885 tree. The default bloom filter is sized to handle up to 500000
886 files. If your repository is larger than that, you should in‐
887 crease this value. Larger values will make git-annex unused and
888 git annex sync --content consume more memory; run git annex info
889 for memory usage numbers.
890 annex.bloomaccuracy
892 Adjusts the accuracy of the bloom filter used by git annex un‐
893 used and git annex sync --content. The default accuracy is
894 10000000 -- 1 unused file out of 10000000 will be missed by git
895 annex unused. Increasing the accuracy will make git annex unused
896 consume more memory; run git annex info for memory usage num‐
897 bers.
898 annex.sshcaching
900 By default, git-annex caches ssh connections using ssh's Con‐
901 trolMaster and ControlPersist settings (if built using a new
902 enough ssh). To disable this, set to false.
903 annex.adviceNoSshCaching
905 When git-annex is unable to use ssh connection caching, or has
906 been configured not to, and concurrency is enabled, it will warn
907 that this might result in multiple ssh processes prompting for
908 passwords at the same time. To disable that warning, eg if you
909 have configured ssh connection caching yourself, or have ssh
910 agent caching passwords, set this to false.
911 annex.alwayscommit
913 By default, git-annex automatically commits data to the git-an‐
914 nex branch after each command is run. If you have a series of
915 commands that you want to make a single commit, you can run the
916 commands with -c annex.alwayscommit=false. You can later commit
917 the data by running git annex merge (or by automatic merges) or
918 git annex sync.
919 annex.commitmessage
921 When git-annex updates the git-annex branch, it usually makes up
922 its own commit message (eg "update"), since users rarely look at
923 or care about changes to that branch. If you do care, you can
924 specify this setting by running commands with -c annex.com‐
925 mitmessage=whatever
926 This works well in combination with annex.alwayscommit=false, to
928 gather up a set of changes and commit them with a message you
929 specify.
930 annex.allowsign
932 By default git-annex avoids gpg signing commits that it makes
933 when they're not the purpose of a command, but only a side ef‐
934 fect. That default avoids lots of gpg password prompts when
935 commit.gpgSign is set. A command like git annex sync or git an‐
936 nex merge will gpg sign its commit, but a command like git annex
937 get, that updates the git-annex branch, will not. The assistant
938 also avoids signing commits.
939 Setting annex.allowsign to true lets all commits be signed, as
941 controlled by commit.gpgSign and other git configuration.
942 annex.merge-annex-branches
944 By default, git-annex branches that have been pulled from re‐
945 motes are automatically merged into the local git-annex branch,
946 so that git-annex has the most up-to-date possible knowledge.
947 To avoid that merging, set this to "false". This can be useful
949 particularly when you don't have write permission to the reposi‐
950 tory.
951 annex.private
953 When this is set to true, no information about the repository
954 will be recorded in the git-annex branch.
955 For example, to make a repository without any mention of it ever
957 appearing in the git-annex branch:
958 git init myprivate
960 cd myprivaterepo
961 git config annex.private true
962 git annex init
963 annex.hardlink
965 Set this to true to make file contents be hard linked between
966 the repository and its remotes when possible, instead of a more
967 expensive copy.
968 Use with caution -- This can invalidate numcopies counting,
970 since with hard links, fewer copies of a file can exist. So, it
971 is a good idea to mark a repository using this setting as un‐
972 trusted.
973 When a repository is set up using git clone --shared, git-annex
975 init will automatically set annex.hardlink and mark the reposi‐
976 tory as untrusted.
977 When annex.thin is also set, setting annex.hardlink has no ef‐
979 fect.
980 annex.thin
982 Set this to true to make unlocked files be a hard link to their
983 content in the annex, rather than a second copy. This can save
984 considerable disk space, but when a modification is made to a
985 file, you will lose the local (and possibly only) copy of the
986 old version. So, enable with care.
987 After setting (or unsetting) this, you should run git annex fix
989 to fix up the annexed files in the work tree to be hard links
990 (or copies).
991 Note that this has no effect when the filesystem does not sup‐
993 port hard links. And when multiple files in the work tree have
994 the same content, only one of them gets hard linked to the an‐
995 nex.
996 annex.supportunlocked
998 By default git-annex supports unlocked files as well as locked
999 files, so this defaults to true. If set to false, git-annex will
1000 only support locked files. That will avoid doing the work needed
1001 to support unlocked files.
1002 Note that setting this to false does not prevent a repository
1004 from having unlocked files added to it, and in that case the
1005 content of the files will not be accessible until they are
1006 locked.
1007 After changing this config, you need to re-run git-annex init
1009 for it to take effect.
1010 annex.resolvemerge
1012 Set to false to prevent merge conflicts in the checked out
1013 branch being automatically resolved by the git-annex assitant,
1014 git-annex sync, git-annex merge, and the git-annex post-receive
1015 hook.
1016 To configure the behavior in all clones of the repository, this
1018 can be set in git-annex-config(1).
1019 annex.synccontent
1021 Set to true to make git-annex sync default to syncing annexed
1022 content.
1023 To configure the behavior in all clones of the repository, this
1025 can be set in git-annex-config(1).
1026 annex.synconlyannex
1028 Set to true to make git-annex sync default to only sincing the
1029 git-annex branch and annexed content.
1030 To configure the behavior in all clones of the repository, this
1032 can be set in git-annex-config(1).
1033 annex.debug
1035 Set to true to enable debug logging by default.
1036 annex.debugfilter
1038 Set to configure which debug messages to display (when debug
1039 message display has been enabled by annex.debug or --debug). The
1040 value is one or more module names, separated by commas.
1041 annex.version
1043 The current version of the git-annex repository. This is main‐
1044 tained by git-annex and should never be manually changed.
1045 annex.autoupgraderepository
1047 When an old git-annex repository version has become deprecated,
1048 git-annex will normally automatically upgrade the repository to
1049 the new version.
1050 If this is set to false, git-annex won't automatically upgrade
1052 the repository. Instead it will exit with an error message. You
1053 can run git annex upgrade yourself when you are ready to upgrade
1054 the repository.
1055 annex.crippledfilesystem
1057 Set to true if the repository is on a crippled filesystem, such
1058 as FAT, which does not support symbolic links, or hard links, or
1059 unix permissions. This is automatically probed by "git annex
1060 init".
1061 annex.pidlock
1063 Normally, git-annex uses fine-grained lock files to allow multi‐
1064 ple processes to run concurrently without getting in each oth‐
1065 ers' way. That works great, unless you are using git-annex on a
1066 filesystem that does not support POSIX fcntl locks. This is
1067 sometimes the case when using NFS or Lustre filesystems.
1068 To support such situations, you can set annex.pidlock to true,
1070 and it will fall back to a single top-level pid file lock.
1071 Although, often, you'd really be better off fixing your net‐
1073 worked filesystem configuration to support POSIX locks.. And,
1074 some networked filesystems are so inconsistent that one node
1075 can't reliably tell when the other node is holding a pid lock.
1076 Caveat emptor.
1077 annex.pidlocktimeout
1079 git-annex will wait up to this many seconds for the pid lock
1080 file to go away, and will then abort if it cannot continue. De‐
1081 fault: 300
1082 When using pid lock files, it's possible for a stale lock file
1084 to get left behind by previous run of git-annex that crashed or
1085 was interrupted. This is mostly avoided, but can occur espe‐
1086 cially when using a network file system. This timeout prevents
1087 git-annex waiting forever in such a situation.
1088 annex.cachecreds
1090 When "true" (the default), git-annex will cache credentials used
1091 to access special remotes in files in .git/annex/creds/ that
1092 only you can read. To disable that caching, set to "false", and
1093 credentials will only be read from the environment, or if they
1094 have been embedded in encrypted form in the git repository, will
1095 be extracted and decrypted each time git-annex needs to access
1096 the remote.
1097 annex.secure-erase-command
1099 This can be set to a command that should be run whenever git-an‐
1100 nex removes the content of a file from the repository.
1101 In the command line, %file is replaced with the file that should
1103 be erased.
1104 For example, to use the wipe command, set it to wipe -f %file.
1106 annex.freezecontent-command, annex.thawcontent-command
1108 Usually the write permission bits are unset to protect annexed
1109 objects from being modified or deleted. The freezecontent-com‐
1110 mand is run after git-annex has removed the write bit. The thaw‐
1111 content-command should undo its effect, and is run before git-
1112 annex restores the write bit.
1113 In the command line, %path is replaced with the file or direc‐
1115 tory to operate on.
1116 annex.tune.objecthash1, annex.tune.objecthashlower, annex.tune.branch‐
1118 hash1
1119 These can be passed to git annex init to tune the repository.
1120 They cannot be safely changed in a running repository and should
1121 never be set in global git configuration. For details, see
1122 <https://git-annex.branchable.com/tuning/>.
1123
1125 Remotes are configured using these settings in .git/config.
1126 remote.<name>.annex-cost
1128 When determining which repository to transfer annexed files from
1129 or to, ones with lower costs are preferred. The default cost is
1130 100 for local repositories, and 200 for remote repositories.
1131 remote.<name>.annex-cost-command
1133 If set, the command is run, and the number it outputs is used as
1134 the cost. This allows varying the cost based on e.g., the cur‐
1135 rent network.
1136 remote.<name>.annex-start-command
1138 A command to run when git-annex begins to use the remote. This
1139 can be used to, for example, mount the directory containing the
1140 remote.
1141 The command may be run repeatedly when multiple git-annex pro‐
1143 cesses are running concurrently.
1144 remote.<name>.annex-stop-command
1146 A command to run when git-annex is done using the remote.
1147 The command will only be run once *all* running git-annex pro‐
1149 cesses are finished using the remote.
1150 remote.<name>.annex-shell
1152 Specify an alternative git-annex-shell executable on the remote
1153 instead of looking for "git-annex-shell" on the PATH.
1154 This is useful if the git-annex-shell program is outside the
1156 PATH or has a non-standard name.
1157 remote.<name>.annex-ignore
1159 If set to true, prevents git-annex from storing file contents on
1160 this remote by default. (You can still request it be used by
1161 the --from and --to options.)
1162 This is, for example, useful if the remote is located somewhere
1164 without git-annex-shell. (For example, if it's on GitHub). Or,
1165 it could be used if the network connection between two reposito‐
1166 ries is too slow to be used normally.
1167 This does not prevent git-annex sync (or the git-annex assist‐
1169 ant) from syncing the git repository to the remote.
1170 remote.<name>.annex-ignore-command
1172 If set, the command is run, and if it exits nonzero, that's the
1173 same as setting annex-ignore to true. This allows controlling
1174 behavior based on e.g., the current network.
1175 remote.<name>.annex-sync
1177 If set to false, prevents git-annex sync (and the git-annex as‐
1178 sistant) from syncing with this remote by default. However, git
1179 annex sync <name> can still be used to sync with the remote.
1180 remote.<name>.annex-sync-command
1182 If set, the command is run, and if it exits nonzero, that's the
1183 same as setting annex-sync to false. This allows controlling be‐
1184 havior based on e.g., the current network.
1185 remote.<name>.annex-pull
1187 If set to false, prevents git-annex sync (and the git-annex as‐
1188 sistant etc) from ever pulling (or fetching) from the remote.
1189 remote.<name>.annex-push
1191 If set to false, prevents git-annex sync (and the git-annex as‐
1192 sistant etc) from ever pushing to the remote.
1193 remote.<name>.annex-readonly
1195 If set to true, prevents git-annex from making changes to a re‐
1196 mote. This both prevents git-annex sync from pushing changes,
1197 and prevents storing or removing files from read-only remote.
1198 remote.<name>.annex-verify, annex.verify
1200 By default, git-annex will verify the checksums of objects down‐
1201 loaded from remotes. If you trust a remote and don't want the
1202 overhead of these checksums, you can set this to false.
1203 Note that even when this is set to false, git-annex does verifi‐
1205 cation in some edge cases, where it's likely the case than an
1206 object was downloaded incorrectly, or when needed for security.
1207 remote.<name>.annex-tracking-branch
1209 This is for use with special remotes that support exports and
1210 imports.
1211 When set to eg, "master", this tells git-annex that you want the
1213 special remote to track that branch.
1214 When set to eg, "master:subdir", the special remote tracks only
1216 the subdirectory of that branch.
1217 git-annex sync --content will import changes from the remote and
1219 merge them into the annex-tracking-branch. They also export
1220 changes made to the branch to the remote.
1221 remote.<name>.annex-export-tracking
1223 Deprecated name for remote.<name>.annex-tracking-branch. Will
1224 still be used if it's configured and remote.<name>.annex-track‐
1225 ing-branch is not.
1226 remote.<name>.annexUrl
1228 Can be used to specify a different url than the regular re‐
1229 mote.<name>.url for git-annex to use when talking with the re‐
1230 mote. Similar to the pushUrl used by git-push.
1231 remote.<name>.annex-uuid
1233 git-annex caches UUIDs of remote repositories here.
1234 remote.<name>.annex-config-uuid
1236 Used for some special remotes, points to a different special re‐
1237 mote configuration to use.
1238 remote.<name>.annex-retry, annex.retry
1240 Number of times a transfer that fails can be retried. (default
1241 0)
1242 remote.<name>.annex-forward-retry, annex.forward-retry
1244 If a transfer made some forward progress before failing, this
1245 allows it to be retried even when annex.retry does not. The
1246 value is the maximum number of times to do that. (default 5)
1247 When both annex.retry and this are set, the maximum number of
1249 retries is the larger of the two.
1250 remote.<name>.annex-retry-delay, annex.retry-delay
1252 Number of seconds to delay before the first retry of a transfer.
1253 When making multiple retries of the same transfer, the delay
1254 doubles after each retry. (default 1)
1255 remote.<name>.annex-bwlimit, annex.bwlimit
1257 This can be used to limit how much bandwidth is used for a
1258 transfer from or to a remote.
1259 For example, to limit transfers to 1 mebibyte per second: git
1261 config annex.bwlimit "1MiB"
1262 This will work with many remotes, including git remotes, but not
1264 for remotes where the transfer is run by a separate program than
1265 git-annex.
1266 remote.<name>.annex-stalldetecton, annex.stalldetection
1268 Configuring this lets stalled or too-slow transfers be detected,
1269 and dealt with, so rather than getting stuck, git-annex will
1270 cancel the stalled operation. The transfer will be considered to
1271 have failed, so settings like annex.retry will control what it
1272 does next.
1273 By default, git-annex detects transfers that have probably
1275 stalled, and suggests configuring this. If it is incorrectly de‐
1276 tecting stalls, setting this to "false" will avoid that.
1277 Set to "true" to enable automatic stall detection. If a remote
1279 does not update its progress consistently, no automatic stall
1280 detection will be done. And it may take a while for git-annex to
1281 decide a remote is really stalled when using automatic stall de‐
1282 tection, since it needs to be conservative about what looks like
1283 a stall.
1284 For more fine control over what constitutes a stall, set to a
1286 value in the form "$amount/$timeperiod" to specify how much data
1287 git-annex should expect to see flowing, minimum, over a given
1288 period of time.
1289 For example, to detect outright stalls where no data has been
1291 transferred after 30 seconds: git config annex.stalldetection
1292 "1KB/30s"
1293 Or, if you have a remote on a USB drive that is normally capable
1295 of several megabytes per second, but has bad sectors where it
1296 gets stuck for a long time, you could use: git config remote.us‐
1297 bdrive.annex-stalldetection "1MB/1m"
1298 This is not enabled by default, because it can make git-annex
1300 use more resources. To be able to cancel stalls, git-annex has
1301 to run transfers in separate processes (one per concurrent job).
1302 So it may need to open more connections to a remote than usual,
1303 or the communication with those processes may make it a bit
1304 slower.
1305 remote.<name>.annex-checkuuid
1307 This only affects remotes that have their url pointing to a di‐
1308 rectory on the same system. git-annex normally checks the uuid
1309 of such remotes each time it's run, which lets it transparently
1310 deal with different drives being mounted to the location at dif‐
1311 ferent times.
1312 Setting annex-checkuuid to false will prevent it from checking
1314 the uuid at startup (although the uuid is still verified before
1315 making any changes to the remote repository). This may be useful
1316 to set to prevent unncessary spin-up or automounting of a drive.
1317 remote.<name>.annex-trustlevel
1319 Configures a local trust level for the remote. This overrides
1320 the value configured by the trust and untrust commands. The
1321 value can be any of "trusted", "semitrusted" or "untrusted".
1322 remote.<name>.annex-availability
1324 Can be used to tell git-annex whether a remote is LocallyAvail‐
1325 able or GloballyAvailable. Normally, git-annex determines this
1326 automatically.
1327 remote.<name>.annex-speculate-present
1329 Set to "true" to make git-annex speculate that this remote may
1330 contain the content of any file, even though its normal location
1331 tracking does not indicate that it does. This will cause git-an‐
1332 nex to try to get all file contents from the remote. Can be use‐
1333 ful in setting up a caching remote.
1334 remote.<name>.annex-private
1336 When this is set to true, no information about the remote will
1337 be recorded in the git-annex branch. This is mostly useful for
1338 special remotes, and is set when using git-annex-initremote(1)
1339 with the --private option.
1340 remote.<name>.annex-bare
1342 Can be used to tell git-annex if a remote is a bare repository
1343 or not. Normally, git-annex determines this automatically.
1344 remote.<name>.annex-ssh-options
1346 Options to use when using ssh to talk to this remote.
1347 remote.<name>.annex-rsync-options
1349 Options to use when using rsync to or from this remote. For ex‐
1350 ample, to force IPv6, and limit the bandwidth to 100Kbyte/s, set
1351 it to -6 --bwlimit 100
1352 Note that git-annex-shell has a whitelist of allowed rsync op‐
1354 tions, and others will not be be passed to the remote rsync. So
1355 using some options may break the communication between the local
1356 and remote rsyncs.
1357 remote.<name>.annex-rsync-upload-options
1359 Options to use when using rsync to upload a file to a remote.
1360 These options are passed after other applicable rsync options,
1362 so can be used to override them. For example, to limit upload
1363 bandwidth to 10Kbyte/s, set --bwlimit 10.
1364 remote.<name>.annex-rsync-download-options
1366 Options to use when using rsync to download a file from a re‐
1367 mote.
1368 These options are passed after other applicable rsync options,
1370 so can be used to override them.
1371 remote.<name>.annex-rsync-transport
1373 The remote shell to use to connect to the rsync remote. Possible
1374 values are ssh (the default) and rsh, together with their argu‐
1375 ments, for instance ssh -p 2222 -c blowfish; Note that the re‐
1376 mote hostname should not appear there, see rsync(1) for details.
1377 When the transport used is ssh, connections are automatically
1378 cached unless annex.sshcaching is unset.
1379 remote.<name>.annex-bup-split-options
1381 Options to pass to bup split when storing content in this re‐
1382 mote. For example, to limit the bandwidth to 100Kbyte/s, set it
1383 to --bwlimit 100k (There is no corresponding option for bup
1384 join.)
1385 remote.<name>.annex-gnupg-options
1387 Options to pass to GnuPG when it's encrypting data. For in‐
1388 stance, to use the AES cipher with a 256 bits key and disable
1389 compression, set it to --cipher-algo AES256 --compress-algo
1390 none. (These options take precedence over the default GnuPG con‐
1391 figuration, which is otherwise used.)
1392 remote.<name>.annex-gnupg-decrypt-options
1394 Options to pass to GnuPG when it's decrypting data. (These op‐
1395 tions take precedence over the default GnuPG configuration,
1396 which is otherwise used.)
1397 annex.ssh-options, annex.rsync-options,
1399 annex.rsync-upload-options, annex.rsync-download-options, an‐
1400 nex.bup-split-options, annex.gnupg-options, annex.gnupg-de‐
1401 crypt-options
1402 Default options to use if a remote does not have more specific
1404 options as described above.
1405 remote.<name>.annex-rsyncurl
1407 Used by rsync special remotes, this configures the location of
1408 the rsync repository to use. Normally this is automatically set
1409 up by git annex initremote, but you can change it if needed.
1410 remote.<name>.annex-buprepo
1412 Used by bup special remotes, this configures the location of the
1413 bup repository to use. Normally this is automatically set up by
1414 git annex initremote, but you can change it if needed.
1415 remote.<name>.annex-borgrepo
1417 Used by borg special remotes, this configures the location of
1418 the borg repository to use. Normally this is automatically set
1419 up by git annex initremote, but you can change it if needed.
1420 remote.<name>.annex-ddarrepo
1422 Used by ddar special remotes, this configures the location of
1423 the ddar repository to use. Normally this is automatically set
1424 up by git annex initremote, but you can change it if needed.
1425 remote.<name>.annex-directory
1427 Used by directory special remotes, this configures the location
1428 of the directory where annexed files are stored for this remote.
1429 Normally this is automatically set up by git annex initremote,
1430 but you can change it if needed.
1431 remote.<name>.annex-adb
1433 Used to identify remotes on Android devices accessed via adb.
1434 Normally this is automatically set up by git annex initremote.
1435 remote.<name>.annex-androiddirectory
1437 Used by adb special remotes, this is the directory on the An‐
1438 droid device where files are stored for this remote. Normally
1439 this is automatically set up by git annex initremote, but you
1440 can change it if needed.
1441 remote.<name>.annex-androidserial
1443 Used by adb special remotes, this is the serial number of the
1444 Android device used by the remote. Normally this is automati‐
1445 cally set up by git annex initremote, but you can change it if
1446 needed, eg when upgrading to a new Android device.
1447 remote.<name>.annex-s3
1449 Used to identify Amazon S3 special remotes. Normally this is
1450 automatically set up by git annex initremote.
1451 remote.<name>.annex-glacier
1453 Used to identify Amazon Glacier special remotes. Normally this
1454 is automatically set up by git annex initremote.
1455 remote.<name>.annex-webdav
1457 Used to identify webdav special remotes. Normally this is auto‐
1458 matically set up by git annex initremote.
1459 remote.<name>.annex-tahoe
1461 Used to identify tahoe special remotes. Points to the configu‐
1462 ration directory for tahoe.
1463 remote.<name>.annex-gcrypt
1465 Used to identify gcrypt special remotes. Normally this is auto‐
1466 matically set up by git annex initremote.
1467 It is set to "true" if this is a gcrypt remote. If the gcrypt
1469 remote is accessible over ssh and has git-annex-shell available
1470 to manage it, it's set to "shell".
1471 remote.<name>.annex-git-lfs
1473 Used to identify git-lfs special remotes. Normally this is au‐
1474 tomatically set up by git annex initremote.
1475 It is set to "true" if this is a git-lfs remote.
1477 remote.<name>.annex-httpalso
1479 Used to identify httpalso special remotes. Normally this is au‐
1480 tomatically set up by git annex initremote.
1481 remote.<name>.annex-externaltype
1483 Used external special remotes to record the type of the remote.
1484 Eg, if this is set to "foo", git-annex will run a "git-annex-re‐
1486 mote-foo" program to communicate with the external special re‐
1487 mote.
1488 If this is set to "readonly", then git-annex will not run any
1490 external special remote program, but will try to access things
1491 stored in the remote using http. That only works for some exter‐
1492 nal special remotes, so consult the documentation of the one you
1493 are using.
1494 remote.<name>.annex-hooktype
1496 Used by hook special remotes to record the type of the remote.
1497 annex.web-options
1499 Options to pass to curl when git-annex uses it to download urls
1500 (rather than the default built-in url downloader).
1501 For example, to force IPv4 only, set it to "-4". Or to make
1503 curl use your ~/.netrc file, set it to "--netrc".
1504 Setting this option makes git-annex use curl, but only when an‐
1506 nex.security.allowed-ip-addresses is configured in a specific
1507 way. See its documentation.
1508 annex.youtube-dl-options
1510 Options to pass to youtube-dl when using it to find the url to
1511 download for a video.
1512 Some options may break git-annex's integration with youtube-dl.
1514 For example, the --output option could cause it to store files
1515 somewhere git-annex won't find them. Avoid setting here or in
1516 the youtube-dl config file any options that cause youtube-dl to
1517 download more than one file, or to store the file anywhere other
1518 than the current working directory.
1519 annex.youtube-dl-command
1521 Command to run for youtube-dl. Default is "youtube-dl".
1522 annex.aria-torrent-options
1524 Options to pass to aria2c when using it to download a torrent.
1525 annex.http-headers
1527 HTTP headers to send when downloading from the web. Multiple
1528 lines of this option can be set, one per header.
1529 annex.http-headers-command
1531 If set, the command is run and each line of its output is used
1532 as a HTTP header. This overrides annex.http-headers.
1533 annex.security.allowed-url-schemes
1535 List of URL schemes that git-annex is allowed to download con‐
1536 tent from. The default is "http https ftp".
1537 Think very carefully before changing this; there are security
1539 implications. For example, if it's changed to allow "file" URLs,
1540 then anyone who can get a commit into your git-annex repository
1541 could git-annex addurl a pointer to a private file located out‐
1542 side that repository, possibly causing it to be copied into your
1543 repository and transferred on to other remotes, exposing its
1544 content.
1545 Some special remotes support their own domain-specific URL
1547 schemes; those are not affected by this configuration setting.
1548 annex.security.allowed-ip-addresses
1550 By default, git-annex only makes connections to public IP ad‐
1551 dresses; it will refuse to use HTTP and other servers on local‐
1552 host or on a private network.
1553 This setting can override that behavior, allowing access to par‐
1555 ticular IP addresses that would normally be blocked. For example
1556 "127.0.0.1 ::1" allows access to localhost (both IPV4 and IPV6).
1557 To allow access to all IP addresses, use "all"
1558 Think very carefully before changing this; there are security
1560 implications. Anyone who can get a commit into your git-annex
1561 repository could git annex addurl an url on a private server,
1562 possibly causing it to be downloaded into your repository and
1563 transferred to other remotes, exposing its content.
1564 Note that, since the interfaces of curl and youtube-dl do not
1566 allow these IP address restrictions to be enforced, curl and
1567 youtube-dl will never be used unless annex.security.al‐
1568 lowed-ip-addresses=all.
1569 To allow accessing local or private IP addresses on only spe‐
1571 cific ports, use the syntax "[addr]:port". For example,
1572 "[127.0.0.1]:80 [127.0.0.1]:443 [::1]:80 [::1]:443" allows lo‐
1573 calhost on the http ports only.
1574 annex.security.allowed-http-addresses
1576 Old name for annex.security.allowed-ip-addresses. If set, this
1577 is treated the same as having annex.security.allowed-ip-ad‐
1578 dresses set.
1579 annex.security.allow-unverified-downloads
1581 For security reasons, git-annex refuses to download content from
1582 most special remotes when it cannot check a hash to verify that
1583 the correct content was downloaded. This particularly impacts
1584 downloading the content of URL or WORM keys, which lack hashes.
1585 The best way to avoid problems due to this is to migrate files
1587 away from such keys, before their content reaches a special re‐
1588 mote. See git-annex-migrate(1).
1589 When the content is only available from a special remote, you
1591 can use this configuration to force git-annex to download it.
1592 But you do so at your own risk, and it's very important you read
1593 and understand the information below first!
1594 Downloading unverified content from encrypted special remotes is
1596 prevented, because the special remote could send some other en‐
1597 crypted content than what you expect, causing git-annex to de‐
1598 crypt data that you never checked into git-annex, and risking
1599 exposing the decrypted data to any non-encrypted remotes you
1600 send content to.
1601 Downloading unverified content from (non-encrypted) external
1603 special remotes is prevented, because they could follow http
1604 redirects to web servers on localhost or on a private network,
1605 or in some cases to a file:/// url.
1606 If you decide to bypass this security check, the best thing to
1608 do is to only set it temporarily while running the command that
1609 gets the file. The value to set the config to is "ACKTHPPT".
1610 For example:
1611 git -c annex.security.allow-unverified-downloads=ACKTHPPT annex
1613 get myfile
1614 It would be a good idea to check that it downloaded the file you
1616 expected, too.
1617 remote.<name>.annex-security-allow-unverified-downloads
1619 Per-remote configuration of annex.security.allow-unveri‐
1620 fied-downloads.
1621
1623 annex.delayadd
1624 Makes the watch and assistant commands delay for the specified
1626 number of seconds before adding a newly created file to the an‐
1627 nex. Normally this is not needed, because they already wait for
1628 all writers of the file to close it.
1629 Note that this only delays adding files created while the daemon
1631 is running. Changes made when it is not running will be added
1632 immediately the next time it is started up.
1633 annex.expireunused
1635 Controls what the assistant does about unused file contents that
1636 are stored in the repository.
1637 The default is false, which causes all old and unused file con‐
1639 tents to be retained, unless the assistant is able to move them
1640 to some other repository (such as a backup repository).
1641 Can be set to a time specification, like "7d" or "1m", and then
1643 file contents that have been known to be unused for a week or a
1644 month will be deleted.
1645 annex.fscknudge
1647 When set to false, prevents the webapp from reminding you when
1648 using repositories that lack consistency checks.
1649 annex.autoupgrade
1651 When set to ask (the default), the webapp will check for new
1652 versions and prompt if they should be upgraded to. When set to
1653 true, automatically upgrades without prompting (on some sup‐
1654 ported platforms). When set to false, disables any upgrade
1655 checking.
1656 Note that upgrade checking is only done when git-annex is in‐
1658 stalled from one of the prebuilt images from its website. This
1659 does not bypass e.g., a Linux distribution's own upgrade han‐
1660 dling code.
1661 This setting also controls whether to restart the git-annex as‐
1663 sistant when the git-annex binary is detected to have changed.
1664 That is useful no matter how you installed git-annex.
1665 annex.autocommit
1667 Set to false to prevent the git-annex assistant and git-annex
1668 sync from automatically committing changes to files in the
1669 repository.
1670 To configure the behavior in all clones of the repository, this
1672 can be set in git-annex-config(1).
1673 annex.startupscan
1675 Set to false to prevent the git-annex assistant from scanning
1676 the repository for new and changed files on startup. This will
1677 prevent it from noticing changes that were made while it was not
1678 running, but can be a useful performance tweak for a large
1679 repository.
1680 annex.listen
1682 Configures which address the webapp listens on. The default is
1683 localhost. Can be either an IP address, or a hostname that re‐
1684 solves to the desired address.
1685
1687 The key-value backend used when adding a new file to the annex can be
1688 configured on a per-file-type basis via .gitattributes files. In the
1689 file, the annex.backend attribute can be set to the name of the backend
1690 to use. For example, this here's how to use the WORM backend by de‐
1691 fault, but the SHA256E backend for ogg files:
1692 * annex.backend=WORM
1694 *.ogg annex.backend=SHA256E
1695 There is a annex.largefiles attribute, which is used to configure which
1697 files are large enough to be added to the annex. Since attributes can‐
1698 not contain spaces, it is difficult to use for more complex an‐
1699 nex.largefiles settings. Setting annex.largefiles in git-annex-con‐
1700 fig(1) is an easier way to configure it across all clones of the repos‐
1701 itory. See git-annex-matching-expression(1) for details on the syntax.
1702 The numcopies and mincopies settings can also be configured on a
1704 per-file-type basis via the annex.numcopies and annex.mincopies at‐
1705 tributes in .gitattributes files. This overrides other settings. For
1706 example, this makes two copies be needed for wav files and 3 copies for
1707 flac files:
1708 *.wav annex.numcopies=2
1710 *.flac annex.numcopies=3
1711 Note that setting numcopies or mincopies to 0 is very unsafe.
1713 These settings are honored by git-annex whenever it's operating on a
1715 matching file. However, when using --all, --unused, or --key to specify
1716 keys to operate on, git-annex is operating on keys and not files, so
1717 will not honor the settings from .gitattributes. For this reason, the
1718 git annex numcopies and git annex mincopies commands are useful to con‐
1719 figure a global default.
1720 Also note that when using views, only the toplevel .gitattributes file
1722 is preserved in the view, so other settings in other files won't have
1723 any effect.
1724
1726 git-annex, when called as a git subcommand, may return exit codes 0 or
1727 1 for success or failures, or, more rarely, 127 or 128 for certain very
1728 specific failures. git-annex itself should return 0 on success and 1
1729 on failure, unless the --time-limit=time option is hit, in which case
1730 it returns with exit code 101.
1731
1733 These environment variables are used by git-annex when set:
1734 GIT_WORK_TREE, GIT_DIR
1736 Handled the same as they are by git, see git(1)
1737 GIT_SSH, GIT_SSH_COMMAND
1739 Handled similarly to the same as described in git(1). The one
1740 difference is that git-annex will sometimes pass an additional
1741 "-n" parameter to these, as the first parameter, to prevent ssh
1742 from reading from stdin. Since that can break existing uses of
1743 these environment variables that don't expect the extra parame‐
1744 ter, you will need to set GIT_ANNEX_USE_GIT_SSH=1 to make git-
1745 annex support these.
1746 Note that setting either of these environment variables prevents
1748 git-annex from automatically enabling ssh connection caching
1749 (see annex.sshcaching), so it will slow down some operations
1750 with remotes over ssh. It's up to you to enable ssh connection
1751 caching if you need it; see ssh's documentation.
1752 Also, annex.ssh-options and remote.<name>.annex-ssh-options
1754 won't have any effect when these envionment variables are set.
1755 Usually it's better to configure any desired options through
1757 your ~/.ssh/config file, or by setting annex.ssh-options.
1758 GIT_ANNEX_VECTOR_CLOCK
1760 Normally git-annex timestamps lines in the log files committed
1761 to the git-annex branch. Setting this environment variable to a
1762 number will make git-annex use that (or a larger number) rather
1763 than the current number of seconds since the UNIX epoch. Note
1764 that decimal seconds are supported.
1765 This is only provided for advanced users who either have a bet‐
1767 ter way to tell which commit is current than the local clock, or
1768 who need to avoid embedding timestamps for policy reasons.
1769 Some special remotes use additional environment variables
1771 for authentication etc. For example, AWS_ACCESS_KEY_ID and
1772 GIT_ANNEX_P2P_AUTHTOKEN. See special remote documentation.
1773
1775 These files are used by git-annex:
1776 .git/annex/objects/ in your git repository contains the annexed file
1778 contents that are currently available. Annexed files in your git repos‐
1779 itory symlink to that content.
1780 .git/annex/ in your git repository contains other run-time information
1782 used by git-annex.
1783 ~/.config/git-annex/autostart is a list of git repositories to start
1785 the git-annex assistant in.
1786 .git/hooks/pre-commit-annex in your git repository will be run whenever
1788 a commit is made to the HEAD branch, either by git commit, git-annex
1789 sync, or the git-annex assistant.
1790 .git/hooks/post-update-annex in your git repository will be run when‐
1792 ever the git-annex branch is updated. You can make this hook run git
1793 update-server-info when publishing a git-annex repository by http.
1794
1796 More git-annex documentation is available on its web site,
1797 <https://git-annex.branchable.com/>
1798 If git-annex is installed from a package, a copy of its documentation
1800 should be included, in, for example, /usr/share/doc/git-annex/.
1801
1803 Joey Hess <id@joeyh.name>
1804 <https://git-annex.branchable.com/>
1806 git-annex(1)