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 trust [repository ...]
215 Records that a repository is trusted to not unexpectedly lose
216 content. Use with care.
217 See git-annex-trust(1) for details.
219 untrust [repository ...]
221 Records that a repository is not trusted and could lose content
222 at any time.
223 See git-annex-untrust(1) for details.
225 semitrust [repository ...]
227 Returns a repository to the default semi trusted state.
228 See git-annex-semitrust(1) for details.
230 group repository groupname
232 Add a repository to a group.
233 See git-annex-group(1) for details.
235 ungroup repository groupname
237 Removes a repository from a group.
238 See git-annex-ungroup(1) for details.
240 wanted repository [expression]
242 Get or set preferred content expression.
243 See git-annex-wanted(1) for details.
245 groupwanted groupname [expression]
247 Get or set groupwanted expression.
248 See git-annex-groupwanted(1) for details.
250 required repository [expression]
252 Get or set required content expression.
253 See git-annex-required(1) for details.
255 schedule repository [expression]
257 Get or set scheduled jobs.
258 See git-annex-schedule(1) for details.
260 config Get and set other configuration stored in git-annex branch.
262 See git-annex-config(1) for details.
264 vicfg Opens EDITOR on a temp file containing most of the above config‐
266 uration settings, as well as a few others, and when it exits,
267 stores any changes made back to the git-annex branch.
268 See git-annex-vicfg(1) for details.
270 adjust Switches a repository to use an adjusted branch, which can auto‐
272 matically unlock all files, etc.
273 See git-annex-adjust(1) for details.
275 direct Switches a repository to use direct mode. (deprecated)
277 See git-annex-direct(1) for details.
279 indirect
281 Switches a repository to use indirect mode. (deprecated)
282 See git-annex-indirect(1) for details.
284
286 fsck [path ...]
287 Checks the annex consistency, and warns about or fixes any prob‐
289 lems found. This is a good complement to git fsck.
290 See git-annex-fsck(1) for details.
292 expire [repository:]time ...
294 Expires repositories that have not recently performed an activ‐
295 ity (such as a fsck).
296 See git-annex-expire(1) for details.
298 unused Checks the annex for data that does not correspond to any files
300 present in any tag or branch, and prints a numbered list of the
301 data.
302 See git-annex-unused(1) for details.
304 dropunused [number|range ...]
306 Drops the data corresponding to the numbers, as listed by the
307 last git annex unused
308 See git-annex-dropunused(1) for details.
310 addunused [number|range ...]
312 Adds back files for the content corresponding to the numbers or
313 ranges, as listed by the last git annex unused.
314 See git-annex-addunused(1) for details.
316 fix [path ...]
318 Fixes up symlinks that have become broken to again point to
319 annexed content.
320 See git-annex-fix(1) for details.
322 merge Automatically merge changes from remotes.
324 See git-annex-merge(1) for details.
326 upgrade
328 Upgrades the repository.
329 See git-annex-upgrade(1) for details.
331 dead [repository ...] [--key key]
333 Indicates that a repository or a single key has been irretriev‐
334 ably lost.
335 See git-annex-dead(1) for details.
337 forget Causes the git-annex branch to be rewritten, throwing away his‐
339 torical data about past locations of files.
340 See git-annex-forget(1) for details.
342 repair This can repair many of the problems with git repositories that
344 git fsck detects, but does not itself fix. It's useful if a
345 repository has become badly damaged. One way this can happen is
346 if a repository used by git-annex is on a removable drive that
347 gets unplugged at the wrong time.
348 See git-annex-repair(1) for details.
350 p2p Configure peer-2-Peer links between repositories.
352 See git-annex-p2p(1) for details.
354
356 find [path ...]
357 Outputs a list of annexed files in the specified path. With no
359 path, finds files in the current directory and its subdirecto‐
360 ries.
361 See git-annex-find(1) for details.
363 whereis [path ...]
365 Displays information about where the contents of files are
366 located.
367 See git-annex-whereis(1) for details.
369 list [path ...]
371 Displays a table of remotes that contain the contents of the
372 specified files. This is similar to whereis but a more compact
373 display.
374 See git-annex-list(1) for details.
376 log [path ...]
378 Displays the location log for the specified file or files, show‐
379 ing each repository they were added to ("+") and removed from
380 ("-").
381 See git-annex-log(1) for details.
383 info [directory|file|remote|uuid ...]
385 Displays statistics and other information for the specified
386 item, which can be a directory, or a file, or a remote, or the
387 uuid of a repository.
388 When no item is specified, displays statistics and information
390 for the repository as a whole.
391 See git-annex-info(1) for details.
393 version
395 Shows the version of git-annex, as well as repository version
396 information.
397 See git-annex-version(1) for details.
399 map Generate map of repositories.
401 See git-annex-map(1) for details.
403 inprogress
405 Access files while they're being downloaded.
406 See git-annex-inprogress(1) for details.
408
410 metadata [path ...]
411 The content of an annexed file can have any number of metadata
413 fields attached to it to describe it. Each metadata field can in
414 turn have any number of values.
415 This command can be used to set metadata, or show the currently
417 set metadata.
418 See git-annex-metadata(1) for details.
420 view [tag ...] [field=value ...] [field=glob ...] [!tag ...]
422 [field!=value ...]
423 Uses metadata to build a view branch of the files in the current
424 branch, and checks out the view branch. Only files in the cur‐
425 rent branch whose metadata matches all the specified field val‐
426 ues and tags will be shown in the view.
427 See git-annex-view(1) for details.
429 vpop [N]
431 Switches from the currently active view back to the previous
432 view. Or, from the first view back to original branch.
433 See git-annex-vpop(1) for details.
435 vfilter [tag ...] [field=value ...] [!tag ...] [field!=value ...]
437 Filters the current view to only the files that have the speci‐
438 fied field values and tags.
439 See git-annex-vfilter(1) for details.
441 vadd [field=glob ...] [field=value ...] [tag ...]
443 Changes the current view, adding an additional level of directo‐
444 ries to categorize the files.
445 See git-annex-vfilter(1) for details.
447 vcycle When a view involves nested subdirectories, this cycles the
449 order.
450 See git-annex-vcycle(1) for details.
452
454 migrate [path ...]
455 Changes the specified annexed files to use a different key-value
457 backend.
458 See git-annex-migrate(1) for details.
460 reinject src dest
462 Moves the src file into the annex as the content of the dest
463 file. This can be useful if you have obtained the content of a
464 file from elsewhere and want to put it in the local annex.
465 See git-annex-reinject(1) for details.
467 unannex [path ...]
469 Use this to undo an accidental git annex add command. It puts
470 the file back how it was before the add.
471 See git-annex-unannex(1) for details.
473 uninit De-initialize git-annex and clean out repository.
475 See git-annex-uninit(1) for details.
477 reinit uuid|description
479 Initialize repository, reusing old UUID.
480 See git-annex-reinit(1) for details.
482
484 pre-commit [path ...]
485 This is meant to be called from git's pre-commit hook. git annex
487 init automatically creates a pre-commit hook using this.
488 See git-annex-pre-commit(1) for details.
490 post-receive
492 This is meant to be called from git's post-receive hook. git
493 annex init automatically creates a post-receive hook using this.
494 See git-annex-post-receive(1) for details.
496 lookupkey [file ...]
498 Looks up key used for file.
499 See git-annex-lookupkey(1) for details.
501 calckey [file ...]
503 Calculates the key that would be used to refer to a file.
504 See git-annex-calckey(1) for details.
506 contentlocation [key ..]
508 Looks up location of annexed content for a key.
509 See git-annex-contentlocation(1) for details.
511 examinekey [key ...]
513 Print information that can be determined purely by looking at
514 the key.
515 See git-annex-examinekey(1) for details.
517 matchexpression
519 Checks if a preferred content expression matches provided data.
520 See git-annex-matchexpression(1) for details.
522 fromkey [key file]
524 Manually set up a file in the git repository to link to a speci‐
525 fied key.
526 See git-annex-fromkey(1) for details.
528 registerurl [key url]
530 Registers an url for a key.
531 See git-annex-registerurl(1) for details.
533 setkey key file
535 Moves a file into the annex as the content of a key.
536 See git-annex-setkey(1) for details.
538 dropkey [key ...]
540 Drops annexed content for specified keys.
541 See git-annex-dropkey(1) for details.
543 transferkey key [--from=remote|--to=remote]
545 Transfers a key from or to a remote.
546 See git-annex-transferkey(1) for details.
548 transferrer
550 Used internally by git-annex to transfer content.
551 See git-annex-transferrer(1) for details.
553 transferkeys
555 Used internally by old versions of the assistant.
556 See git-annex-transferkey(1) for details.
558 setpresentkey key uuid [1|0]
560 This plumbing-level command changes git-annex's records about
561 whether the specified key's content is present in a remote with
562 the specified uuid.
563 See git-annex-setpresentkey(1) for details.
565 readpresentkey key uuid
567 Read records of where key is present.
568 See git-annex-readpresentkey(1) for details.
570 checkpresentkey key remote
572 Check if key is present in remote.
573 See git-annex-checkpresentkey(1) for details.
575 rekey [file key ...]
577 Change keys used for files.
578 See git-annex-rekey(1) for details.
580 resolvemerge
582 Resolves a conflicted merge, by adding both conflicting versions
583 of the file to the tree, using variants of their filename. This
584 is done automatically when using git annex sync or git annex
585 merge.
586 See git-annex-resolvemerge(1) for details.
588 diffdriver
590 This can be used to make git diff use an external diff driver
591 with annexed files.
592 See git-annex-diffdriver(1) for details.
594 smudge This command lets git-annex be used as a git filter driver,
596 allowing annexed files in the git repository to be unlocked at
597 all times, instead of being symlinks.
598 See git-annex-smudge(1) for details.
600 findref [ref]
602 Lists files in a git ref. (deprecated)
603 See git-annex-findref(1) for details.
605 proxy -- git cmd [options]
607 Bypass direct mode guard. (deprecated)
608 See git-annex-proxy(1) for details.
610
612 test
613 This runs git-annex's built-in test suite.
615 See git-annex-test(1) for details.
617 testremote remote
619 This tests a remote by generating some random objects and send‐
620 ing them to the remote, then redownloading them, removing them
621 from the remote, etc.
622 It's safe to run in an existing repository (the repository con‐
624 tents are not altered), although it may perform expensive data
625 transfers.
626 See git-annex-testremote(1) for details.
628 fuzztest
630 Generates random changes to files in the current repository, for
631 use in testing the assistant.
632 See git-annex-fuzztest(1) for details.
634 benchmark
636 This runs git-annex's built-in benchmarks, if it was built with
637 benchmarking support.
638 See git-annex-benchmark(1) for details.
640
642 These common options are accepted by all git-annex commands, and may
643 not be explicitly listed on their individual man pages. (Many commands
644 also accept the git-annex-matching-options(1).)
645 --force
647 Force unsafe actions, such as dropping a file's content when no
648 other source of it can be verified to still exist, or adding
649 ignored files. Use with care.
650 --fast Enable less expensive, but also less thorough versions of some
652 commands. What is avoided depends on the command.
653 --quiet
655 Avoid the default verbose display of what is done; only show
656 errors.
657 --verbose
659 Enable verbose display.
660 --debug
662 Show debug messages.
663 --no-debug
665 Disable debug messages.
666 --numcopies=n
668 Overrides the numcopies setting, forcing git-annex to ensure the
669 specified number of copies exist.
670 Note that setting numcopies to 0 is very unsafe.
672 --time-limit=time
674 Limits how long a git-annex command runs. The time can be some‐
675 thing like "5h", or "30m" or even "45s" or "10d".
676 Note that git-annex may continue running a little past the spec‐
678 ified time limit, in order to finish processing a file.
679 Also, note that if the time limit prevents git-annex from doing
681 all it was asked to, it will exit with a special code, 101.
682 --trust=repository
684 --semitrust=repository
686 --untrust=repository
688 Overrides trust settings for a repository. May be specified more
689 than once.
690 The repository should be specified using the name of a config‐
692 ured remote, or the UUID or description of a repository.
693 --trust-glacier
695 Amazon Glacier inventories take hours to retrieve, and may not
696 represent the current state of a repository. So git-annex does
697 not trust that files that the inventory claims are in Glacier
698 are really there. This switch can be used to allow it to trust
699 the inventory.
700 Be careful using this, especially if you or someone else might
702 have recently removed a file from Glacier. If you try to drop
703 the only other copy of the file, and this switch is enabled, you
704 could lose data!
705 --backend=name
707 Specifies which key-value backend to use. This can be used when
708 adding a file to the annex, or migrating a file. Once files are
709 in the annex, their backend is known and this option is not nec‐
710 essary.
711 --user-agent=value
713 Overrides the User-Agent to use when downloading files from the
714 web.
715 --notify-finish
717 Caused a desktop notification to be displayed after each suc‐
718 cessful file download and upload.
719 (Only supported on some platforms, e.g. Linux with dbus. A no-op
721 when not supported.)
722 --notify-start
724 Caused a desktop notification to be displayed when a file upload
725 or download has started, or when a file is dropped.
726 -c name=value
728 Overrides git configuration settings. May be specified multiple
729 times.
730
732 Like other git commands, git-annex is configured via .git/config.
733 These settings, as well as relevant git config settings, are the ones
734 git-annex uses.
735 (Some of these settings can also be set, across all clones of the
737 repository, using git-annex-config. See its man page for a list.)
738 annex.uuid
740 A unique UUID for this repository (automatically set).
741 annex.backend
743 Name of the default key-value backend to use when adding new
744 files to the repository.
745 This is overridden by annex annex.backend configuration in the
747 .gitattributes files, and by the --backend option.
748 (This used to be named annex.backends, and that will still be
750 used if set.)
751 annex.securehashesonly
753 Set to true to indicate that the repository should only use
754 cryptographically secure hashes (SHA2, SHA3) and not insecure
755 hashes (MD5, SHA1) for content.
756 When this is set, the contents of files using cryptographically
758 insecure hashes will not be allowed to be added to the reposi‐
759 tory.
760 Also, git-annex fsck will complain about any files present in
762 the repository that use insecure hashes. And, git-annex import
763 --no-content will refuse to import files from special remotes
764 using insecure hashes.
765 To configure the behavior in new clones of the repository, this
767 can be set using git-annex-config.
768 annex.maxextensionlength
770 Maximum length, in bytes, of what is considered a filename
771 extension when adding a file to a backend that preserves file‐
772 name extensions. The default length is 4, which allows exten‐
773 sions like "jpeg". The dot before the extension is not counted
774 part of its length. At most two extensions at the end of a file‐
775 name will be preserved, e.g. .gz or .tar.gz .
776 annex.diskreserve
778 Amount of disk space to reserve. Disk space is checked when
779 transferring content to avoid running out, and additional free
780 space can be reserved via this option, to make space for more
781 important content (such as git commit logs). Can be specified
782 with any commonly used units, for example, "0.5 gb", "500M", or
783 "100 KiloBytes"
784 The default reserve is 1 megabyte.
786 annex.skipunknown
788 Set to true to make commands like "git-annex get" silently skip
789 over items that are listed in the command line, but are not
790 checked into git.
791 Set to false to make it an error for commands like "git-annex
793 get" to be asked to operate on files that are not checked into
794 git.
795 The default is currently true, but is planned to change to false
797 in a release in 2022.
798 Note that, when annex.skipunknown is false, a command like "git-
800 annex get ." will fail if no files in the current directory are
801 checked into git, but a command like "git-annex get" will not
802 fail, because the current directory is not listed, but is
803 implicit. Commands like "git-annex get foo/" will fail if no
804 files in the directory are checked into git, but if at least one
805 file is, it will ignore other files that are not. This is all
806 the same as the behavior of "git-ls files --error-unmatch".
807 Also note that git-annex skips files that are checked into git,
809 but are not annexed files, this setting does not affect that.
810 annex.largefiles
812 Used to configure which files are large enough to be added to
813 the annex. It is an expression that matches the large files, eg
814 "include=*.mp3 or largerthan(500kb)" See git-annex-match‐
815 ing-expression(1) for details on the syntax.
816 Overrides any annex.largefiles attributes in .gitattributes
818 files.
819 To configure a default annex.largefiles for all clones of the
821 repository, this can be set in git-annex-config(1).
822 This configures the behavior of both git-annex and git when
824 adding files to the repository. By default, git-annex add adds
825 all files to the annex (except dotfiles), and git add adds files
826 to git (unless they were added to the annex previously). When
827 annex.largefiles is configured, both git annex add and git add
828 will add matching large files to the annex, and the other files
829 to git.
830 Other git-annex commands also honor annex.largefiles, including
832 git annex import, git annex addurl, git annex importfeed and the
833 assistant.
834 annex.dotfiles
836 Normally, dotfiles are assumed to be files like .gitignore,
837 whose content should always be part of the git repository, so
838 they will not be added to the annex. Setting annex.dotfiles to
839 true makes dotfiles be added to the annex the same as any other
840 file.
841 To annex only some dotfiles, set this and configure annex.large‐
843 files to match the ones you want. For example, to match only
844 dotfiles ending in ".big"
845 git config annex.largefiles "(include=.*.big or
847 include=*/.*.big) or (exclude=.* and exclude=*/.*)"
848 git config annex.dotfiles true
849 To configure a default annex.dotfiles for all clones of the
851 repository, this can be set in git-annex-config(1).
852 annex.gitaddtoannex
854 Setting this to false will prevent git add from adding files to
855 the annex, despite the annex.largefiles configuration.
856 annex.addsmallfiles
858 Controls whether small files (not matching annex.largefiles)
859 should be checked into git by git annex add. Defaults to true;
860 set to false to instead make small files be skipped.
861 annex.addunlocked
863 Commands like git-annex add default to adding files to the
864 repository in locked form. This can make them add the files in
865 unlocked form, the same as if git-annex-unlock(1) were run on
866 the files.
867 This can be set to "true" to add everything unlocked, or it can
869 be a more complicated expression that matches files by name,
870 size, or content. See git-annex-matching-expression(1) for
871 details.
872 To configure a default annex.addunlocked for all clones of the
874 repository, this can be set in git-annex-config(1).
875 (Using git add always adds files in unlocked form and it is not
877 affected by this setting.)
878 When a repository has core.symlinks set to false, or has an
880 adjusted unlocked branch checked out, this setting is ignored,
881 and files are always added to the repository in unlocked form.
882 annex.numcopies
884 This is a deprecated setting. You should instead use the git
885 annex numcopies command to configure how many copies of files
886 are kept across all repositories, or the annex.numcopies .gitat‐
887 tributes setting.
888 This config setting is only looked at when git annex numcopies
890 has never been configured, and when there's no annex.numcopies
891 setting in the .gitattributes file.
892 Note that setting numcopies to 0 is very unsafe.
894 annex.genmetadata
896 Set this to true to make git-annex automatically generate some
897 metadata when adding files to the repository.
898 In particular, it stores year, month, and day metadata, from the
900 file's modification date.
901 When importfeed is used, it stores additional metadata from the
903 feed, such as the author, title, etc.
904 annex.used-refspec
906 This controls which refs git-annex unused considers to be used.
907 See REFSPEC FORMAT in git-annex-unused(1) for details.
908 annex.jobs
910 Configure the number of concurrent jobs to run. Default is 1.
911 Only git-annex commands that support the --jobs option will use
913 this.
914 Setting this to "cpus" will run one job per CPU core.
916 When the --batch option is used, this configuration is ignored.
918 annex.adjustedbranchrefresh
920 When git-annex-adjust(1) is used to set up an adjusted branch
921 that needs to be refreshed after getting or dropping files, this
922 config controls how frequently the branch is refreshed.
923 Refreshing the branch takes some time, so doing it after every
925 file can be too slow. (It also can generate a lot of dangling
926 git objects.) The default value is 0 (or false), which does not
927 refresh the branch. Setting 1 (or true) will refresh only once,
928 after git-annex has made other changes. Setting 2 refreshes
929 after every file, 3 after every other file, and so on; setting
930 100 refreshes after every 99 files.
931 (If git-annex gets faster in the future, refresh rates will
933 increase proportional to the speed improvements.)
934 annex.queuesize
936 git-annex builds a queue of git commands, in order to combine
937 similar commands for speed. By default the size of the queue is
938 limited to 10240 commands; this can be used to change the size.
939 If you have plenty of memory and are working with very large
940 numbers of files, increasing the queue size can speed it up.
941 annex.bloomcapacity
943 The git annex unused and git annex sync --content commands use a
944 bloom filter to determine what files are present in eg, the work
945 tree. The default bloom filter is sized to handle up to 500000
946 files. If your repository is larger than that, you should
947 increase this value. Larger values will make git-annex unused
948 and git annex sync --content consume more memory; run git annex
949 info for memory usage numbers.
950 annex.bloomaccuracy
952 Adjusts the accuracy of the bloom filter used by git annex
953 unused and git annex sync --content. The default accuracy is
954 10000000 -- 1 unused file out of 10000000 will be missed by git
955 annex unused. Increasing the accuracy will make git annex unused
956 consume more memory; run git annex info for memory usage num‐
957 bers.
958 annex.sshcaching
960 By default, git-annex caches ssh connections using ssh's Con‐
961 trolMaster and ControlPersist settings (if built using a new
962 enough ssh). To disable this, set to false.
963 annex.alwayscommit
965 By default, git-annex automatically commits data to the git-
966 annex branch after each command is run. If you have a series of
967 commands that you want to make a single commit, you can run the
968 commands with -c annex.alwayscommit=false. You can later commit
969 the data by running git annex merge (or by automatic merges) or
970 git annex sync.
971 annex.commitmessage
973 When git-annex updates the git-annex branch, it usually makes up
974 its own commit message ("update"), since users rarely look at or
975 care about changes to that branch. If you do care, you can spec‐
976 ify this setting by running commands with -c annex.commitmes‐
977 sage=whatever
978 This works well in combination with annex.alwayscommit=false, to
980 gather up a set of changes and commit them with a message you
981 specify.
982 annex.allowsign
984 By default git-annex avoids gpg signing commits that it makes
985 when they're not the purpose of a command, but only a side
986 effect. That default avoids lots of gpg password prompts when
987 commit.gpgSign is set. A command like git annex sync or git
988 annex merge will gpg sign its commit, but a command like git
989 annex get, that updates the git-annex branch, will not. The
990 assistant also avoids signing commits.
991 Setting annex.allowsign to true lets all commits be signed, as
993 controlled by commit.gpgSign and other git configuration.
994 annex.merge-annex-branches
996 By default, git-annex branches that have been pulled from
997 remotes are automatically merged into the local git-annex
998 branch, so that git-annex has the most up-to-date possible
999 knowledge.
1000 To avoid that merging, set this to "false". This can be useful
1002 particularly when you don't have write permission to the reposi‐
1003 tory.
1004 annex.hardlink
1006 Set this to true to make file contents be hard linked between
1007 the repository and its remotes when possible, instead of a more
1008 expensive copy.
1009 Use with caution -- This can invalidate numcopies counting,
1011 since with hard links, fewer copies of a file can exist. So, it
1012 is a good idea to mark a repository using this setting as
1013 untrusted.
1014 When a repository is set up using git clone --shared, git-annex
1016 init will automatically set annex.hardlink and mark the reposi‐
1017 tory as untrusted.
1018 When annex.thin is also set, setting annex.hardlink has no
1020 effect.
1021 annex.thin
1023 Set this to true to make unlocked files be a hard link to their
1024 content in the annex, rather than a second copy. This can save
1025 considerable disk space, but when a modification is made to a
1026 file, you will lose the local (and possibly only) copy of the
1027 old version. So, enable with care.
1028 After setting (or unsetting) this, you should run git annex fix
1030 to fix up the annexed files in the work tree to be hard links
1031 (or copies).
1032 Note that this has no effect when the filesystem does not sup‐
1034 port hard links. And when multiple files in the work tree have
1035 the same content, only one of them gets hard linked to the
1036 annex.
1037 annex.resolvemerge
1039 Set to false to prevent merge conflicts in the checked out
1040 branch being automatically resolved by the git-annex assitant,
1041 git-annex sync, git-annex merge, and the git-annex post-receive
1042 hook.
1043 To configure the behavior in all clones of the repository, this
1045 can be set in git-annex-config(1).
1046 annex.synccontent
1048 Set to true to make git-annex sync default to syncing annexed
1049 content.
1050 To configure the behavior in all clones of the repository, this
1052 can be set in git-annex-config(1).
1053 annex.synconlyannex
1055 Set to true to make git-annex sync default to only sincing the
1056 git-annex branch and annexed content.
1057 To configure the behavior in all clones of the repository, this
1059 can be set in git-annex-config(1).
1060 annex.debug
1062 Set to true to enable debug logging by default.
1063 annex.version
1065 The current version of the git-annex repository. This is main‐
1066 tained by git-annex and should never be manually changed.
1067 annex.autoupgraderepository
1069 When an old git-annex repository version has become deprecated,
1070 git-annex will normally automatically upgrade the repository to
1071 the new version.
1072 If this is set to false, git-annex won't automatically upgrade
1074 the repository. Instead it will exit with an error message. You
1075 can run git annex upgrade yourself when you are ready to upgrade
1076 the repository.
1077 annex.crippledfilesystem
1079 Set to true if the repository is on a crippled filesystem, such
1080 as FAT, which does not support symbolic links, or hard links, or
1081 unix permissions. This is automatically probed by "git annex
1082 init".
1083 annex.pidlock
1085 Normally, git-annex uses fine-grained lock files to allow multi‐
1086 ple processes to run concurrently without getting in each oth‐
1087 ers' way. That works great, unless you are using git-annex on a
1088 filesystem that does not support POSIX fcntl locks. This is
1089 sometimes the case when using NFS or Lustre filesystems.
1090 To support such situations, you can set annex.pidlock to true,
1092 and it will fall back to a single top-level pid file lock.
1093 Although, often, you'd really be better off fixing your net‐
1095 worked filesystem configuration to support POSIX locks.. And,
1096 some networked filesystems are so inconsistent that one node
1097 can't reliably tell when the other node is holding a pid lock.
1098 Caveat emptor.
1099 annex.pidlocktimeout
1101 git-annex will wait up to this many seconds for the pid lock
1102 file to go away, and will then abort if it cannot continue.
1103 Default: 300
1104 When using pid lock files, it's possible for a stale lock file
1106 to get left behind by previous run of git-annex that crashed or
1107 was interrupted. This is mostly avoided, but can occur espe‐
1108 cially when using a network file system. This timeout prevents
1109 git-annex waiting forever in such a situation.
1110 annex.cachecreds
1112 When "true" (the default), git-annex will cache credentials used
1113 to access special remotes in files in .git/annex/creds/ that
1114 only you can read. To disable that caching, set to "false", and
1115 credentials will only be read from the environment, or if they
1116 have been embedded in encrypted form in the git repository, will
1117 be extracted and decrypted each time git-annex needs to access
1118 the remote.
1119 annex.secure-erase-command
1121 This can be set to a command that should be run whenever git-
1122 annex removes the content of a file from the repository.
1123 In the command line, %file is replaced with the file that should
1125 be erased.
1126 For example, to use the wipe command, set it to wipe -f %file.
1128 annex.tune.objecthash1, annex.tune.objecthashlower, annex.tune.branch‐
1130 hash1
1131 These can be passed to git annex init to tune the repository.
1132 They cannot be safely changed in a running repository and should
1133 never be set in global git configuration. For details, see
1134 <https://git-annex.branchable.com/tuning/>.
1135
1137 Remotes are configured using these settings in .git/config.
1138 remote.<name>.annex-cost
1140 When determining which repository to transfer annexed files from
1141 or to, ones with lower costs are preferred. The default cost is
1142 100 for local repositories, and 200 for remote repositories.
1143 remote.<name>.annex-cost-command
1145 If set, the command is run, and the number it outputs is used as
1146 the cost. This allows varying the cost based on e.g., the cur‐
1147 rent network.
1148 remote.<name>.annex-start-command
1150 A command to run when git-annex begins to use the remote. This
1151 can be used to, for example, mount the directory containing the
1152 remote.
1153 The command may be run repeatedly when multiple git-annex pro‐
1155 cesses are running concurrently.
1156 remote.<name>.annex-stop-command
1158 A command to run when git-annex is done using the remote.
1159 The command will only be run once *all* running git-annex pro‐
1161 cesses are finished using the remote.
1162 remote.<name>.annex-shell
1164 Specify an alternative git-annex-shell executable on the remote
1165 instead of looking for "git-annex-shell" on the PATH.
1166 This is useful if the git-annex-shell program is outside the
1168 PATH or has a non-standard name.
1169 remote.<name>.annex-ignore
1171 If set to true, prevents git-annex from storing file contents on
1172 this remote by default. (You can still request it be used by
1173 the --from and --to options.)
1174 This is, for example, useful if the remote is located somewhere
1176 without git-annex-shell. (For example, if it's on GitHub). Or,
1177 it could be used if the network connection between two reposito‐
1178 ries is too slow to be used normally.
1179 This does not prevent git-annex sync (or the git-annex assis‐
1181 tant) from syncing the git repository to the remote.
1182 remote.<name>.annex-ignore-command
1184 If set, the command is run, and if it exits nonzero, that's the
1185 same as setting annex-ignore to true. This allows controlling
1186 behavior based on e.g., the current network.
1187 remote.<name>.annex-sync
1189 If set to false, prevents git-annex sync (and the git-annex
1190 assistant) from syncing with this remote by default. However,
1191 git annex sync <name> can still be used to sync with the remote.
1192 remote.<name>.annex-sync-command
1194 If set, the command is run, and if it exits nonzero, that's the
1195 same as setting annex-sync to false. This allows controlling
1196 behavior based on e.g., the current network.
1197 remote.<name>.annex-pull
1199 If set to false, prevents git-annex sync (and the git-annex
1200 assistant etc) from ever pulling (or fetching) from the remote.
1201 remote.<name>.annex-push
1203 If set to false, prevents git-annex sync (and the git-annex
1204 assistant etc) from ever pushing to the remote.
1205 remote.<name>.annex-readonly
1207 If set to true, prevents git-annex from making changes to a
1208 remote. This both prevents git-annex sync from pushing changes,
1209 and prevents storing or removing files from read-only remote.
1210 remote.<name>.annex-verify, annex.verify
1212 By default, git-annex will verify the checksums of objects down‐
1213 loaded from remotes. If you trust a remote and don't want the
1214 overhead of these checksums, you can set this to false.
1215 Note that even when this is set to false, git-annex does verifi‐
1217 cation in some edge cases, where it's likely the case than an
1218 object was downloaded incorrectly, or when needed for security.
1219 remote.<name>.annex-tracking-branch
1221 This is for use with special remotes that support exports and
1222 imports.
1223 When set to eg, "master", this tells git-annex that you want the
1225 special remote to track that branch.
1226 When set to eg, "master:subdir", the special remote tracks only
1228 the subdirectory of that branch.
1229 git-annex sync --content will import changes from the remote and
1231 merge them into the annex-tracking-branch. They also export
1232 changes made to the branch to the remote.
1233 remote.<name>.annex-export-tracking
1235 Deprecated name for remote.<name>.annex-tracking-branch. Will
1236 still be used if it's configured and remote.<name>.annex-track‐
1237 ing-branch is not.
1238 remote.<name>.annexUrl
1240 Can be used to specify a different url than the regular
1241 remote.<name>.url for git-annex to use when talking with the
1242 remote. Similar to the pushUrl used by git-push.
1243 remote.<name>.annex-uuid
1245 git-annex caches UUIDs of remote repositories here.
1246 remote.<name>.annex-config-uuid
1248 Used for some special remotes, points to a different special
1249 remote configuration to use.
1250 remote.<name>.annex-retry, annex.retry
1252 Number of times a transfer that fails can be retried. (default
1253 0)
1254 remote.<name>.annex-forward-retry, annex.forward-retry
1256 If a transfer made some forward progress before failing, this
1257 allows it to be retried even when annex.retry does not. The
1258 value is the maximum number of times to do that. (default 5)
1259 When both annex.retry and this are set, the maximum number of
1261 retries is the larger of the two.
1262 remote.<name>.annex-retry-delay, annex.retry-delay
1264 Number of seconds to delay before the first retry of a transfer.
1265 When making multiple retries of the same transfer, the delay
1266 doubles after each retry. (default 1)
1267 remote.<name>.annex-stalldetecton, annex.stalldetection
1269 This lets stalled or too-slow transfers be detected, and dealt
1270 with, so rather than getting stuck, git-annex will cancel the
1271 stalled operation. When this happens, the transfer will be con‐
1272 sidered to have failed, so settings like annex.retry will con‐
1273 trol what it does next.
1274 The value specifies how much data git-annex should expect to see
1276 flowing, minimum, when it's not stalled, over a given period of
1277 time. The format is "$amount/$timeperiod".
1278 For example, to detect outright stalls where no data has been
1280 transferred after 30 seconds: git config annex.stalldetection
1281 "0/30s"
1282 Or, if you have a remote on a USB drive that is normally capable
1284 of several megabytes per second, but has bad sectors where it
1285 gets stuck for a long time, you could use: git config
1286 remote.usbdrive.annex-stalldetection "1MB/1m"
1287 This is not enabled by default, because it can make git-annex
1289 use more resources. To be able to cancel stalls, git-annex has
1290 to run transfers in separate processes (one per concurrent job).
1291 So it may need to open more connections to a remote than usual,
1292 or the communication with those processes may make it a bit
1293 slower.
1294 remote.<name>.annex-checkuuid
1296 This only affects remotes that have their url pointing to a
1297 directory on the same system. git-annex normally checks the uuid
1298 of such remotes each time it's run, which lets it transparently
1299 deal with different drives being mounted to the location at dif‐
1300 ferent times.
1301 Setting annex-checkuuid to false will prevent it from checking
1303 the uuid at startup (although the uuid is still verified before
1304 making any changes to the remote repository). This may be useful
1305 to set to prevent unncessary spin-up or automounting of a drive.
1306 remote.<name>.annex-trustlevel
1308 Configures a local trust level for the remote. This overrides
1309 the value configured by the trust and untrust commands. The
1310 value can be any of "trusted", "semitrusted" or "untrusted".
1311 remote.<name>.annex-availability
1313 Can be used to tell git-annex whether a remote is LocallyAvail‐
1314 able or GloballyAvailable. Normally, git-annex determines this
1315 automatically.
1316 remote.<name>.annex-speculate-present
1318 Set to "true" to make git-annex speculate that this remote may
1319 contain the content of any file, even though its normal location
1320 tracking does not indicate that it does. This will cause git-
1321 annex to try to get all file contents from the remote. Can be
1322 useful in setting up a caching remote.
1323 remote.<name>.annex-bare
1325 Can be used to tell git-annex if a remote is a bare repository
1326 or not. Normally, git-annex determines this automatically.
1327 remote.<name>.annex-ssh-options
1329 Options to use when using ssh to talk to this remote.
1330 remote.<name>.annex-rsync-options
1332 Options to use when using rsync to or from this remote. For
1333 example, to force IPv6, and limit the bandwidth to 100Kbyte/s,
1334 set it to -6 --bwlimit 100
1335 Note that git-annex-shell has a whitelist of allowed rsync
1337 options, and others will not be be passed to the remote rsync.
1338 So using some options may break the communication between the
1339 local and remote rsyncs.
1340 remote.<name>.annex-rsync-upload-options
1342 Options to use when using rsync to upload a file to a remote.
1343 These options are passed after other applicable rsync options,
1345 so can be used to override them. For example, to limit upload
1346 bandwidth to 10Kbyte/s, set --bwlimit 10.
1347 remote.<name>.annex-rsync-download-options
1349 Options to use when using rsync to download a file from a
1350 remote.
1351 These options are passed after other applicable rsync options,
1353 so can be used to override them.
1354 remote.<name>.annex-rsync-transport
1356 The remote shell to use to connect to the rsync remote. Possible
1357 values are ssh (the default) and rsh, together with their argu‐
1358 ments, for instance ssh -p 2222 -c blowfish; Note that the
1359 remote hostname should not appear there, see rsync(1) for
1360 details. When the transport used is ssh, connections are auto‐
1361 matically cached unless annex.sshcaching is unset.
1362 remote.<name>.annex-bup-split-options
1364 Options to pass to bup split when storing content in this
1365 remote. For example, to limit the bandwidth to 100Kbyte/s, set
1366 it to --bwlimit 100k (There is no corresponding option for bup
1367 join.)
1368 remote.<name>.annex-gnupg-options
1370 Options to pass to GnuPG when it's encrypting data. For
1371 instance, to use the AES cipher with a 256 bits key and disable
1372 compression, set it to --cipher-algo AES256 --compress-algo
1373 none. (These options take precedence over the default GnuPG con‐
1374 figuration, which is otherwise used.)
1375 remote.<name>.annex-gnupg-decrypt-options
1377 Options to pass to GnuPG when it's decrypting data. (These
1378 options take precedence over the default GnuPG configuration,
1379 which is otherwise used.)
1380 annex.ssh-options, annex.rsync-options,
1382 annex.rsync-upload-options, annex.rsync-download-options,
1383 annex.bup-split-options, annex.gnupg-options,
1384 annex.gnupg-decrypt-options
1385 Default options to use if a remote does not have more specific
1387 options as described above.
1388 remote.<name>.annex-rsyncurl
1390 Used by rsync special remotes, this configures the location of
1391 the rsync repository to use. Normally this is automatically set
1392 up by git annex initremote, but you can change it if needed.
1393 remote.<name>.annex-buprepo
1395 Used by bup special remotes, this configures the location of the
1396 bup repository to use. Normally this is automatically set up by
1397 git annex initremote, but you can change it if needed.
1398 remote.<name>.annex-borgrepo
1400 Used by borg special remotes, this configures the location of
1401 the borg 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-ddarrepo
1405 Used by ddar special remotes, this configures the location of
1406 the ddar repository to use. Normally this is automatically set
1407 up by git annex initremote, but you can change it if needed.
1408 remote.<name>.annex-directory
1410 Used by directory special remotes, this configures the location
1411 of the directory where annexed files are stored for this remote.
1412 Normally this is automatically set up by git annex initremote,
1413 but you can change it if needed.
1414 remote.<name>.annex-adb
1416 Used to identify remotes on Android devices accessed via adb.
1417 Normally this is automatically set up by git annex initremote.
1418 remote.<name>.annex-androiddirectory
1420 Used by adb special remotes, this is the directory on the
1421 Android device where files are stored for this remote. Normally
1422 this is automatically set up by git annex initremote, but you
1423 can change it if needed.
1424 remote.<name>.annex-androidserial
1426 Used by adb special remotes, this is the serial number of the
1427 Android device used by the remote. Normally this is automati‐
1428 cally set up by git annex initremote, but you can change it if
1429 needed, eg when upgrading to a new Android device.
1430 remote.<name>.annex-s3
1432 Used to identify Amazon S3 special remotes. Normally this is
1433 automatically set up by git annex initremote.
1434 remote.<name>.annex-glacier
1436 Used to identify Amazon Glacier special remotes. Normally this
1437 is automatically set up by git annex initremote.
1438 remote.<name>.annex-webdav
1440 Used to identify webdav special remotes. Normally this is auto‐
1441 matically set up by git annex initremote.
1442 remote.<name>.annex-tahoe
1444 Used to identify tahoe special remotes. Points to the configu‐
1445 ration directory for tahoe.
1446 remote.<name>.annex-gcrypt
1448 Used to identify gcrypt special remotes. Normally this is auto‐
1449 matically set up by git annex initremote.
1450 It is set to "true" if this is a gcrypt remote. If the gcrypt
1452 remote is accessible over ssh and has git-annex-shell available
1453 to manage it, it's set to "shell".
1454 remote.<name>.annex-git-lfs
1456 Used to identify git-lfs special remotes. Normally this is
1457 automatically set up by git annex initremote.
1458 It is set to "true" if this is a git-lfs remote.
1460 remote.<name>.annex-httpalso
1462 Used to identify httpalso special remotes. Normally this is
1463 automatically set up by git annex initremote.
1464 remote.<name>.annex-externaltype
1466 Used external special remotes to record the type of the remote.
1467 Eg, if this is set to "foo", git-annex will run a "git-
1469 annex-remote-foo" program to communicate with the external spe‐
1470 cial remote.
1471 If this is set to "readonly", then git-annex will not run any
1473 external special remote program, but will try to access things
1474 stored in the remote using http. That only works for some exter‐
1475 nal special remotes, so consult the documentation of the one you
1476 are using.
1477 remote.<name>.annex-hooktype
1479 Used by hook special remotes to record the type of the remote.
1480 annex.web-options
1482 Options to pass to curl when git-annex uses it to download urls
1483 (rather than the default built-in url downloader).
1484 For example, to force IPv4 only, set it to "-4". Or to make
1486 curl use your ~/.netrc file, set it to "--netrc".
1487 Setting this option makes git-annex use curl, but only when
1489 annex.security.allowed-ip-addresses is configured in a specific
1490 way. See its documentation.
1491 annex.youtube-dl-options
1493 Options to pass to youtube-dl when using it to find the url to
1494 download for a video.
1495 Some options may break git-annex's integration with youtube-dl.
1497 For example, the --output option could cause it to store files
1498 somewhere git-annex won't find them. Avoid setting here or in
1499 the youtube-dl config file any options that cause youtube-dl to
1500 download more than one file, or to store the file anywhere other
1501 than the current working directory.
1502 annex.aria-torrent-options
1504 Options to pass to aria2c when using it to download a torrent.
1505 annex.http-headers
1507 HTTP headers to send when downloading from the web. Multiple
1508 lines of this option can be set, one per header.
1509 annex.http-headers-command
1511 If set, the command is run and each line of its output is used
1512 as a HTTP header. This overrides annex.http-headers.
1513 annex.security.allowed-url-schemes
1515 List of URL schemes that git-annex is allowed to download con‐
1516 tent from. The default is "http https ftp".
1517 Think very carefully before changing this; there are security
1519 implications. For example, if it's changed to allow "file" URLs,
1520 then anyone who can get a commit into your git-annex repository
1521 could git-annex addurl a pointer to a private file located out‐
1522 side that repository, possibly causing it to be copied into your
1523 repository and transferred on to other remotes, exposing its
1524 content.
1525 Some special remotes support their own domain-specific URL
1527 schemes; those are not affected by this configuration setting.
1528 annex.security.allowed-ip-addresses
1530 By default, git-annex only makes connections to public IP
1531 addresses; it will refuse to use HTTP and other servers on
1532 localhost or on a private network.
1533 This setting can override that behavior, allowing access to par‐
1535 ticular IP addresses that would normally be blocked. For example
1536 "127.0.0.1 ::1" allows access to localhost (both IPV4 and IPV6).
1537 To allow access to all IP addresses, use "all"
1538 Think very carefully before changing this; there are security
1540 implications. Anyone who can get a commit into your git-annex
1541 repository could git annex addurl an url on a private server,
1542 possibly causing it to be downloaded into your repository and
1543 transferred to other remotes, exposing its content.
1544 Note that, since the interfaces of curl and youtube-dl do not
1546 allow these IP address restrictions to be enforced, curl and
1547 youtube-dl will never be used unless annex.secu‐
1548 rity.allowed-ip-addresses=all.
1549 To allow accessing local or private IP addresses on only spe‐
1551 cific ports, use the syntax "[addr]:port". For example,
1552 "[127.0.0.1]:80 [127.0.0.1]:443 [::1]:80 [::1]:443" allows
1553 localhost on the http ports only.
1554 annex.security.allowed-http-addresses
1556 Old name for annex.security.allowed-ip-addresses. If set, this
1557 is treated the same as having annex.secu‐
1558 rity.allowed-ip-addresses set.
1559 annex.security.allow-unverified-downloads
1561 For security reasons, git-annex refuses to download content from
1562 most special remotes when it cannot check a hash to verify that
1563 the correct content was downloaded. This particularly impacts
1564 downloading the content of URL or WORM keys, which lack hashes.
1565 The best way to avoid problems due to this is to migrate files
1567 away from such keys, before their content reaches a special
1568 remote. See git-annex-migrate(1).
1569 When the content is only available from a special remote, you
1571 can use this configuration to force git-annex to download it.
1572 But you do so at your own risk, and it's very important you read
1573 and understand the information below first!
1574 Downloading unverified content from encrypted special remotes is
1576 prevented, because the special remote could send some other
1577 encrypted content than what you expect, causing git-annex to
1578 decrypt data that you never checked into git-annex, and risking
1579 exposing the decrypted data to any non-encrypted remotes you
1580 send content to.
1581 Downloading unverified content from (non-encrypted) external
1583 special remotes is prevented, because they could follow http
1584 redirects to web servers on localhost or on a private network,
1585 or in some cases to a file:/// url.
1586 If you decide to bypass this security check, the best thing to
1588 do is to only set it temporarily while running the command that
1589 gets the file. The value to set the config to is "ACKTHPPT".
1590 For example:
1591 git -c annex.security.allow-unverified-downloads=ACKTHPPT annex
1593 get myfile
1594 It would be a good idea to check that it downloaded the file you
1596 expected, too.
1597 remote.<name>.annex-security-allow-unverified-downloads
1599 Per-remote configuration of annex.security.allow-unveri‐
1600 fied-downloads.
1601
1603 annex.delayadd
1604 Makes the watch and assistant commands delay for the specified
1606 number of seconds before adding a newly created file to the
1607 annex. Normally this is not needed, because they already wait
1608 for all writers of the file to close it.
1609 annex.expireunused
1611 Controls what the assistant does about unused file contents that
1612 are stored in the repository.
1613 The default is false, which causes all old and unused file con‐
1615 tents to be retained, unless the assistant is able to move them
1616 to some other repository (such as a backup repository).
1617 Can be set to a time specification, like "7d" or "1m", and then
1619 file contents that have been known to be unused for a week or a
1620 month will be deleted.
1621 annex.fscknudge
1623 When set to false, prevents the webapp from reminding you when
1624 using repositories that lack consistency checks.
1625 annex.autoupgrade
1627 When set to ask (the default), the webapp will check for new
1628 versions and prompt if they should be upgraded to. When set to
1629 true, automatically upgrades without prompting (on some sup‐
1630 ported platforms). When set to false, disables any upgrade
1631 checking.
1632 Note that upgrade checking is only done when git-annex is
1634 installed from one of the prebuilt images from its website. This
1635 does not bypass e.g., a Linux distribution's own upgrade han‐
1636 dling code.
1637 This setting also controls whether to restart the git-annex
1639 assistant when the git-annex binary is detected to have changed.
1640 That is useful no matter how you installed git-annex.
1641 annex.autocommit
1643 Set to false to prevent the git-annex assistant and git-annex
1644 sync from automatically committing changes to files in the
1645 repository.
1646 To configure the behavior in all clones of the repository, this
1648 can be set in git-annex-config(1).
1649 annex.startupscan
1651 Set to false to prevent the git-annex assistant from scanning
1652 the repository for new and changed files on startup. This will
1653 prevent it from noticing changes that were made while it was not
1654 running, but can be a useful performance tweak for a large
1655 repository.
1656 annex.listen
1658 Configures which address the webapp listens on. The default is
1659 localhost. Can be either an IP address, or a hostname that
1660 resolves to the desired address.
1661
1663 The key-value backend used when adding a new file to the annex can be
1664 configured on a per-file-type basis via .gitattributes files. In the
1665 file, the annex.backend attribute can be set to the name of the backend
1666 to use. For example, this here's how to use the WORM backend by
1667 default, but the SHA256E backend for ogg files:
1668 * annex.backend=WORM
1670 *.ogg annex.backend=SHA256E
1671 There is a annex.largefiles attribute, which is used to configure which
1673 files are large enough to be added to the annex. Since attributes can‐
1674 not contain spaces, it is difficult to use for more complex
1675 annex.largefiles settings. Setting annex.largefiles in git-annex-con‐
1676 fig(1) is an easier way to configure it across all clones of the repos‐
1677 itory. See git-annex-matching-expression(1) for details on the syntax.
1678 The numcopies setting can also be configured on a per-file-type basis
1680 via the annex.numcopies attribute in .gitattributes files. This over‐
1681 rides other numcopies settings. For example, this makes two copies be
1682 needed for wav files and 3 copies for flac files:
1683 *.wav annex.numcopies=2
1685 *.flac annex.numcopies=3
1686 Note that setting numcopies to 0 is very unsafe.
1688 These settings are honored by git-annex whenever it's operating on a
1690 matching file. However, when using --all, --unused, or --key to specify
1691 keys to operate on, git-annex is operating on keys and not files, so
1692 will not honor the settings from .gitattributes. For this reason, the
1693 git annex numcopies command is useful to configure a global default for
1694 numcopies.
1695 Also note that when using views, only the toplevel .gitattributes file
1697 is preserved in the view, so other settings in other files won't have
1698 any effect.
1699
1701 git-annex, when called as a git subcommand, may return exit codes 0 or
1702 1 for success or failures, or, more rarely, 127 or 128 for certain very
1703 specific failures. git-annex itself should return 0 on success and 1
1704 on failure, unless the --time-limit=time option is hit, in which case
1705 it returns with exit code 101.
1706
1708 These environment variables are used by git-annex when set:
1709 GIT_WORK_TREE, GIT_DIR
1711 Handled the same as they are by git, see git(1)
1712 GIT_SSH, GIT_SSH_COMMAND
1714 Handled similarly to the same as described in git(1). The one
1715 difference is that git-annex will sometimes pass an additional
1716 "-n" parameter to these, as the first parameter, to prevent ssh
1717 from reading from stdin. Since that can break existing uses of
1718 these environment variables that don't expect the extra parame‐
1719 ter, you will need to set GIT_ANNEX_USE_GIT_SSH=1 to make git-
1720 annex support these.
1721 Note that setting either of these environment variables prevents
1723 git-annex from automatically enabling ssh connection caching
1724 (see annex.sshcaching), so it will slow down some operations
1725 with remotes over ssh. It's up to you to enable ssh connection
1726 caching if you need it; see ssh's documentation.
1727 Also, annex.ssh-options and remote.<name>.annex-ssh-options
1729 won't have any effect when these envionment variables are set.
1730 Usually it's better to configure any desired options through
1732 your ~/.ssh/config file, or by setting annex.ssh-options.
1733 GIT_ANNEX_VECTOR_CLOCK
1735 Normally git-annex timestamps lines in the log files committed
1736 to the git-annex branch. Setting this environment variable to a
1737 number will make git-annex use that rather than the current num‐
1738 ber of seconds since the UNIX epoch. Note that decimal seconds
1739 are supported.
1740 This is only provided for advanced users who either have a bet‐
1742 ter way to tell which commit is current than the local clock, or
1743 who need to avoid embedding timestamps for policy reasons. Mis‐
1744 use of this environment variable can confuse git-annex's
1745 book-keeping, sometimes in ways that git annex fsck is unable to
1746 repair.
1747 Some special remotes use additional environment variables
1749 for authentication etc. For example, AWS_ACCESS_KEY_ID and
1750 GIT_ANNEX_P2P_AUTHTOKEN. See special remote documentation.
1751
1753 These files are used by git-annex:
1754 .git/annex/objects/ in your git repository contains the annexed file
1756 contents that are currently available. Annexed files in your git repos‐
1757 itory symlink to that content.
1758 .git/annex/ in your git repository contains other run-time information
1760 used by git-annex.
1761 ~/.config/git-annex/autostart is a list of git repositories to start
1763 the git-annex assistant in.
1764 .git/hooks/pre-commit-annex in your git repository will be run whenever
1766 a commit is made to the HEAD branch, either by git commit, git-annex
1767 sync, or the git-annex assistant.
1768 .git/hooks/post-update-annex in your git repository will be run when‐
1770 ever the git-annex branch is updated. You can make this hook run git
1771 update-server-info when publishing a git-annex repository by http.
1772
1774 More git-annex documentation is available on its web site,
1775 <https://git-annex.branchable.com/>
1776 If git-annex is installed from a package, a copy of its documentation
1778 should be included, in, for example, /usr/share/doc/git-annex/.
1779
1781 Joey Hess <id@joeyh.name>
1782 <https://git-annex.branchable.com/>
1784 git-annex(1)