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.
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 --from remote branch[:subdir] | [path ...]
135 Add a tree of files to the repository.
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 remotedaemon
175 Persistant communication with remotes.
176 See git-annex-remotedaemon(1) for details.
178
180 init [description]
181 Until a repository (or one of its remotes) has been initialized,
183 git-annex will refuse to operate on it, to avoid accidentally
184 using it in a repository that was not intended to have an annex.
185 See git-annex-init(1) for details.
187 describe repository description
189 Changes the description of a repository.
190 See git-annex-describe(1) for details.
192 initremote name type=value [param=value ...]
194 Creates a new special remote, and adds it to .git/config.
195 See git-annex-initremote(1) for details.
197 enableremote name [param=value ...]
199 Enables use of an existing special remote in the current reposi‐
200 tory.
201 See git-annex-enableremote(1) for details.
203 renameremote
205 Renames a special remote.
206 See git-annex-renameremote(1) for details.
208 enable-tor
210 Sets up tor hidden service.
211 See git-annex-enable-tor(1) for details.
213 numcopies [N]
215 Configure desired number of copies.
216 See git-annex-numcopies(1) for details.
218 trust [repository ...]
220 Records that a repository is trusted to not unexpectedly lose
221 content. Use with care.
222 See git-annex-trust(1) for details.
224 untrust [repository ...]
226 Records that a repository is not trusted and could lose content
227 at any time.
228 See git-annex-untrust(1) for details.
230 semitrust [repository ...]
232 Returns a repository to the default semi trusted state.
233 See git-annex-semitrust(1) for details.
235 group repository groupname
237 Add a repository to a group.
238 See git-annex-group(1) for details.
240 ungroup repository groupname
242 Removes a repository from a group.
243 See git-annex-ungroup(1) for details.
245 wanted repository [expression]
247 Get or set preferred content expression.
248 See git-annex-wanted(1) for details.
250 groupwanted groupname [expression]
252 Get or set groupwanted expression.
253 See git-annex-groupwanted(1) for details.
255 required repository [expression]
257 Get or set required content expression.
258 See git-annex-required(1) for details.
260 schedule repository [expression]
262 Get or set scheduled jobs.
263 See git-annex-schedule(1) for details.
265 config Get and set other configuration stored in git-annex branch.
267 See git-annex-config(1) for details.
269 vicfg Opens EDITOR on a temp file containing most of the above config‐
271 uration settings, as well as a few others, and when it exits,
272 stores any changes made back to the git-annex branch.
273 See git-annex-vicfg(1) for details.
275 adjust Switches a repository to use an adjusted branch, which can auto‐
277 matically unlock all files, etc.
278 See git-annex-adjust(1) for details.
280 direct Switches a repository to use direct mode. (deprecated)
282 See git-annex-direct(1) for details.
284 indirect
286 Switches a repository to use indirect mode. (deprecated)
287 See git-annex-indirect(1) for details.
289
291 fsck [path ...]
292 Checks the annex consistency, and warns about or fixes any prob‐
294 lems found. This is a good complement to git fsck.
295 See git-annex-fsck(1) for details.
297 expire [repository:]time ...
299 Expires repositories that have not recently performed an activ‐
300 ity (such as a fsck).
301 See git-annex-expire(1) for details.
303 unused Checks the annex for data that does not correspond to any files
305 present in any tag or branch, and prints a numbered list of the
306 data.
307 See git-annex-unused(1) for details.
309 dropunused [number|range ...]
311 Drops the data corresponding to the numbers, as listed by the
312 last git annex unused
313 See git-annex-dropunused(1) for details.
315 addunused [number|range ...]
317 Adds back files for the content corresponding to the numbers or
318 ranges, as listed by the last git annex unused.
319 See git-annex-addunused(1) for details.
321 fix [path ...]
323 Fixes up symlinks that have become broken to again point to
324 annexed content.
325 See git-annex-fix(1) for details.
327 merge Automatically merge changes from remotes.
329 See git-annex-merge(1) for details.
331 upgrade
333 Upgrades the repository.
334 See git-annex-upgrade(1) for details.
336 dead [repository ...] [--key key]
338 Indicates that a repository or a single key has been irretriev‐
339 ably lost.
340 See git-annex-dead(1) for details.
342 forget Causes the git-annex branch to be rewritten, throwing away his‐
344 torical data about past locations of files.
345 See git-annex-forget(1) for details.
347 repair This can repair many of the problems with git repositories that
349 git fsck detects, but does not itself fix. It's useful if a
350 repository has become badly damaged. One way this can happen is
351 if a repository used by git-annex is on a removable drive that
352 gets unplugged at the wrong time.
353 See git-annex-repair(1) for details.
355 p2p Configure peer-2-Peer links between repositories.
357 See git-annex-p2p(1) for details.
359
361 find [path ...]
362 Outputs a list of annexed files in the specified path. With no
364 path, finds files in the current directory and its subdirecto‐
365 ries.
366 See git-annex-find(1) for details.
368 whereis [path ...]
370 Displays information about where the contents of files are
371 located.
372 See git-annex-whereis(1) for details.
374 list [path ...]
376 Displays a table of remotes that contain the contents of the
377 specified files. This is similar to whereis but a more compact
378 display.
379 See git-annex-list(1) for details.
381 log [path ...]
383 Displays the location log for the specified file or files, show‐
384 ing each repository they were added to ("+") and removed from
385 ("-").
386 See git-annex-log(1) for details.
388 info [directory|file|remote|uuid ...]
390 Displays statistics and other information for the specified
391 item, which can be a directory, or a file, or a remote, or the
392 uuid of a repository.
393 When no item is specified, displays statistics and information
395 for the repository as a whole.
396 See git-annex-info(1) for details.
398 version
400 Shows the version of git-annex, as well as repository version
401 information.
402 See git-annex-version(1) for details.
404 map Generate map of repositories.
406 See git-annex-map(1) for details.
408 inprogress
410 Access files while they're being downloaded.
411 See git-annex-inprogress(1) for details.
413
415 metadata [path ...]
416 The content of an annexed file can have any number of metadata
418 fields attached to it to describe it. Each metadata field can in
419 turn have any number of values.
420 This command can be used to set metadata, or show the currently
422 set metadata.
423 See git-annex-metadata(1) for details.
425 view [tag ...] [field=value ...] [field=glob ...] [!tag ...]
427 [field!=value ...]
428 Uses metadata to build a view branch of the files in the current
429 branch, and checks out the view branch. Only files in the cur‐
430 rent branch whose metadata matches all the specified field val‐
431 ues and tags will be shown in the view.
432 See git-annex-view(1) for details.
434 vpop [N]
436 Switches from the currently active view back to the previous
437 view. Or, from the first view back to original branch.
438 See git-annex-vpop(1) for details.
440 vfilter [tag ...] [field=value ...] [!tag ...] [field!=value ...]
442 Filters the current view to only the files that have the speci‐
443 fied field values and tags.
444 See git-annex-vfilter(1) for details.
446 vadd [field=glob ...] [field=value ...] [tag ...]
448 Changes the current view, adding an additional level of directo‐
449 ries to categorize the files.
450 See git-annex-vfilter(1) for details.
452 vcycle When a view involves nested subdirectories, this cycles the
454 order.
455 See git-annex-vcycle(1) for details.
457
459 migrate [path ...]
460 Changes the specified annexed files to use a different key-value
462 backend.
463 See git-annex-migrate(1) for details.
465 reinject src dest
467 Moves the src file into the annex as the content of the dest
468 file. This can be useful if you have obtained the content of a
469 file from elsewhere and want to put it in the local annex.
470 See git-annex-reinject(1) for details.
472 unannex [path ...]
474 Use this to undo an accidental git annex add command. It puts
475 the file back how it was before the add.
476 See git-annex-unannex(1) for details.
478 uninit De-initialize git-annex and clean out repository.
480 See git-annex-uninit(1) for details.
482 reinit uuid|description
484 Initialize repository, reusing old UUID.
485 See git-annex-reinit(1) for details.
487
489 pre-commit [path ...]
490 This is meant to be called from git's pre-commit hook. git annex
492 init automatically creates a pre-commit hook using this.
493 See git-annex-pre-commit(1) for details.
495 post-receive
497 This is meant to be called from git's post-receive hook. git
498 annex init automatically creates a post-receive hook using this.
499 See git-annex-post-receive(1) for details.
501 lookupkey [file ...]
503 Looks up key used for file.
504 See git-annex-lookupkey(1) for details.
506 calckey [file ...]
508 Calculates the key that would be used to refer to a file.
509 See git-annex-calckey(1) for details.
511 contentlocation [key ..]
513 Looks up location of annexed content for a key.
514 See git-annex-contentlocation(1) for details.
516 examinekey [key ...]
518 Print information that can be determined purely by looking at
519 the key.
520 See git-annex-examinekey(1) for details.
522 matchexpression
524 Checks if a preferred content expression matches provided data.
525 See git-annex-matchexpression(1) for details.
527 fromkey [key file]
529 Manually set up a file in the git repository to link to a speci‐
530 fied key.
531 See git-annex-fromkey(1) for details.
533 registerurl [key url]
535 Registers an url for a key.
536 See git-annex-registerurl(1) for details.
538 setkey key file
540 Moves a file into the annex as the content of a key.
541 See git-annex-setkey(1) for details.
543 dropkey [key ...]
545 Drops annexed content for specified keys.
546 See git-annex-dropkey(1) for details.
548 transferkey key [--from=remote|--to=remote]
550 Transfers a key from or to a remote.
551 See git-annex-transferkey(1) for details.
553 transferkeys
555 Used internally by 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 annex.uuid
735 A unique UUID for this repository (automatically set).
736 annex.backend
738 Name of the default key-value backend to use when adding new
739 files to the repository.
740 This is overridden by annex annex.backend configuration in the
742 .gitattributes files, and by the --backend option.
743 (This used to be named annex.backends, and that will still be
745 used if set.)
746 annex.securehashesonly
748 Set to true to indicate that the repository should only use
749 cryptographically secure hashes (SHA2, SHA3) and not insecure
750 hashes (MD5, SHA1) for content.
751 When this is set, the contents of files using cryptographically
753 insecure hashes will not be allowed to be added to the reposi‐
754 tory.
755 Also, git-annex fsck will complain about any files present in
757 the repository that use insecure hashes.
758 To configure the behavior in new clones of the repository, this
760 can be set using git-annex-config.
761 annex.maxextensionlength
763 Maximum length, in bytes, of what is considered a filename
764 extension when adding a file to a backend that preserves file‐
765 name extensions. The default length is 4, which allows exten‐
766 sions like "jpeg". The dot before the extension is not counted
767 part of its length. At most two extensions at the end of a file‐
768 name will be preserved, e.g. .gz or .tar.gz .
769 annex.diskreserve
771 Amount of disk space to reserve. Disk space is checked when
772 transferring content to avoid running out, and additional free
773 space can be reserved via this option, to make space for more
774 important content (such as git commit logs). Can be specified
775 with any commonly used units, for example, "0.5 gb", "500M", or
776 "100 KiloBytes"
777 The default reserve is 1 megabyte.
779 annex.largefiles
781 Used to configure which files are large enough to be added to
782 the annex. It is an expression that matches the large files, eg
783 "include=*.mp3 or largerthan(500kb)" See git-annex-match‐
784 ing-expression(1) for details on the syntax.
785 Overrides any annex.largefiles attributes in .gitattributes
787 files.
788 To configure a default annex.largefiles for all clones of the
790 repository, this can be set in git-annex-config(1).
791 This configures the behavior of both git-annex and git when
793 adding files to the repository. By default, git-annex add adds
794 all files to the annex (except dotfiles), and git add adds files
795 to git (unless they were added to the annex previously). When
796 annex.largefiles is configured, both git annex add and git add
797 will add matching large files to the annex, and the other files
798 to git.
799 Other git-annex commands also honor annex.largefiles, including
801 git annex import, git annex addurl, git annex importfeed and the
802 assistant.
803 annex.dotfiles
805 Normally, dotfiles are assumed to be files like .gitignore,
806 whose content should always be part of the git repository, so
807 they will not be added to the annex. Setting annex.dotfiles to
808 true makes dotfiles be added to the annex the same as any other
809 file.
810 To annex only some dotfiles, set this and configure annex.large‐
812 files to match the ones you want. For example, to match only
813 dotfiles ending in ".big"
814 git config annex.largefiles "(include=.*.big or
816 include=*/.*.big) or (exclude=.* and exclude=*/.*)"
817 git config annex.dotfiles true
818 To configure a default annex.dotfiles for all clones of the
820 repository, this can be set in git-annex-config(1).
821 annex.gitaddtoannex
823 Setting this to false will prevent git add from adding files to
824 the annex, despite the annex.largefiles configuration.
825 annex.addsmallfiles
827 Controls whether small files (not matching annex.largefiles)
828 should be checked into git by git annex add. Defaults to true;
829 set to false to instead make small files be skipped.
830 annex.addunlocked
832 Commands like git-annex add default to adding files to the
833 repository in locked form. This can make them add the files in
834 unlocked form, the same as if git-annex-unlock(1) were run on
835 the files.
836 This can be set to "true" to add everything unlocked, or it can
838 be a more complicated expression that matches files by name,
839 size, or content. See git-annex-matching-expression(1) for
840 details.
841 To configure a default annex.addunlocked for all clones of the
843 repository, this can be set in git-annex-config(1).
844 (Using git add always adds files in unlocked form and it is not
846 affected by this setting.)
847 When a repository has core.symlinks set to false, or has an
849 adjusted unlocked branch checked out, this setting is ignored,
850 and files are always added to the repository in unlocked form.
851 annex.numcopies
853 This is a deprecated setting. You should instead use the git
854 annex numcopies command to configure how many copies of files
855 are kept across all repositories, or the annex.numcopies .gitat‐
856 tributes setting.
857 This config setting is only looked at when git annex numcopies
859 has never been configured, and when there's no annex.numcopies
860 setting in the .gitattributes file.
861 Note that setting numcopies to 0 is very unsafe.
863 annex.genmetadata
865 Set this to true to make git-annex automatically generate some
866 metadata when adding files to the repository.
867 In particular, it stores year, month, and day metadata, from the
869 file's modification date.
870 When importfeed is used, it stores additional metadata from the
872 feed, such as the author, title, etc.
873 annex.used-refspec
875 This controls which refs git-annex unused considers to be used.
876 See REFSPEC FORMAT in git-annex-unused(1) for details.
877 annex.jobs
879 Configure the number of concurrent jobs to run. Default is 1.
880 Only git-annex commands that support the --jobs option will use
882 this.
883 Setting this to "cpus" will run one job per CPU core.
885 annex.queuesize
887 git-annex builds a queue of git commands, in order to combine
888 similar commands for speed. By default the size of the queue is
889 limited to 10240 commands; this can be used to change the size.
890 If you have plenty of memory and are working with very large
891 numbers of files, increasing the queue size can speed it up.
892 annex.bloomcapacity
894 The git annex unused and git annex sync --content commands use a
895 bloom filter to determine what files are present in eg, the work
896 tree. The default bloom filter is sized to handle up to 500000
897 files. If your repository is larger than that, you should
898 increase this value. Larger values will make git-annex unused
899 and git annex sync --content consume more memory; run git annex
900 info for memory usage numbers.
901 annex.bloomaccuracy
903 Adjusts the accuracy of the bloom filter used by git annex
904 unused and git annex sync --content. The default accuracy is
905 10000000 -- 1 unused file out of 10000000 will be missed by git
906 annex unused. Increasing the accuracy will make git annex unused
907 consume more memory; run git annex info for memory usage num‐
908 bers.
909 annex.sshcaching
911 By default, git-annex caches ssh connections using ssh's Con‐
912 trolMaster and ControlPersist settings (if built using a new
913 enough ssh). To disable this, set to false.
914 annex.alwayscommit
916 By default, git-annex automatically commits data to the git-
917 annex branch after each command is run. If you have a series of
918 commands that you want to make a single commit, you can run the
919 commands with -c annex.alwayscommit=false. You can later commit
920 the data by running git annex merge (or by automatic merges) or
921 git annex sync.
922 You should beware running git gc when using this configuration,
924 since it could garbage collect objects that are staged in git-
925 annex's index but not yet committed.
926 annex.commitmessage
928 When git-annex updates the git-annex branch, it usually makes up
929 its own commit message ("update"), since users rarely look at or
930 care about changes to that branch. If you do care, you can spec‐
931 ify this setting by running commands with -c annex.commitmes‐
932 sage=whatever
933 This works well in combination with annex.alwayscommit=false, to
935 gather up a set of changes and commit them with a message you
936 specify.
937 annex.allowsign
939 By default git-annex avoids gpg signing commits that it makes
940 when they're not the purpose of a command, but only a side
941 effect. That default avoids lots of gpg password prompts when
942 commit.gpgSign is set. A command like git annex sync or git
943 annex merge will gpg sign its commit, but a command like git
944 annex get, that updates the git-annex branch, will not. The
945 assistant also avoids signing commits.
946 Setting annex.allowsign to true lets all commits be signed, as
948 controlled by commit.gpgSign and other git configuration.
949 annex.merge-annex-branches
951 By default, git-annex branches that have been pulled from
952 remotes are automatically merged into the local git-annex
953 branch, so that git-annex has the most up-to-date possible
954 knowledge.
955 To avoid that merging, set this to "false". This can be useful
957 particularly when you don't have write permission to the reposi‐
958 tory.
959 annex.hardlink
961 Set this to true to make file contents be hard linked between
962 the repository and its remotes when possible, instead of a more
963 expensive copy.
964 Use with caution -- This can invalidate numcopies counting,
966 since with hard links, fewer copies of a file can exist. So, it
967 is a good idea to mark a repository using this setting as
968 untrusted.
969 When a repository is set up using git clone --shared, git-annex
971 init will automatically set annex.hardlink and mark the reposi‐
972 tory as untrusted.
973 annex.thin
975 Set this to true to make unlocked files be a hard link to their
976 content in the annex, rather than a second copy. This can save
977 considerable disk space, but when a modification is made to a
978 file, you will lose the local (and possibly only) copy of the
979 old version. So, enable with care.
980 After setting (or unsetting) this, you should run git annex fix
982 to fix up the annexed files in the work tree to be hard links
983 (or copies).
984 Note that this has no effect when the filesystem does not sup‐
986 port hard links. And when multiple files in the work tree have
987 the same content, only one of them gets hard linked to the
988 annex.
989 annex.resolvemerge
991 Set to false to prevent merge conflicts in the checked out
992 branch being automatically resolved by the git-annex assitant,
993 git-annex sync, git-annex merge, and the git-annex post-receive
994 hook.
995 To configure the behavior in all clones of the repository, this
997 can be set in git-annex-config(1).
998 annex.synccontent
1000 Set to true to make git-annex sync default to syncing annexed
1001 content.
1002 To configure the behavior in all clones of the repository, this
1004 can be set in git-annex-config(1).
1005 annex.synconlyannex
1007 Set to true to make git-annex sync default to only sincing the
1008 git-annex branch and annexed content.
1009 To configure the behavior in all clones of the repository, this
1011 can be set in git-annex-config(1).
1012 annex.debug
1014 Set to true to enable debug logging by default.
1015 annex.version
1017 The current version of the git-annex repository. This is main‐
1018 tained by git-annex and should never be manually changed.
1019 annex.autoupgraderepository
1021 When an old git-annex repository version has become deprecated,
1022 git-annex will normally automatically upgrade the repository to
1023 the new version.
1024 If this is set to false, git-annex won't automatically upgrade
1026 the repository. Instead it will exit with an error message. You
1027 can run git annex upgrade yourself when you are ready to upgrade
1028 the repository.
1029 annex.crippledfilesystem
1031 Set to true if the repository is on a crippled filesystem, such
1032 as FAT, which does not support symbolic links, or hard links, or
1033 unix permissions. This is automatically probed by "git annex
1034 init".
1035 annex.pidlock
1037 Normally, git-annex uses fine-grained lock files to allow multi‐
1038 ple processes to run concurrently without getting in each oth‐
1039 ers' way. That works great, unless you are using git-annex on a
1040 filesystem that does not support POSIX fcntl locks. This is
1041 sometimes the case when using NFS or Lustre filesystems.
1042 To support such situations, you can set annex.pidlock to true,
1044 and it will fall back to a single top-level pid file lock.
1045 Although, often, you'd really be better off fixing your net‐
1047 worked filesystem configuration to support POSIX locks.. And,
1048 some networked filesystems are so inconsistent that one node
1049 can't reliably tell when the other node is holding a pid lock.
1050 Caveat emptor.
1051 annex.pidlocktimeout
1053 When using pid lock files, it's possible for a stale lock file
1054 to get left behind by previous run of git-annex that crashed or
1055 was interrupted. This is mostly avoided, but can occur espe‐
1056 cially when using a network file system.
1057 git-annex will wait up to this many seconds for the pid lock
1059 file to go away, and will then abort if it cannot continue.
1060 Default: 300
1061 annex.cachecreds
1063 When "true" (the default), git-annex will cache credentials used
1064 to access special remotes in files in .git/annex/creds/ that
1065 only you can read. To disable that caching, set to "false", and
1066 credentials will only be read from the environment, or if they
1067 have been embedded in encrypted form in the git repository, will
1068 be extracted and decrypted each time git-annex needs to access
1069 the remote.
1070 annex.secure-erase-command
1072 This can be set to a command that should be run whenever git-
1073 annex removes the content of a file from the repository.
1074 In the command line, %file is replaced with the file that should
1076 be erased.
1077 For example, to use the wipe command, set it to wipe -f %file.
1079 annex.tune.objecthash1, annex.tune.objecthashlower, annex.tune.branch‐
1081 hash1
1082 These can be passed to git annex init to tune the repository.
1083 They cannot be safely changed in a running repository and should
1084 never be set in global git configuration. For details, see
1085 <https://git-annex.branchable.com/tuning/>.
1086
1088 Remotes are configured using these settings in .git/config.
1089 remote.<name>.annex-cost
1091 When determining which repository to transfer annexed files from
1092 or to, ones with lower costs are preferred. The default cost is
1093 100 for local repositories, and 200 for remote repositories.
1094 remote.<name>.annex-cost-command
1096 If set, the command is run, and the number it outputs is used as
1097 the cost. This allows varying the cost based on e.g., the cur‐
1098 rent network.
1099 remote.<name>.annex-start-command
1101 A command to run when git-annex begins to use the remote. This
1102 can be used to, for example, mount the directory containing the
1103 remote.
1104 The command may be run repeatedly when multiple git-annex pro‐
1106 cesses are running concurrently.
1107 remote.<name>.annex-stop-command
1109 A command to run when git-annex is done using the remote.
1110 The command will only be run once *all* running git-annex pro‐
1112 cesses are finished using the remote.
1113 remote.<name>.annex-shell
1115 Specify an alternative git-annex-shell executable on the remote
1116 instead of looking for "git-annex-shell" on the PATH.
1117 This is useful if the git-annex-shell program is outside the
1119 PATH or has a non-standard name.
1120 remote.<name>.annex-ignore
1122 If set to true, prevents git-annex from storing file contents on
1123 this remote by default. (You can still request it be used by
1124 the --from and --to options.)
1125 This is, for example, useful if the remote is located somewhere
1127 without git-annex-shell. (For example, if it's on GitHub). Or,
1128 it could be used if the network connection between two reposito‐
1129 ries is too slow to be used normally.
1130 This does not prevent git-annex sync (or the git-annex assis‐
1132 tant) from syncing the git repository to the remote.
1133 remote.<name>.annex-ignore-command
1135 If set, the command is run, and if it exits nonzero, that's the
1136 same as setting annex-ignore to true. This allows controlling
1137 behavior based on e.g., the current network.
1138 remote.<name>.annex-sync
1140 If set to false, prevents git-annex sync (and the git-annex
1141 assistant) from syncing with this remote by default. However,
1142 git annex sync <name> can still be used to sync with the remote.
1143 remote.<name>.annex-sync-command
1145 If set, the command is run, and if it exits nonzero, that's the
1146 same as setting annex-sync to false. This allows controlling
1147 behavior based on e.g., the current network.
1148 remote.<name>.annex-pull
1150 If set to false, prevents git-annex sync (and the git-annex
1151 assistant etc) from ever pulling (or fetching) from the remote.
1152 remote.<name>.annex-push
1154 If set to false, prevents git-annex sync (and the git-annex
1155 assistant etc) from ever pushing to the remote.
1156 remote.<name>.annex-readonly
1158 If set to true, prevents git-annex from making changes to a
1159 remote. This both prevents git-annex sync from pushing changes,
1160 and prevents storing or removing files from read-only remote.
1161 remote.<name>.annex-verify, annex.verify
1163 By default, git-annex will verify the checksums of objects down‐
1164 loaded from remotes. If you trust a remote and don't want the
1165 overhead of these checksums, you can set this to false.
1166 Note that even when this is set to false, git-annex does verifi‐
1168 cation in some edge cases, where it's likely the case than an
1169 object was downloaded incorrectly, or when needed for security.
1170 remote.<name>.annex-tracking-branch
1172 This is for use with special remotes that support exports and
1173 imports.
1174 When set to eg, "master", this tells git-annex that you want the
1176 special remote to track that branch.
1177 When set to eg, "master:subdir", the special remote tracks only
1179 the subdirectory of that branch.
1180 git-annex sync --content will import changes from the remote and
1182 merge them into the annex-tracking-branch. They also export
1183 changes made to the branch to the remote.
1184 remote.<name>.annex-export-tracking
1186 Deprecated name for remote.<name>.annex-tracking-branch. Will
1187 still be used if it's configured and remote.<name>.annex-track‐
1188 ing-branch is not.
1189 remote.<name>.annexUrl
1191 Can be used to specify a different url than the regular
1192 remote.<name>.url for git-annex to use when talking with the
1193 remote. Similar to the pushUrl used by git-push.
1194 remote.<name>.annex-uuid
1196 git-annex caches UUIDs of remote repositories here.
1197 remote.<name>.annex-config-uuid
1199 Used for some special remotes, points to a different special
1200 remote configuration to use.
1201 remote.<name>.annex-retry, annex.retry
1203 Configure retries of failed transfers on a per-remote and gen‐
1204 eral basis, respectively. The value is the number of retries
1205 that can be made of the same transfer. (default 0)
1206 remote.<name>.annex-retry-delay, annex.retry-delay
1208 Number of seconds to delay before the first retry of a transfer.
1209 When making multiple retries of the same transfer, the delay
1210 doubles after each retry. (default 1)
1211 remote.<name>.annex-checkuuid
1213 This only affects remotes that have their url pointing to a
1214 directory on the same system. git-annex normally checks the uuid
1215 of such remotes each time it's run, which lets it transparently
1216 deal with different drives being mounted to the location at dif‐
1217 ferent times.
1218 Setting annex-checkuuid to false will prevent it from checking
1220 the uuid at startup (although the uuid is still verified before
1221 making any changes to the remote repository). This may be useful
1222 to set to prevent unncessary spin-up or automounting of a drive.
1223 remote.<name>.annex-trustlevel
1225 Configures a local trust level for the remote. This overrides
1226 the value configured by the trust and untrust commands. The
1227 value can be any of "trusted", "semitrusted" or "untrusted".
1228 remote.<name>.annex-availability
1230 Can be used to tell git-annex whether a remote is LocallyAvail‐
1231 able or GloballyAvailable. Normally, git-annex determines this
1232 automatically.
1233 remote.<name>.annex-speculate-present
1235 Set to "true" to make git-annex speculate that this remote may
1236 contain the content of any file, even though its normal location
1237 tracking does not indicate that it does. This will cause git-
1238 annex to try to get all file contents from the remote. Can be
1239 useful in setting up a caching remote.
1240 remote.<name>.annex-bare
1242 Can be used to tell git-annex if a remote is a bare repository
1243 or not. Normally, git-annex determines this automatically.
1244 remote.<name>.annex-ssh-options
1246 Options to use when using ssh to talk to this remote.
1247 remote.<name>.annex-rsync-options
1249 Options to use when using rsync to or from this remote. For
1250 example, to force IPv6, and limit the bandwidth to 100Kbyte/s,
1251 set it to -6 --bwlimit 100
1252 Note that git-annex-shell has a whitelist of allowed rsync
1254 options, and others will not be be passed to the remote rsync.
1255 So using some options may break the communication between the
1256 local and remote rsyncs.
1257 remote.<name>.annex-rsync-upload-options
1259 Options to use when using rsync to upload a file to a remote.
1260 These options are passed after other applicable rsync options,
1262 so can be used to override them. For example, to limit upload
1263 bandwidth to 10Kbyte/s, set --bwlimit 10.
1264 remote.<name>.annex-rsync-download-options
1266 Options to use when using rsync to download a file from a
1267 remote.
1268 These options are passed after other applicable rsync options,
1270 so can be used to override them.
1271 remote.<name>.annex-rsync-transport
1273 The remote shell to use to connect to the rsync remote. Possible
1274 values are ssh (the default) and rsh, together with their argu‐
1275 ments, for instance ssh -p 2222 -c blowfish; Note that the
1276 remote hostname should not appear there, see rsync(1) for
1277 details. When the transport used is ssh, connections are auto‐
1278 matically cached unless annex.sshcaching is unset.
1279 remote.<name>.annex-bup-split-options
1281 Options to pass to bup split when storing content in this
1282 remote. For example, to limit the bandwidth to 100Kbyte/s, set
1283 it to --bwlimit 100k (There is no corresponding option for bup
1284 join.)
1285 remote.<name>.annex-gnupg-options
1287 Options to pass to GnuPG when it's encrypting data. For
1288 instance, to use the AES cipher with a 256 bits key and disable
1289 compression, set it to --cipher-algo AES256 --compress-algo
1290 none. (These options take precedence over the default GnuPG con‐
1291 figuration, which is otherwise used.)
1292 remote.<name>.annex-gnupg-decrypt-options
1294 Options to pass to GnuPG when it's decrypting data. (These
1295 options take precedence over the default GnuPG configuration,
1296 which is otherwise used.)
1297 annex.ssh-options, annex.rsync-options,
1299 annex.rsync-upload-options, annex.rsync-download-options,
1300 annex.bup-split-options, annex.gnupg-options,
1301 annex.gnupg-decrypt-options
1302 Default options to use if a remote does not have more specific
1304 options as described above.
1305 remote.<name>.annex-rsyncurl
1307 Used by rsync special remotes, this configures the location of
1308 the rsync repository to use. Normally this is automatically set
1309 up by git annex initremote, but you can change it if needed.
1310 remote.<name>.annex-buprepo
1312 Used by bup special remotes, this configures the location of the
1313 bup repository to use. Normally this is automatically set up by
1314 git annex initremote, but you can change it if needed.
1315 remote.<name>.annex-ddarrepo
1317 Used by ddar special remotes, this configures the location of
1318 the ddar repository to use. Normally this is automatically set
1319 up by git annex initremote, but you can change it if needed.
1320 remote.<name>.annex-directory
1322 Used by directory special remotes, this configures the location
1323 of the directory where annexed files are stored for this remote.
1324 Normally this is automatically set up by git annex initremote,
1325 but you can change it if needed.
1326 remote.<name>.annex-adb
1328 Used to identify remotes on Android devices accessed via adb.
1329 Normally this is automatically set up by git annex initremote.
1330 remote.<name>.annex-androiddirectory
1332 Used by adb special remotes, this is the directory on the
1333 Android device where files are stored for this remote. Normally
1334 this is automatically set up by git annex initremote, but you
1335 can change it if needed.
1336 remote.<name>.annex-androidserial
1338 Used by adb special remotes, this is the serial number of the
1339 Android device used by the remote. Normally this is automati‐
1340 cally set up by git annex initremote, but you can change it if
1341 needed, eg when upgrading to a new Android device.
1342 remote.<name>.annex-s3
1344 Used to identify Amazon S3 special remotes. Normally this is
1345 automatically set up by git annex initremote.
1346 remote.<name>.annex-glacier
1348 Used to identify Amazon Glacier special remotes. Normally this
1349 is automatically set up by git annex initremote.
1350 remote.<name>.annex-webdav
1352 Used to identify webdav special remotes. Normally this is auto‐
1353 matically set up by git annex initremote.
1354 remote.<name>.annex-tahoe
1356 Used to identify tahoe special remotes. Points to the configu‐
1357 ration directory for tahoe.
1358 remote.<name>.annex-gcrypt
1360 Used to identify gcrypt special remotes. Normally this is auto‐
1361 matically set up by git annex initremote.
1362 It is set to "true" if this is a gcrypt remote. If the gcrypt
1364 remote is accessible over ssh and has git-annex-shell available
1365 to manage it, it's set to "shell".
1366 remote.<name>.annex-git-lfs
1368 Used to identify git-lfs special remotes. Normally this is
1369 automatically set up by git annex initremote.
1370 It is set to "true" if this is a git-lfs remote.
1372 remote.<name>.annex-hooktype, remote.<name>.annex-externaltype
1374 Used by hook special remotes and external special remotes to
1375 record the type of the remote.
1376 annex.web-options
1378 Options to pass to curl when git-annex uses it to download urls
1379 (rather than the default built-in url downloader).
1380 For example, to force IPv4 only, set it to "-4". Or to make
1382 curl use your ~/.netrc file, set it to "--netrc".
1383 Setting this option makes git-annex use curl, but only when
1385 annex.security.allowed-ip-addresses is configured in a specific
1386 way. See its documentation.
1387 annex.youtube-dl-options
1389 Options to pass to youtube-dl when using it to find the url to
1390 download for a video.
1391 Some options may break git-annex's integration with youtube-dl.
1393 For example, the --output option could cause it to store files
1394 somewhere git-annex won't find them. Avoid setting here or in
1395 the youtube-dl config file any options that cause youtube-dl to
1396 download more than one file, or to store the file anywhere other
1397 than the current working directory.
1398 annex.aria-torrent-options
1400 Options to pass to aria2c when using it to download a torrent.
1401 annex.http-headers
1403 HTTP headers to send when downloading from the web. Multiple
1404 lines of this option can be set, one per header.
1405 annex.http-headers-command
1407 If set, the command is run and each line of its output is used
1408 as a HTTP header. This overrides annex.http-headers.
1409 annex.security.allowed-url-schemes
1411 List of URL schemes that git-annex is allowed to download con‐
1412 tent from. The default is "http https ftp".
1413 Think very carefully before changing this; there are security
1415 implications. For example, if it's changed to allow "file" URLs,
1416 then anyone who can get a commit into your git-annex repository
1417 could git-annex addurl a pointer to a private file located out‐
1418 side that repository, possibly causing it to be copied into your
1419 repository and transferred on to other remotes, exposing its
1420 content.
1421 Some special remotes support their own domain-specific URL
1423 schemes; those are not affected by this configuration setting.
1424 annex.security.allowed-ip-addresses
1426 By default, git-annex only makes connections to public IP
1427 addresses; it will refuse to use HTTP and other servers on
1428 localhost or on a private network.
1429 This setting can override that behavior, allowing access to par‐
1431 ticular IP addresses that would normally be blocked. For example
1432 "127.0.0.1 ::1" allows access to localhost (both IPV4 and IPV6).
1433 To allow access to all IP addresses, use "all"
1434 Think very carefully before changing this; there are security
1436 implications. Anyone who can get a commit into your git-annex
1437 repository could git annex addurl an url on a private server,
1438 possibly causing it to be downloaded into your repository and
1439 transferred to other remotes, exposing its content.
1440 Note that, since the interfaces of curl and youtube-dl do not
1442 allow these IP address restrictions to be enforced, curl and
1443 youtube-dl will never be used unless annex.secu‐
1444 rity.allowed-ip-addresses=all.
1445 To allow accessing local or private IP addresses on only spe‐
1447 cific ports, use the syntax "[addr]:port". For example,
1448 "[127.0.0.1]:80 [127.0.0.1]:443 [::1]:80 [::1]:443" allows
1449 localhost on the http ports only.
1450 annex.security.allowed-http-addresses
1452 Old name for annex.security.allowed-ip-addresses. If set, this
1453 is treated the same as having annex.secu‐
1454 rity.allowed-ip-addresses set.
1455 annex.security.allow-unverified-downloads
1457 For security reasons, git-annex refuses to download content from
1458 most special remotes when it cannot check a hash to verify that
1459 the correct content was downloaded. This particularly impacts
1460 downloading the content of URL or WORM keys, which lack hashes.
1461 The best way to avoid problems due to this is to migrate files
1463 away from such keys, before their content reaches a special
1464 remote. See git-annex-migrate(1).
1465 When the content is only available from a special remote, you
1467 can use this configuration to force git-annex to download it.
1468 But you do so at your own risk, and it's very important you read
1469 and understand the information below first!
1470 Downloading unverified content from encrypted special remotes is
1472 prevented, because the special remote could send some other
1473 encrypted content than what you expect, causing git-annex to
1474 decrypt data that you never checked into git-annex, and risking
1475 exposing the decrypted data to any non-encrypted remotes you
1476 send content to.
1477 Downloading unverified content from (non-encrypted) external
1479 special remotes is prevented, because they could follow http
1480 redirects to web servers on localhost or on a private network,
1481 or in some cases to a file:/// url.
1482 If you decide to bypass this security check, the best thing to
1484 do is to only set it temporarily while running the command that
1485 gets the file. The value to set the config to is "ACKTHPPT".
1486 For example:
1487 git -c annex.security.allow-unverified-downloads=ACKTHPPT annex
1489 get myfile
1490 It would be a good idea to check that it downloaded the file you
1492 expected, too.
1493 remote.<name>.annex-security-allow-unverified-downloads
1495 Per-remote configuration of annex.security.allow-unveri‐
1496 fied-downloads.
1497
1499 annex.delayadd
1500 Makes the watch and assistant commands delay for the specified
1502 number of seconds before adding a newly created file to the
1503 annex. Normally this is not needed, because they already wait
1504 for all writers of the file to close it.
1505 annex.expireunused
1507 Controls what the assistant does about unused file contents that
1508 are stored in the repository.
1509 The default is false, which causes all old and unused file con‐
1511 tents to be retained, unless the assistant is able to move them
1512 to some other repository (such as a backup repository).
1513 Can be set to a time specification, like "7d" or "1m", and then
1515 file contents that have been known to be unused for a week or a
1516 month will be deleted.
1517 annex.fscknudge
1519 When set to false, prevents the webapp from reminding you when
1520 using repositories that lack consistency checks.
1521 annex.autoupgrade
1523 When set to ask (the default), the webapp will check for new
1524 versions and prompt if they should be upgraded to. When set to
1525 true, automatically upgrades without prompting (on some sup‐
1526 ported platforms). When set to false, disables any upgrade
1527 checking.
1528 Note that upgrade checking is only done when git-annex is
1530 installed from one of the prebuilt images from its website. This
1531 does not bypass e.g., a Linux distribution's own upgrade han‐
1532 dling code.
1533 This setting also controls whether to restart the git-annex
1535 assistant when the git-annex binary is detected to have changed.
1536 That is useful no matter how you installed git-annex.
1537 annex.autocommit
1539 Set to false to prevent the git-annex assistant and git-annex
1540 sync from automatically committing changes to files in the
1541 repository.
1542 To configure the behavior in all clones of the repository, this
1544 can be set in git-annex-config(1).
1545 annex.startupscan
1547 Set to false to prevent the git-annex assistant from scanning
1548 the repository for new and changed files on startup. This will
1549 prevent it from noticing changes that were made while it was not
1550 running, but can be a useful performance tweak for a large
1551 repository.
1552 annex.listen
1554 Configures which address the webapp listens on. The default is
1555 localhost. Can be either an IP address, or a hostname that
1556 resolves to the desired address.
1557
1559 The key-value backend used when adding a new file to the annex can be
1560 configured on a per-file-type basis via .gitattributes files. In the
1561 file, the annex.backend attribute can be set to the name of the backend
1562 to use. For example, this here's how to use the WORM backend by
1563 default, but the SHA256E backend for ogg files:
1564 * annex.backend=WORM
1566 *.ogg annex.backend=SHA256E
1567 There is a annex.largefiles attribute, which is used to configure which
1569 files are large enough to be added to the annex. Since attributes can‐
1570 not contain spaces, it is difficult to use for more complex
1571 annex.largefiles settings. Setting annex.largefiles in git-annex-con‐
1572 fig(1) is an easier way to configure it across all clones of the repos‐
1573 itory. See git-annex-matching-expression(1) for details on the syntax.
1574 The numcopies setting can also be configured on a per-file-type basis
1576 via the annex.numcopies attribute in .gitattributes files. This over‐
1577 rides other numcopies settings. For example, this makes two copies be
1578 needed for wav files and 3 copies for flac files:
1579 *.wav annex.numcopies=2
1581 *.flac annex.numcopies=3
1582 Note that setting numcopies to 0 is very unsafe.
1584 These settings are honored by git-annex whenever it's operating on a
1586 matching file. However, when using --all, --unused, or --key to specify
1587 keys to operate on, git-annex is operating on keys and not files, so
1588 will not honor the settings from .gitattributes. For this reason, the
1589 git annex numcopies command is useful to configure a global default for
1590 numcopies.
1591 Also note that when using views, only the toplevel .gitattributes file
1593 is preserved in the view, so other settings in other files won't have
1594 any effect.
1595
1597 git-annex, when called as a git subcommand, may return exit codes 0 or
1598 1 for success or failures, or, more rarely, 127 or 128 for certain very
1599 specific failures. git-annex itself should return 0 on success and 1
1600 on failure, unless the --time-limit=time option is hit, in which case
1601 it returns with exit code 101.
1602
1604 These environment variables are used by git-annex when set:
1605 GIT_WORK_TREE, GIT_DIR
1607 Handled the same as they are by git, see git(1)
1608 GIT_SSH, GIT_SSH_COMMAND
1610 Handled similarly to the same as described in git(1). The one
1611 difference is that git-annex will sometimes pass an additional
1612 "-n" parameter to these, as the first parameter, to prevent ssh
1613 from reading from stdin. Since that can break existing uses of
1614 these environment variables that don't expect the extra parame‐
1615 ter, you will need to set GIT_ANNEX_USE_GIT_SSH=1 to make git-
1616 annex support these.
1617 Note that setting either of these environment variables prevents
1619 git-annex from automatically enabling ssh connection caching
1620 (see annex.sshcaching), so it will slow down some operations
1621 with remotes over ssh. It's up to you to enable ssh connection
1622 caching if you need it; see ssh's documentation.
1623 Also, annex.ssh-options and remote.<name>.annex-ssh-options
1625 won't have any effect when these envionment variables are set.
1626 Usually it's better to configure any desired options through
1628 your ~/.ssh/config file, or by setting annex.ssh-options.
1629 GIT_ANNEX_VECTOR_CLOCK
1631 Normally git-annex timestamps lines in the log files committed
1632 to the git-annex branch. Setting this environment variable to a
1633 number will make git-annex use that rather than the current num‐
1634 ber of seconds since the UNIX epoch. Note that decimal seconds
1635 are supported.
1636 This is only provided for advanced users who either have a bet‐
1638 ter way to tell which commit is current than the local clock, or
1639 who need to avoid embedding timestamps for policy reasons. Mis‐
1640 use of this environment variable can confuse git-annex's
1641 book-keeping, sometimes in ways that git annex fsck is unable to
1642 repair.
1643 Some special remotes use additional environment variables for
1645 authentication etc. For example, AWS_ACCESS_KEY_ID and
1646 GIT_ANNEX_P2P_AUTHTOKEN. See special remote documentation.
1647
1649 These files are used by git-annex:
1650 .git/annex/objects/ in your git repository contains the annexed file
1652 contents that are currently available. Annexed files in your git repos‐
1653 itory symlink to that content.
1654 .git/annex/ in your git repository contains other run-time information
1656 used by git-annex.
1657 ~/.config/git-annex/autostart is a list of git repositories to start
1659 the git-annex assistant in.
1660 .git/hooks/pre-commit-annex in your git repository will be run whenever
1662 a commit is made to the HEAD branch, either by git commit, git-annex
1663 sync, or the git-annex assistant.
1664 .git/hooks/post-update-annex in your git repository will be run when‐
1666 ever the git-annex branch is updated. You can make this hook run git
1667 update-server-info when publishing a git-annex repository by http.
1668
1670 More git-annex documentation is available on its web site,
1671 <https://git-annex.branchable.com/>
1672 If git-annex is installed from a package, a copy of its documentation
1674 should be included, in, for example, /usr/share/doc/git-annex/.
1675
1677 Joey Hess <id@joeyh.name>
1678 <https://git-annex.branchable.com/>
1680 git-annex(1)