Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
git-annex(1)		    General Commands Manual		  git-annex(1)

NAME
       git-annex - manage files	with git, without checking their contents in

SYNOPSIS
       git annex command [params ...]

DESCRIPTION
       git-annex  allows  managing  files  with	git, without checking the file
       contents	into git. While	that may seem paradoxical, it is  useful  when
       dealing with files larger than git can currently	easily handle, whether
       due to limitations in memory, checksumming time,	or disk	space.

       Even without file content tracking, being able  to  manage  files  with
       git, move files around and delete files with versioned directory	trees,
       and use branches	and distributed	clones,	are all	very handy reasons  to
       use git.	And annexed files can co-exist in the same git repository with
       regularly versioned files, which	is convenient  for  maintaining	 docu-
       ments,  Makefiles,  etc that are	associated with	annexed	files but that
       benefit from full revision control.

       When a file is annexed, its content is moved into  a  key-value	store,
       and  a  symlink	is made	that points to the content. These symlinks are
       checked into git	and versioned like regular files. You  can  move  them
       around,	delete them, and so on.	Pushing	to another git repository will
       make git-annex there aware of the annexed file, and it can be  used  to
       retrieve	its content from the key-value store.

EXAMPLES
	# git annex get	video/hackity_hack_and_kaxxt.mov
	get video/hackity_hack_and_kaxxt.mov (not available)
	  I was	unable to access these remotes:	server
	  Try making some of these repositories	available:
	    5863d8c0-d9a9-11df-adb2-af51e6559a49  -- my	home file server
	    58d84e8a-d9ae-11df-a1aa-ab9aa8c00826  -- portable USB drive
	    ca20064c-dbb5-11df-b2fe-002170d25c55  -- backup SATA drive
	failed
	# sudo mount /media/usb
	# git remote add usbdrive /media/usb
	# git annex get	video/hackity_hack_and_kaxxt.mov
	get video/hackity_hack_and_kaxxt.mov (from usbdrive...)	ok

	# git annex add	iso
	add iso/Debian_5.0.iso ok

	# git annex drop iso/Debian_4.0.iso
	drop iso/Debian_4.0.iso	ok

	# git annex move iso --to=usbdrive
	move iso/Debian_5.0.iso	(moving	to usbdrive...)	ok

COMMONLY USED COMMANDS
       help

	      Display built-in help.

	      For help on a specific command, use git annex help command

       add [path ...]
	      Adds files to the	annex.

	      See git-annex-add(1) for details.

       get [path ...]
	      Makes the	content	of annexed files available in this repository.

	      See git-annex-get(1) for details.

       drop [path ...]
	      Drops the	content	of annexed files from this repository.

	      See git-annex-drop(1) for	details.

       move [path ...] [--from=remote|--to=remote]
	      Moves the	content	of files from or to another remote.

	      See git-annex-move(1) for	details.

       copy [path ...] [--from=remote|--to=remote]
	      Copies the content of files from or to another remote.

	      See git-annex-copy(1) for	details.

       status [path ...]
	      Similar  to git status --short, displays the status of the files
	      in the working tree.

	      See git-annex-status(1) for details.

       unlock [path ...]
	      Unlock annexed files for modification.

	      See git-annex-unlock(1) for details.

       edit [path ...]
	      This is an alias for the unlock command. May be easier to	remem-
	      ber,  if	you  think  of this as allowing	you to edit an annexed
	      file.

       lock [path ...]
	      Use this to undo an unlock command if you	don't want  to	modify
	      the files, or have made modifications you	want to	discard.

	      See git-annex-lock(1) for	details.

       sync [remote ...]
	      Synchronize local	repository with	remotes.

	      See git-annex-sync(1) for	details.

       mirror [path ...] [--to=remote|--from=remote]
	      Mirror content of	files to/from another repository.

	      See git-annex-mirror(1) for details.

       addurl [url ...]
	      Downloads	each url to its	own file, which	is added to the	annex.

	      See git-annex-addurl(1) for details.

       rmurl file url
	      Record that the file is no longer	available at the url.

	      See git-annex-rmurl(1) for details.

       import --from remote branch[:subdir] | [path ...]
	      Add a tree of files to the repository.

	      See git-annex-import(1) for details.

       importfeed [url ...]
	      Imports the contents of podcast feeds into the annex.

	      See git-annex-importfeed(1) for details.

       export treeish --to remote
	      Export content to	a remote.

	      See git-annex-export(1) for details.

       undo [filename|directory] ...
	      Undo last	change to a file or directory.

	      See git-annex-undo(1) for	details.

       multicast
	      Multicast	file distribution.

	      See git-annex-multicast(1) for details.

       watch  Watch for	changes	and autocommit.

	      See git-annex-watch(1) for details.

       assistant
	      Automatically sync folders between devices.

	      See git-annex-assistant(1) for details.

       webapp Opens  a	web app, that allows easy setup	of a git-annex reposi-
	      tory, and	control	of the git-annex assistant. If	the  assistant
	      is not already running, it will be started.

	      See git-annex-webapp(1) for details.

       remotedaemon
	      Persistant communication with remotes.

	      See git-annex-remotedaemon(1) for	details.

REPOSITORY SETUP COMMANDS
       init [description]

	      Until a repository (or one of its	remotes) has been initialized,
	      git-annex	will refuse to operate on it,  to  avoid  accidentally
	      using it in a repository that was	not intended to	have an	annex.

	      See git-annex-init(1) for	details.

       describe	repository description
	      Changes the description of a repository.

	      See git-annex-describe(1)	for details.

       initremote name type=value [param=value ...]
	      Creates a	new special remote, and	adds it	to .git/config.

	      See git-annex-initremote(1) for details.

       enableremote name [param=value ...]
	      Enables use of an	existing special remote	in the current reposi-
	      tory.

	      See git-annex-enableremote(1) for	details.

       renameremote
	      Renames a	special	remote.

	      See git-annex-renameremote(1) for	details.

       enable-tor
	      Sets up tor hidden service.

	      See git-annex-enable-tor(1) for details.

       numcopies [N]
	      Configure	desired	number of copies.

	      See git-annex-numcopies(1) for details.

       trust [repository ...]
	      Records that a repository	is trusted to  not  unexpectedly  lose
	      content. Use with	care.

	      See git-annex-trust(1) for details.

       untrust [repository ...]
	      Records  that a repository is not	trusted	and could lose content
	      at any time.

	      See git-annex-untrust(1) for details.

       semitrust [repository ...]
	      Returns a	repository to the default semi trusted state.

	      See git-annex-semitrust(1) for details.

       group repository	groupname
	      Add a repository to a group.

	      See git-annex-group(1) for details.

       ungroup repository groupname
	      Removes a	repository from	a group.

	      See git-annex-ungroup(1) for details.

       wanted repository [expression]
	      Get or set preferred content expression.

	      See git-annex-wanted(1) for details.

       groupwanted groupname [expression]
	      Get or set groupwanted expression.

	      See git-annex-groupwanted(1) for details.

       required	repository [expression]
	      Get or set required content expression.

	      See git-annex-required(1)	for details.

       schedule	repository [expression]
	      Get or set scheduled jobs.

	      See git-annex-schedule(1)	for details.

       config Get and set other	configuration stored in	git-annex branch.

	      See git-annex-config(1) for details.

       vicfg  Opens EDITOR on a	temp file containing most of the above config-
	      uration  settings,  as  well as a	few others, and	when it	exits,
	      stores any changes made back to the git-annex branch.

	      See git-annex-vicfg(1) for details.

       adjust Switches a repository to use an adjusted branch, which can auto-
	      matically	unlock all files, etc.

	      See git-annex-adjust(1) for details.

       direct Switches a repository to use direct mode.	(deprecated)

	      See git-annex-direct(1) for details.

       indirect
	      Switches a repository to use indirect mode. (deprecated)

	      See git-annex-indirect(1)	for details.

