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 repair This can repair many of the problems with git repositories that
349 git fsck detects, but does not itself fix. It's useful if a
350 repository has become badly damaged. One way this can happen is
351 if a repository used by git-annex is on a removable drive that
352 gets unplugged at the wrong time.
353 See git-annex-repair(1) for details.
355 p2p Configure peer-2-Peer links between repositories.
357 See git-annex-p2p(1) for details.
359
361 find [path ...]
362 Outputs a list of annexed files in the specified path. With no
364 path, finds files in the current directory and its subdirecto‐
365 ries.
366 See git-annex-find(1) for details.
368 whereis [path ...]
370 Displays information about where the contents of files are lo‐
371 cated.
372 See git-annex-whereis(1) for details.
374 list [path ...]
376 Displays a table of remotes that contain the contents of the
377 specified files. This is similar to whereis but a more compact
378 display.
379 See git-annex-list(1) for details.
381 log [path ...]
383 Displays the location log for the specified file or files, show‐
384 ing each repository they were added to ("+") and removed from
385 ("-").
386 See git-annex-log(1) for details.
388 info [directory|file|remote|uuid ...]
390 Displays statistics and other information for the specified
391 item, which can be a directory, or a file, or a remote, or the
392 uuid of a repository.
393 When no item is specified, displays statistics and information
395 for the repository as a whole.
396 See git-annex-info(1) for details.
398 version
400 Shows the version of git-annex, as well as repository version
401 information.
402 See git-annex-version(1) for details.
404 map Generate map of repositories.
406 See git-annex-map(1) for details.
408 inprogress
410 Access files while they're being downloaded.
411 See git-annex-inprogress(1) for details.
413
415 metadata [path ...]
416 The content of an annexed file can have any number of metadata
418 fields attached to it to describe it. Each metadata field can in
419 turn have any number of values.
420 This command can be used to set metadata, or show the currently
422 set metadata.
423 See git-annex-metadata(1) for details.
425 view [tag ...] [field=value ...] [field=glob ...] [!tag ...]
427 [field!=value ...]
428 Uses metadata to build a view branch of the files in the current
429 branch, and checks out the view branch. Only files in the cur‐
430 rent branch whose metadata matches all the specified field val‐
431 ues and tags will be shown in the view.
432 See git-annex-view(1) for details.
434 vpop [N]
436 Switches from the currently active view back to the previous
437 view. Or, from the first view back to original branch.
438 See git-annex-vpop(1) for details.
440 vfilter [tag ...] [field=value ...] [!tag ...] [field!=value ...]
442 Filters the current view to only the files that have the speci‐
443 fied field values and tags.
444 See git-annex-vfilter(1) for details.
446 vadd [field=glob ...] [field=value ...] [tag ...]
448 Changes the current view, adding an additional level of directo‐
449 ries to categorize the files.
450 See git-annex-vfilter(1) for details.
452 vcycle When a view involves nested subdirectories, this cycles the or‐
454 der.
455 See git-annex-vcycle(1) for details.
457
459 migrate [path ...]
460 Changes the specified annexed files to use a different key-value
462 backend.
463 See git-annex-migrate(1) for details.
465 reinject src dest
467 Moves the src file into the annex as the content of the dest
468 file. This can be useful if you have obtained the content of a
469 file from elsewhere and want to put it in the local annex.
470 See git-annex-reinject(1) for details.
472 unannex [path ...]
474 Use this to undo an accidental git annex add command. It puts
475 the file back how it was before the add.
476 See git-annex-unannex(1) for details.
478 uninit De-initialize git-annex and clean out repository.
480 See git-annex-uninit(1) for details.
482 reinit uuid|description
484 Initialize repository, reusing old UUID.
485 See git-annex-reinit(1) for details.
487
489 pre-commit [path ...]
490 This is meant to be called from git's pre-commit hook. git annex
492 init automatically creates a pre-commit hook using this.
493 See git-annex-pre-commit(1) for details.
495 post-receive
497 This is meant to be called from git's post-receive hook. git an‐
498 nex init automatically creates a post-receive hook using this.
499 See git-annex-post-receive(1) for details.
501 lookupkey [file ...]
503 Looks up key used for file.
504 See git-annex-lookupkey(1) for details.
506 calckey [file ...]
508 Calculates the key that would be used to refer to a file.
509 See git-annex-calckey(1) for details.
511 contentlocation [key ..]
513 Looks up location of annexed content for a key.
514 See git-annex-contentlocation(1) for details.
516 examinekey [key ...]
518 Print information that can be determined purely by looking at
519 the key.
520 See git-annex-examinekey(1) for details.
522 matchexpression
524 Checks if a preferred content expression matches provided data.
525 See git-annex-matchexpression(1) for details.
527 fromkey [key file]
529 Manually set up a file in the git repository to link to a speci‐
530 fied key.
531 See git-annex-fromkey(1) for details.
533 registerurl [key url]
535 Registers an url for a key.
536 See git-annex-registerurl(1) for details.
538 unregisterurl [key url]
540 Unregisters an url for a key.
541 See git-annex-unregisterurl(1) for details.
543 setkey key file
545 Moves a file into the annex as the content of a key.
546 See git-annex-setkey(1) for details.
548 dropkey [key ...]
550 Drops annexed content for specified keys.
551 See git-annex-dropkey(1) for details.
553 transferkey key [--from=remote|--to=remote]
555 Transfers a key from or to a remote.
556 See git-annex-transferkey(1) for details.
558 transferrer
560 Used internally by git-annex to transfer content.
561 See git-annex-transferrer(1) for details.
563 transferkeys
565 Used internally by old versions of the assistant.
566 See git-annex-transferkey(1) for details.
568 setpresentkey key uuid [1|0]
570 This plumbing-level command changes git-annex's records about
571 whether the specified key's content is present in a remote with
572 the specified uuid.
573 See git-annex-setpresentkey(1) for details.
575 readpresentkey key uuid
577 Read records of where key is present.
578 See git-annex-readpresentkey(1) for details.
580 checkpresentkey key remote
582 Check if key is present in remote.
583 See git-annex-checkpresentkey(1) for details.
585 rekey [file key ...]
587 Change keys used for files.
588 See git-annex-rekey(1) for details.
590 resolvemerge
592 Resolves a conflicted merge, by adding both conflicting versions
593 of the file to the tree, using variants of their filename. This
594 is done automatically when using git annex sync or git annex
595 merge.
596 See git-annex-resolvemerge(1) for details.
598 diffdriver
600 This can be used to make git diff use an external diff driver
601 with annexed files.
602 See git-annex-diffdriver(1) for details.
604 smudge This command lets git-annex be used as a git filter driver, al‐
606 lowing annexed files in the git repository to be unlocked at all
607 times, instead of being symlinks.
608 See git-annex-smudge(1) for details.
610 findref [ref]
612 Lists files in a git ref. (deprecated)
613 See git-annex-findref(1) for details.
615 proxy -- git cmd [options]
617 Bypass direct mode guard. (deprecated)
618 See git-annex-proxy(1) for details.
620
622 test
623 This runs git-annex's built-in test suite.
625 See git-annex-test(1) for details.
627 testremote remote
629 This tests a remote by generating some random objects and send‐
630 ing them to the remote, then redownloading them, removing them
631 from the remote, etc.
632 It's safe to run in an existing repository (the repository con‐
634 tents are not altered), although it may perform expensive data
635 transfers.
636 See git-annex-testremote(1) for details.
638 fuzztest
640 Generates random changes to files in the current repository, for
641 use in testing the assistant.
642 See git-annex-fuzztest(1) for details.
644 benchmark
646 This runs git-annex's built-in benchmarks, if it was built with
647 benchmarking support.
648 See git-annex-benchmark(1) for details.
650
652 In addition to all the commands listed above, more commands can be
653 added to git-annex by dropping commands named like "git-annex-foo" into
654 a directory in the PATH.
655
657 These common options are accepted by all git-annex commands, and may
658 not be explicitly listed on their individual man pages. (Many commands
659 also accept the git-annex-matching-options(1).)
660 --force
662 Force unsafe actions, such as dropping a file's content when no
663 other source of it can be verified to still exist, or adding ig‐
664 nored files. Use with care.
665 --fast Enable less expensive, but also less thorough versions of some
667 commands. What is avoided depends on the command.
668 --quiet
670 Avoid the default verbose display of what is done; only show er‐
671 rors.
672 --verbose
674 Enable verbose display.
675 --debug
677 Display debug messages.
678 --no-debug
680 Disable display of debug messages.
681 --debugfilter=name[,name..]
683 When debug message display has been enabled by --debug, this
684 filters the debug messages that are displayed to ones coming
685 from modules with the specified names.
686 To find the names of modules, see the full debug output, which
688 includes the module name, eg "(Utility.Process)"
689 The full module name does not need to be specified when using
691 this, a substring of the name will do.
692 For example, --debugfilter=Process,External will display debug‐
694 ging output when git-annex runs processes, and when it communi‐
695 cates with external special remotes.
696 --numcopies=n
698 Overrides the numcopies setting.
699 Note that setting numcopies to 0 is very unsafe.
701 --mincopies=n
703 Overrides the mincopies setting.
704 Note that setting mincopies to 0 is very unsafe.
706 --time-limit=time
708 Limits how long a git-annex command runs. The time can be some‐
709 thing like "5h", or "30m" or even "45s" or "10d".
710 Note that git-annex may continue running a little past the spec‐
712 ified time limit, in order to finish processing a file.
713 Also, note that if the time limit prevents git-annex from doing
715 all it was asked to, it will exit with a special code, 101.
716 --semitrust=repository
718 --untrust=repository
720 Overrides trust settings for a repository. May be specified more
721 than once.
722 The repository should be specified using the name of a config‐
724 ured remote, or the UUID or description of a repository.
725 --trust=repository
727 This used to override trust settings for a repository, but now
728 will not do so, because trusting a repository can lead to data
729 loss, and data loss is now only enabled when using the --force
730 option.
731 --trust-glacier
733 This used to override trust settings for Glacier special re‐
734 motes, but now will not do so, because it could lead to data
735 loss, and data loss is now only enabled when using the --force
736 option.
737 --backend=name
739 Specifies which key-value backend to use. This can be used when
740 adding a file to the annex, or migrating a file. Once files are
741 in the annex, their backend is known and this option is not nec‐
742 essary.
743 --user-agent=value
745 Overrides the User-Agent to use when downloading files from the
746 web.
747 --notify-finish
749 Caused a desktop notification to be displayed after each suc‐
750 cessful file download and upload.
751 (Only supported on some platforms, e.g. Linux with dbus. A no-op
753 when not supported.)
754 --notify-start
756 Caused a desktop notification to be displayed when a file upload
757 or download has started, or when a file is dropped.
758 -c name=value
760 Overrides git configuration settings. May be specified multiple
761 times.
762
764 Like other git commands, git-annex is configured via .git/config.
765 These settings, as well as relevant git config settings, are the ones
766 git-annex uses.
767 (Some of these settings can also be set, across all clones of the
769 repository, using git-annex-config. See its man page for a list.)
770 annex.uuid
772 A unique UUID for this repository (automatically set).
773 annex.backend
775 Name of the default key-value backend to use when adding new
776 files to the repository.
777 This is overridden by annex annex.backend configuration in the
779 .gitattributes files, and by the --backend option.
780 (This used to be named annex.backends, and that will still be
782 used if set.)
783 annex.securehashesonly
785 Set to true to indicate that the repository should only use
786 cryptographically secure hashes (SHA2, SHA3) and not insecure
787 hashes (MD5, SHA1) for content.
788 When this is set, the contents of files using cryptographically
790 insecure hashes will not be allowed to be added to the reposi‐
791 tory.
792 Also, git-annex fsck will complain about any files present in
794 the repository that use insecure hashes. And, git-annex import
795 --no-content will refuse to import files from special remotes
796 using insecure hashes.
797 To configure the behavior in new clones of the repository, this
799 can be set using git-annex-config.
800 annex.maxextensionlength
802 Maximum length, in bytes, of what is considered a filename ex‐
803 tension when adding a file to a backend that preserves filename
804 extensions. The default length is 4, which allows extensions
805 like "jpeg". The dot before the extension is not counted part of
806 its length. At most two extensions at the end of a filename will
807 be preserved, e.g. .gz or .tar.gz .
808 annex.diskreserve
810 Amount of disk space to reserve. Disk space is checked when
811 transferring content to avoid running out, and additional free
812 space can be reserved via this option, to make space for more
813 important content (such as git commit logs). Can be specified
814 with any commonly used units, for example, "0.5 gb", "500M", or
815 "100 KiloBytes"
816 The default reserve is 1 megabyte.
818 annex.skipunknown
820 Set to true to make commands like "git-annex get" silently skip
821 over items that are listed in the command line, but are not
822 checked into git.
823 Set to false to make it an error for commands like "git-annex
825 get" to be asked to operate on files that are not checked into
826 git.
827 The default is currently true, but is planned to change to false
829 in a release in 2022.
830 Note that, when annex.skipunknown is false, a command like "git-
832 annex get ." will fail if no files in the current directory are
833 checked into git, but a command like "git-annex get" will not
834 fail, because the current directory is not listed, but is im‐
835 plicit. Commands like "git-annex get foo/" will fail if no files
836 in the directory are checked into git, but if at least one file
837 is, it will ignore other files that are not. This is all the
838 same as the behavior of "git-ls files --error-unmatch".
839 Also note that git-annex skips files that are checked into git,
841 but are not annexed files, this setting does not affect that.
842 annex.largefiles
844 Used to configure which files are large enough to be added to
845 the annex. It is an expression that matches the large files, eg
846 "include=*.mp3 or largerthan=500kb" See git-annex-matching-ex‐
847 pression(1) for details on the syntax.
848 Overrides any annex.largefiles attributes in .gitattributes
850 files.
851 To configure a default annex.largefiles for all clones of the
853 repository, this can be set in git-annex-config(1).
854 This configures the behavior of both git-annex and git when
856 adding files to the repository. By default, git-annex add adds
857 all files to the annex (except dotfiles), and git add adds files
858 to git (unless they were added to the annex previously). When
859 annex.largefiles is configured, both git annex add and git add
860 will add matching large files to the annex, and the other files
861 to git.
862 Other git-annex commands also honor annex.largefiles, including
864 git annex import, git annex addurl, git annex importfeed and the
865 assistant.
866 annex.dotfiles
868 Normally, dotfiles are assumed to be files like .gitignore,
869 whose content should always be part of the git repository, so
870 they will not be added to the annex. Setting annex.dotfiles to
871 true makes dotfiles be added to the annex the same as any other
872 file.
873 To annex only some dotfiles, set this and configure annex.large‐
875 files to match the ones you want. For example, to match only
876 dotfiles ending in ".big"
877 git config annex.largefiles "(include=.*.big or in‐
879 clude=*/.*.big) or (exclude=.* and exclude=*/.*)"
880 git config annex.dotfiles true
881 To configure a default annex.dotfiles for all clones of the
883 repository, this can be set in git-annex-config(1).
884 annex.gitaddtoannex
886 Setting this to false will prevent git add from adding files to
887 the annex, despite the annex.largefiles configuration.
888 annex.addsmallfiles
890 Controls whether small files (not matching annex.largefiles)
891 should be checked into git by git annex add. Defaults to true;
892 set to false to instead make small files be skipped.
893 annex.addunlocked
895 Commands like git-annex add default to adding files to the
896 repository in locked form. This can make them add the files in
897 unlocked form, the same as if git-annex-unlock(1) were run on
898 the files.
899 This can be set to "true" to add everything unlocked, or it can
901 be a more complicated expression that matches files by name,
902 size, or content. See git-annex-matching-expression(1) for de‐
903 tails.
904 To configure a default annex.addunlocked for all clones of the
906 repository, this can be set in git-annex-config(1).
907 (Using git add always adds files in unlocked form and it is not
909 affected by this setting.)
910 When a repository has core.symlinks set to false, or has an ad‐
912 justed unlocked branch checked out, this setting is ignored, and
913 files are always added to the repository in unlocked form.
914 annex.numcopies
916 This is a deprecated setting. You should instead use the git an‐
917 nex numcopies command to configure how many copies of files are
918 kept across all repositories, or the annex.numcopies .gitat‐
919 tributes setting.
920 This config setting is only looked at when git annex numcopies
922 has never been configured, and when there's no annex.numcopies
923 setting in the .gitattributes file.
924 Note that setting numcopies to 0 is very unsafe.
926 annex.genmetadata
928 Set this to true to make git-annex automatically generate some
929 metadata when adding files to the repository.
930 In particular, it stores year, month, and day metadata, from the
932 file's modification date.
933 When importfeed is used, it stores additional metadata from the
935 feed, such as the author, title, etc.
936 annex.used-refspec
938 This controls which refs git-annex unused considers to be used.
939 See REFSPEC FORMAT in git-annex-unused(1) for details.
940 annex.jobs
942 Configure the number of concurrent jobs to run. Default is 1.
943 Only git-annex commands that support the --jobs option will use
945 this.
946 Setting this to "cpus" will run one job per CPU core.
948 When the --batch option is used, this configuration is ignored.
950 annex.adjustedbranchrefresh
952 When git-annex-adjust(1) is used to set up an adjusted branch
953 that needs to be refreshed after getting or dropping files, this
954 config controls how frequently the branch is refreshed.
955 Refreshing the branch takes some time, so doing it after every
957 file can be too slow. (It also can generate a lot of dangling
958 git objects.) The default value is 0 (or false), which does not
959 refresh the branch. Setting 1 (or true) will refresh only once,
960 after git-annex has made other changes. Setting 2 refreshes af‐
961 ter every file, 3 after every other file, and so on; setting 100
962 refreshes after every 99 files.
963 (If git-annex gets faster in the future, refresh rates will in‐
965 crease proportional to the speed improvements.)
966 annex.queuesize
968 git-annex builds a queue of git commands, in order to combine
969 similar commands for speed. By default the size of the queue is
970 limited to 10240 commands; this can be used to change the size.
971 If you have plenty of memory and are working with very large
972 numbers of files, increasing the queue size can speed it up.
973 annex.bloomcapacity
975 The git annex unused and git annex sync --content commands use a
976 bloom filter to determine what files are present in eg, the work
977 tree. The default bloom filter is sized to handle up to 500000
978 files. If your repository is larger than that, you should in‐
979 crease this value. Larger values will make git-annex unused and
980 git annex sync --content consume more memory; run git annex info
981 for memory usage numbers.
982 annex.bloomaccuracy
984 Adjusts the accuracy of the bloom filter used by git annex un‐
985 used and git annex sync --content. The default accuracy is
986 10000000 -- 1 unused file out of 10000000 will be missed by git
987 annex unused. Increasing the accuracy will make git annex unused
988 consume more memory; run git annex info for memory usage num‐
989 bers.
990 annex.sshcaching
992 By default, git-annex caches ssh connections using ssh's Con‐
993 trolMaster and ControlPersist settings (if built using a new
994 enough ssh). To disable this, set to false.
995 annex.alwayscommit
997 By default, git-annex automatically commits data to the git-an‐
998 nex branch after each command is run. If you have a series of
999 commands that you want to make a single commit, you can run the
1000 commands with -c annex.alwayscommit=false. You can later commit
1001 the data by running git annex merge (or by automatic merges) or
1002 git annex sync.
1003 annex.commitmessage
1005 When git-annex updates the git-annex branch, it usually makes up
1006 its own commit message ("update"), since users rarely look at or
1007 care about changes to that branch. If you do care, you can spec‐
1008 ify this setting by running commands with -c annex.commitmes‐
1009 sage=whatever
1010 This works well in combination with annex.alwayscommit=false, to
1012 gather up a set of changes and commit them with a message you
1013 specify.
1014 annex.allowsign
1016 By default git-annex avoids gpg signing commits that it makes
1017 when they're not the purpose of a command, but only a side ef‐
1018 fect. That default avoids lots of gpg password prompts when
1019 commit.gpgSign is set. A command like git annex sync or git an‐
1020 nex merge will gpg sign its commit, but a command like git annex
1021 get, that updates the git-annex branch, will not. The assistant
1022 also avoids signing commits.
1023 Setting annex.allowsign to true lets all commits be signed, as
1025 controlled by commit.gpgSign and other git configuration.
1026 annex.merge-annex-branches
1028 By default, git-annex branches that have been pulled from re‐
1029 motes are automatically merged into the local git-annex branch,
1030 so that git-annex has the most up-to-date possible knowledge.
1031 To avoid that merging, set this to "false". This can be useful
1033 particularly when you don't have write permission to the reposi‐
1034 tory.
1035 annex.private
1037 When this is set to true, no information about the repository
1038 will be recorded in the git-annex branch.
1039 For example, to make a repository without any mention of it ever
1041 appearing in the git-annex branch:
1042 git init myprivate
1044 cd myprivaterepo
1045 git config annex.private true
1046 git annex init
1047 annex.hardlink
1049 Set this to true to make file contents be hard linked between
1050 the repository and its remotes when possible, instead of a more
1051 expensive copy.
1052 Use with caution -- This can invalidate numcopies counting,
1054 since with hard links, fewer copies of a file can exist. So, it
1055 is a good idea to mark a repository using this setting as un‐
1056 trusted.
1057 When a repository is set up using git clone --shared, git-annex
1059 init will automatically set annex.hardlink and mark the reposi‐
1060 tory as untrusted.
1061 When annex.thin is also set, setting annex.hardlink has no ef‐
1063 fect.
1064 annex.thin
1066 Set this to true to make unlocked files be a hard link to their
1067 content in the annex, rather than a second copy. This can save
1068 considerable disk space, but when a modification is made to a
1069 file, you will lose the local (and possibly only) copy of the
1070 old version. So, enable with care.
1071 After setting (or unsetting) this, you should run git annex fix
1073 to fix up the annexed files in the work tree to be hard links
1074 (or copies).
1075 Note that this has no effect when the filesystem does not sup‐
1077 port hard links. And when multiple files in the work tree have
1078 the same content, only one of them gets hard linked to the an‐
1079 nex.
1080 annex.supportunlocked
1082 By default git-annex supports unlocked files as well as locked
1083 files, so this defaults to true. If set to false, git-annex will
1084 only support locked files. That will avoid doing the work needed
1085 to support unlocked files.
1086 Note that setting this to false does not prevent a repository
1088 from having unlocked files added to it, and in that case the
1089 content of the files will not be accessible until they are
1090 locked.
1091 After changing this config, you need to re-run git-annex init
1093 for it to take effect.
1094 annex.resolvemerge
1096 Set to false to prevent merge conflicts in the checked out
1097 branch being automatically resolved by the git-annex assitant,
1098 git-annex sync, git-annex merge, and the git-annex post-receive
1099 hook.
1100 To configure the behavior in all clones of the repository, this
1102 can be set in git-annex-config(1).
1103 annex.synccontent
1105 Set to true to make git-annex sync default to syncing annexed
1106 content.
1107 To configure the behavior in all clones of the repository, this
1109 can be set in git-annex-config(1).
1110 annex.synconlyannex
1112 Set to true to make git-annex sync default to only sincing the
1113 git-annex branch and annexed content.
1114 To configure the behavior in all clones of the repository, this
1116 can be set in git-annex-config(1).
1117 annex.debug
1119 Set to true to enable debug logging by default.
1120 annex.debugfilter
1122 Set to configure which debug messages to display (when debug
1123 message display has been enabled by annex.debug or --debug). The
1124 value is one or more module names, separated by commas.
1125 annex.version
1127 The current version of the git-annex repository. This is main‐
1128 tained by git-annex and should never be manually changed.
1129 annex.autoupgraderepository
1131 When an old git-annex repository version has become deprecated,
1132 git-annex will normally automatically upgrade the repository to
1133 the new version.
1134 If this is set to false, git-annex won't automatically upgrade
1136 the repository. Instead it will exit with an error message. You
1137 can run git annex upgrade yourself when you are ready to upgrade
1138 the repository.
1139 annex.crippledfilesystem
1141 Set to true if the repository is on a crippled filesystem, such
1142 as FAT, which does not support symbolic links, or hard links, or
1143 unix permissions. This is automatically probed by "git annex
1144 init".
1145 annex.pidlock
1147 Normally, git-annex uses fine-grained lock files to allow multi‐
1148 ple processes to run concurrently without getting in each oth‐
1149 ers' way. That works great, unless you are using git-annex on a
1150 filesystem that does not support POSIX fcntl locks. This is
1151 sometimes the case when using NFS or Lustre filesystems.
1152 To support such situations, you can set annex.pidlock to true,
1154 and it will fall back to a single top-level pid file lock.
1155 Although, often, you'd really be better off fixing your net‐
1157 worked filesystem configuration to support POSIX locks.. And,
1158 some networked filesystems are so inconsistent that one node
1159 can't reliably tell when the other node is holding a pid lock.
1160 Caveat emptor.
1161 annex.pidlocktimeout
1163 git-annex will wait up to this many seconds for the pid lock
1164 file to go away, and will then abort if it cannot continue. De‐
1165 fault: 300
1166 When using pid lock files, it's possible for a stale lock file
1168 to get left behind by previous run of git-annex that crashed or
1169 was interrupted. This is mostly avoided, but can occur espe‐
1170 cially when using a network file system. This timeout prevents
1171 git-annex waiting forever in such a situation.
1172 annex.cachecreds
1174 When "true" (the default), git-annex will cache credentials used
1175 to access special remotes in files in .git/annex/creds/ that
1176 only you can read. To disable that caching, set to "false", and
1177 credentials will only be read from the environment, or if they
1178 have been embedded in encrypted form in the git repository, will
1179 be extracted and decrypted each time git-annex needs to access
1180 the remote.
1181 annex.secure-erase-command
1183 This can be set to a command that should be run whenever git-an‐
1184 nex removes the content of a file from the repository.
1185 In the command line, %file is replaced with the file that should
1187 be erased.
1188 For example, to use the wipe command, set it to wipe -f %file.
1190 annex.tune.objecthash1, annex.tune.objecthashlower, annex.tune.branch‐
1192 hash1
1193 These can be passed to git annex init to tune the repository.
1194 They cannot be safely changed in a running repository and should
1195 never be set in global git configuration. For details, see
1196 <https://git-annex.branchable.com/tuning/>.
1197
1199 Remotes are configured using these settings in .git/config.
1200 remote.<name>.annex-cost
1202 When determining which repository to transfer annexed files from
1203 or to, ones with lower costs are preferred. The default cost is
1204 100 for local repositories, and 200 for remote repositories.
1205 remote.<name>.annex-cost-command
1207 If set, the command is run, and the number it outputs is used as
1208 the cost. This allows varying the cost based on e.g., the cur‐
1209 rent network.
1210 remote.<name>.annex-start-command
1212 A command to run when git-annex begins to use the remote. This
1213 can be used to, for example, mount the directory containing the
1214 remote.
1215 The command may be run repeatedly when multiple git-annex pro‐
1217 cesses are running concurrently.
1218 remote.<name>.annex-stop-command
1220 A command to run when git-annex is done using the remote.
1221 The command will only be run once *all* running git-annex pro‐
1223 cesses are finished using the remote.
1224 remote.<name>.annex-shell
1226 Specify an alternative git-annex-shell executable on the remote
1227 instead of looking for "git-annex-shell" on the PATH.
1228 This is useful if the git-annex-shell program is outside the
1230 PATH or has a non-standard name.
1231 remote.<name>.annex-ignore
1233 If set to true, prevents git-annex from storing file contents on
1234 this remote by default. (You can still request it be used by
1235 the --from and --to options.)
1236 This is, for example, useful if the remote is located somewhere
1238 without git-annex-shell. (For example, if it's on GitHub). Or,
1239 it could be used if the network connection between two reposito‐
1240 ries is too slow to be used normally.
1241 This does not prevent git-annex sync (or the git-annex assist‐
1243 ant) from syncing the git repository to the remote.
1244 remote.<name>.annex-ignore-command
1246 If set, the command is run, and if it exits nonzero, that's the
1247 same as setting annex-ignore to true. This allows controlling
1248 behavior based on e.g., the current network.
1249 remote.<name>.annex-sync
1251 If set to false, prevents git-annex sync (and the git-annex as‐
1252 sistant) from syncing with this remote by default. However, git
1253 annex sync <name> can still be used to sync with the remote.
1254 remote.<name>.annex-sync-command
1256 If set, the command is run, and if it exits nonzero, that's the
1257 same as setting annex-sync to false. This allows controlling be‐
1258 havior based on e.g., the current network.
1259 remote.<name>.annex-pull
1261 If set to false, prevents git-annex sync (and the git-annex as‐
1262 sistant etc) from ever pulling (or fetching) from the remote.
1263 remote.<name>.annex-push
1265 If set to false, prevents git-annex sync (and the git-annex as‐
1266 sistant etc) from ever pushing to the remote.
1267 remote.<name>.annex-readonly
1269 If set to true, prevents git-annex from making changes to a re‐
1270 mote. This both prevents git-annex sync from pushing changes,
1271 and prevents storing or removing files from read-only remote.
1272 remote.<name>.annex-verify, annex.verify
1274 By default, git-annex will verify the checksums of objects down‐
1275 loaded from remotes. If you trust a remote and don't want the
1276 overhead of these checksums, you can set this to false.
1277 Note that even when this is set to false, git-annex does verifi‐
1279 cation in some edge cases, where it's likely the case than an
1280 object was downloaded incorrectly, or when needed for security.
1281 remote.<name>.annex-tracking-branch
1283 This is for use with special remotes that support exports and
1284 imports.
1285 When set to eg, "master", this tells git-annex that you want the
1287 special remote to track that branch.
1288 When set to eg, "master:subdir", the special remote tracks only
1290 the subdirectory of that branch.
1291 git-annex sync --content will import changes from the remote and
1293 merge them into the annex-tracking-branch. They also export
1294 changes made to the branch to the remote.
1295 remote.<name>.annex-export-tracking
1297 Deprecated name for remote.<name>.annex-tracking-branch. Will
1298 still be used if it's configured and remote.<name>.annex-track‐
1299 ing-branch is not.
1300 remote.<name>.annexUrl
1302 Can be used to specify a different url than the regular re‐
1303 mote.<name>.url for git-annex to use when talking with the re‐
1304 mote. Similar to the pushUrl used by git-push.
1305 remote.<name>.annex-uuid
1307 git-annex caches UUIDs of remote repositories here.
1308 remote.<name>.annex-config-uuid
1310 Used for some special remotes, points to a different special re‐
1311 mote configuration to use.
1312 remote.<name>.annex-retry, annex.retry
1314 Number of times a transfer that fails can be retried. (default
1315 0)
1316 remote.<name>.annex-forward-retry, annex.forward-retry
1318 If a transfer made some forward progress before failing, this
1319 allows it to be retried even when annex.retry does not. The
1320 value is the maximum number of times to do that. (default 5)
1321 When both annex.retry and this are set, the maximum number of
1323 retries is the larger of the two.
1324 remote.<name>.annex-retry-delay, annex.retry-delay
1326 Number of seconds to delay before the first retry of a transfer.
1327 When making multiple retries of the same transfer, the delay
1328 doubles after each retry. (default 1)
1329 remote.<name>.annex-stalldetecton, annex.stalldetection
1331 Configuring this lets stalled or too-slow transfers be detected,
1332 and dealt with, so rather than getting stuck, git-annex will
1333 cancel the stalled operation. The transfer will be considered to
1334 have failed, so settings like annex.retry will control what it
1335 does next.
1336 By default, git-annex detects transfers that have probably
1338 stalled, and suggests configuring this. If it is incorrectly de‐
1339 tecting stalls, setting this to "false" will avoid that.
1340 Set to "true" to enable automatic stall detection. If a remote
1342 does not update its progress consistently, no automatic stall
1343 detection will be done. And it may take a while for git-annex to
1344 decide a remote is really stalled when using automatic stall de‐
1345 tection, since it needs to be conservative about what looks like
1346 a stall.
1347 For more fine control over what constitutes a stall, set to a
1349 value in the form "$amount/$timeperiod" to specify how much data
1350 git-annex should expect to see flowing, minimum, over a given
1351 period of time.
1352 For example, to detect outright stalls where no data has been
1354 transferred after 30 seconds: git config annex.stalldetection
1355 "1KB/30s"
1356 Or, if you have a remote on a USB drive that is normally capable
1358 of several megabytes per second, but has bad sectors where it
1359 gets stuck for a long time, you could use: git config remote.us‐
1360 bdrive.annex-stalldetection "1MB/1m"
1361 This is not enabled by default, because it can make git-annex
1363 use more resources. To be able to cancel stalls, git-annex has
1364 to run transfers in separate processes (one per concurrent job).
1365 So it may need to open more connections to a remote than usual,
1366 or the communication with those processes may make it a bit
1367 slower.
1368 remote.<name>.annex-checkuuid
1370 This only affects remotes that have their url pointing to a di‐
1371 rectory on the same system. git-annex normally checks the uuid
1372 of such remotes each time it's run, which lets it transparently
1373 deal with different drives being mounted to the location at dif‐
1374 ferent times.
1375 Setting annex-checkuuid to false will prevent it from checking
1377 the uuid at startup (although the uuid is still verified before
1378 making any changes to the remote repository). This may be useful
1379 to set to prevent unncessary spin-up or automounting of a drive.
1380 remote.<name>.annex-trustlevel
1382 Configures a local trust level for the remote. This overrides
1383 the value configured by the trust and untrust commands. The
1384 value can be any of "trusted", "semitrusted" or "untrusted".
1385 remote.<name>.annex-availability
1387 Can be used to tell git-annex whether a remote is LocallyAvail‐
1388 able or GloballyAvailable. Normally, git-annex determines this
1389 automatically.
1390 remote.<name>.annex-speculate-present
1392 Set to "true" to make git-annex speculate that this remote may
1393 contain the content of any file, even though its normal location
1394 tracking does not indicate that it does. This will cause git-an‐
1395 nex to try to get all file contents from the remote. Can be use‐
1396 ful in setting up a caching remote.
1397 remote.<name>.annex-private
1399 When this is set to true, no information about the remote will
1400 be recorded in the git-annex branch. This is mostly useful for
1401 special remotes, and is set when using git-annex-initremote(1)
1402 with the --private option.
1403 remote.<name>.annex-bare
1405 Can be used to tell git-annex if a remote is a bare repository
1406 or not. Normally, git-annex determines this automatically.
1407 remote.<name>.annex-ssh-options
1409 Options to use when using ssh to talk to this remote.
1410 remote.<name>.annex-rsync-options
1412 Options to use when using rsync to or from this remote. For ex‐
1413 ample, to force IPv6, and limit the bandwidth to 100Kbyte/s, set
1414 it to -6 --bwlimit 100
1415 Note that git-annex-shell has a whitelist of allowed rsync op‐
1417 tions, and others will not be be passed to the remote rsync. So
1418 using some options may break the communication between the local
1419 and remote rsyncs.
1420 remote.<name>.annex-rsync-upload-options
1422 Options to use when using rsync to upload a file to a remote.
1423 These options are passed after other applicable rsync options,
1425 so can be used to override them. For example, to limit upload
1426 bandwidth to 10Kbyte/s, set --bwlimit 10.
1427 remote.<name>.annex-rsync-download-options
1429 Options to use when using rsync to download a file from a re‐
1430 mote.
1431 These options are passed after other applicable rsync options,
1433 so can be used to override them.
1434 remote.<name>.annex-rsync-transport
1436 The remote shell to use to connect to the rsync remote. Possible
1437 values are ssh (the default) and rsh, together with their argu‐
1438 ments, for instance ssh -p 2222 -c blowfish; Note that the re‐
1439 mote hostname should not appear there, see rsync(1) for details.
1440 When the transport used is ssh, connections are automatically
1441 cached unless annex.sshcaching is unset.
1442 remote.<name>.annex-bup-split-options
1444 Options to pass to bup split when storing content in this re‐
1445 mote. For example, to limit the bandwidth to 100Kbyte/s, set it
1446 to --bwlimit 100k (There is no corresponding option for bup
1447 join.)
1448 remote.<name>.annex-gnupg-options
1450 Options to pass to GnuPG when it's encrypting data. For in‐
1451 stance, to use the AES cipher with a 256 bits key and disable
1452 compression, set it to --cipher-algo AES256 --compress-algo
1453 none. (These options take precedence over the default GnuPG con‐
1454 figuration, which is otherwise used.)
1455 remote.<name>.annex-gnupg-decrypt-options
1457 Options to pass to GnuPG when it's decrypting data. (These op‐
1458 tions take precedence over the default GnuPG configuration,
1459 which is otherwise used.)
1460 annex.ssh-options, annex.rsync-options,
1462 annex.rsync-upload-options, annex.rsync-download-options, an‐
1463 nex.bup-split-options, annex.gnupg-options, annex.gnupg-de‐
1464 crypt-options
1465 Default options to use if a remote does not have more specific
1467 options as described above.
1468 remote.<name>.annex-rsyncurl
1470 Used by rsync special remotes, this configures the location of
1471 the rsync repository to use. Normally this is automatically set
1472 up by git annex initremote, but you can change it if needed.
1473 remote.<name>.annex-buprepo
1475 Used by bup special remotes, this configures the location of the
1476 bup repository to use. Normally this is automatically set up by
1477 git annex initremote, but you can change it if needed.
1478 remote.<name>.annex-borgrepo
1480 Used by borg special remotes, this configures the location of
1481 the borg repository to use. Normally this is automatically set
1482 up by git annex initremote, but you can change it if needed.
1483 remote.<name>.annex-ddarrepo
1485 Used by ddar special remotes, this configures the location of
1486 the ddar repository to use. Normally this is automatically set
1487 up by git annex initremote, but you can change it if needed.
1488 remote.<name>.annex-directory
1490 Used by directory special remotes, this configures the location
1491 of the directory where annexed files are stored for this remote.
1492 Normally this is automatically set up by git annex initremote,
1493 but you can change it if needed.
1494 remote.<name>.annex-adb
1496 Used to identify remotes on Android devices accessed via adb.
1497 Normally this is automatically set up by git annex initremote.
1498 remote.<name>.annex-androiddirectory
1500 Used by adb special remotes, this is the directory on the An‐
1501 droid device where files are stored for this remote. Normally
1502 this is automatically set up by git annex initremote, but you
1503 can change it if needed.
1504 remote.<name>.annex-androidserial
1506 Used by adb special remotes, this is the serial number of the
1507 Android device used by the remote. Normally this is automati‐
1508 cally set up by git annex initremote, but you can change it if
1509 needed, eg when upgrading to a new Android device.
1510 remote.<name>.annex-s3
1512 Used to identify Amazon S3 special remotes. Normally this is
1513 automatically set up by git annex initremote.
1514 remote.<name>.annex-glacier
1516 Used to identify Amazon Glacier special remotes. Normally this
1517 is automatically set up by git annex initremote.
1518 remote.<name>.annex-webdav
1520 Used to identify webdav special remotes. Normally this is auto‐
1521 matically set up by git annex initremote.
1522 remote.<name>.annex-tahoe
1524 Used to identify tahoe special remotes. Points to the configu‐
1525 ration directory for tahoe.
1526 remote.<name>.annex-gcrypt
1528 Used to identify gcrypt special remotes. Normally this is auto‐
1529 matically set up by git annex initremote.
1530 It is set to "true" if this is a gcrypt remote. If the gcrypt
1532 remote is accessible over ssh and has git-annex-shell available
1533 to manage it, it's set to "shell".
1534 remote.<name>.annex-git-lfs
1536 Used to identify git-lfs special remotes. Normally this is au‐
1537 tomatically set up by git annex initremote.
1538 It is set to "true" if this is a git-lfs remote.
1540 remote.<name>.annex-httpalso
1542 Used to identify httpalso special remotes. Normally this is au‐
1543 tomatically set up by git annex initremote.
1544 remote.<name>.annex-externaltype
1546 Used external special remotes to record the type of the remote.
1547 Eg, if this is set to "foo", git-annex will run a "git-annex-re‐
1549 mote-foo" program to communicate with the external special re‐
1550 mote.
1551 If this is set to "readonly", then git-annex will not run any
1553 external special remote program, but will try to access things
1554 stored in the remote using http. That only works for some exter‐
1555 nal special remotes, so consult the documentation of the one you
1556 are using.
1557 remote.<name>.annex-hooktype
1559 Used by hook special remotes to record the type of the remote.
1560 annex.web-options
1562 Options to pass to curl when git-annex uses it to download urls
1563 (rather than the default built-in url downloader).
1564 For example, to force IPv4 only, set it to "-4". Or to make
1566 curl use your ~/.netrc file, set it to "--netrc".
1567 Setting this option makes git-annex use curl, but only when an‐
1569 nex.security.allowed-ip-addresses is configured in a specific
1570 way. See its documentation.
1571 annex.youtube-dl-options
1573 Options to pass to youtube-dl when using it to find the url to
1574 download for a video.
1575 Some options may break git-annex's integration with youtube-dl.
1577 For example, the --output option could cause it to store files
1578 somewhere git-annex won't find them. Avoid setting here or in
1579 the youtube-dl config file any options that cause youtube-dl to
1580 download more than one file, or to store the file anywhere other
1581 than the current working directory.
1582 annex.aria-torrent-options
1584 Options to pass to aria2c when using it to download a torrent.
1585 annex.http-headers
1587 HTTP headers to send when downloading from the web. Multiple
1588 lines of this option can be set, one per header.
1589 annex.http-headers-command
1591 If set, the command is run and each line of its output is used
1592 as a HTTP header. This overrides annex.http-headers.
1593 annex.security.allowed-url-schemes
1595 List of URL schemes that git-annex is allowed to download con‐
1596 tent from. The default is "http https ftp".
1597 Think very carefully before changing this; there are security
1599 implications. For example, if it's changed to allow "file" URLs,
1600 then anyone who can get a commit into your git-annex repository
1601 could git-annex addurl a pointer to a private file located out‐
1602 side that repository, possibly causing it to be copied into your
1603 repository and transferred on to other remotes, exposing its
1604 content.
1605 Some special remotes support their own domain-specific URL
1607 schemes; those are not affected by this configuration setting.
1608 annex.security.allowed-ip-addresses
1610 By default, git-annex only makes connections to public IP ad‐
1611 dresses; it will refuse to use HTTP and other servers on local‐
1612 host or on a private network.
1613 This setting can override that behavior, allowing access to par‐
1615 ticular IP addresses that would normally be blocked. For example
1616 "127.0.0.1 ::1" allows access to localhost (both IPV4 and IPV6).
1617 To allow access to all IP addresses, use "all"
1618 Think very carefully before changing this; there are security
1620 implications. Anyone who can get a commit into your git-annex
1621 repository could git annex addurl an url on a private server,
1622 possibly causing it to be downloaded into your repository and
1623 transferred to other remotes, exposing its content.
1624 Note that, since the interfaces of curl and youtube-dl do not
1626 allow these IP address restrictions to be enforced, curl and
1627 youtube-dl will never be used unless annex.security.al‐
1628 lowed-ip-addresses=all.
1629 To allow accessing local or private IP addresses on only spe‐
1631 cific ports, use the syntax "[addr]:port". For example,
1632 "[127.0.0.1]:80 [127.0.0.1]:443 [::1]:80 [::1]:443" allows lo‐
1633 calhost on the http ports only.
1634 annex.security.allowed-http-addresses
1636 Old name for annex.security.allowed-ip-addresses. If set, this
1637 is treated the same as having annex.security.allowed-ip-ad‐
1638 dresses set.
1639 annex.security.allow-unverified-downloads
1641 For security reasons, git-annex refuses to download content from
1642 most special remotes when it cannot check a hash to verify that
1643 the correct content was downloaded. This particularly impacts
1644 downloading the content of URL or WORM keys, which lack hashes.
1645 The best way to avoid problems due to this is to migrate files
1647 away from such keys, before their content reaches a special re‐
1648 mote. See git-annex-migrate(1).
1649 When the content is only available from a special remote, you
1651 can use this configuration to force git-annex to download it.
1652 But you do so at your own risk, and it's very important you read
1653 and understand the information below first!
1654 Downloading unverified content from encrypted special remotes is
1656 prevented, because the special remote could send some other en‐
1657 crypted content than what you expect, causing git-annex to de‐
1658 crypt data that you never checked into git-annex, and risking
1659 exposing the decrypted data to any non-encrypted remotes you
1660 send content to.
1661 Downloading unverified content from (non-encrypted) external
1663 special remotes is prevented, because they could follow http
1664 redirects to web servers on localhost or on a private network,
1665 or in some cases to a file:/// url.
1666 If you decide to bypass this security check, the best thing to
1668 do is to only set it temporarily while running the command that
1669 gets the file. The value to set the config to is "ACKTHPPT".
1670 For example:
1671 git -c annex.security.allow-unverified-downloads=ACKTHPPT annex
1673 get myfile
1674 It would be a good idea to check that it downloaded the file you
1676 expected, too.
1677 remote.<name>.annex-security-allow-unverified-downloads
1679 Per-remote configuration of annex.security.allow-unveri‐
1680 fied-downloads.
1681
1683 annex.delayadd
1684 Makes the watch and assistant commands delay for the specified
1686 number of seconds before adding a newly created file to the an‐
1687 nex. Normally this is not needed, because they already wait for
1688 all writers of the file to close it.
1689 annex.expireunused
1691 Controls what the assistant does about unused file contents that
1692 are stored in the repository.
1693 The default is false, which causes all old and unused file con‐
1695 tents to be retained, unless the assistant is able to move them
1696 to some other repository (such as a backup repository).
1697 Can be set to a time specification, like "7d" or "1m", and then
1699 file contents that have been known to be unused for a week or a
1700 month will be deleted.
1701 annex.fscknudge
1703 When set to false, prevents the webapp from reminding you when
1704 using repositories that lack consistency checks.
1705 annex.autoupgrade
1707 When set to ask (the default), the webapp will check for new
1708 versions and prompt if they should be upgraded to. When set to
1709 true, automatically upgrades without prompting (on some sup‐
1710 ported platforms). When set to false, disables any upgrade
1711 checking.
1712 Note that upgrade checking is only done when git-annex is in‐
1714 stalled from one of the prebuilt images from its website. This
1715 does not bypass e.g., a Linux distribution's own upgrade han‐
1716 dling code.
1717 This setting also controls whether to restart the git-annex as‐
1719 sistant when the git-annex binary is detected to have changed.
1720 That is useful no matter how you installed git-annex.
1721 annex.autocommit
1723 Set to false to prevent the git-annex assistant and git-annex
1724 sync from automatically committing changes to files in the
1725 repository.
1726 To configure the behavior in all clones of the repository, this
1728 can be set in git-annex-config(1).
1729 annex.startupscan
1731 Set to false to prevent the git-annex assistant from scanning
1732 the repository for new and changed files on startup. This will
1733 prevent it from noticing changes that were made while it was not
1734 running, but can be a useful performance tweak for a large
1735 repository.
1736 annex.listen
1738 Configures which address the webapp listens on. The default is
1739 localhost. Can be either an IP address, or a hostname that re‐
1740 solves to the desired address.
1741
1743 The key-value backend used when adding a new file to the annex can be
1744 configured on a per-file-type basis via .gitattributes files. In the
1745 file, the annex.backend attribute can be set to the name of the backend
1746 to use. For example, this here's how to use the WORM backend by de‐
1747 fault, but the SHA256E backend for ogg files:
1748 * annex.backend=WORM
1750 *.ogg annex.backend=SHA256E
1751 There is a annex.largefiles attribute, which is used to configure which
1753 files are large enough to be added to the annex. Since attributes can‐
1754 not contain spaces, it is difficult to use for more complex an‐
1755 nex.largefiles settings. Setting annex.largefiles in git-annex-con‐
1756 fig(1) is an easier way to configure it across all clones of the repos‐
1757 itory. See git-annex-matching-expression(1) for details on the syntax.
1758 The numcopies and mincopies settings can also be configured on a
1760 per-file-type basis via the annex.numcopies and annex.mincopies at‐
1761 tributes in .gitattributes files. This overrides other settings. For
1762 example, this makes two copies be needed for wav files and 3 copies for
1763 flac files:
1764 *.wav annex.numcopies=2
1766 *.flac annex.numcopies=3
1767 Note that setting numcopies or mincopies to 0 is very unsafe.
1769 These settings are honored by git-annex whenever it's operating on a
1771 matching file. However, when using --all, --unused, or --key to specify
1772 keys to operate on, git-annex is operating on keys and not files, so
1773 will not honor the settings from .gitattributes. For this reason, the
1774 git annex numcopies and git annex mincopies commands are useful to con‐
1775 figure a global default.
1776 Also note that when using views, only the toplevel .gitattributes file
1778 is preserved in the view, so other settings in other files won't have
1779 any effect.
1780
1782 git-annex, when called as a git subcommand, may return exit codes 0 or
1783 1 for success or failures, or, more rarely, 127 or 128 for certain very
1784 specific failures. git-annex itself should return 0 on success and 1
1785 on failure, unless the --time-limit=time option is hit, in which case
1786 it returns with exit code 101.
1787
1789 These environment variables are used by git-annex when set:
1790 GIT_WORK_TREE, GIT_DIR
1792 Handled the same as they are by git, see git(1)
1793 GIT_SSH, GIT_SSH_COMMAND
1795 Handled similarly to the same as described in git(1). The one
1796 difference is that git-annex will sometimes pass an additional
1797 "-n" parameter to these, as the first parameter, to prevent ssh
1798 from reading from stdin. Since that can break existing uses of
1799 these environment variables that don't expect the extra parame‐
1800 ter, you will need to set GIT_ANNEX_USE_GIT_SSH=1 to make git-
1801 annex support these.
1802 Note that setting either of these environment variables prevents
1804 git-annex from automatically enabling ssh connection caching
1805 (see annex.sshcaching), so it will slow down some operations
1806 with remotes over ssh. It's up to you to enable ssh connection
1807 caching if you need it; see ssh's documentation.
1808 Also, annex.ssh-options and remote.<name>.annex-ssh-options
1810 won't have any effect when these envionment variables are set.
1811 Usually it's better to configure any desired options through
1813 your ~/.ssh/config file, or by setting annex.ssh-options.
1814 GIT_ANNEX_VECTOR_CLOCK
1816 Normally git-annex timestamps lines in the log files committed
1817 to the git-annex branch. Setting this environment variable to a
1818 number will make git-annex use that rather than the current num‐
1819 ber of seconds since the UNIX epoch. Note that decimal seconds
1820 are supported.
1821 This is only provided for advanced users who either have a bet‐
1823 ter way to tell which commit is current than the local clock, or
1824 who need to avoid embedding timestamps for policy reasons. Mis‐
1825 use of this environment variable can confuse git-annex's
1826 book-keeping, sometimes in ways that git annex fsck is unable to
1827 repair.
1828 Some special remotes use additional environment variables
1830 for authentication etc. For example, AWS_ACCESS_KEY_ID and
1831 GIT_ANNEX_P2P_AUTHTOKEN. See special remote documentation.
1832
1834 These files are used by git-annex:
1835 .git/annex/objects/ in your git repository contains the annexed file
1837 contents that are currently available. Annexed files in your git repos‐
1838 itory symlink to that content.
1839 .git/annex/ in your git repository contains other run-time information
1841 used by git-annex.
1842 ~/.config/git-annex/autostart is a list of git repositories to start
1844 the git-annex assistant in.
1845 .git/hooks/pre-commit-annex in your git repository will be run whenever
1847 a commit is made to the HEAD branch, either by git commit, git-annex
1848 sync, or the git-annex assistant.
1849 .git/hooks/post-update-annex in your git repository will be run when‐
1851 ever the git-annex branch is updated. You can make this hook run git
1852 update-server-info when publishing a git-annex repository by http.
1853
1855 More git-annex documentation is available on its web site,
1856 <https://git-annex.branchable.com/>
1857 If git-annex is installed from a package, a copy of its documentation
1859 should be included, in, for example, /usr/share/doc/git-annex/.
1860
1862 Joey Hess <id@joeyh.name>
1863 <https://git-annex.branchable.com/>
1865 git-annex(1)