annex.largefiles can be configured in .gitattributes too

This is particulary useful for v6 repositories, since the .gitattributes
configuration will apply in all clones of the repository.

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