REPOSITORY MAINTENANCE COMMANDS
       fsck [path ...]

	      Checks the annex consistency, and	warns about or fixes any prob-
	      lems found.  This	is a good complement to	git fsck.

	      See git-annex-fsck(1) for	details.

       expire [repository:]time	...
	      Expires repositories that	have not recently performed an	activ-
	      ity (such	as a fsck).

	      See git-annex-expire(1) for details.

       unused Checks  the annex	for data that does not correspond to any files
	      present in any tag or branch, and	prints a numbered list of  the
	      data.

	      See git-annex-unused(1) for details.

       dropunused [number|range	...]
	      Drops  the  data	corresponding to the numbers, as listed	by the
	      last git annex unused

	      See git-annex-dropunused(1) for details.

       addunused [number|range ...]
	      Adds back	files for the content corresponding to the numbers  or
	      ranges, as listed	by the last git	annex unused.

	      See git-annex-addunused(1) for details.

       fix [path ...]
	      Fixes  up	symlinks that have become broken to again point	to an-
	      nexed content.

	      See git-annex-fix(1) for details.

       merge  Automatically merge changes from remotes.

	      See git-annex-merge(1) for details.

       upgrade
	      Upgrades the repository.

	      See git-annex-upgrade(1) for details.

       dead [repository	...] [--key key]
	      Indicates	that a repository or a single key has been  irretriev-
	      ably lost.

	      See git-annex-dead(1) for	details.

       forget Causes  the git-annex branch to be rewritten, throwing away his-
	      torical data about past locations	of files.

	      See git-annex-forget(1) for details.

       repair This can repair many of the problems with	git repositories  that
	      git  fsck	 detects,  but	does  not itself fix. It's useful if a
	      repository has become badly damaged. One way this	can happen  is
	      if  a  repository	used by	git-annex is on	a removable drive that
	      gets unplugged at	the wrong time.

	      See git-annex-repair(1) for details.

       p2p    Configure	peer-2-Peer links between repositories.

	      See git-annex-p2p(1) for details.

QUERY COMMANDS
       find [path ...]

	      Outputs a	list of	annexed	files in the specified path.  With  no
	      path,  finds  files in the current directory and its subdirecto-
	      ries.

	      See git-annex-find(1) for	details.

       whereis [path ...]
	      Displays information about where the contents of files  are  lo-
	      cated.

	      See git-annex-whereis(1) for details.

       list [path ...]
	      Displays	a  table  of  remotes that contain the contents	of the
	      specified	files. This is similar to whereis but a	 more  compact
	      display.

	      See git-annex-list(1) for	details.

       log [path ...]
	      Displays the location log	for the	specified file or files, show-
	      ing each repository they were added to ("+")  and	 removed  from
	      ("-").

	      See git-annex-log(1) for details.

       info [directory|file|remote|uuid	...]
	      Displays	statistics  and	 other	information  for the specified
	      item, which can be a directory, or a file, or a remote,  or  the
	      uuid of a	repository.

	      When  no	item is	specified, displays statistics and information
	      for the repository as a whole.

	      See git-annex-info(1) for	details.

       version
	      Shows the	version	of git-annex, as well  as  repository  version
	      information.

	      See git-annex-version(1) for details.

       map    Generate map of repositories.

	      See git-annex-map(1) for details.

       inprogress
	      Access files while they're being downloaded.

	      See git-annex-inprogress(1) for details.

METADATA COMMANDS
       metadata	[path ...]

	      The  content  of an annexed file can have	any number of metadata
	      fields attached to it to describe	it. Each metadata field	can in
	      turn have	any number of values.

	      This  command can	be used	to set metadata, or show the currently
	      set metadata.

	      See git-annex-metadata(1)	for details.

       view  [tag  ...]	 [field=value  ...]  [field=glob   ...]	  [!tag	  ...]
       [field!=value ...]
	      Uses metadata to build a view branch of the files	in the current
	      branch, and checks out the view branch. Only files in  the  cur-
	      rent  branch whose metadata matches all the specified field val-
	      ues and tags will	be shown in the	view.

	      See git-annex-view(1) for	details.

       vpop [N]
	      Switches from the	currently active view  back  to	 the  previous
	      view.  Or, from the first	view back to original branch.

	      See git-annex-vpop(1) for	details.

       vfilter [tag ...] [field=value ...] [!tag ...] [field!=value ...]
	      Filters  the current view	to only	the files that have the	speci-
	      fied field values	and tags.

	      See git-annex-vfilter(1) for details.

       vadd [field=glob	...] [field=value ...] [tag ...]
	      Changes the current view,	adding an additional level of directo-
	      ries to categorize the files.

	      See git-annex-vfilter(1) for details.

       vcycle When  a view involves nested subdirectories, this	cycles the or-
	      der.

	      See git-annex-vcycle(1) for details.

UTILITY	COMMANDS
       migrate [path ...]

	      Changes the specified annexed files to use a different key-value
	      backend.

	      See git-annex-migrate(1) for details.

       reinject	src dest
	      Moves  the  src  file  into the annex as the content of the dest
	      file.  This can be useful	if you have obtained the content of  a
	      file from	elsewhere and want to put it in	the local annex.

	      See git-annex-reinject(1)	for details.

       unannex [path ...]
	      Use  this	 to  undo an accidental	git annex add command. It puts
	      the file back how	it was before the add.

	      See git-annex-unannex(1) for details.

       uninit De-initialize git-annex and clean	out repository.

	      See git-annex-uninit(1) for details.

       reinit uuid|description
	      Initialize repository, reusing old UUID.

	      See git-annex-reinit(1) for details.

