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 findref [ref]
620 Lists files in a git ref. (deprecated)
621 See git-annex-findref(1) for details.
623 proxy -- git cmd [options]
625 Bypass direct mode guard. (deprecated)
626 See git-annex-proxy(1) for details.
628
630 test
631 This runs git-annex's built-in test suite.
633 See git-annex-test(1) for details.
635 testremote remote
637 This tests a remote by generating some random objects and send‐
638 ing them to the remote, then redownloading them, removing them
639 from the remote, etc.
640 It's safe to run in an existing repository (the repository con‐
642 tents are not altered), although it may perform expensive data
643 transfers.
644 See git-annex-testremote(1) for details.
646 fuzztest
648 Generates random changes to files in the current repository, for
649 use in testing the assistant.
650 See git-annex-fuzztest(1) for details.
652 benchmark
654 This runs git-annex's built-in benchmarks, if it was built with
655 benchmarking support.
656 See git-annex-benchmark(1) for details.
658
660 In addition to all the commands listed above, more commands can be
661 added to git-annex by dropping commands named like "git-annex-foo" into
662 a directory in the PATH.
663
665 Like other git commands, git-annex is configured via .git/config.
666 These settings, as well as relevant git config settings, are the ones
667 git-annex uses.
668 (Some of these settings can also be set, across all clones of the
670 repository, using git-annex-config. See its man page for a list.)
671 annex.uuid
673 A unique UUID for this repository (automatically set).
674 annex.backend
676 Name of the default key-value backend to use when adding new
677 files to the repository.
678 This is overridden by annex annex.backend configuration in the
680 .gitattributes files, and by the --backend option.
681 (This used to be named annex.backends, and that will still be
683 used if set.)
684 annex.securehashesonly
686 Set to true to indicate that the repository should only use
687 cryptographically secure hashes (SHA2, SHA3) and not insecure
688 hashes (MD5, SHA1) for content.
689 When this is set, the contents of files using cryptographically
691 insecure hashes will not be allowed to be added to the reposi‐
692 tory.
693 Also, git-annex fsck will complain about any files present in
695 the repository that use insecure hashes. And, git-annex import
696 --no-content will refuse to import files from special remotes
697 using insecure hashes.
698 To configure the behavior in new clones of the repository, this
700 can be set using git-annex-config.
701 annex.maxextensionlength
703 Maximum length, in bytes, of what is considered a filename ex‐
704 tension when adding a file to a backend that preserves filename
705 extensions. The default length is 4, which allows extensions
706 like "jpeg". The dot before the extension is not counted part of
707 its length. At most two extensions at the end of a filename will
708 be preserved, e.g. .gz or .tar.gz .
709 annex.diskreserve
711 Amount of disk space to reserve. Disk space is checked when
712 transferring content to avoid running out, and additional free
713 space can be reserved via this option, to make space for more
714 important content (such as git commit logs). Can be specified
715 with any commonly used units, for example, "0.5 gb", "500M", or
716 "100 KiloBytes"
717 The default reserve is 1 megabyte.
719 annex.skipunknown
721 Set to true to make commands like "git-annex get" silently skip
722 over items that are listed in the command line, but are not
723 checked into git.
724 Set to false to make it an error for commands like "git-annex
726 get" to be asked to operate on files that are not checked into
727 git.
728 The default is currently true, but is planned to change to false
730 in a release in 2022.
731 Note that, when annex.skipunknown is false, a command like "git-
733 annex get ." will fail if no files in the current directory are
734 checked into git, but a command like "git-annex get" will not
735 fail, because the current directory is not listed, but is im‐
736 plicit. Commands like "git-annex get foo/" will fail if no files
737 in the directory are checked into git, but if at least one file
738 is, it will ignore other files that are not. This is all the
739 same as the behavior of "git-ls files --error-unmatch".
740 Also note that git-annex skips files that are checked into git,
742 but are not annexed files, this setting does not affect that.
743 annex.largefiles
745 Used to configure which files are large enough to be added to
746 the annex. It is an expression that matches the large files, eg
747 "include=*.mp3 or largerthan=500kb" See git-annex-matching-ex‐
748 pression(1) for details on the syntax.
749 Overrides any annex.largefiles attributes in .gitattributes
751 files.
752 To configure a default annex.largefiles for all clones of the
754 repository, this can be set in git-annex-config(1).
755 This configures the behavior of both git-annex and git when
757 adding files to the repository. By default, git-annex add adds
758 all files to the annex (except dotfiles), and git add adds files
759 to git (unless they were added to the annex previously). When
760 annex.largefiles is configured, both git annex add and git add
761 will add matching large files to the annex, and the other files
762 to git.
763 Other git-annex commands also honor annex.largefiles, including
765 git annex import, git annex addurl, git annex importfeed and the
766 assistant.
767 annex.dotfiles
769 Normally, dotfiles are assumed to be files like .gitignore,
770 whose content should always be part of the git repository, so
771 they will not be added to the annex. Setting annex.dotfiles to
772 true makes dotfiles be added to the annex the same as any other
773 file.
774 To annex only some dotfiles, set this and configure annex.large‐
776 files to match the ones you want. For example, to match only
777 dotfiles ending in ".big"
778 git config annex.largefiles "(include=.*.big or in‐
780 clude=*/.*.big) or (exclude=.* and exclude=*/.*)"
781 git config annex.dotfiles true
782 To configure a default annex.dotfiles for all clones of the
784 repository, this can be set in git-annex-config(1).
785 annex.gitaddtoannex
787 Setting this to false will prevent git add from adding files to
788 the annex, despite the annex.largefiles configuration.
789 annex.addsmallfiles
791 Controls whether small files (not matching annex.largefiles)
792 should be checked into git by git annex add. Defaults to true;
793 set to false to instead make small files be skipped.
794 annex.addunlocked
796 Commands like git-annex add default to adding files to the
797 repository in locked form. This can make them add the files in
798 unlocked form, the same as if git-annex-unlock(1) were run on
799 the files.
800 This can be set to "true" to add everything unlocked, or it can
802 be a more complicated expression that matches files by name,
803 size, or content. See git-annex-matching-expression(1) for de‐
804 tails.
805 To configure a default annex.addunlocked for all clones of the
807 repository, this can be set in git-annex-config(1).
808 (Using git add always adds files in unlocked form and it is not
810 affected by this setting.)
811 When a repository has core.symlinks set to false, or has an ad‐
813 justed unlocked branch checked out, this setting is ignored, and
814 files are always added to the repository in unlocked form.
815 annex.numcopies
817 This is a deprecated setting. You should instead use the git an‐
818 nex numcopies command to configure how many copies of files are
819 kept across all repositories, or the annex.numcopies .gitat‐
820 tributes setting.
821 This config setting is only looked at when git annex numcopies
823 has never been configured, and when there's no annex.numcopies
824 setting in the .gitattributes file.
825 Note that setting numcopies to 0 is very unsafe.
827 annex.genmetadata
829 Set this to true to make git-annex automatically generate some
830 metadata when adding files to the repository.
831 In particular, it stores year, month, and day metadata, from the
833 file's modification date.
834 When importfeed is used, it stores additional metadata from the
836 feed, such as the author, title, etc.
837 annex.used-refspec
839 This controls which refs git-annex unused considers to be used.
840 See REFSPEC FORMAT in git-annex-unused(1) for details.
841 annex.jobs
843 Configure the number of concurrent jobs to run. Default is 1.
844 Only git-annex commands that support the --jobs option will use
846 this.
847 Setting this to "cpus" will run one job per CPU core.
849 When the --batch option is used, this configuration is ignored.
851 annex.adjustedbranchrefresh
853 When git-annex-adjust(1) is used to set up an adjusted branch
854 that needs to be refreshed after getting or dropping files, this
855 config controls how frequently the branch is refreshed.
856 Refreshing the branch takes some time, so doing it after every
858 file can be too slow. (It also can generate a lot of dangling
859 git objects.) The default value is 0 (or false), which does not
860 refresh the branch. Setting 1 (or true) will refresh only once,
861 after git-annex has made other changes. Setting 2 refreshes af‐
862 ter every file, 3 after every other file, and so on; setting 100
863 refreshes after every 99 files.
864 (If git-annex gets faster in the future, refresh rates will in‐
866 crease proportional to the speed improvements.)
867 annex.queuesize
869 git-annex builds a queue of git commands, in order to combine
870 similar commands for speed. By default the size of the queue is
871 limited to 10240 commands; this can be used to change the size.
872 If you have plenty of memory and are working with very large
873 numbers of files, increasing the queue size can speed it up.
874 annex.bloomcapacity
876 The git annex unused and git annex sync --content commands use a
877 bloom filter to determine what files are present in eg, the work
878 tree. The default bloom filter is sized to handle up to 500000
879 files. If your repository is larger than that, you should in‐
880 crease this value. Larger values will make git-annex unused and
881 git annex sync --content consume more memory; run git annex info
882 for memory usage numbers.
883 annex.bloomaccuracy
885 Adjusts the accuracy of the bloom filter used by git annex un‐
886 used and git annex sync --content. The default accuracy is
887 10000000 -- 1 unused file out of 10000000 will be missed by git
888 annex unused. Increasing the accuracy will make git annex unused
889 consume more memory; run git annex info for memory usage num‐
890 bers.
891 annex.sshcaching
893 By default, git-annex caches ssh connections using ssh's Con‐
894 trolMaster and ControlPersist settings (if built using a new
895 enough ssh). To disable this, set to false.
896 annex.adviceNoSshCaching
898 When git-annex is unable to use ssh connection caching, or has
899 been configured not to, and concurrency is enabled, it will warn
900 that this might result in multiple ssh processes prompting for
901 passwords at the same time. To disable that warning, eg if you
902 have configured ssh connection caching yourself, or have ssh
903 agent caching passwords, set this to false.
904 annex.alwayscommit
906 By default, git-annex automatically commits data to the git-an‐
907 nex branch after each command is run. If you have a series of
908 commands that you want to make a single commit, you can run the
909 commands with -c annex.alwayscommit=false. You can later commit
910 the data by running git annex merge (or by automatic merges) or
911 git annex sync.
912 annex.commitmessage
914 When git-annex updates the git-annex branch, it usually makes up
915 its own commit message (eg "update"), since users rarely look at
916 or care about changes to that branch. If you do care, you can
917 specify this setting by running commands with -c annex.com‐
918 mitmessage=whatever
919 This works well in combination with annex.alwayscommit=false, to
921 gather up a set of changes and commit them with a message you
922 specify.
923 annex.allowsign
925 By default git-annex avoids gpg signing commits that it makes
926 when they're not the purpose of a command, but only a side ef‐
927 fect. That default avoids lots of gpg password prompts when
928 commit.gpgSign is set. A command like git annex sync or git an‐
929 nex merge will gpg sign its commit, but a command like git annex
930 get, that updates the git-annex branch, will not. The assistant
931 also avoids signing commits.
932 Setting annex.allowsign to true lets all commits be signed, as
934 controlled by commit.gpgSign and other git configuration.
935 annex.merge-annex-branches
937 By default, git-annex branches that have been pulled from re‐
938 motes are automatically merged into the local git-annex branch,
939 so that git-annex has the most up-to-date possible knowledge.
940 To avoid that merging, set this to "false". This can be useful
942 particularly when you don't have write permission to the reposi‐
943 tory.
944 annex.private
946 When this is set to true, no information about the repository
947 will be recorded in the git-annex branch.
948 For example, to make a repository without any mention of it ever
950 appearing in the git-annex branch:
951 git init myprivate
953 cd myprivaterepo
954 git config annex.private true
955 git annex init
956 annex.hardlink
958 Set this to true to make file contents be hard linked between
959 the repository and its remotes when possible, instead of a more
960 expensive copy.
961 Use with caution -- This can invalidate numcopies counting,
963 since with hard links, fewer copies of a file can exist. So, it
964 is a good idea to mark a repository using this setting as un‐
965 trusted.
966 When a repository is set up using git clone --shared, git-annex
968 init will automatically set annex.hardlink and mark the reposi‐
969 tory as untrusted.
970 When annex.thin is also set, setting annex.hardlink has no ef‐
972 fect.
973 annex.thin
975 Set this to true to make unlocked files be a hard link to their
976 content in the annex, rather than a second copy. This can save
977 considerable disk space, but when a modification is made to a
978 file, you will lose the local (and possibly only) copy of the
979 old version. So, enable with care.
980 After setting (or unsetting) this, you should run git annex fix
982 to fix up the annexed files in the work tree to be hard links
983 (or copies).
984 Note that this has no effect when the filesystem does not sup‐
986 port hard links. And when multiple files in the work tree have
987 the same content, only one of them gets hard linked to the an‐
988 nex.
989 annex.supportunlocked
991 By default git-annex supports unlocked files as well as locked
992 files, so this defaults to true. If set to false, git-annex will
993 only support locked files. That will avoid doing the work needed
994 to support unlocked files.
995 Note that setting this to false does not prevent a repository
997 from having unlocked files added to it, and in that case the
998 content of the files will not be accessible until they are
999 locked.
1000 After changing this config, you need to re-run git-annex init
1002 for it to take effect.
1003 annex.resolvemerge
1005 Set to false to prevent merge conflicts in the checked out
1006 branch being automatically resolved by the git-annex assitant,
1007 git-annex sync, git-annex merge, and the git-annex post-receive
1008 hook.
1009 To configure the behavior in all clones of the repository, this
1011 can be set in git-annex-config(1).
1012 annex.synccontent
1014 Set to true to make git-annex sync default to syncing annexed
1015 content.
1016 To configure the behavior in all clones of the repository, this
1018 can be set in git-annex-config(1).
1019 annex.synconlyannex
1021 Set to true to make git-annex sync default to only sincing the
1022 git-annex branch and annexed content.
1023 To configure the behavior in all clones of the repository, this
1025 can be set in git-annex-config(1).
1026 annex.debug
1028 Set to true to enable debug logging by default.
1029 annex.debugfilter
1031 Set to configure which debug messages to display (when debug
1032 message display has been enabled by annex.debug or --debug). The
1033 value is one or more module names, separated by commas.
1034 annex.version
1036 The current version of the git-annex repository. This is main‐
1037 tained by git-annex and should never be manually changed.
1038 annex.autoupgraderepository
1040 When an old git-annex repository version has become deprecated,
1041 git-annex will normally automatically upgrade the repository to
1042 the new version.
1043 If this is set to false, git-annex won't automatically upgrade
1045 the repository. Instead it will exit with an error message. You
1046 can run git annex upgrade yourself when you are ready to upgrade
1047 the repository.
1048 annex.crippledfilesystem
1050 Set to true if the repository is on a crippled filesystem, such
1051 as FAT, which does not support symbolic links, or hard links, or
1052 unix permissions. This is automatically probed by "git annex
1053 init".
1054 annex.pidlock
1056 Normally, git-annex uses fine-grained lock files to allow multi‐
1057 ple processes to run concurrently without getting in each oth‐
1058 ers' way. That works great, unless you are using git-annex on a
1059 filesystem that does not support POSIX fcntl locks. This is
1060 sometimes the case when using NFS or Lustre filesystems.
1061 To support such situations, you can set annex.pidlock to true,
1063 and it will fall back to a single top-level pid file lock.
1064 Although, often, you'd really be better off fixing your net‐
1066 worked filesystem configuration to support POSIX locks.. And,
1067 some networked filesystems are so inconsistent that one node
1068 can't reliably tell when the other node is holding a pid lock.
1069 Caveat emptor.
1070 annex.pidlocktimeout
1072 git-annex will wait up to this many seconds for the pid lock
1073 file to go away, and will then abort if it cannot continue. De‐
1074 fault: 300
1075 When using pid lock files, it's possible for a stale lock file
1077 to get left behind by previous run of git-annex that crashed or
1078 was interrupted. This is mostly avoided, but can occur espe‐
1079 cially when using a network file system. This timeout prevents
1080 git-annex waiting forever in such a situation.
1081 annex.cachecreds
1083 When "true" (the default), git-annex will cache credentials used
1084 to access special remotes in files in .git/annex/creds/ that
1085 only you can read. To disable that caching, set to "false", and
1086 credentials will only be read from the environment, or if they
1087 have been embedded in encrypted form in the git repository, will
1088 be extracted and decrypted each time git-annex needs to access
1089 the remote.
1090 annex.secure-erase-command
1092 This can be set to a command that should be run whenever git-an‐
1093 nex removes the content of a file from the repository.
1094 In the command line, %file is replaced with the file that should
1096 be erased.
1097 For example, to use the wipe command, set it to wipe -f %file.
1099 annex.freezecontent-command, annex.thawcontent-command
1101 Usually the write permission bits are unset to protect annexed
1102 objects from being modified or deleted. The freezecontent-com‐
1103 mand is run after git-annex has removed the write bit. The thaw‐
1104 content-command should undo its effect, and is run before git-
1105 annex restores the write bit.
1106 In the command line, %path is replaced with the file or direc‐
1108 tory to operate on.
1109 annex.tune.objecthash1, annex.tune.objecthashlower, annex.tune.branch‐
1111 hash1
1112 These can be passed to git annex init to tune the repository.
1113 They cannot be safely changed in a running repository and should
1114 never be set in global git configuration. For details, see
1115 <https://git-annex.branchable.com/tuning/>.
1116
1118 Remotes are configured using these settings in .git/config.
1119 remote.<name>.annex-cost
1121 When determining which repository to transfer annexed files from
1122 or to, ones with lower costs are preferred. The default cost is
1123 100 for local repositories, and 200 for remote repositories.
1124 remote.<name>.annex-cost-command
1126 If set, the command is run, and the number it outputs is used as
1127 the cost. This allows varying the cost based on e.g., the cur‐
1128 rent network.
1129 remote.<name>.annex-start-command
1131 A command to run when git-annex begins to use the remote. This
1132 can be used to, for example, mount the directory containing the
1133 remote.
1134 The command may be run repeatedly when multiple git-annex pro‐
1136 cesses are running concurrently.
1137 remote.<name>.annex-stop-command
1139 A command to run when git-annex is done using the remote.
1140 The command will only be run once *all* running git-annex pro‐
1142 cesses are finished using the remote.
1143 remote.<name>.annex-shell
1145 Specify an alternative git-annex-shell executable on the remote
1146 instead of looking for "git-annex-shell" on the PATH.
1147 This is useful if the git-annex-shell program is outside the
1149 PATH or has a non-standard name.
1150 remote.<name>.annex-ignore
1152 If set to true, prevents git-annex from storing file contents on
1153 this remote by default. (You can still request it be used by
1154 the --from and --to options.)
1155 This is, for example, useful if the remote is located somewhere
1157 without git-annex-shell. (For example, if it's on GitHub). Or,
1158 it could be used if the network connection between two reposito‐
1159 ries is too slow to be used normally.
1160 This does not prevent git-annex sync (or the git-annex assist‐
1162 ant) from syncing the git repository to the remote.
1163 remote.<name>.annex-ignore-command
1165 If set, the command is run, and if it exits nonzero, that's the
1166 same as setting annex-ignore to true. This allows controlling
1167 behavior based on e.g., the current network.
1168 remote.<name>.annex-sync
1170 If set to false, prevents git-annex sync (and the git-annex as‐
1171 sistant) from syncing with this remote by default. However, git
1172 annex sync <name> can still be used to sync with the remote.
1173 remote.<name>.annex-sync-command
1175 If set, the command is run, and if it exits nonzero, that's the
1176 same as setting annex-sync to false. This allows controlling be‐
1177 havior based on e.g., the current network.
1178 remote.<name>.annex-pull
1180 If set to false, prevents git-annex sync (and the git-annex as‐
1181 sistant etc) from ever pulling (or fetching) from the remote.
1182 remote.<name>.annex-push
1184 If set to false, prevents git-annex sync (and the git-annex as‐
1185 sistant etc) from ever pushing to the remote.
1186 remote.<name>.annex-readonly
1188 If set to true, prevents git-annex from making changes to a re‐
1189 mote. This both prevents git-annex sync from pushing changes,
1190 and prevents storing or removing files from read-only remote.
1191 remote.<name>.annex-verify, annex.verify
1193 By default, git-annex will verify the checksums of objects down‐
1194 loaded from remotes. If you trust a remote and don't want the
1195 overhead of these checksums, you can set this to false.
1196 Note that even when this is set to false, git-annex does verifi‐
1198 cation in some edge cases, where it's likely the case than an
1199 object was downloaded incorrectly, or when needed for security.
1200 remote.<name>.annex-tracking-branch
1202 This is for use with special remotes that support exports and
1203 imports.
1204 When set to eg, "master", this tells git-annex that you want the
1206 special remote to track that branch.
1207 When set to eg, "master:subdir", the special remote tracks only
1209 the subdirectory of that branch.
1210 git-annex sync --content will import changes from the remote and
1212 merge them into the annex-tracking-branch. They also export
1213 changes made to the branch to the remote.
1214 remote.<name>.annex-export-tracking
1216 Deprecated name for remote.<name>.annex-tracking-branch. Will
1217 still be used if it's configured and remote.<name>.annex-track‐
1218 ing-branch is not.
1219 remote.<name>.annexUrl
1221 Can be used to specify a different url than the regular re‐
1222 mote.<name>.url for git-annex to use when talking with the re‐
1223 mote. Similar to the pushUrl used by git-push.
1224 remote.<name>.annex-uuid
1226 git-annex caches UUIDs of remote repositories here.
1227 remote.<name>.annex-config-uuid
1229 Used for some special remotes, points to a different special re‐
1230 mote configuration to use.
1231 remote.<name>.annex-retry, annex.retry
1233 Number of times a transfer that fails can be retried. (default
1234 0)
1235 remote.<name>.annex-forward-retry, annex.forward-retry
1237 If a transfer made some forward progress before failing, this
1238 allows it to be retried even when annex.retry does not. The
1239 value is the maximum number of times to do that. (default 5)
1240 When both annex.retry and this are set, the maximum number of
1242 retries is the larger of the two.
1243 remote.<name>.annex-retry-delay, annex.retry-delay
1245 Number of seconds to delay before the first retry of a transfer.
1246 When making multiple retries of the same transfer, the delay
1247 doubles after each retry. (default 1)
1248 remote.<name>.annex-bwlimit, annex.bwlimit
1250 This can be used to limit how much bandwidth is used for a
1251 transfer from or to a remote.
1252 For example, to limit transfers to 1 mebibyte per second: git
1254 config annex.bwlimit "1MiB"
1255 This will work with many remotes, including git remotes, but not
1257 for remotes where the transfer is run by a separate program than
1258 git-annex.
1259 remote.<name>.annex-stalldetecton, annex.stalldetection
1261 Configuring this lets stalled or too-slow transfers be detected,
1262 and dealt with, so rather than getting stuck, git-annex will
1263 cancel the stalled operation. The transfer will be considered to
1264 have failed, so settings like annex.retry will control what it
1265 does next.
1266 By default, git-annex detects transfers that have probably
1268 stalled, and suggests configuring this. If it is incorrectly de‐
1269 tecting stalls, setting this to "false" will avoid that.
1270 Set to "true" to enable automatic stall detection. If a remote
1272 does not update its progress consistently, no automatic stall
1273 detection will be done. And it may take a while for git-annex to
1274 decide a remote is really stalled when using automatic stall de‐
1275 tection, since it needs to be conservative about what looks like
1276 a stall.
1277 For more fine control over what constitutes a stall, set to a
1279 value in the form "$amount/$timeperiod" to specify how much data
1280 git-annex should expect to see flowing, minimum, over a given
1281 period of time.
1282 For example, to detect outright stalls where no data has been
1284 transferred after 30 seconds: git config annex.stalldetection
1285 "1KB/30s"
1286 Or, if you have a remote on a USB drive that is normally capable
1288 of several megabytes per second, but has bad sectors where it
1289 gets stuck for a long time, you could use: git config remote.us‐
1290 bdrive.annex-stalldetection "1MB/1m"
1291 This is not enabled by default, because it can make git-annex
1293 use more resources. To be able to cancel stalls, git-annex has
1294 to run transfers in separate processes (one per concurrent job).
1295 So it may need to open more connections to a remote than usual,
1296 or the communication with those processes may make it a bit
1297 slower.
1298 remote.<name>.annex-checkuuid
1300 This only affects remotes that have their url pointing to a di‐
1301 rectory on the same system. git-annex normally checks the uuid
1302 of such remotes each time it's run, which lets it transparently
1303 deal with different drives being mounted to the location at dif‐
1304 ferent times.
1305 Setting annex-checkuuid to false will prevent it from checking
1307 the uuid at startup (although the uuid is still verified before
1308 making any changes to the remote repository). This may be useful
1309 to set to prevent unncessary spin-up or automounting of a drive.
1310 remote.<name>.annex-trustlevel
1312 Configures a local trust level for the remote. This overrides
1313 the value configured by the trust and untrust commands. The
1314 value can be any of "trusted", "semitrusted" or "untrusted".
1315 remote.<name>.annex-availability
1317 Can be used to tell git-annex whether a remote is LocallyAvail‐
1318 able or GloballyAvailable. Normally, git-annex determines this
1319 automatically.
1320 remote.<name>.annex-speculate-present
1322 Set to "true" to make git-annex speculate that this remote may
1323 contain the content of any file, even though its normal location
1324 tracking does not indicate that it does. This will cause git-an‐
1325 nex to try to get all file contents from the remote. Can be use‐
1326 ful in setting up a caching remote.
1327 remote.<name>.annex-private
1329 When this is set to true, no information about the remote will
1330 be recorded in the git-annex branch. This is mostly useful for
1331 special remotes, and is set when using git-annex-initremote(1)
1332 with the --private option.
1333 remote.<name>.annex-bare
1335 Can be used to tell git-annex if a remote is a bare repository
1336 or not. Normally, git-annex determines this automatically.
1337 remote.<name>.annex-ssh-options
1339 Options to use when using ssh to talk to this remote.
1340 remote.<name>.annex-rsync-options
1342 Options to use when using rsync to or from this remote. For ex‐
1343 ample, to force IPv6, and limit the bandwidth to 100Kbyte/s, set
1344 it to -6 --bwlimit 100
1345 Note that git-annex-shell has a whitelist of allowed rsync op‐
1347 tions, and others will not be be passed to the remote rsync. So
1348 using some options may break the communication between the local
1349 and remote rsyncs.
1350 remote.<name>.annex-rsync-upload-options
1352 Options to use when using rsync to upload a file to a remote.
1353 These options are passed after other applicable rsync options,
1355 so can be used to override them. For example, to limit upload
1356 bandwidth to 10Kbyte/s, set --bwlimit 10.
1357 remote.<name>.annex-rsync-download-options
1359 Options to use when using rsync to download a file from a re‐
1360 mote.
1361 These options are passed after other applicable rsync options,
1363 so can be used to override them.
1364 remote.<name>.annex-rsync-transport
1366 The remote shell to use to connect to the rsync remote. Possible
1367 values are ssh (the default) and rsh, together with their argu‐
1368 ments, for instance ssh -p 2222 -c blowfish; Note that the re‐
1369 mote hostname should not appear there, see rsync(1) for details.
1370 When the transport used is ssh, connections are automatically
1371 cached unless annex.sshcaching is unset.
1372 remote.<name>.annex-bup-split-options
1374 Options to pass to bup split when storing content in this re‐
1375 mote. For example, to limit the bandwidth to 100Kbyte/s, set it
1376 to --bwlimit 100k (There is no corresponding option for bup
1377 join.)
1378 remote.<name>.annex-gnupg-options
1380 Options to pass to GnuPG when it's encrypting data. For in‐
1381 stance, to use the AES cipher with a 256 bits key and disable
1382 compression, set it to --cipher-algo AES256 --compress-algo
1383 none. (These options take precedence over the default GnuPG con‐
1384 figuration, which is otherwise used.)
1385 remote.<name>.annex-gnupg-decrypt-options
1387 Options to pass to GnuPG when it's decrypting data. (These op‐
1388 tions take precedence over the default GnuPG configuration,
1389 which is otherwise used.)
1390 annex.ssh-options, annex.rsync-options,
1392 annex.rsync-upload-options, annex.rsync-download-options, an‐
1393 nex.bup-split-options, annex.gnupg-options, annex.gnupg-de‐
1394 crypt-options
1395 Default options to use if a remote does not have more specific
1397 options as described above.
1398 remote.<name>.annex-rsyncurl
1400 Used by rsync special remotes, this configures the location of
1401 the rsync repository to use. Normally this is automatically set
1402 up by git annex initremote, but you can change it if needed.
1403 remote.<name>.annex-buprepo
1405 Used by bup special remotes, this configures the location of the
1406 bup repository to use. Normally this is automatically set up by
1407 git annex initremote, but you can change it if needed.
1408 remote.<name>.annex-borgrepo
1410 Used by borg special remotes, this configures the location of
1411 the borg repository to use. Normally this is automatically set
1412 up by git annex initremote, but you can change it if needed.
1413 remote.<name>.annex-ddarrepo
1415 Used by ddar special remotes, this configures the location of
1416 the ddar repository to use. Normally this is automatically set
1417 up by git annex initremote, but you can change it if needed.
1418 remote.<name>.annex-directory
1420 Used by directory special remotes, this configures the location
1421 of the directory where annexed files are stored for this remote.
1422 Normally this is automatically set up by git annex initremote,
1423 but you can change it if needed.
1424 remote.<name>.annex-adb
1426 Used to identify remotes on Android devices accessed via adb.
1427 Normally this is automatically set up by git annex initremote.
1428 remote.<name>.annex-androiddirectory
1430 Used by adb special remotes, this is the directory on the An‐
1431 droid device where files are stored for this remote. Normally
1432 this is automatically set up by git annex initremote, but you
1433 can change it if needed.
1434 remote.<name>.annex-androidserial
1436 Used by adb special remotes, this is the serial number of the
1437 Android device used by the remote. Normally this is automati‐
1438 cally set up by git annex initremote, but you can change it if
1439 needed, eg when upgrading to a new Android device.
1440 remote.<name>.annex-s3
1442 Used to identify Amazon S3 special remotes. Normally this is
1443 automatically set up by git annex initremote.
1444 remote.<name>.annex-glacier
1446 Used to identify Amazon Glacier special remotes. Normally this
1447 is automatically set up by git annex initremote.
1448 remote.<name>.annex-webdav
1450 Used to identify webdav special remotes. Normally this is auto‐
1451 matically set up by git annex initremote.
1452 remote.<name>.annex-tahoe
1454 Used to identify tahoe special remotes. Points to the configu‐
1455 ration directory for tahoe.
1456 remote.<name>.annex-gcrypt
1458 Used to identify gcrypt special remotes. Normally this is auto‐
1459 matically set up by git annex initremote.
1460 It is set to "true" if this is a gcrypt remote. If the gcrypt
1462 remote is accessible over ssh and has git-annex-shell available
1463 to manage it, it's set to "shell".
1464 remote.<name>.annex-git-lfs
1466 Used to identify git-lfs special remotes. Normally this is au‐
1467 tomatically set up by git annex initremote.
1468 It is set to "true" if this is a git-lfs remote.
1470 remote.<name>.annex-httpalso
1472 Used to identify httpalso special remotes. Normally this is au‐
1473 tomatically set up by git annex initremote.
1474 remote.<name>.annex-externaltype
1476 Used external special remotes to record the type of the remote.
1477 Eg, if this is set to "foo", git-annex will run a "git-annex-re‐
1479 mote-foo" program to communicate with the external special re‐
1480 mote.
1481 If this is set to "readonly", then git-annex will not run any
1483 external special remote program, but will try to access things
1484 stored in the remote using http. That only works for some exter‐
1485 nal special remotes, so consult the documentation of the one you
1486 are using.
1487 remote.<name>.annex-hooktype
1489 Used by hook special remotes to record the type of the remote.
1490 annex.web-options
1492 Options to pass to curl when git-annex uses it to download urls
1493 (rather than the default built-in url downloader).
1494 For example, to force IPv4 only, set it to "-4". Or to make
1496 curl use your ~/.netrc file, set it to "--netrc".
1497 Setting this option makes git-annex use curl, but only when an‐
1499 nex.security.allowed-ip-addresses is configured in a specific
1500 way. See its documentation.
1501 annex.youtube-dl-options
1503 Options to pass to youtube-dl when using it to find the url to
1504 download for a video.
1505 Some options may break git-annex's integration with youtube-dl.
1507 For example, the --output option could cause it to store files
1508 somewhere git-annex won't find them. Avoid setting here or in
1509 the youtube-dl config file any options that cause youtube-dl to
1510 download more than one file, or to store the file anywhere other
1511 than the current working directory.
1512 annex.youtube-dl-command
1514 Command to run for youtube-dl. Default is "youtube-dl".
1515 annex.aria-torrent-options
1517 Options to pass to aria2c when using it to download a torrent.
1518 annex.http-headers
1520 HTTP headers to send when downloading from the web. Multiple
1521 lines of this option can be set, one per header.
1522 annex.http-headers-command
1524 If set, the command is run and each line of its output is used
1525 as a HTTP header. This overrides annex.http-headers.
1526 annex.security.allowed-url-schemes
1528 List of URL schemes that git-annex is allowed to download con‐
1529 tent from. The default is "http https ftp".
1530 Think very carefully before changing this; there are security
1532 implications. For example, if it's changed to allow "file" URLs,
1533 then anyone who can get a commit into your git-annex repository
1534 could git-annex addurl a pointer to a private file located out‐
1535 side that repository, possibly causing it to be copied into your
1536 repository and transferred on to other remotes, exposing its
1537 content.
1538 Some special remotes support their own domain-specific URL
1540 schemes; those are not affected by this configuration setting.
1541 annex.security.allowed-ip-addresses
1543 By default, git-annex only makes connections to public IP ad‐
1544 dresses; it will refuse to use HTTP and other servers on local‐
1545 host or on a private network.
1546 This setting can override that behavior, allowing access to par‐
1548 ticular IP addresses that would normally be blocked. For example
1549 "127.0.0.1 ::1" allows access to localhost (both IPV4 and IPV6).
1550 To allow access to all IP addresses, use "all"
1551 Think very carefully before changing this; there are security
1553 implications. Anyone who can get a commit into your git-annex
1554 repository could git annex addurl an url on a private server,
1555 possibly causing it to be downloaded into your repository and
1556 transferred to other remotes, exposing its content.
1557 Note that, since the interfaces of curl and youtube-dl do not
1559 allow these IP address restrictions to be enforced, curl and
1560 youtube-dl will never be used unless annex.security.al‐
1561 lowed-ip-addresses=all.
1562 To allow accessing local or private IP addresses on only spe‐
1564 cific ports, use the syntax "[addr]:port". For example,
1565 "[127.0.0.1]:80 [127.0.0.1]:443 [::1]:80 [::1]:443" allows lo‐
1566 calhost on the http ports only.
1567 annex.security.allowed-http-addresses
1569 Old name for annex.security.allowed-ip-addresses. If set, this
1570 is treated the same as having annex.security.allowed-ip-ad‐
1571 dresses set.
1572 annex.security.allow-unverified-downloads
1574 For security reasons, git-annex refuses to download content from
1575 most special remotes when it cannot check a hash to verify that
1576 the correct content was downloaded. This particularly impacts
1577 downloading the content of URL or WORM keys, which lack hashes.
1578 The best way to avoid problems due to this is to migrate files
1580 away from such keys, before their content reaches a special re‐
1581 mote. See git-annex-migrate(1).
1582 When the content is only available from a special remote, you
1584 can use this configuration to force git-annex to download it.
1585 But you do so at your own risk, and it's very important you read
1586 and understand the information below first!
1587 Downloading unverified content from encrypted special remotes is
1589 prevented, because the special remote could send some other en‐
1590 crypted content than what you expect, causing git-annex to de‐
1591 crypt data that you never checked into git-annex, and risking
1592 exposing the decrypted data to any non-encrypted remotes you
1593 send content to.
1594 Downloading unverified content from (non-encrypted) external
1596 special remotes is prevented, because they could follow http
1597 redirects to web servers on localhost or on a private network,
1598 or in some cases to a file:/// url.
1599 If you decide to bypass this security check, the best thing to
1601 do is to only set it temporarily while running the command that
1602 gets the file. The value to set the config to is "ACKTHPPT".
1603 For example:
1604 git -c annex.security.allow-unverified-downloads=ACKTHPPT annex
1606 get myfile
1607 It would be a good idea to check that it downloaded the file you
1609 expected, too.
1610 remote.<name>.annex-security-allow-unverified-downloads
1612 Per-remote configuration of annex.security.allow-unveri‐
1613 fied-downloads.
1614
1616 annex.delayadd
1617 Makes the watch and assistant commands delay for the specified
1619 number of seconds before adding a newly created file to the an‐
1620 nex. Normally this is not needed, because they already wait for
1621 all writers of the file to close it.
1622 Note that this only delays adding files created while the daemon
1624 is running. Changes made when it is not running will be added
1625 immediately the next time it is started up.
1626 annex.expireunused
1628 Controls what the assistant does about unused file contents that
1629 are stored in the repository.
1630 The default is false, which causes all old and unused file con‐
1632 tents to be retained, unless the assistant is able to move them
1633 to some other repository (such as a backup repository).
1634 Can be set to a time specification, like "7d" or "1m", and then
1636 file contents that have been known to be unused for a week or a
1637 month will be deleted.
1638 annex.fscknudge
1640 When set to false, prevents the webapp from reminding you when
1641 using repositories that lack consistency checks.
1642 annex.autoupgrade
1644 When set to ask (the default), the webapp will check for new
1645 versions and prompt if they should be upgraded to. When set to
1646 true, automatically upgrades without prompting (on some sup‐
1647 ported platforms). When set to false, disables any upgrade
1648 checking.
1649 Note that upgrade checking is only done when git-annex is in‐
1651 stalled from one of the prebuilt images from its website. This
1652 does not bypass e.g., a Linux distribution's own upgrade han‐
1653 dling code.
1654 This setting also controls whether to restart the git-annex as‐
1656 sistant when the git-annex binary is detected to have changed.
1657 That is useful no matter how you installed git-annex.
1658 annex.autocommit
1660 Set to false to prevent the git-annex assistant and git-annex
1661 sync from automatically committing changes to files in the
1662 repository.
1663 To configure the behavior in all clones of the repository, this
1665 can be set in git-annex-config(1).
1666 annex.startupscan
1668 Set to false to prevent the git-annex assistant from scanning
1669 the repository for new and changed files on startup. This will
1670 prevent it from noticing changes that were made while it was not
1671 running, but can be a useful performance tweak for a large
1672 repository.
1673 annex.listen
1675 Configures which address the webapp listens on. The default is
1676 localhost. Can be either an IP address, or a hostname that re‐
1677 solves to the desired address.
1678
1680 The key-value backend used when adding a new file to the annex can be
1681 configured on a per-file-type basis via .gitattributes files. In the
1682 file, the annex.backend attribute can be set to the name of the backend
1683 to use. For example, this here's how to use the WORM backend by de‐
1684 fault, but the SHA256E backend for ogg files:
1685 * annex.backend=WORM
1687 *.ogg annex.backend=SHA256E
1688 There is a annex.largefiles attribute, which is used to configure which
1690 files are large enough to be added to the annex. Since attributes can‐
1691 not contain spaces, it is difficult to use for more complex an‐
1692 nex.largefiles settings. Setting annex.largefiles in git-annex-con‐
1693 fig(1) is an easier way to configure it across all clones of the repos‐
1694 itory. See git-annex-matching-expression(1) for details on the syntax.
1695 The numcopies and mincopies settings can also be configured on a
1697 per-file-type basis via the annex.numcopies and annex.mincopies at‐
1698 tributes in .gitattributes files. This overrides other settings. For
1699 example, this makes two copies be needed for wav files and 3 copies for
1700 flac files:
1701 *.wav annex.numcopies=2
1703 *.flac annex.numcopies=3
1704 Note that setting numcopies or mincopies to 0 is very unsafe.
1706 These settings are honored by git-annex whenever it's operating on a
1708 matching file. However, when using --all, --unused, or --key to specify
1709 keys to operate on, git-annex is operating on keys and not files, so
1710 will not honor the settings from .gitattributes. For this reason, the
1711 git annex numcopies and git annex mincopies commands are useful to con‐
1712 figure a global default.
1713 Also note that when using views, only the toplevel .gitattributes file
1715 is preserved in the view, so other settings in other files won't have
1716 any effect.
1717
1719 git-annex, when called as a git subcommand, may return exit codes 0 or
1720 1 for success or failures, or, more rarely, 127 or 128 for certain very
1721 specific failures. git-annex itself should return 0 on success and 1
1722 on failure, unless the --time-limit=time option is hit, in which case
1723 it returns with exit code 101.
1724
1726 These environment variables are used by git-annex when set:
1727 GIT_WORK_TREE, GIT_DIR
1729 Handled the same as they are by git, see git(1)
1730 GIT_SSH, GIT_SSH_COMMAND
1732 Handled similarly to the same as described in git(1). The one
1733 difference is that git-annex will sometimes pass an additional
1734 "-n" parameter to these, as the first parameter, to prevent ssh
1735 from reading from stdin. Since that can break existing uses of
1736 these environment variables that don't expect the extra parame‐
1737 ter, you will need to set GIT_ANNEX_USE_GIT_SSH=1 to make git-
1738 annex support these.
1739 Note that setting either of these environment variables prevents
1741 git-annex from automatically enabling ssh connection caching
1742 (see annex.sshcaching), so it will slow down some operations
1743 with remotes over ssh. It's up to you to enable ssh connection
1744 caching if you need it; see ssh's documentation.
1745 Also, annex.ssh-options and remote.<name>.annex-ssh-options
1747 won't have any effect when these envionment variables are set.
1748 Usually it's better to configure any desired options through
1750 your ~/.ssh/config file, or by setting annex.ssh-options.
1751 GIT_ANNEX_VECTOR_CLOCK
1753 Normally git-annex timestamps lines in the log files committed
1754 to the git-annex branch. Setting this environment variable to a
1755 number will make git-annex use that (or a larger number) rather
1756 than the current number of seconds since the UNIX epoch. Note
1757 that decimal seconds are supported.
1758 This is only provided for advanced users who either have a bet‐
1760 ter way to tell which commit is current than the local clock, or
1761 who need to avoid embedding timestamps for policy reasons.
1762 Some special remotes use additional environment variables
1764 for authentication etc. For example, AWS_ACCESS_KEY_ID and
1765 GIT_ANNEX_P2P_AUTHTOKEN. See special remote documentation.
1766
1768 These files are used by git-annex:
1769 .git/annex/objects/ in your git repository contains the annexed file
1771 contents that are currently available. Annexed files in your git repos‐
1772 itory symlink to that content.
1773 .git/annex/ in your git repository contains other run-time information
1775 used by git-annex.
1776 ~/.config/git-annex/autostart is a list of git repositories to start
1778 the git-annex assistant in.
1779 .git/hooks/pre-commit-annex in your git repository will be run whenever
1781 a commit is made to the HEAD branch, either by git commit, git-annex
1782 sync, or the git-annex assistant.
1783 .git/hooks/post-update-annex in your git repository will be run when‐
1785 ever the git-annex branch is updated. You can make this hook run git
1786 update-server-info when publishing a git-annex repository by http.
1787
1789 More git-annex documentation is available on its web site,
1790 <https://git-annex.branchable.com/>
1791 If git-annex is installed from a package, a copy of its documentation
1793 should be included, in, for example, /usr/share/doc/git-annex/.
1794
1796 Joey Hess <id@joeyh.name>
1797 <https://git-annex.branchable.com/>
1799 git-annex(1)