From 1e5aca5087e573aa93b4b6efe7c6f5abd90d0001 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@kitenet.net>
Date: Fri, 29 Mar 2013 16:17:13 -0400
Subject: New annex.largefiles setting, which configures which files `git annex
 add` and the assistant add to the annex.

I would have sort of liked to put this in .gitattributes, but it seems
it does not support multi-word attribute values. Also, making this a single
config setting makes it easy to only parse the expression once.

A natural next step would be to make the assistant `git add` files that
are not annex.largefiles. OTOH, I don't think `git annex add` should
`git add` such files, because git-annex command line tools are
not in the business of wrapping git command line tools.
---
 doc/git-annex.mdwn | 38 ++++++++++++++++++++++++++++++++++----
 1 file changed, 34 insertions(+), 4 deletions(-)

(limited to 'doc')

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 35a1b2cdf..502c1e168 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -735,6 +735,23 @@ file contents are present at either of two repositories.
 
   Closes a group of file matching options.
 
+# PREFERRED CONTENT
+
+Each repository has a preferred content setting, which specifies content
+that the repository wants to have present. These settings can be configured
+using `git annex vicfg`. They are used by the `--auto` option, and
+by the git-annex assistant.
+
+The preferred content settings are similar, but not identical to
+the file matching options specified above, just without the dashes.
+For example:
+
+	exclude=archive/* and (include=*.mp3 or smallerthan=1mb)
+
+The main differences are that `exclude=` and `include=` always
+match relative to the top of the git repository, and that there is
+no equivilant to --in.
+
 # CONFIGURATION
 
 Like other git commands, git-annex is configured via `.git/config`.
@@ -765,6 +782,19 @@ Here are all the supported configuration settings.
 
   The default reserve is 1 megabyte.
 
+* `annex.largefiles`
+
+  Allows configuring which files `git annex add` and the assistant consider
+  to be large enough to need to be added to the annex. By default,
+  all files are added to the annex.
+
+  The value is a preferred content expression. See PREFERRED CONTENT
+  for details.
+
+  Example:
+
+	annex.largefiles = largerthan=100kb or include=*.mp3
+
 * `annex.queuesize`
 
   git-annex builds a queue of git commands, in order to combine similar
@@ -790,10 +820,6 @@ Here are all the supported configuration settings.
   the accuracy will make `git annex unused` consume more memory;
   run `git annex status` for memory usage numbers.
 
-* `annex.version`
-
-  Automatically maintained, and used to automate upgrades between versions.
-
 * `annex.sshcaching`
 
   By default, git-annex caches ssh connections
@@ -819,6 +845,10 @@ Here are all the supported configuration settings.
   Set to false to prevent the git-annex assistant from automatically
   committing changes to files in the repository.
 
+* `annex.version`
+
+  Automatically maintained, and used to automate upgrades between versions.
+
 * `annex.direct`
 
   Set to true when the repository is in direct mode. Should not be set
-- 
cgit v1.2.3