PLUMBING COMMANDS
       pre-commit [path	...]

	      This is meant to be called from git's pre-commit hook. git annex
	      init automatically creates a pre-commit hook using this.

	      See git-annex-pre-commit(1) for details.

       post-receive
	      This is meant to be called from git's post-receive hook. git an-
	      nex init automatically creates a post-receive hook using this.

	      See git-annex-post-receive(1) for	details.

       lookupkey [file ...]
	      Looks up key used	for file.

	      See git-annex-lookupkey(1) for details.

       calckey [file ...]
	      Calculates the key that would be used to refer to	a file.

	      See git-annex-calckey(1) for details.

       contentlocation [key ..]
	      Looks up location	of annexed content for a key.

	      See git-annex-contentlocation(1) for details.

       examinekey [key ...]
	      Print information	that can be determined purely  by  looking  at
	      the key.

	      See git-annex-examinekey(1) for details.

       matchexpression
	      Checks if	a preferred content expression matches provided	data.

	      See git-annex-matchexpression(1) for details.

       fromkey [key file]
	      Manually set up a	file in	the git	repository to link to a	speci-
	      fied key.

	      See git-annex-fromkey(1) for details.

       registerurl [key	url]
	      Registers	an url for a key.

	      See git-annex-registerurl(1) for details.

       setkey key file
	      Moves a file into	the annex as the content of a key.

	      See git-annex-setkey(1) for details.

       dropkey [key ...]
	      Drops annexed content for	specified keys.

	      See git-annex-dropkey(1) for details.

       transferkey key [--from=remote|--to=remote]
	      Transfers	a key from or to a remote.

	      See git-annex-transferkey(1) for details.

       transferkeys
	      Used internally by the assistant.

	      See git-annex-transferkey(1) for details.

       setpresentkey key uuid [1|0]
	      This plumbing-level command changes  git-annex's	records	 about
	      whether  the specified key's content is present in a remote with
	      the specified uuid.

	      See git-annex-setpresentkey(1) for details.

       readpresentkey key uuid
	      Read records of where key	is present.

	      See git-annex-readpresentkey(1) for details.

       checkpresentkey key remote
	      Check if key is present in remote.

	      See git-annex-checkpresentkey(1) for details.

       rekey [file key ...]
	      Change keys used for files.

	      See git-annex-rekey(1) for details.

       resolvemerge
	      Resolves a conflicted merge, by adding both conflicting versions
	      of  the file to the tree,	using variants of their	filename. This
	      is done automatically when using git annex  sync	or  git	 annex
	      merge.

	      See git-annex-resolvemerge(1) for	details.

       diffdriver
	      This  can	 be  used to make git diff use an external diff	driver
	      with annexed files.

	      See git-annex-diffdriver(1) for details.

       smudge This command lets	git-annex be used as a git filter driver,  al-
	      lowing annexed files in the git repository to be unlocked	at all
	      times, instead of	being symlinks.

	      See git-annex-smudge(1) for details.

       findref [ref]
	      Lists files in a git ref.	(deprecated)

	      See git-annex-findref(1) for details.

       proxy --	git cmd	[options]
	      Bypass direct mode guard.	(deprecated)

	      See git-annex-proxy(1) for details.

TESTING	COMMANDS
       test

	      This runs	git-annex's built-in test suite.

	      See git-annex-test(1) for	details.

       testremote remote
	      This tests a remote by generating	some random objects and	 send-
	      ing  them	 to the	remote,	then redownloading them, removing them
	      from the remote, etc.

	      It's safe	to run in an existing repository (the repository  con-
	      tents  are  not altered),	although it may	perform	expensive data
	      transfers.

	      See git-annex-testremote(1) for details.

       fuzztest
	      Generates	random changes to files	in the current repository, for
	      use in testing the assistant.

	      See git-annex-fuzztest(1)	for details.

       benchmark
	      This  runs git-annex's built-in benchmarks, if it	was built with
	      benchmarking support.

	      See git-annex-benchmark(1) for details.

COMMON OPTIONS
       These common options are	accepted by all	git-annex  commands,  and  may
       not be explicitly listed	on their individual man	pages.	(Many commands
       also accept the git-annex-matching-options(1).)

       --force
	      Force unsafe actions, such as dropping a file's content when  no
	      other source of it can be	verified to still exist, or adding ig-
	      nored files.  Use	with care.

       --fast Enable less expensive, but also less thorough versions  of  some
	      commands.	 What is avoided depends on the	command.

       --quiet
	      Avoid the	default	verbose	display	of what	is done; only show er-
	      rors.

       --verbose
	      Enable verbose display.

       --debug
	      Show debug messages.

       --no-debug
	      Disable debug messages.

       --numcopies=n
	      Overrides	the numcopies setting, forcing git-annex to ensure the
	      specified	number of copies exist.

	      Note that	setting	numcopies to 0 is very unsafe.

       --time-limit=time
	      Limits  how long a git-annex command runs. The time can be some-
	      thing like "5h", or "30m"	or even	"45s" or "10d".

	      Note that	git-annex may continue running a little	past the spec-
	      ified time limit,	in order to finish processing a	file.

	      Also,  note that if the time limit prevents git-annex from doing
	      all it was asked to, it will exit	with a special code, 101.

       --trust=repository

       --semitrust=repository

       --untrust=repository
	      Overrides	trust settings for a repository. May be	specified more
	      than once.

	      The  repository  should be specified using the name of a config-
	      ured remote, or the UUID or description of a repository.

       --trust-glacier
	      Amazon Glacier inventories take hours to retrieve, and  may  not
	      represent	 the  current state of a repository. So	git-annex does
	      not trust	that files that	the inventory claims  are  in  Glacier
	      are  really there.  This switch can be used to allow it to trust
	      the inventory.

	      Be careful using this, especially	if you or someone  else	 might
	      have  recently  removed  a file from Glacier. If you try to drop
	      the only other copy of the file, and this	switch is enabled, you
	      could lose data!

       --backend=name
	      Specifies	 which key-value backend to use. This can be used when
	      adding a file to the annex, or migrating a file. Once files  are
	      in the annex, their backend is known and this option is not nec-
	      essary.

       --user-agent=value
	      Overrides	the User-Agent to use when downloading files from  the
	      web.

       --notify-finish
	      Caused  a	 desktop  notification to be displayed after each suc-
	      cessful file download and	upload.

	      (Only supported on some platforms, e.g. Linux with dbus. A no-op
	      when not supported.)

       --notify-start
	      Caused a desktop notification to be displayed when a file	upload
	      or download has started, or when a file is dropped.

       -c name=value
	      Overrides	git configuration settings. May	be specified  multiple
	      times.

