diff options
Diffstat (limited to 'doc/git-annex.mdwn')
| -rw-r--r-- | doc/git-annex.mdwn | 91 |
1 files changed, 68 insertions, 23 deletions
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn index 471f21957..77a2b38e9 100644 --- a/doc/git-annex.mdwn +++ b/doc/git-annex.mdwn @@ -795,6 +795,9 @@ Here are all the supported configuration settings. Space-separated list of names of the key-value backends to use. The first listed is used to store new files by default. + This is overridden by annex annex.backend configuration in the + .gitattributes files. + * `annex.diskreserve` Amount of disk space to reserve. Disk space is checked when transferring @@ -807,26 +810,7 @@ Here are all the supported configuration settings. * `annex.largefiles` - Allows configuring which files are considered to be large enough to - need to be added to the annex. By default, all specified files are added - to the annex, but configuring this can cause the small files to be - checked into git, without using the annex. - - The value is a preferred content expression. See [[git-annex-preferred-content]](1) - for details. - - Example: - - annex.largefiles = largerthan=100kb and not (include=*.c or include=*.h) - - This setting is checked by `git annex add`, `git annex import` and the assistant. - It's also used by `git annex addurl` and `git annex importfeed` when - downloading files. - - It can be useful to temporarily override it via -c at the command line. - For example: - - git annex add -c annex.largefiles='include=*' 99kbfile + See "LARGE FILES CONFIGURATION" below. * `annex.addsmallfiles` @@ -838,10 +822,12 @@ Here are all the supported configuration settings. This is a deprecated setting. You should instead use the `git annex numcopies` command to configure how many copies of files - are kept across all repositories. + are kept across all repositories, or the annex.numcopies .gitattributes + setting. This config setting is only looked at when `git annex numcopies` has - never been configured. + never been configured, and when there's no annex.numcopies setting in the + .gitattributes file. Note that setting numcopies to 0 is very unsafe. @@ -1304,6 +1290,9 @@ but the SHA256E backend for ogg files: * annex.backend=WORM *.ogg annex.backend=SHA256E +There is a annex.largefiles attribute; see "LARGE FILES CONFIGURATION" +below. + The numcopies setting can also be configured on a per-file-type basis via the `annex.numcopies` attribute in `.gitattributes` files. This overrides other numcopies settings. @@ -1318,12 +1307,68 @@ 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. +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. +# LARGE FILES CONFIGURATION + +Normally commands like `git annex add` always add files to the annex. +And when using the v6 repository mode, even `git add` and `git commit -a` +will add files to the annex. + +However, sometimes it's useful to keep the content of some smaller files in +git, any only annex the larger files. For example, a game's code should be +committed to git while its artwork is stored in the annex. + +The annex.largefiles configuration meets this need. It's checked by +`git annex add`, by `git add` and `git commit -a` (in v6 repositories), +by `git annex import` and the assistant. It's also used by +`git annex addurl` and `git annex importfeed` when downloading files. +When a file does not match annex.largefiles, it will be added to git instead +of to the annex. + +There are two ways to configure annex.largefiles. Setting it in the +`.gitattributes` file is recommended to consistently use the same +configuration across different checkouts of the repository. Setting the +annex.largefiles git configuration lets different checkouts behave +differently. The git configuration overrides the `.gitattributes` +configuration. + +For example, in the game scenario, here's how to make only files of a +certian size be annexed, and never source code files: + + git config annex.largefiles 'largerthan=100kb and (not include=*.c)' + +The value is a preferred content expression. +See [[git-annex-preferred-content]](1) for details. + +To configure the same thing in the `.gitattributes` file, looks a little +bit different: + + * annex.largefiles=(largerthan=100kb) + *.c annex.largefiles=nothing + +That has the same effect as the git configuration, because the attribute for +*.c overrides the previous attribute. + +Note that, since git attribute values cannot contain whitespace, +it's useful to instead parenthesize the terms of the preferred content +expression. This trick allows setting the annex.largefiles attribute to more +complicated expressions. For example, this is the same as the git config +shown earlier: + + * annex.largefiles=(largerthan=100kb)and(not(include=*.c)) + +By the way, if you've set up an annex.largefiles configuration but want to +force a file to be stored in the annex, you can temporarily override the +configuration like this: + + git annex add -c annex.largefiles=anything smallfile + # EXIT STATUS git-annex, when called as a git subcommand, may return exit codes 0 or 1 |