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 Like many git commands, git-annex can be passed a path that is either a
57 file or a directory. In the latter case it acts on all relevant files
58 in the directory. When no path is specified, most git-annex commands
59 default to acting on all relevant files in the current directory (and
60 subdirectories).
61 help Display built-in help.
63 For help on a specific command, use git annex help command
65 add [path ...]
67 Adds files in the path to the annex. If no path is specified,
68 adds files from the current directory and below.
69 See git-annex-add(1) for details.
71 get [path ...]
73 Makes the content of annexed files available in this repository.
74 See git-annex-get(1) for details.
76 drop [path ...]
78 Drops the content of annexed files from this repository.
79 See git-annex-drop(1) for details.
81 move [path ...] [--from=remote|--to=remote]
83 Moves the content of files from or to another remote.
84 See git-annex-move(1) for details.
86 copy [path ...] [--from=remote|--to=remote]
88 Copies the content of files from or to another remote.
89 See git-annex-copy(1) for details.
91 status [path ...]
93 Similar to git status --short, displays the status of the files
94 in the working tree. Particularly useful in direct mode.
95 See git-annex-status(1) for details.
97 unlock [path ...]
99 Unlock annexed files for modification.
100 See git-annex-unlock(1) for details.
102 edit [path ...]
104 This is an alias for the unlock command. May be easier to remem‐
105 ber, if you think of this as allowing you to edit an annexed
106 file.
107 lock [path ...]
109 Use this to undo an unlock command if you don't want to modify
110 the files, or have made modifications you want to discard.
111 See git-annex-lock(1) for details.
113 sync [remote ...]
115 Synchronize local repository with remotes.
116 See git-annex-sync(1) for details.
118 mirror [path ...] [--to=remote|--from=remote]
120 Mirror content of files to/from another repository.
121 See git-annex-mirror(1) for details.
123 addurl [url ...]
125 Downloads each url to its own file, which is added to the annex.
126 See git-annex-addurl(1) for details.
128 rmurl file url
130 Record that the file is no longer available at the url.
131 See git-annex-rmurl(1) for details.
133 import [path ...]
135 Move and add files from outside git working copy into the annex.
136 See git-annex-import(1) for details.
138 importfeed [url ...]
140 Imports the contents of podcast feeds into the annex.
141 See git-annex-importfeed(1) for details.
143 export treeish --to remote
145 Export content to a remote.
146 See git-annex-export(1) for details.
148 undo [filename|directory] ...
150 Undo last change to a file or directory.
151 See git-annex-undo(1) for details.
153 multicast
155 Multicast file distribution.
156 See git-annex-multicast(1) for details.
158 watch Watch for changes and autocommit.
160 See git-annex-watch(1) for details.
162 assistant
164 Automatically sync folders between devices.
165 See git-annex-assistant(1) for details.
167 webapp Opens a web app, that allows easy setup of a git-annex reposi‐
169 tory, and control of the git-annex assistant. If the assistant
170 is not already running, it will be started.
171 See git-annex-webapp(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 enable-tor
200 Sets up tor hidden service.
201 See git-annex-enable-tor(1) for details.
203 numcopies [N]
205 Configure desired number of copies.
206 See git-annex-numcopies(1) for details.
208 trust [repository ...]
210 Records that a repository is trusted to not unexpectedly lose
211 content. Use with care.
212 See git-annex-trust(1) for details.
214 untrust [repository ...]
216 Records that a repository is not trusted and could lose content
217 at any time.
218 See git-annex-untrust(1) for details.
220 semitrust [repository ...]
222 Returns a repository to the default semi trusted state.
223 See git-annex-semitrust(1) for details.
225 group repository groupname
227 Add a repository to a group.
228 See git-annex-group(1) for details.
230 ungroup repository groupname
232 Removes a repository from a group.
233 See git-annex-ungroup(1) for details.
235 wanted repository [expression]
237 Get or set preferred content expression.
238 See git-annex-wanted(1) for details.
240 groupwanted groupname [expression]
242 Get or set groupwanted expression.
243 See git-annex-groupwanted(1) for details.
245 required repository [expression]
247 Get or set required content expression.
248 See git-annex-required(1) for details.
250 schedule repository [expression]
252 Get or set scheduled jobs.
253 See git-annex-schedule(1) for details.
255 config Get and set other configuration stored in git-annex branch.
257 See git-annex-config(1) for details.
259 vicfg Opens EDITOR on a temp file containing most of the above config‐
261 uration settings, as well as a few others, and when it exits,
262 stores any changes made back to the git-annex branch.
263 See git-annex-vicfg(1) for details.
265 direct Switches a repository to use direct mode, where rather than sym‐
267 links to files, the files are directly present in the reposi‐
268 tory.
269 See git-annex-direct(1) for details.
271 indirect
273 Switches a repository back from direct mode to the default,
274 indirect mode.
275 See git-annex-indirect(1) for details.
277 adjust Switches a repository to use an adjusted branch, which can auto‐
279 matically unlock all files, etc.
280 See git-annex-adjust(1) for details.
282
284 fsck [path ...]
285 Checks the annex consistency, and warns about or fixes any prob‐
287 lems found. This is a good complement to git fsck.
288 See git-annex-fsck(1) for details.
290 expire [repository:]time ...
292 Expires repositories that have not recently performed an activ‐
293 ity (such as a fsck).
294 See git-annex-expire(1) for details.
296 unused Checks the annex for data that does not correspond to any files
298 present in any tag or branch, and prints a numbered list of the
299 data.
300 See git-annex-unused(1) for details.
302 dropunused [number|range ...]
304 Drops the data corresponding to the numbers, as listed by the
305 last git annex unused
306 See git-annex-dropunused(1) for details.
308 addunused [number|range ...]
310 Adds back files for the content corresponding to the numbers or
311 ranges, as listed by the last git annex unused.
312 See git-annex-addunused(1) for details.
314 fix [path ...]
316 Fixes up symlinks that have become broken to again point to
317 annexed content.
318 See git-annex-fix(1) for details.
320 merge Automatically merge changes from remotes.
322 See git-annex-merge(1) for details.
324 upgrade
326 Upgrades the repository to current layout.
327 See git-annex-upgrade(1) for details.
329 dead [repository ...] [--key key]
331 Indicates that a repository or a single key has been irretriev‐
332 ably lost.
333 See git-annex-dead(1) for details.
335 forget Causes the git-annex branch to be rewritten, throwing away his‐
337 torical data about past locations of files.
338 See git-annex-forget(1) for details.
340 repair This can repair many of the problems with git repositories that
342 git fsck detects, but does not itself fix. It's useful if a
343 repository has become badly damaged. One way this can happen is
344 if a repository used by git-annex is on a removable drive that
345 gets unplugged at the wrong time.
346 See git-annex-repair(1) for details.
348 p2p Configure peer-2-Peer links between repositories.
350 See git-annex-p2p(1) for details.
352
354 find [path ...]
355 Outputs a list of annexed files in the specified path. With no
357 path, finds files in the current directory and its subdirecto‐
358 ries.
359 See git-annex-find(1) for details.
361 whereis [path ...]
363 Displays information about where the contents of files are
364 located.
365 See git-annex-whereis(1) for details.
367 list [path ...]
369 Displays a table of remotes that contain the contents of the
370 specified files. This is similar to whereis but a more compact
371 display.
372 See git-annex-list(1) for details.
374 log [path ...]
376 Displays the location log for the specified file or files, show‐
377 ing each repository they were added to ("+") and removed from
378 ("-").
379 See git-annex-log(1) for details.
381 info [directory|file|remote|uuid ...]
383 Displays statistics and other information for the specified
384 item, which can be a directory, or a file, or a remote, or the
385 uuid of a repository.
386 When no item is specified, displays statistics and information
388 for the repository as a whole.
389 See git-annex-info(1) for details.
391 version
393 Shows the version of git-annex, as well as repository version
394 information.
395 See git-annex-version(1) for details.
397 map Generate map of repositories.
399 See git-annex-map(1) for details.
401 inprogress
403 Access files while they're being downloaded.
404 See git-annex-inprogress(1) for details.
406
408 metadata [path ...]
409 The content of an annexed file can have any number of metadata
411 fields attached to it to describe it. Each metadata field can in
412 turn have any number of values.
413 This command can be used to set metadata, or show the currently
415 set metadata.
416 See git-annex-metadata(1) for details.
418 view [tag ...] [field=value ...] [field=glob ...] [!tag ...]
420 [field!=value ...]
421 Uses metadata to build a view branch of the files in the current
422 branch, and checks out the view branch. Only files in the cur‐
423 rent branch whose metadata matches all the specified field val‐
424 ues and tags will be shown in the view.
425 See git-annex-view(1) for details.
427 vpop [N]
429 Switches from the currently active view back to the previous
430 view. Or, from the first view back to original branch.
431 See git-annex-vpop(1) for details.
433 vfilter [tag ...] [field=value ...] [!tag ...] [field!=value ...]
435 Filters the current view to only the files that have the speci‐
436 fied field values and tags.
437 See git-annex-vfilter(1) for details.
439 vadd [field=glob ...] [field=value ...] [tag ...]
441 Changes the current view, adding an additional level of directo‐
442 ries to categorize the files.
443 See git-annex-vfilter(1) for details.
445 vcycle When a view involves nested subdirectories, this cycles the
447 order.
448 See git-annex-vcycle(1) for details.
450
452 migrate [path ...]
453 Changes the specified annexed files to use a different key-value
455 backend.
456 See git-annex-migrate(1) for details.
458 reinject src dest
460 Moves the src file into the annex as the content of the dest
461 file. This can be useful if you have obtained the content of a
462 file from elsewhere and want to put it in the local annex.
463 See git-annex-reinject(1) for details.
465 unannex [path ...]
467 Use this to undo an accidental git annex add command. It puts
468 the file back how it was before the add.
469 See git-annex-unannex(1) for details.
471 uninit De-initialize git-annex and clean out repository.
473 See git-annex-uninit(1) for details.
475 reinit uuid|description
477 Initialize repository, reusing old UUID.
478 See git-annex-reinit(1) for details.
480
482 pre-commit [path ...]
483 This is meant to be called from git's pre-commit hook. git annex
485 init automatically creates a pre-commit hook using this.
486 See git-annex-pre-commit(1) for details.
488 post-receive
490 This is meant to be called from git's post-receive hook. git
491 annex init automatically creates a post-receive hook using this.
492 See git-annex-post-receive(1) for details.
494 lookupkey [file ...]
496 Looks up key used for file.
497 See git-annex-lookupkey(1) for details.
499 calckey [file ...]
501 Calculates the key that would be used to refer to a file.
502 See git-annex-calckey(1) for details.
504 contentlocation [key ..]
506 Looks up location of annexed content for a key.
507 See git-annex-contentlocation(1) for details.
509 examinekey [key ...]
511 Print information that can be determined purely by looking at
512 the key.
513 See git-annex-examinekey(1) for details.
515 matchexpression
517 Checks if a preferred content expression matches provided data.
518 See git-annex-matchexpression(1) for details.
520 fromkey [key file]
522 Manually set up a file in the git repository to link to a speci‐
523 fied key.
524 See git-annex-fromkey(1) for details.
526 registerurl [key url]
528 Registers an url for a key.
529 See git-annex-registerurl(1) for details.
531 setkey key file
533 Moves a file into the annex as the content of a key.
534 See git-annex-setkey(1) for details.
536 dropkey [key ...]
538 Drops annexed content for specified keys.
539 See git-annex-dropkey(1) for details.
541 transferkey key [--from=remote|--to=remote]
543 Transfers a key from or to a remote.
544 See git-annex-transferkey(1) for details.
546 transferkeys
548 Used internally by the assistant.
549 See git-annex-transferkey(1) for details.
551 setpresentkey key uuid [1|0]
553 This plumbing-level command changes git-annex's records about
554 whether the specified key's content is present in a remote with
555 the specified uuid.
556 See git-annex-setpresentkey(1) for details.
558 readpresentkey key uuid
560 Read records of where key is present.
561 See git-annex-readpresentkey(1) for details.
563 checkpresentkey key remote
565 Check if key is present in remote.
566 See git-annex-checkpresentkey(1) for details.
568 rekey [file key ...]
570 Change keys used for files.
571 See git-annex-rekey(1) for details.
573 findref [ref]
575 Lists files in a git ref.
576 See git-annex-findref(1) for details.
578 proxy -- git cmd [options]
580 Only useful in a direct mode repository, this runs the specified
581 git command with a temporary work tree, and updates the working
582 tree to reflect any changes staged or committed by the git com‐
583 mand.
584 See git-annex-proxy(1) for details.
586 resolvemerge
588 Resolves a conflicted merge, by adding both conflicting versions
589 of the file to the tree, using variants of their filename. This
590 is done automatically when using git annex sync or git annex
591 merge.
592 See git-annex-resolvemerge(1) for details.
594 diffdriver
596 This can be used to make git diff use an external diff driver
597 with annexed files.
598 See git-annex-diffdriver(1) for details.
600 smudge This command lets git-annex be used as a git filter driver,
602 allowing annexed files in the git repository to be unlocked at
603 all times, instead of being symlinks.
604 See git-annex-smudge(1) for details.
606 remotedaemon
608 Detects when network remotes have received git pushes and
609 fetches from them.
610 See git-annex-remotedaemon(1) for details.
612
614 test
615 This runs git-annex's built-in test suite.
617 See git-annex-test(1) for details.
619 testremote remote
621 This tests a remote by generating some random objects and send‐
622 ing them to the remote, then redownloading them, removing them
623 from the remote, etc.
624 It's safe to run in an existing repository (the repository con‐
626 tents are not altered), although it may perform expensive data
627 transfers.
628 See git-annex-testremote(1) for details.
630 fuzztest
632 Generates random changes to files in the current repository, for
633 use in testing the assistant.
634 See git-annex-fuzztest(1) for details.
636 benchmark
638 This runs git-annex's built-in benchmarks, if it was built with
639 benchmarking support.
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-inventory
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. Here
733 are all the supported configuration settings.
734 annex.uuid
736 A unique UUID for this repository (automatically set).
737 annex.backend
739 Name of the default key-value backend to use when adding new
740 files to the repository.
741 This is overridden by annex annex.backend configuration in the
743 .gitattributes files, and by the --backend option.
744 (This used to be named annex.backends, and that will still be
746 used if set.)
747 annex.securehashesonly
749 Set to true to indicate that the repository should only use
750 cryptographically secure hashes (SHA2, SHA3) and not insecure
751 hashes (MD5, SHA1) for content.
752 When this is set, the contents of files using cryptographically inse‐
754 cure hashes will not be allowed to be added to the repository.
755 Also, git-annex fsck will complain about any files present in the
757 repository that use insecure hashes.
758 To configure the behavior in new clones of the repository, this can be
760 set in git-annex-config.
761 annex.maxextensionlength
763 Maximum length of what is considered a filename extension when
764 adding a file to a backend that preserves filename extensions.
765 The default length is 4, which allows extensions like "jpeg".
766 The dot before the extension is not counted part of its length.
767 annex.diskreserve
769 Amount of disk space to reserve. Disk space is checked when
770 transferring content to avoid running out, and additional free
771 space can be reserved via this option, to make space for more
772 important content (such as git commit logs). Can be specified
773 with any commonly used units, for example, "0.5 gb", "500M", or
774 "100 KiloBytes"
775 The default reserve is 1 megabyte.
777 annex.largefiles
779 Used to configure which files are large enough to be added to
780 the annex. Default: All files.
781 Overrides any annex.largefiles attributes in .gitattributes
783 files.
784 See <https://git-annex.branchable.com/tips/largefiles> for
786 details.
787 annex.addsmallfiles
789 Controls whether small files (not matching annex.largefiles)
790 should be checked into git by git annex add. Defaults to true;
791 set to false to instead make small files be skipped.
792 annex.addunlocked
794 Set to true to make commands like git-annex add that add files
795 to the repository add them in unlocked form. The default is to
796 add files in locked form. This only has effect in version 6
797 repositories.
798 When a repository has core.symlinks set to false, it implicitly
800 sets annex.addunlocked to true.
801 annex.numcopies
803 This is a deprecated setting. You should instead use the git
804 annex numcopies command to configure how many copies of files
805 are kept across all repositories, or the annex.numcopies .gitat‐
806 tributes setting.
807 This config setting is only looked at when git annex numcopies
809 has never been configured, and when there's no annex.numcopies
810 setting in the .gitattributes file.
811 Note that setting numcopies to 0 is very unsafe.
813 annex.genmetadata
815 Set this to true to make git-annex automatically generate some
816 metadata when adding files to the repository.
817 In particular, it stores year, month, and day metadata, from the
819 file's modification date.
820 When importfeed is used, it stores additional metadata from the
822 feed, such as the author, title, etc.
823 annex.used-refspec
825 This controls which refs git-annex unused considers to be used.
826 See REFSPEC FORMAT in git-annex-unused(1) for details.
827 annex.jobs
829 Configure the number of concurrent jobs to run. Default is 1.
830 Only git-annex commands that support the --jobs option will use
832 this.
833 annex.queuesize
835 git-annex builds a queue of git commands, in order to combine
836 similar commands for speed. By default the size of the queue is
837 limited to 10240 commands; this can be used to change the size.
838 If you have plenty of memory and are working with very large
839 numbers of files, increasing the queue size can speed it up.
840 annex.bloomcapacity
842 The git annex unused and git annex sync --content commands use a
843 bloom filter to determine what files are present in eg, the work
844 tree. The default bloom filter is sized to handle up to 500000
845 files. If your repository is larger than that, you should
846 increase this value. Larger values will make git-annex unused
847 and git annex sync --content consume more memory; run git annex
848 info for memory usage numbers.
849 annex.bloomaccuracy
851 Adjusts the accuracy of the bloom filter used by git annex
852 unused and git annex sync --content. The default accuracy is
853 10000000 -- 1 unused file out of 10000000 will be missed by git
854 annex unused. Increasing the accuracy will make git annex unused
855 consume more memory; run git annex info for memory usage num‐
856 bers.
857 annex.sshcaching
859 By default, git-annex caches ssh connections using ssh's Con‐
860 trolMaster and ControlPersist settings (if built using a new
861 enough ssh). To disable this, set to false.
862 annex.alwayscommit
864 By default, git-annex automatically commits data to the git-
865 annex branch after each command is run. If you have a series of
866 commands that you want to make a single commit, you can run the
867 commands with -c annex.alwayscommit=false. You can later commit
868 the data by running git annex merge (or by automatic merges) or
869 git annex sync.
870 You should beware running git gc when using this configuration,
872 since it could garbage collect objects that are staged in git-
873 annex's index but not yet committed.
874 annex.commitmessage
876 When git-annex updates the git-annex branch, it usually makes up
877 its own commit message ("update"), since users rarely look at or
878 care about changes to that branch. If you do care, you can spec‐
879 ify this setting by running commands with -c annex.commitmes‐
880 sage=whatever
881 This works well in combination with annex.alwayscommit=false, to
883 gather up a set of changes and commit them with a message you
884 specify.
885 annex.merge-annex-branches
887 By default, git-annex branches that have been pulled from
888 remotes are automatically merged into the local git-annex
889 branch, so that git-annex has the most up-to-date possible
890 knowledge.
891 To avoid that merging, set this to "false". This can be useful
893 particularly when you don't have write permission to the reposi‐
894 tory.
895 annex.hardlink
897 Set this to true to make file contents be hard linked between
898 the repository and its remotes when possible, instead of a more
899 expensive copy.
900 Use with caution -- This can invalidate numcopies counting,
902 since with hard links, fewer copies of a file can exist. So, it
903 is a good idea to mark a repository using this setting as
904 untrusted.
905 When a repository is set up using git clone --shared, git-annex
907 init will automatically set annex.hardlink and mark the reposi‐
908 tory as untrusted.
909 annex.thin
911 Set this to true to make unlocked files be a hard link to their
912 content in the annex, rather than a second copy. (Only when sup‐
913 ported by the file system, and only in repository version 6.)
914 This can save considerable disk space, but when a modification
915 is made to a file, you will lose the local (and possibly only)
916 copy of the old version. So, enable with care.
917 After setting (or unsetting) this, you should run git annex fix
919 to fix up the annexed files in the work tree to be hard links
920 (or copies).
921 Note that annex.thin is not honored when git updates an annexed
923 file in the working tree. So when git checkout or git merge
924 updates the working tree, a second copy of annexed files will
925 result. You can run git-annex fix to fix up the hard links after
926 running such git commands.
927 annex.delayadd
929 Makes the watch and assistant commands delay for the specified
930 number of seconds before adding a newly created file to the
931 annex. Normally this is not needed, because they already wait
932 for all writers of the file to close it. On Mac OSX, when not
933 using direct mode this defaults to 1 second, to work around a
934 bad interaction with software there.
935 annex.expireunused
937 Controls what the assistant does about unused file contents that
938 are stored in the repository.
939 The default is false, which causes all old and unused file con‐
941 tents to be retained, unless the assistant is able to move them
942 to some other repository (such as a backup repository).
943 Can be set to a time specification, like "7d" or "1m", and then
945 file contents that have been known to be unused for a week or a
946 month will be deleted.
947 annex.fscknudge
949 When set to false, prevents the webapp from reminding you when
950 using repositories that lack consistency checks.
951 annex.autoupgrade
953 When set to ask (the default), the webapp will check for new
954 versions and prompt if they should be upgraded to. When set to
955 true, automatically upgrades without prompting (on some sup‐
956 ported platforms). When set to false, disables any upgrade
957 checking.
958 Note that upgrade checking is only done when git-annex is
960 installed from one of the prebuilt images from its website. This
961 does not bypass e.g., a Linux distribution's own upgrade han‐
962 dling code.
963 This setting also controls whether to restart the git-annex
965 assistant when the git-annex binary is detected to have changed.
966 That is useful no matter how you installed git-annex.
967 annex.autocommit
969 Set to false to prevent the git-annex assistant and git-annex
970 sync from automatically committing changes to files in the
971 repository.
972 To configure the behavior in all clones of the repository, this
974 can be set in git-annex-config.
975 annex.resolvemerge
977 Set to false to prevent merge conflicts in the checked out
978 branch being automatically resolved by the git-annex assitant,
979 git-annex sync, git-annex merge, and the git-annex post-receive
980 hook.
981 To configure the behavior in all clones of the repository, this
983 can be set in git-annex-config.
984 annex.synccontent
986 Set to true to make git-annex sync default to syncing content.
987 To configure the behavior in all clones of the repository, this
989 can be set in git-annex-config.
990 annex.startupscan
992 Set to false to prevent the git-annex assistant from scanning
993 the repository for new and changed files on startup. This will
994 prevent it from noticing changes that were made while it was not
995 running, but can be a useful performance tweak for a large
996 repository.
997 annex.listen
999 Configures which address the webapp listens on. The default is
1000 localhost. Can be either an IP address, or a hostname that
1001 resolves to the desired address.
1002 annex.debug
1004 Set to true to enable debug logging by default.
1005 annex.version
1007 Automatically maintained, and used to automate upgrades between
1008 versions.
1009 annex.direct
1011 Set to true when the repository is in direct mode. Should not be
1012 set manually; use the "git annex direct" and "git annex indi‐
1013 rect" commands instead.
1014 annex.crippledfilesystem
1016 Set to true if the repository is on a crippled filesystem, such
1017 as FAT, which does not support symbolic links, or hard links, or
1018 unix permissions. This is automatically probed by "git annex
1019 init".
1020 annex.pidlock
1022 Normally, git-annex uses fine-grained lock files to allow multi‐
1023 ple processes to run concurrently without getting in each oth‐
1024 ers' way. That works great, unless you are using git-annex on a
1025 filesystem that does not support POSIX fcntl locks. This is
1026 sometimes the case when using NFS or Lustre filesystems.
1027 To support such situations, you can set annex.pidlock to true,
1029 and it will fall back to a single top-level pid file lock.
1030 Although, often, you'd really be better off fixing your net‐
1032 worked filesystem configuration to support POSIX locks.. And,
1033 some networked filesystems are so inconsistent that one node
1034 can't reliably tell when the other node is holding a pid lock.
1035 Caveat emptor.
1036 annex.pidlocktimeout
1038 When using pid lock files, it's possible for a stale lock file
1039 to get left behind by previous run of git-annex that crashed or
1040 was interrupted. This is mostly avoided, but can occur espe‐
1041 cially when using a network file system.
1042 git-annex will wait up to this many seconds for the pid lock
1044 file to go away, and will then abort if it cannot continue.
1045 Default: 300
1046 remote.<name>.annex-cost
1048 When determining which repository to transfer annexed files from
1049 or to, ones with lower costs are preferred. The default cost is
1050 100 for local repositories, and 200 for remote repositories.
1051 remote.<name>.annex-cost-command
1053 If set, the command is run, and the number it outputs is used as
1054 the cost. This allows varying the cost based on e.g., the cur‐
1055 rent network.
1056 remote.<name>.annex-start-command
1058 A command to run when git-annex begins to use the remote. This
1059 can be used to, for example, mount the directory containing the
1060 remote.
1061 The command may be run repeatedly when multiple git-annex pro‐
1063 cesses are running concurrently.
1064 remote.<name>.annex-stop-command
1066 A command to run when git-annex is done using the remote.
1067 The command will only be run once *all* running git-annex pro‐
1069 cesses are finished using the remote.
1070 remote.<name>.annex-shell
1072 Specify an alternative git-annex-shell executable on the remote
1073 instead of looking for "git-annex-shell" on the PATH.
1074 This is useful if the git-annex-shell program is outside the
1076 PATH or has a non-standard name.
1077 remote.<name>.annex-ignore
1079 If set to true, prevents git-annex from storing file contents on
1080 this remote by default. (You can still request it be used by
1081 the --from and --to options.)
1082 This is, for example, useful if the remote is located somewhere
1084 without git-annex-shell. (For example, if it's on GitHub). Or,
1085 it could be used if the network connection between two reposito‐
1086 ries is too slow to be used normally.
1087 This does not prevent git-annex sync (or the git-annex assis‐
1089 tant) from syncing the git repository to the remote.
1090 remote.<name>.annex-ignore-command
1092 If set, the command is run, and if it exits nonzero, that's the
1093 same as setting annex-ignore to true. This allows controlling
1094 behavior based on e.g., the current network.
1095 remote.<name>.annex-sync
1097 If set to false, prevents git-annex sync (and the git-annex
1098 assistant) from syncing with this remote by default. However,
1099 git annex sync <name> can still be used to sync with the remote.
1100 remote.<name>.annex-sync-command
1102 If set, the command is run, and if it exits nonzero, that's the
1103 same as setting annex-sync to false. This allows controlling
1104 behavior based on e.g., the current network.
1105 remote.<name>.annex-pull
1107 If set to false, prevents git-annex sync (and the git-annex
1108 assistant etc) from ever pulling (or fetching) from the remote.
1109 remote.<name>.annex-push
1111 If set to false, prevents git-annex sync (and the git-annex
1112 assistant etc) from ever pushing to the remote.
1113 remote.<name>.annex-readonly
1115 If set to true, prevents git-annex from making changes to a
1116 remote. This both prevents git-annex sync from pushing changes,
1117 and prevents storing or removing files from read-only remote.
1118 remote.<name>.annex-verify, annex.verify
1120 By default, git-annex will verify the checksums of objects down‐
1121 loaded from remotes. If you trust a remote and don't want the
1122 overhead of these checksums, you can set this to false.
1123 Note that even when this is set to false, git-annex does verifi‐
1125 cation in some edge cases, where it's likely the case than an
1126 object was downloaded incorrectly, or when needed for security.
1127 remote.<name>.annex-export-tracking
1129 When set to a branch name or other treeish, this makes what's
1130 exported to the special remote track changes to the branch. See
1131 git-annex-export(1). git-annex sync --content and the git-annex
1132 assistant update exports when changes have been committed to the
1133 tracking branch.
1134 remote.<name>.annexUrl
1136 Can be used to specify a different url than the regular
1137 remote.<name>.url for git-annex to use when talking with the
1138 remote. Similar to the pushUrl used by git-push.
1139 remote.<name>.annex-uuid
1141 git-annex caches UUIDs of remote repositories here.
1142 remote.<name>.annex-retry, annex.retry
1144 Configure retries of failed transfers on a per-remote and gen‐
1145 eral basis, respectively. The value is the number of retries
1146 that can be made of the same transfer. (default 0)
1147 remote.<name>.annex-retry-delay, annex.retry-delay
1149 Number of seconds to delay before the first retry of a transfer.
1150 When making multiple retries of the same transfer, the delay
1151 doubles after each retry. (default 1)
1152 remote.<name>.annex-checkuuid
1154 This only affects remotes that have their url pointing to a
1155 directory on the same system. git-annex normally checks the uuid
1156 of such remotes each time it's run, which lets it transparently
1157 deal with different drives being mounted to the location at dif‐
1158 ferent times.
1159 Setting annex-checkuuid to false will prevent it from checking
1161 the uuid at startup (although the uuid is still verified before
1162 making any changes to the remote repository). This may be useful
1163 to set to prevent unncessary spin-up or automounting of a drive.
1164 remote.<name>.annex-trustlevel
1166 Configures a local trust level for the remote. This overrides
1167 the value configured by the trust and untrust commands. The
1168 value can be any of "trusted", "semitrusted" or "untrusted".
1169 remote.<name>.annex-availability
1171 Can be used to tell git-annex whether a remote is LocallyAvail‐
1172 able or GloballyAvailable. Normally, git-annex determines this
1173 automatically.
1174 remote.<name>.annex-speculate-present
1176 Set to "true" to make git-annex speculate that this remote may
1177 contain the content of any file, even though its normal location
1178 tracking does not indicate that it does. This will cause git-
1179 annex to try to get all file contents from the remote. Can be
1180 useful in setting up a caching remote.
1181 remote.<name>.annex-bare
1183 Can be used to tell git-annex if a remote is a bare repository
1184 or not. Normally, git-annex determines this automatically.
1185 remote.<name>.annex-ssh-options
1187 Options to use when using ssh to talk to this remote.
1188 remote.<name>.annex-rsync-options
1190 Options to use when using rsync to or from this remote. For
1191 example, to force IPv6, and limit the bandwidth to 100Kbyte/s,
1192 set it to -6 --bwlimit 100
1193 Note that git-annex-shell has a whitelist of allowed rsync
1195 options, and others will not be be passed to the remote rsync.
1196 So using some options may break the communication between the
1197 local and remote rsyncs.
1198 remote.<name>.annex-rsync-upload-options
1200 Options to use when using rsync to upload a file to a remote.
1201 These options are passed after other applicable rsync options,
1203 so can be used to override them. For example, to limit upload
1204 bandwidth to 10Kbyte/s, set --bwlimit 10.
1205 remote.<name>.annex-rsync-download-options
1207 Options to use when using rsync to download a file from a
1208 remote.
1209 These options are passed after other applicable rsync options,
1211 so can be used to override them.
1212 remote.<name>.annex-rsync-transport
1214 The remote shell to use to connect to the rsync remote. Possible
1215 values are ssh (the default) and rsh, together with their argu‐
1216 ments, for instance ssh -p 2222 -c blowfish; Note that the
1217 remote hostname should not appear there, see rsync(1) for
1218 details. When the transport used is ssh, connections are auto‐
1219 matically cached unless annex.sshcaching is unset.
1220 remote.<name>.annex-bup-split-options
1222 Options to pass to bup split when storing content in this
1223 remote. For example, to limit the bandwidth to 100Kbyte/s, set
1224 it to --bwlimit 100k (There is no corresponding option for bup
1225 join.)
1226 remote.<name>.annex-gnupg-options
1228 Options to pass to GnuPG when it's encrypting data. For
1229 instance, to use the AES cipher with a 256 bits key and disable
1230 compression, set it to --cipher-algo AES256 --compress-algo
1231 none. (These options take precedence over the default GnuPG con‐
1232 figuration, which is otherwise used.)
1233 remote.<name>.annex-gnupg-decrypt-options
1235 Options to pass to GnuPG when it's decrypting data. (These
1236 options take precedence over the default GnuPG configuration,
1237 which is otherwise used.)
1238 annex.ssh-options, annex.rsync-options,
1240 annex.rsync-upload-options, annex.rsync-download-options,
1241 annex.bup-split-options, annex.gnupg-options,
1242 annex.gnupg-decrypt-options
1243 Default options to use if a remote does not have more specific
1245 options as described above.
1246 annex.web-options
1248 Options to pass to curl when git-annex uses it to download urls
1249 (rather than the default built-in url downloader).
1250 For example, to force IPv4 only, set it to "-4". Or to make
1252 curl use your ~/.netrc file, set it to "--netrc".
1253 Setting this option makes git-annex use curl, but only when
1255 annex.security.allowed-http-addresses is configured in a spe‐
1256 cific way. See its documentation.
1257 annex.youtube-dl-options
1259 Options to pass to youtube-dl when using it to find the url to
1260 download for a video.
1261 Some options may break git-annex's integration with youtube-dl.
1263 For example, the --output option could cause it to store files
1264 somewhere git-annex won't find them. Avoid setting here or in
1265 the youtube-dl config file any options that cause youtube-dl to
1266 download more than one file, or to store the file anywhere other
1267 than the current working directory.
1268 annex.aria-torrent-options
1270 Options to pass to aria2c when using it to download a torrent.
1271 annex.http-headers
1273 HTTP headers to send when downloading from the web. Multiple
1274 lines of this option can be set, one per header.
1275 annex.http-headers-command
1277 If set, the command is run and each line of its output is used
1278 as a HTTP header. This overrides annex.http-headers.
1279 annex.security.allowed-url-schemes
1281 List of URL schemes that git-annex is allowed to download con‐
1282 tent from. The default is "http https ftp".
1283 Think very carefully before changing this; there are security
1285 implications. For example, if it's changed to allow "file" URLs,
1286 then anyone who can get a commit into your git-annex repository
1287 could git-annex addurl a pointer to a private file located out‐
1288 side that repository, possibly causing it to be copied into your
1289 repository and transferred on to other remotes, exposing its
1290 content.
1291 Some special remotes support their own domain-specific URL
1293 schemes; those are not affected by this configuration setting.
1294 annex.security.allowed-http-addresses
1296 By default, git-annex only makes HTTP connections to public IP
1297 addresses; it will refuse to use HTTP servers on localhost or on
1298 a private network.
1299 This setting can override that behavior, allowing access to par‐
1301 ticular IP addresses. For example "127.0.0.1 ::1" allows access
1302 to localhost (both IPV4 and IPV6). To allow access to all IP
1303 addresses, use "all"
1304 Think very carefully before changing this; there are security
1306 implications. Anyone who can get a commit into your git-annex
1307 repository could git annex addurl an url on a private http
1308 server, possibly causing it to be downloaded into your reposi‐
1309 tory and transferred to other remotes, exposing its content.
1310 Note that, since the interfaces of curl and youtube-dl do not
1312 allow these IP address restrictions to be enforced, curl and
1313 youtube-dl will never be used unless annex.secu‐
1314 rity.allowed-http-addresses=all.
1315 annex.security.allow-unverified-downloads
1317 For security reasons, git-annex refuses to download content from
1318 most special remotes when it cannot check a hash to verify that
1319 the correct content was downloaded. This particularly impacts
1320 downloading the content of URL or WORM keys, which lack hashes.
1321 The best way to avoid problems due to this is to migrate files
1323 away from such keys, before their content reaches a special
1324 remote. See git-annex-migrate(1).
1325 When the content is only available from a special remote, you
1327 can use this configuration to force git-annex to download it.
1328 But you do so at your own risk, and it's very important you read
1329 and understand the information below first!
1330 Downloading unverified content from encrypted special remotes is
1332 prevented, because the special remote could send some other
1333 encrypted content than what you expect, causing git-annex to
1334 decrypt data that you never checked into git-annex, and risking
1335 exposing the decrypted data to any non-encrypted remotes you
1336 send content to.
1337 Downloading unverified content from (non-encrypted) external
1339 special remotes is prevented, because they could follow http
1340 redirects to web servers on localhost or on a private network,
1341 or in some cases to a file:/// url.
1342 If you decide to bypass this security check, the best thing to
1344 do is to only set it temporarily while running the command that
1345 gets the file. The value to set the config to is "ACKTHPPT".
1346 For example:
1347 git -c annex.security.allow-unverified-downloads=ACKTHPPT annex
1349 get myfile
1350 It would be a good idea to check that it downloaded the file you
1352 expected, too.
1353 remote.name.annex-security-allow-unverified-downloads
1355 Per-remote configuration of annex.security.allow-unveri‐
1356 fied-downloads.
1357 annex.secure-erase-command
1359 This can be set to a command that should be run whenever git-
1360 annex removes the content of a file from the repository.
1361 In the command line, %file is replaced with the file that should
1363 be erased.
1364 For example, to use the wipe command, set it to wipe -f %file.
1366 remote.<name>.rsyncurl
1368 Used by rsync special remotes, this configures the location of
1369 the rsync repository to use. Normally this is automatically set
1370 up by git annex initremote, but you can change it if needed.
1371 remote.<name>.buprepo
1373 Used by bup special remotes, this configures the location of the
1374 bup repository to use. Normally this is automatically set up by
1375 git annex initremote, but you can change it if needed.
1376 remote.<name>.ddarrepo
1378 Used by ddar special remotes, this configures the location of
1379 the ddar repository to use. Normally this is automatically set
1380 up by git annex initremote, but you can change it if needed.
1381 remote.<name>.directory
1383 Used by directory special remotes, this configures the location
1384 of the directory where annexed files are stored for this remote.
1385 Normally this is automatically set up by git annex initremote,
1386 but you can change it if needed.
1387 remote.<name>.adb
1389 Used to identify remotes on Android devices accessed via adb.
1390 Normally this is automatically set up by git annex initremote.
1391 remote.<name>.androiddirectory
1393 Used by adb special remotes, this is the directory on the
1394 Android device where files are stored for this remote. Normally
1395 this is automatically set up by git annex initremote, but you
1396 can change it if needed.
1397 remote.<name>.androidserial
1399 Used by adb special remotes, this is the serial number of the
1400 Android device used by the remote. Normally this is automati‐
1401 cally set up by git annex initremote, but you can change it if
1402 needed, eg when upgrading to a new Android device.
1403 remote.<name>.s3
1405 Used to identify Amazon S3 special remotes. Normally this is
1406 automatically set up by git annex initremote.
1407 remote.<name>.glacier
1409 Used to identify Amazon Glacier special remotes. Normally this
1410 is automatically set up by git annex initremote.
1411 remote.<name>.webdav
1413 Used to identify webdav special remotes. Normally this is auto‐
1414 matically set up by git annex initremote.
1415 remote.<name>.tahoe
1417 Used to identify tahoe special remotes. Points to the configu‐
1418 ration directory for tahoe.
1419 remote.<name>.gcrypt
1421 Used to identify gcrypt special remotes. Normally this is auto‐
1422 matically set up by git annex initremote.
1423 It is set to "true" if this is a gcrypt remote. If the gcrypt
1425 remote is accessible over ssh and has git-annex-shell available
1426 to manage it, it's set to "shell".
1427 remote.<name>.hooktype, remote.<name>.externaltype
1429 Used by hook special remotes and external special remotes to
1430 record the type of the remote.
1431 annex.tune.objecthash1, annex.tune.objecthashlower, annex.tune.branch‐
1433 hash1
1434 These can be passed to git annex init to tune the repository.
1435 They cannot be safely changed in a running repository and should
1436 never be set in global git configuration. For details, see
1437 <https://git-annex.branchable.com/tuning/>.
1438
1440 The key-value backend used when adding a new file to the annex can be
1441 configured on a per-file-type basis via .gitattributes files. In the
1442 file, the annex.backend attribute can be set to the name of the backend
1443 to use. For example, this here's how to use the WORM backend by
1444 default, but the SHA256E backend for ogg files:
1445 * annex.backend=WORM
1447 *.ogg annex.backend=SHA256E
1448 There is a annex.largefiles attribute; which is used to configure which
1450 files are large enough to be added to the annex. See <https://git-
1451 annex.branchable.com/tips/largefiles> for details.
1452 The numcopies setting can also be configured on a per-file-type basis
1454 via the annex.numcopies attribute in .gitattributes files. This over‐
1455 rides other numcopies settings. For example, this makes two copies be
1456 needed for wav files and 3 copies for flac files:
1457 *.wav annex.numcopies=2
1459 *.flac annex.numcopies=3
1460 Note that setting numcopies to 0 is very unsafe.
1462 These settings are honored by git-annex whenever it's operating on a
1464 matching file. However, when using --all, --unused, or --key to specify
1465 keys to operate on, git-annex is operating on keys and not files, so
1466 will not honor the settings from .gitattributes. For this reason, the
1467 git annex numcopies command is useful to configure a global default for
1468 numcopies.
1469 Also note that when using views, only the toplevel .gitattributes file
1471 is preserved in the view, so other settings in other files won't have
1472 any effect.
1473
1475 git-annex, when called as a git subcommand, may return exit codes 0 or
1476 1 for success or failures, or, more rarely, 127 or 128 for certain very
1477 specific failures. git-annex itself should return 0 on success and 1
1478 on failure, unless the --time-limit=time option is hit, in which case
1479 it returns with exit code 101.
1480
1482 These environment variables are used by git-annex when set:
1483 GIT_WORK_TREE, GIT_DIR
1485 Handled the same as they are by git, see git(1)
1486 GIT_SSH, GIT_SSH_COMMAND
1488 Handled similarly to the same as described in git(1). The one
1489 difference is that git-annex will sometimes pass an additional
1490 "-n" parameter to these, as the first parameter, to prevent ssh
1491 from reading from stdin. Since that can break existing uses of
1492 these environment variables that don't expect the extra parame‐
1493 ter, you will need to set GIT_ANNEX_USE_GIT_SSH=1 to make git-
1494 annex support these.
1495 Note that setting either of these environment variables prevents
1497 git-annex from automatically enabling ssh connection caching
1498 (see annex.sshcaching), so it will slow down some operations
1499 with remotes over ssh. It's up to you to enable ssh connection
1500 caching if you need it; see ssh's documentation.
1501 Also, annex.ssh-options and remote.<name>.annex-ssh-options
1503 won't have any effect when these envionment variables are set.
1504 Usually it's better to configure any desired options through
1506 your ~/.ssh/config file, or by setting annex.ssh-options.
1507 GIT_ANNEX_VECTOR_CLOCK
1509 Normally git-annex timestamps lines in the log files committed
1510 to the git-annex branch. Setting this environment variable to a
1511 number will make git-annex use that rather than the current num‐
1512 ber of seconds since the UNIX epoch. Note that decimal seconds
1513 are supported.
1514 This is only provided for advanced users who either have a bet‐
1516 ter way to tell which commit is current than the local clock, or
1517 who need to avoid embedding timestamps for policy reasons. Mis‐
1518 use of this environment variable can confuse git-annex's
1519 book-keeping, sometimes in ways that git annex fsck is unable to
1520 repair.
1521 Some special remotes use additional environment variables for
1523 authentication etc. For example, AWS_ACCESS_KEY_ID and
1524 GIT_ANNEX_P2P_AUTHTOKEN. See special remote documentation.
1525
1527 These files are used by git-annex:
1528 .git/annex/objects/ in your git repository contains the annexed file
1530 contents that are currently available. Annexed files in your git repos‐
1531 itory symlink to that content.
1532 .git/annex/ in your git repository contains other run-time information
1534 used by git-annex.
1535 ~/.config/git-annex/autostart is a list of git repositories to start
1537 the git-annex assistant in.
1538 .git/hooks/pre-commit-annex in your git repository will be run whenever
1540 a commit is made to the HEAD branch, either by git commit, git-annex
1541 sync, or the git-annex assistant.
1542 .git/hooks/post-update-annex in your git repository will be run when‐
1544 ever the git-annex branch is updated. You can make this hook run git
1545 update-server-info when publishing a git-annex repository by http.
1546
1548 More git-annex documentation is available on its web site,
1549 <https://git-annex.branchable.com/>
1550 If git-annex is installed from a package, a copy of its documentation
1552 should be included, in, for example, /usr/share/doc/git-annex/.
1553
1555 Joey Hess <id@joeyh.name>
1556 <https://git-annex.branchable.com/>
1558 git-annex(1)