CONFIGURATION
       Like other git commands,	git-annex is configured	via .git/config.

       annex.uuid
	      A	unique UUID for	this repository	(automatically set).

       annex.backend
	      Name  of	the  default  key-value	backend	to use when adding new
	      files to the repository.

	      This is overridden by annex annex.backend	configuration  in  the
	      .gitattributes files, and	by the --backend option.

	      (This  used  to  be named	annex.backends,	and that will still be
	      used if set.)

       annex.securehashesonly
	      Set to true to indicate that  the	 repository  should  only  use
	      cryptographically	 secure	 hashes	 (SHA2,	SHA3) and not insecure
	      hashes (MD5, SHA1) for content.

	      When this	is set,	the contents of	files using  cryptographically
	      insecure	hashes	will not be allowed to be added	to the reposi-
	      tory.

	      Also, git-annex fsck will	complain about any  files  present  in
	      the repository that use insecure hashes.

	      To  configure the	behavior in new	clones of the repository, this
	      can be set using git-annex-config.

       annex.maxextensionlength
	      Maximum length, in bytes,	of what	is considered a	 filename  ex-
	      tension  when adding a file to a backend that preserves filename
	      extensions. The default length is	 4,  which  allows  extensions
	      like "jpeg". The dot before the extension	is not counted part of
	      its length. At most two extensions at the	end of a filename will
	      be preserved, e.g. .gz or	.tar.gz	.

       annex.diskreserve
	      Amount  of  disk	space  to  reserve. Disk space is checked when
	      transferring content to avoid running out, and  additional  free
	      space  can  be  reserved via this	option,	to make	space for more
	      important	content	(such as git commit logs).  Can	 be  specified
	      with  any	commonly used units, for example, "0.5 gb", "500M", or
	      "100 KiloBytes"

	      The default reserve is 1 megabyte.

       annex.skipunknown
	      Set to true to make commands like	"git-annex get"	silently  skip
	      over  items  that	 are  listed  in the command line, but are not
	      checked into git.

	      Set to false to make it an error for  commands  like  "git-annex
	      get"  to	be asked to operate on files that are not checked into
	      git.

	      The default is currently true, but is planned to change to false
	      in a release in 2022.

	      Note that, when annex.skipunknown	is false, a command like "git-
	      annex get	."  will fail if no files in the current directory are
	      checked  into  git,  but a command like "git-annex get" will not
	      fail, because the	current	directory is not listed,  but  is  im-
	      plicit. Commands like "git-annex get foo/" will fail if no files
	      in the directory are checked into	git, but if at least one  file
	      is,  it  will  ignore  other files that are not. This is all the
	      same as the behavior of "git-ls files --error-unmatch".

	      Also note	that git-annex skips files that	are checked into  git,
	      but are not annexed files, this setting does not affect that.

       annex.largefiles
	      Used  to	configure  which files are large enough	to be added to
	      the annex.  It is	an expression that matches the large files, eg
	      "include=*.mp3  or largerthan(500kb)" See	git-annex-matching-ex-
	      pression(1) for details on the syntax.

	      Overrides	 any  annex.largefiles	attributes  in	.gitattributes
	      files.

	      To  configure  a	default	annex.largefiles for all clones	of the
	      repository, this can be set in git-annex-config(1).

	      This configures the behavior of  both  git-annex	and  git  when
	      adding  files  to	the repository.	By default, git-annex add adds
	      all files	to the annex (except dotfiles),	and git	add adds files
	      to  git  (unless they were added to the annex previously).  When
	      annex.largefiles is configured, both git annex add and  git  add
	      will  add	matching large files to	the annex, and the other files
	      to git.

	      Other git-annex commands also honor annex.largefiles,  including
	      git annex	import,	git annex addurl, git annex importfeed and the
	      assistant.

       annex.dotfiles
	      Normally,	dotfiles are assumed  to  be  files  like  .gitignore,
	      whose  content  should  always be	part of	the git	repository, so
	      they will	not be added to	the annex. Setting  annex.dotfiles  to
	      true  makes dotfiles be added to the annex the same as any other
	      file.

	      To annex only some dotfiles, set this and	configure annex.large-
	      files  to	 match	the  ones you want. For	example, to match only
	      dotfiles ending in ".big"

	       git   config   annex.largefiles	 "(include=.*.big    or	   in-
	      clude=*/.*.big) or (exclude=.* and exclude=*/.*)"
	       git config annex.dotfiles true

	      To  configure  a	default	 annex.dotfiles	 for all clones	of the
	      repository, this can be set in git-annex-config(1).

       annex.gitaddtoannex
	      Setting this to false will prevent git add from adding files  to
	      the annex, despite the annex.largefiles configuration.

       annex.addsmallfiles
	      Controls	whether	 small	files  (not matching annex.largefiles)
	      should be	checked	into git by git	annex add. Defaults  to	 true;
	      set to false to instead make small files be skipped.

       annex.addunlocked
	      Commands	like  git-annex	 add  default  to  adding files	to the
	      repository in locked form. This can make them add	the  files  in
	      unlocked	form,  the  same as if git-annex-unlock(1) were	run on
	      the files.

	      This can be set to "true"	to add everything unlocked, or it  can
	      be  a  more  complicated	expression that	matches	files by name,
	      size, or content.	See git-annex-matching-expression(1)  for  de-
	      tails.

	      To  configure  a default annex.addunlocked for all clones	of the
	      repository, this can be set in git-annex-config(1).

	      (Using git add always adds files in unlocked form	and it is  not
	      affected by this setting.)

	      When  a repository has core.symlinks set to false, or has	an ad-
	      justed unlocked branch checked out, this setting is ignored, and
	      files are	always added to	the repository in unlocked form.

       annex.numcopies
	      This is a	deprecated setting. You	should instead use the git an-
	      nex numcopies command to configure how many copies of files  are
	      kept  across  all	 repositories,	or the annex.numcopies .gitat-
	      tributes setting.

	      This config setting is only looked at when git  annex  numcopies
	      has  never  been configured, and when there's no annex.numcopies
	      setting in the .gitattributes file.

	      Note that	setting	numcopies to 0 is very unsafe.

       annex.genmetadata
	      Set this to true to make git-annex automatically	generate  some
	      metadata when adding files to the	repository.

	      In particular, it	stores year, month, and	day metadata, from the
	      file's modification date.

	      When importfeed is used, it stores additional metadata from  the
	      feed, such as the	author,	title, etc.

       annex.used-refspec
	      This  controls which refs	git-annex unused considers to be used.
	      See REFSPEC FORMAT in git-annex-unused(1)	for details.

       annex.jobs
	      Configure	the number of concurrent jobs to run. Default is 1.

	      Only git-annex commands that support the --jobs option will  use
	      this.

	      Setting this to "cpus" will run one job per CPU core.

       annex.queuesize
	      git-annex	 builds	 a  queue of git commands, in order to combine
	      similar commands for speed. By default the size of the queue  is
	      limited  to 10240	commands; this can be used to change the size.
	      If you have plenty of memory and are  working  with  very	 large
	      numbers of files,	increasing the queue size can speed it up.

       annex.bloomcapacity
	      The git annex unused and git annex sync --content	commands use a
	      bloom filter to determine	what files are present in eg, the work
	      tree.   The default bloom	filter is sized	to handle up to	500000
	      files. If	your repository	is larger than that,  you  should  in-
	      crease  this value. Larger values	will make git-annex unused and
	      git annex	sync --content consume more memory; run	git annex info
	      for memory usage numbers.

       annex.bloomaccuracy
	      Adjusts  the  accuracy of	the bloom filter used by git annex un-
	      used and git annex sync  --content.   The	 default  accuracy  is
	      10000000	-- 1 unused file out of	10000000 will be missed	by git
	      annex unused. Increasing the accuracy will make git annex	unused
	      consume  more  memory;  run git annex info for memory usage num-
	      bers.

       annex.sshcaching
	      By default, git-annex caches ssh connections  using  ssh's  Con-
	      trolMaster  and  ControlPersist  settings	 (if built using a new
	      enough ssh). To disable this, set	to false.

       annex.alwayscommit
	      By default, git-annex automatically commits data to the  git-an-
	      nex  branch  after  each command is run. If you have a series of
	      commands that you	want to	make a single commit, you can run  the
	      commands	with -c	annex.alwayscommit=false. You can later	commit
	      the data by running git annex merge (or by automatic merges)  or
	      git annex	sync.

       annex.commitmessage
	      When git-annex updates the git-annex branch, it usually makes up
	      its own commit message ("update"), since users rarely look at or
	      care about changes to that branch. If you	do care, you can spec-
	      ify this setting by running commands  with  -c  annex.commitmes-
	      sage=whatever

	      This works well in combination with annex.alwayscommit=false, to
	      gather up	a set of changes and commit them with  a  message  you
	      specify.

       annex.allowsign
	      By  default  git-annex  avoids gpg signing commits that it makes
	      when they're not the purpose of a	command, but only a  side  ef-
	      fect.   That  default  avoids  lots of gpg password prompts when
	      commit.gpgSign is	set. A command like git	annex sync or git  an-
	      nex merge	will gpg sign its commit, but a	command	like git annex
	      get, that	updates	the git-annex branch, will not.	The  assistant
	      also avoids signing commits.

	      Setting  annex.allowsign	to true	lets all commits be signed, as
	      controlled by commit.gpgSign and other git configuration.

       annex.merge-annex-branches
	      By default, git-annex branches that have been  pulled  from  re-
	      motes  are automatically merged into the local git-annex branch,
	      so that git-annex	has the	most up-to-date	possible knowledge.

	      To avoid that merging, set this to "false". This can  be	useful
	      particularly when	you don't have write permission	to the reposi-
	      tory.

       annex.hardlink
	      Set this to true to make file contents be	 hard  linked  between
	      the  repository and its remotes when possible, instead of	a more
	      expensive	copy.

	      Use with caution --  This	 can  invalidate  numcopies  counting,
	      since  with hard links, fewer copies of a	file can exist.	So, it
	      is a good	idea to	mark a repository using	this  setting  as  un-
	      trusted.

	      When  a repository is set	up using git clone --shared, git-annex
	      init will	automatically set annex.hardlink and mark the  reposi-
	      tory as untrusted.

       annex.thin
	      Set  this	to true	to make	unlocked files be a hard link to their
	      content in the annex, rather than	a second copy. This  can  save
	      considerable  disk  space,  but when a modification is made to a
	      file, you	will lose the local (and possibly only)	 copy  of  the
	      old version. So, enable with care.

	      After  setting (or unsetting) this, you should run git annex fix
	      to fix up	the annexed files in the work tree to  be  hard	 links
	      (or copies).

	      Note  that  this has no effect when the filesystem does not sup-
	      port hard	links.	And when multiple files	in the work tree  have
	      the  same	 content, only one of them gets	hard linked to the an-
	      nex.

       annex.resolvemerge
	      Set to false to prevent  merge  conflicts	 in  the  checked  out
	      branch  being  automatically resolved by the git-annex assitant,
	      git-annex	sync, git-annex	merge, and the git-annex  post-receive
	      hook.

	      To  configure the	behavior in all	clones of the repository, this
	      can be set in git-annex-config(1).

       annex.synccontent
	      Set to true to make git-annex sync default  to  syncing  annexed
	      content.

	      To  configure the	behavior in all	clones of the repository, this
	      can be set in git-annex-config(1).

       annex.synconlyannex
	      Set to true to make git-annex sync default to only  sincing  the
	      git-annex	branch and annexed content.

	      To  configure the	behavior in all	clones of the repository, this
	      can be set in git-annex-config(1).

       annex.debug
	      Set to true to enable debug logging by default.

       annex.version
	      The current version of the git-annex repository. This  is	 main-
	      tained by	git-annex and should never be manually changed.

       annex.autoupgraderepository
	      When  an old git-annex repository	version	has become deprecated,
	      git-annex	will normally automatically upgrade the	repository  to
	      the new version.

	      If  this	is set to false, git-annex won't automatically upgrade
	      the repository. Instead it will exit with	an error message.  You
	      can run git annex	upgrade	yourself when you are ready to upgrade
	      the repository.

       annex.crippledfilesystem
	      Set to true if the repository is on a crippled filesystem,  such
	      as FAT, which does not support symbolic links, or	hard links, or
	      unix permissions.	 This is automatically probed  by  "git	 annex
	      init".

       annex.pidlock
	      Normally,	git-annex uses fine-grained lock files to allow	multi-
	      ple processes to run concurrently	without	getting	in  each  oth-
	      ers' way.	 That works great, unless you are using	git-annex on a
	      filesystem that does not support	POSIX  fcntl  locks.  This  is
	      sometimes	the case when using NFS	or Lustre filesystems.

	      To  support  such	situations, you	can set	annex.pidlock to true,
	      and it will fall back to a single	top-level pid file lock.

	      Although,	often, you'd really be better  off  fixing  your  net-
	      worked  filesystem  configuration	 to support POSIX locks.. And,
	      some networked filesystems are so	 inconsistent  that  one  node
	      can't  reliably  tell when the other node	is holding a pid lock.
	      Caveat emptor.

       annex.pidlocktimeout
	      When using pid lock files, it's possible for a stale  lock  file
	      to  get left behind by previous run of git-annex that crashed or
	      was interrupted.	This is	mostly avoided,	but  can  occur	 espe-
	      cially when using	a network file system.

	      git-annex	 will  wait  up	 to this many seconds for the pid lock
	      file to go away, and will	then abort if it cannot	continue.  De-
	      fault: 300

       annex.cachecreds
	      When "true" (the default), git-annex will	cache credentials used
	      to access	special	remotes	in  files  in  .git/annex/creds/  that
	      only  you	can read. To disable that caching, set to "false", and
	      credentials will only be read from the environment, or  if  they
	      have been	embedded in encrypted form in the git repository, will
	      be extracted and decrypted each time git-annex needs  to	access
	      the remote.

       annex.secure-erase-command
	      This can be set to a command that	should be run whenever git-an-
	      nex removes the content of a file	from the repository.

	      In the command line, %file is replaced with the file that	should
	      be erased.

	      For example, to use the wipe command, set	it to wipe -f %file.

       annex.tune.objecthash1,	annex.tune.objecthashlower, annex.tune.branch-
       hash1
	      These can	be passed to git annex init to	tune  the  repository.
	      They cannot be safely changed in a running repository and	should
	      never be set in global  git  configuration.   For	 details,  see
	      <https://git-annex.branchable.com/tuning/>.

