git-annex-10.20230626: doc/git-annex-config.mdwn

# NAME

git-annex config - configuration stored in git-annex branch

# SYNOPSIS

git annex config --set name value

git annex config --get name

git annex config --unset name

git annex config --show-origin name

# DESCRIPTION

Set or get configuration settings stored in the git-annex branch.

Unlike `git config` settings, these settings can be seen
in all clones of the repository, once they have gotten their
git-annex branches in sync.

These settings can be overridden on a per-repository basis using
`git config`.

git-annex does not check the git-annex branch for all the `git config`
settings that affect it (which are listed on the git-annex man page
CONFIGURATION section). Only a few make sense to be able to set such
that all clones of a repository see the setting, and so git-annex only
looks for these.

# SUPPORTED SETTINGS

* `annex.numcopies`

  Tells git-annex how many copies it should preserve of files, over all
  repositories. The default is 1.

  When git-annex is asked to drop a file, it first verifies that the
  number of copies can be satisfied among all the other
  repositories that have a copy of the file.
  
  In unusual situations, involving special remotes that do not support
  locking, and concurrent drops of the same content from multiple
  repositories, git-annex may violate the numcopies setting. It still
  guarantees at least 1 copy is preserved. This can be configured by
  setting annex.mincopies.

  This is the same setting that the [[git-annex-numcopies]](1) command
  configures. It can be overridden on a per-file basis
  by the annex.numcopies setting in `.gitattributes` files.

* `annex.mincopies`

  Tells git-annex how many copies it is required to preserve of files, 
  over all repositories. The default is 1.

  This supplements the annex.numcopies setting. 
  In unusual situations, involving special remotes that do not support
  locking, and concurrent drops of the same content from multiple
  repositories, git-annex may violate the numcopies setting.
  In these unusual situations, git-annex ensures that the number of copies
  never goes below mincopies.
  
  It is a good idea to not only rely on only setting mincopies. Set
  numcopies as well, to a larger number, and keep mincopies at the
  bare minimum you're comfortable with. Setting mincopies to a large
  number, rather than setting numcopies will in some cases prevent
  droping content in entirely safe situations.

  This is the same setting that the [[git-annex-mincopies]](1) command
  configures. It can be overridden on a per-file basis
  by the annex.mincopies setting in `.gitattributes` files.

* `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-expression]](1) for details on the syntax.
  
  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`,
  `git-annex assist`, and the `git-annex assistant`.

  This sets a default, which can be overridden by annex.largefiles
  attributes in `.gitattributes` files, or by `git config`.

* `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. 

  This sets a default, which can be overridden by annex.dotfiles
  in `git config`.

* `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 details.

   This sets a default, which can be overridden by annex.addunlocked
   in `git config`.

* `annex.autocommit`

  Set to false to prevent the `git-annex assistant`, `git-annex assist`
  and `git-annex sync` from automatically committing changes to files
  in the repository.
   
  This sets a default, which can be overridden by annex.autocommit
  in `git config`.

* `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 pull`, ``git-annex merge`, 
  and the `git-annex post-receive` hook.
   
  This sets a default, which can be overridden by annex.resolvemerge
  in `git config`.

* `annex.synccontent`

  Set to true to make `git-annex sync` default to transferring
  annexed content.
  
  Set to false to prevent `git-annex pull` and `git-annex` push from
  transferring annexed content.
  
  This sets a default, which can be overridden by annex.synccontent
  in `git config`.

* `annex.synconlyannex`

  Set to true to make `git-annex sync`, `git-annex pull` and `git-annex
  push` default to only operate on the git-annex branch and annexed content.
  
  This sets a default, which can be overridden by annex.synconlyannex
  in `git config`.

* `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 repository.

  Also, `git-annex fsck` will complain about any files present in
  the repository that use insecure hashes.
  
  Note that this is only read from the git-annex branch by
  `git annex init`, and is copied to the corresponding git config setting. 
  So, changes to the value in the git-annex branch won't affect a
  repository once it has been initialized.

# OPTIONS

* `--set name value`

  Set a value.

* `--get name`

  Get a value.

* `--unset`

  Unset a value.

* `--show-origin name`

  Explain where the value is configured, whether in the git-annex branch,
  or in a `git config` file, or `.gitattributes` file. When a value is
  configured in multiple places, displays the place and the value that
  will be used.

  Note that the parameter can be the name of one of the settings listed
  above, but also any other configuration setting supported by git-annex.
  For example, "annex.backend" cannot be set in the git-annex branch, but
  it can be set in `.gitattributes` or `git config` and this option can
  explain which setting will be used for it.

* `--for-file file`

  Can be used in combination with `--show-origin` to specify what
  filename to check for in `.gitattributes`.

* Also the [[git-annex-common-options]](1) can be used.

# EXAMPLE

Suppose you want to prevent git annex sync from committing changes
to files, so a manual git commit workflow is used in all clones of the
repository. Then run:

	git annex config --set annex.autocommit false

If you want to override that in a partiticular clone, just use git config
in the clone:

	git config annex.autocommit true

And to get back to the default behavior:

	git annex config --unset annex.autocommit

# SEE ALSO

[[git-annex]](1)

git-config(1)

[[git-annex-vicfg]](1)

# AUTHOR

Joey Hess <id@joeyh.name>

Warning: Automatically converted into a man page by mdwn2man. Edit with care.