CONFIGURATION OF REMOTES
       Remotes are configured using these settings in .git/config.

       remote.<name>.annex-cost
	      When determining which repository	to transfer annexed files from
	      or to, ones with lower costs are preferred.  The default cost is
	      100 for local repositories, and 200 for remote repositories.

       remote.<name>.annex-cost-command
	      If set, the command is run, and the number it outputs is used as
	      the cost.	 This allows varying the cost based on e.g., the  cur-
	      rent network.

       remote.<name>.annex-start-command
	      A	 command  to run when git-annex	begins to use the remote. This
	      can be used to, for example, mount the directory containing  the
	      remote.

	      The  command  may	be run repeatedly when multiple	git-annex pro-
	      cesses are running concurrently.

       remote.<name>.annex-stop-command
	      A	command	to run when git-annex is done using the	remote.

	      The command will only be run once	*all* running  git-annex  pro-
	      cesses are finished using	the remote.

       remote.<name>.annex-shell
	      Specify  an alternative git-annex-shell executable on the	remote
	      instead of looking for "git-annex-shell" on the PATH.

	      This is useful if	the git-annex-shell  program  is  outside  the
	      PATH or has a non-standard name.

       remote.<name>.annex-ignore
	      If set to	true, prevents git-annex from storing file contents on
	      this remote by default.  (You can	still request it  be  used  by
	      the --from and --to options.)

	      This  is,	for example, useful if the remote is located somewhere
	      without git-annex-shell. (For example, if	it's on	GitHub).   Or,
	      it could be used if the network connection between two reposito-
	      ries is too slow to be used normally.

	      This does	not prevent git-annex sync (or the  git-annex  assist-
	      ant) from	syncing	the git	repository to the remote.

       remote.<name>.annex-ignore-command
	      If  set, the command is run, and if it exits nonzero, that's the
	      same as setting annex-ignore to true.  This  allows  controlling
	      behavior based on	e.g., the current network.

       remote.<name>.annex-sync
	      If  set to false,	prevents git-annex sync	(and the git-annex as-
	      sistant) from syncing with this remote by	default. However,  git
	      annex sync <name>	can still be used to sync with the remote.

       remote.<name>.annex-sync-command
	      If  set, the command is run, and if it exits nonzero, that's the
	      same as setting annex-sync to false. This	allows controlling be-
	      havior based on e.g., the	current	network.

       remote.<name>.annex-pull
	      If  set to false,	prevents git-annex sync	(and the git-annex as-
	      sistant etc) from	ever pulling (or fetching) from	the remote.

       remote.<name>.annex-push
	      If set to	false, prevents	git-annex sync (and the	git-annex  as-
	      sistant etc) from	ever pushing to	the remote.

       remote.<name>.annex-readonly
	      If  set to true, prevents	git-annex from making changes to a re-
	      mote.  This both prevents	git-annex sync from  pushing  changes,
	      and prevents storing or removing files from read-only remote.

       remote.<name>.annex-verify, annex.verify
	      By default, git-annex will verify	the checksums of objects down-
	      loaded from remotes. If you trust	a remote and  don't  want  the
	      overhead of these	checksums, you can set this to false.

	      Note that	even when this is set to false,	git-annex does verifi-
	      cation in	some edge cases, where it's likely the	case  than  an
	      object was downloaded incorrectly, or when needed	for security.

       remote.<name>.annex-tracking-branch
	      This  is	for  use with special remotes that support exports and
	      imports.

	      When set to eg, "master",	this tells git-annex that you want the
	      special remote to	track that branch.

	      When  set	to eg, "master:subdir",	the special remote tracks only
	      the subdirectory of that branch.

	      git-annex	sync --content will import changes from	the remote and
	      merge  them  into	 the  annex-tracking-branch.  They also	export
	      changes made to the branch to the	remote.

       remote.<name>.annex-export-tracking
	      Deprecated name  for  remote.<name>.annex-tracking-branch.  Will
	      still  be	used if	it's configured	and remote.<name>.annex-track-
	      ing-branch is not.

       remote.<name>.annexUrl
	      Can be used to specify a different  url  than  the  regular  re-
	      mote.<name>.url  for  git-annex to use when talking with the re-
	      mote. Similar to the pushUrl used	by git-push.

       remote.<name>.annex-uuid
	      git-annex	caches UUIDs of	remote repositories here.

       remote.<name>.annex-config-uuid
	      Used for some special remotes, points to a different special re-
	      mote configuration to use.

       remote.<name>.annex-retry, annex.retry
	      Configure	 retries  of failed transfers on a per-remote and gen-
	      eral basis, respectively.	The value is  the  number  of  retries
	      that can be made of the same transfer. (default 0)

       remote.<name>.annex-retry-delay,	annex.retry-delay
	      Number of	seconds	to delay before	the first retry	of a transfer.
	      When making multiple retries of the  same	 transfer,  the	 delay
	      doubles after each retry.	(default 1)

       remote.<name>.annex-checkuuid
	      This  only affects remotes that have their url pointing to a di-
	      rectory on the same system. git-annex normally checks  the  uuid
	      of  such remotes each time it's run, which lets it transparently
	      deal with	different drives being mounted to the location at dif-
	      ferent times.

	      Setting  annex-checkuuid	to false will prevent it from checking
	      the uuid at startup (although the	uuid is	still verified	before
	      making any changes to the	remote repository). This may be	useful
	      to set to	prevent	unncessary spin-up or automounting of a	drive.

       remote.<name>.annex-trustlevel
	      Configures a local trust level for the  remote.  This  overrides
	      the  value  configured  by  the  trust and untrust commands. The
	      value can	be any of "trusted", "semitrusted" or "untrusted".

       remote.<name>.annex-availability
	      Can be used to tell git-annex whether a remote is	 LocallyAvail-
	      able  or	GloballyAvailable. Normally, git-annex determines this
	      automatically.

       remote.<name>.annex-speculate-present
	      Set to "true" to make git-annex speculate	that this  remote  may
	      contain the content of any file, even though its normal location
	      tracking does not	indicate that it does. This will cause git-an-
	      nex to try to get	all file contents from the remote. Can be use-
	      ful in setting up	a caching remote.

       remote.<name>.annex-bare
	      Can be used to tell git-annex if a remote	is a  bare  repository
	      or not. Normally,	git-annex determines this automatically.

       remote.<name>.annex-ssh-options
	      Options to use when using	ssh to talk to this remote.

       remote.<name>.annex-rsync-options
	      Options  to use when using rsync to or from this remote. For ex-
	      ample, to	force IPv6, and	limit the bandwidth to 100Kbyte/s, set
	      it to -6 --bwlimit 100

	      Note  that  git-annex-shell has a	whitelist of allowed rsync op-
	      tions, and others	will not be be passed to the remote rsync.  So
	      using some options may break the communication between the local
	      and remote rsyncs.

       remote.<name>.annex-rsync-upload-options
	      Options to use when using	rsync to upload	a file to a remote.

	      These options are	passed after other applicable  rsync  options,
	      so  can  be  used	to override them. For example, to limit	upload
	      bandwidth	to 10Kbyte/s, set --bwlimit 10.

       remote.<name>.annex-rsync-download-options
	      Options to use when using	rsync to download a file  from	a  re-
	      mote.

	      These  options  are passed after other applicable	rsync options,
	      so can be	used to	override them.

       remote.<name>.annex-rsync-transport
	      The remote shell to use to connect to the	rsync remote. Possible
	      values  are ssh (the default) and	rsh, together with their argu-
	      ments, for instance ssh -p 2222 -c blowfish; Note	that  the  re-
	      mote hostname should not appear there, see rsync(1) for details.
	      When the transport used is ssh,  connections  are	 automatically
	      cached unless annex.sshcaching is	unset.

       remote.<name>.annex-bup-split-options
	      Options  to  pass	 to bup	split when storing content in this re-
	      mote.  For example, to limit the bandwidth to 100Kbyte/s,	set it
	      to  --bwlimit  100k  (There  is  no corresponding	option for bup
	      join.)

       remote.<name>.annex-gnupg-options
	      Options to pass to GnuPG when  it's  encrypting  data.  For  in-
	      stance,  to  use	the AES	cipher with a 256 bits key and disable
	      compression, set	it  to	--cipher-algo  AES256  --compress-algo
	      none. (These options take	precedence over	the default GnuPG con-
	      figuration, which	is otherwise used.)

       remote.<name>.annex-gnupg-decrypt-options
	      Options to pass to GnuPG when it's decrypting data.  (These  op-
	      tions  take  precedence  over  the  default GnuPG	configuration,
	      which is otherwise used.)

       annex.ssh-options, annex.rsync-options,
	      annex.rsync-upload-options,  annex.rsync-download-options,   an-
	      nex.bup-split-options,	annex.gnupg-options,   annex.gnupg-de-
	      crypt-options

	      Default options to use if	a remote does not have	more  specific
	      options as described above.

       remote.<name>.annex-rsyncurl
	      Used  by	rsync special remotes, this configures the location of
	      the rsync	repository to use. Normally this is automatically  set
	      up by git	annex initremote, but you can change it	if needed.

       remote.<name>.annex-buprepo
	      Used by bup special remotes, this	configures the location	of the
	      bup repository to	use. Normally this is automatically set	up  by
	      git annex	initremote, but	you can	change it if needed.

       remote.<name>.annex-ddarrepo
	      Used  by	ddar  special remotes, this configures the location of
	      the ddar repository to use. Normally this	is  automatically  set
	      up by git	annex initremote, but you can change it	if needed.

       remote.<name>.annex-directory
	      Used  by directory special remotes, this configures the location
	      of the directory where annexed files are stored for this remote.
	      Normally	this  is automatically set up by git annex initremote,
	      but you can change it if needed.

       remote.<name>.annex-adb
	      Used to identify remotes on Android devices  accessed  via  adb.
	      Normally this is automatically set up by git annex initremote.

       remote.<name>.annex-androiddirectory
	      Used  by	adb  special remotes, this is the directory on the An-
	      droid device where files are stored for  this  remote.  Normally
	      this  is	automatically  set up by git annex initremote, but you
	      can change it if needed.

       remote.<name>.annex-androidserial
	      Used by adb special remotes, this	is the serial  number  of  the
	      Android  device  used  by	the remote. Normally this is automati-
	      cally set	up by git annex	initremote, but	you can	change	it  if
	      needed, eg when upgrading	to a new Android device.

       remote.<name>.annex-s3
	      Used  to	identify  Amazon S3 special remotes.  Normally this is
	      automatically set	up by git annex	initremote.

       remote.<name>.annex-glacier
	      Used to identify Amazon Glacier special remotes.	Normally  this
	      is automatically set up by git annex initremote.

       remote.<name>.annex-webdav
	      Used to identify webdav special remotes.	Normally this is auto-
	      matically	set up by git annex initremote.

       remote.<name>.annex-tahoe
	      Used to identify tahoe special remotes.  Points to the  configu-
	      ration directory for tahoe.

       remote.<name>.annex-gcrypt
	      Used to identify gcrypt special remotes.	Normally this is auto-
	      matically	set up by git annex initremote.

	      It is set	to "true" if this is a gcrypt remote.  If  the	gcrypt
	      remote  is accessible over ssh and has git-annex-shell available
	      to manage	it, it's set to	"shell".

       remote.<name>.annex-git-lfs
	      Used to identify git-lfs special remotes.	 Normally this is  au-
	      tomatically set up by git	annex initremote.

	      It is set	to "true" if this is a git-lfs remote.

       remote.<name>.annex-externaltype
	      Used external special remotes to record the type of the remote.

	      Eg, if this is set to "foo", git-annex will run a	"git-annex-re-
	      mote-foo"	program	to communicate with the	external  special  re-
	      mote.

	      If  this	is  set	to "readonly", then git-annex will not run any
	      external special remote program, but will	try to	access	things
	      stored in	the remote using http. That only works for some	exter-
	      nal special remotes, so consult the documentation	of the one you
	      are using.

       remote.<name>.annex-hooktype
	      Used by hook special remotes to record the type of the remote.

       annex.web-options
	      Options  to pass to curl when git-annex uses it to download urls
	      (rather than the default built-in	url downloader).

	      For example, to force IPv4 only, set it to  "-4".	  Or  to  make
	      curl use your ~/.netrc file, set it to "--netrc".

	      Setting  this option makes git-annex use curl, but only when an-
	      nex.security.allowed-ip-addresses	is configured  in  a  specific
	      way. See its documentation.

       annex.youtube-dl-options
	      Options  to  pass	to youtube-dl when using it to find the	url to
	      download for a video.

	      Some options may break git-annex's integration with  youtube-dl.
	      For  example,  the --output option could cause it	to store files
	      somewhere	git-annex won't	find them. Avoid setting  here	or  in
	      the  youtube-dl config file any options that cause youtube-dl to
	      download more than one file, or to store the file	anywhere other
	      than the current working directory.

       annex.aria-torrent-options
	      Options to pass to aria2c	when using it to download a torrent.

       annex.http-headers
	      HTTP  headers  to	 send  when downloading	from the web. Multiple
	      lines of this option can be set, one per header.

       annex.http-headers-command
	      If set, the command is run and each line of its output  is  used
	      as a HTTP	header.	This overrides annex.http-headers.

       annex.security.allowed-url-schemes
	      List  of	URL schemes that git-annex is allowed to download con-
	      tent from.  The default is "http https ftp".

	      Think very carefully before changing this;  there	 are  security
	      implications. For	example, if it's changed to allow "file" URLs,
	      then anyone who can get a	commit into your git-annex  repository
	      could  git-annex addurl a	pointer	to a private file located out-
	      side that	repository, possibly causing it	to be copied into your
	      repository  and  transferred  on	to other remotes, exposing its
	      content.

	      Some special  remotes  support  their  own  domain-specific  URL
	      schemes; those are not affected by this configuration setting.

       annex.security.allowed-ip-addresses
	      By  default,  git-annex  only makes connections to public	IP ad-
	      dresses; it will refuse to use HTTP and other servers on	local-
	      host or on a private network.

	      This setting can override	that behavior, allowing	access to par-
	      ticular IP addresses that	would normally be blocked. For example
	      "127.0.0.1 ::1" allows access to localhost (both IPV4 and	IPV6).
	      To allow access to all IP	addresses, use "all"

	      Think very carefully before changing this;  there	 are  security
	      implications.  Anyone  who  can get a commit into	your git-annex
	      repository could git annex addurl	an url on  a  private  server,
	      possibly	causing	 it  to	be downloaded into your	repository and
	      transferred to other remotes, exposing its content.

	      Note that, since the interfaces of curl and  youtube-dl  do  not
	      allow  these  IP	address	 restrictions to be enforced, curl and
	      youtube-dl  will	never  be   used   unless   annex.security.al-
	      lowed-ip-addresses=all.

	      To  allow	 accessing  local or private IP	addresses on only spe-
	      cific  ports,  use  the  syntax  "[addr]:port".	For   example,
	      "[127.0.0.1]:80  [127.0.0.1]:443	[::1]:80 [::1]:443" allows lo-
	      calhost on the http ports	only.

       annex.security.allowed-http-addresses
	      Old name for annex.security.allowed-ip-addresses.	 If set,  this
	      is  treated  the	same  as  having annex.security.allowed-ip-ad-
	      dresses set.

       annex.security.allow-unverified-downloads
	      For security reasons, git-annex refuses to download content from
	      most  special remotes when it cannot check a hash	to verify that
	      the correct content was downloaded.  This	 particularly  impacts
	      downloading the content of URL or	WORM keys, which lack hashes.

	      The  best	 way to	avoid problems due to this is to migrate files
	      away from	such keys, before their	content	reaches	a special  re-
	      mote.  See git-annex-migrate(1).

	      When  the	 content  is only available from a special remote, you
	      can use this configuration to force git-annex  to	 download  it.
	      But you do so at your own	risk, and it's very important you read
	      and understand the information below first!

	      Downloading unverified content from encrypted special remotes is
	      prevented,  because the special remote could send	some other en-
	      crypted content than what	you expect, causing git-annex  to  de-
	      crypt  data  that	 you never checked into	git-annex, and risking
	      exposing the decrypted data to  any  non-encrypted  remotes  you
	      send content to.

	      Downloading  unverified  content	from  (non-encrypted) external
	      special remotes is prevented, because  they  could  follow  http
	      redirects	 to  web servers on localhost or on a private network,
	      or in some cases to a file:/// url.

	      If you decide to bypass this security check, the best  thing  to
	      do  is to	only set it temporarily	while running the command that
	      gets the file.  The value	to set the config  to  is  "ACKTHPPT".
	      For example:

	       git -c annex.security.allow-unverified-downloads=ACKTHPPT annex
	      get myfile

	      It would be a good idea to check that it downloaded the file you
	      expected,	too.

       remote.<name>.annex-security-allow-unverified-downloads
	      Per-remote    configuration    of	  annex.security.allow-unveri-
	      fied-downloads.

CONFIGURATION OF ASSISTANT
       annex.delayadd

	      Makes the	watch and assistant commands delay for	the  specified
	      number  of seconds before	adding a newly created file to the an-
	      nex. Normally this is not	needed,	because	they already wait  for
	      all writers of the file to close it.

       annex.expireunused
	      Controls what the	assistant does about unused file contents that
	      are stored in the	repository.

	      The default is false, which causes all old and unused file  con-
	      tents  to	be retained, unless the	assistant is able to move them
	      to some other repository (such as	a backup repository).

	      Can be set to a time specification, like "7d" or "1m", and  then
	      file  contents that have been known to be	unused for a week or a
	      month will be deleted.

       annex.fscknudge
	      When set to false, prevents the webapp from reminding  you  when
	      using repositories that lack consistency checks.

       annex.autoupgrade
	      When  set	 to  ask  (the default), the webapp will check for new
	      versions and prompt if they should be upgraded to. When  set  to
	      true,  automatically  upgrades  without  prompting (on some sup-
	      ported platforms). When  set  to	false,	disables  any  upgrade
	      checking.

	      Note  that  upgrade  checking is only done when git-annex	is in-
	      stalled from one of the prebuilt images from its	website.  This
	      does  not	 bypass	 e.g., a Linux distribution's own upgrade han-
	      dling code.

	      This setting also	controls whether to restart the	git-annex  as-
	      sistant  when  the git-annex binary is detected to have changed.
	      That is useful no	matter how you installed git-annex.

       annex.autocommit
	      Set to false to prevent the git-annex  assistant	and  git-annex
	      sync  from  automatically	 committing  changes  to  files	in the
	      repository.

	      To configure the behavior	in all clones of the repository,  this
	      can be set in git-annex-config(1).

       annex.startupscan
	      Set  to  false  to prevent the git-annex assistant from scanning
	      the repository for new and changed files on startup.  This  will
	      prevent it from noticing changes that were made while it was not
	      running, but can be a  useful  performance  tweak	 for  a	 large
	      repository.

       annex.listen
	      Configures  which	 address the webapp listens on.	The default is
	      localhost.  Can be either	an IP address, or a hostname that  re-
	      solves to	the desired address.

CONFIGURATION VIA .gitattributes
       The  key-value  backend used when adding	a new file to the annex	can be
       configured on a per-file-type basis via .gitattributes  files.  In  the
       file, the annex.backend attribute can be	set to the name	of the backend
       to use. For example, this here's	how to use the	WORM  backend  by  de-
       fault, but the SHA256E backend for ogg files:

	* annex.backend=WORM
	*.ogg annex.backend=SHA256E

       There is	a annex.largefiles attribute, which is used to configure which
       files are large enough to be added to the annex.	Since attributes  can-
       not  contain  spaces,  it  is  difficult	 to  use  for more complex an-
       nex.largefiles settings.	 Setting  annex.largefiles  in	git-annex-con-
       fig(1) is an easier way to configure it across all clones of the	repos-
       itory.  See git-annex-matching-expression(1) for	details	on the syntax.

       The numcopies setting can also be configured on a  per-file-type	 basis
       via  the	 annex.numcopies attribute in .gitattributes files. This over-
       rides other numcopies settings.	For example, this makes	two copies  be
       needed for wav files and	3 copies for flac files:

	*.wav annex.numcopies=2
	*.flac annex.numcopies=3

       Note that setting numcopies to 0	is very	unsafe.

       These  settings	are  honored by	git-annex whenever it's	operating on a
       matching	file. However, when using --all, --unused, or --key to specify
       keys  to	 operate  on, git-annex	is operating on	keys and not files, so
       will not	honor the settings from	.gitattributes.	For this  reason,  the
       git annex numcopies command is useful to	configure a global default for
       numcopies.

       Also note that when using views,	only the toplevel .gitattributes  file
       is  preserved  in the view, so other settings in	other files won't have
       any effect.

EXIT STATUS
       git-annex, when called as a git subcommand, may return exit codes 0  or
       1 for success or	failures, or, more rarely, 127 or 128 for certain very
       specific	failures.  git-annex itself should return 0 on success	and  1
       on  failure,  unless the	--time-limit=time option is hit, in which case
       it returns with exit code 101.

ENVIRONMENT
       These environment variables are used by git-annex when set:

       GIT_WORK_TREE, GIT_DIR
	      Handled the same as they are by git, see git(1)

       GIT_SSH,	GIT_SSH_COMMAND
	      Handled similarly	to the same as described in git(1).   The  one
	      difference  is  that git-annex will sometimes pass an additional
	      "-n" parameter to	these, as the first parameter, to prevent  ssh
	      from  reading  from stdin. Since that can	break existing uses of
	      these environment	variables that don't expect the	extra  parame-
	      ter,  you	 will need to set GIT_ANNEX_USE_GIT_SSH=1 to make git-
	      annex support these.

	      Note that	setting	either of these	environment variables prevents
	      git-annex	 from  automatically  enabling	ssh connection caching
	      (see annex.sshcaching), so it will  slow	down  some  operations
	      with  remotes  over ssh. It's up to you to enable	ssh connection
	      caching if you need it; see ssh's	documentation.

	      Also,  annex.ssh-options	 and   remote.<name>.annex-ssh-options
	      won't have any effect when these envionment variables are	set.

	      Usually  it's  better  to	 configure any desired options through
	      your ~/.ssh/config file, or by setting annex.ssh-options.

       GIT_ANNEX_VECTOR_CLOCK
	      Normally git-annex timestamps lines in the log  files  committed
	      to  the git-annex	branch.	Setting	this environment variable to a
	      number will make git-annex use that rather than the current num-
	      ber  of  seconds since the UNIX epoch. Note that decimal seconds
	      are supported.

	      This is only provided for	advanced users who either have a  bet-
	      ter way to tell which commit is current than the local clock, or
	      who need to avoid	embedding timestamps for policy	reasons.  Mis-
	      use   of	this  environment  variable  can  confuse  git-annex's
	      book-keeping, sometimes in ways that git annex fsck is unable to
	      repair.

       Some special remotes use	additional environment variables
	      for  authentication  etc.	 For  example,	AWS_ACCESS_KEY_ID  and
	      GIT_ANNEX_P2P_AUTHTOKEN. See special remote documentation.

FILES
       These files are used by git-annex:

       .git/annex/objects/ in your git repository contains  the	 annexed  file
       contents	that are currently available. Annexed files in your git	repos-
       itory symlink to	that content.

       .git/annex/ in your git repository contains other run-time  information
       used by git-annex.

       ~/.config/git-annex/autostart  is  a  list of git repositories to start
       the git-annex assistant in.

       .git/hooks/pre-commit-annex in your git repository will be run whenever
       a  commit  is  made to the HEAD branch, either by git commit, git-annex
       sync, or	the git-annex assistant.

       .git/hooks/post-update-annex in your git	repository will	be  run	 when-
       ever  the  git-annex  branch is updated.	You can	make this hook run git
       update-server-info when publishing a git-annex repository by http.

SEE ALSO
       More  git-annex	documentation  is   available	on   its   web	 site,
       <https://git-annex.branchable.com/>

       If  git-annex  is installed from	a package, a copy of its documentation
       should be included, in, for example, /usr/share/doc/git-annex/.

AUTHOR
       Joey Hess <id@joeyh.name>

       <https://git-annex.branchable.com/>

								  git-annex(1)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | COMMONLY USED COMMANDS | REPOSITORY SETUP COMMANDS | REPOSITORY MAINTENANCE COMMANDS | QUERY COMMANDS | METADATA COMMANDS | UTILITY COMMANDS | PLUMBING COMMANDS | TESTING COMMANDS | COMMON OPTIONS | CONFIGURATION | CONFIGURATION OF REMOTES | CONFIGURATION OF ASSISTANT | CONFIGURATION VIA .gitattributes | EXIT STATUS | ENVIRONMENT | FILES | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=git-annex&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help