rework largefiles documentation

4 files changed, 85 insertions, 79 deletions

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 77a2b38e9..cb27ec11a 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -810,7 +810,12 @@ Here are all the supported configuration settings.
 
 * `annex.largefiles`
 
-  See "LARGE FILES CONFIGURATION" below.
+  Used to configure which files are large enough to be added to the annex.
+  Default: All files.
+
+  Overrides any annex.largefiles attributes in `.gitattributes` files.
+
+  See <https://git-annex.branchable.com/tips/largefiles> for details.
 
 * `annex.addsmallfiles`
 
@@ -1277,7 +1282,7 @@ Here are all the supported configuration settings.
 
   These can be passed to `git annex init` to tune the repository.
   They cannot be safely changed in a running repository.
-  For details, see <http://git-annex.branchable.com/tuning/>.
+  For details, see <https://git-annex.branchable.com/tuning/>.
 
 # CONFIGURATION VIA .gitattributes
 
@@ -1290,8 +1295,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.
+There is a annex.largefiles attribute; which is used to configure which
+files are large enough to be added to the annex.
+See <https://git-annex.branchable.com/tips/largefiles> for details.
 
 The numcopies setting can also be configured on a per-file-type basis via
 the `annex.numcopies` attribute in `.gitattributes` files. This overrides
@@ -1314,61 +1320,6 @@ 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
@@ -1402,7 +1353,7 @@ whenever the git-annex branch is updated. You can make this hook run
 # SEE ALSO
 
 More git-annex documentation is available on its web site,
-<http://git-annex.branchable.com/>
+<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/`.
@@ -1411,6 +1362,6 @@ should be included, in, for example, `/usr/share/doc/git-annex/`.
 
 Joey Hess <id@joeyh.name>
 
-<http://git-annex.branchable.com/>
+<https://git-annex.branchable.com/>
 
 Warning: Automatically converted into a man page by mdwn2man. Edit with care.
diff --git a/doc/tips/largefiles.mdwn b/doc/tips/largefiles.mdwn
new file mode 100644
index 000000000..46e153399
--- /dev/null
+++ b/doc/tips/largefiles.mdwn
@@ -0,0 +1,67 @@
+[[!meta title="annex.largefiles: configuring mixed content repositories"]]
+
+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.
+
+Let's suppose you're developing a video game, written in C. You have
+source code, and some large game assets. You want to ensure the source
+code is stored in git -- that's what git's for! And you want to store
+the game assets in the git annex -- to avod bloating your git repos with
+possibly enormous files, but still version control them.
+
+The annex.largefiles configuration is useful for such mixed content
+repositories. 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, these commands will
+add its content to git instead of to the annex.
+
+## examples
+
+For example, let's make only files larger than 100 kb be added to the annex,
+and never *.c and *.h source files.
+
+Write this to the `.gitattributes` file:
+
+	* annex.largefiles=(largerthan=100kb)
+	*.c annex.largefiles=nothing
+	*.h annex.largefiles=nothing
+
+Or, set the git configuration instead:
+  
+	git config annex.largefiles 'largerthan=100kb and not (include=*.c or include=*.h)'
+
+Both of these settings do the same thing. Setting it in the `.gitattributes`
+file makes any checkout of the repository share that configuration, so is often
+a good choice. Setting the annex.largefiles git configuration lets different
+checkouts behave differently. The git configuration overrides the
+`.gitattributes` configuration.
+
+## syntax
+
+The way the `.gitattributes` example above works is, *.c and *.h files
+have the annex.largefiles attribute set to "nothing", which matches nothing,
+and so those files are never treated as large files. All other files use
+the other value, which checks the file size.
+
+The value of annex.largefiles is a
+[[preferred content expression|git-annex-preferred-content]] that is
+used to match the large files.
+
+Note that, since git attribute values cannot contain whitespace,
+it's useful to instead parenthesize the terms of the 
+[[preferred content expression|git-annex-preferred-content]]. This trick
+allows setting the annex.largefiles attribute to more complicated expressions.
+For example, this is the same as the git config shown earlier, shoehorned
+into a git attribute:
+
+	* annex.largefiles=(largerthan=100kb)and(not((include=*.c)or(include=*.h)))
+
+## temporarily override
+
+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
diff --git a/doc/tips/replacing_Sparkleshare_or_dvcs-autosync_with_the_assistant.mdwn b/doc/tips/replacing_Sparkleshare_or_dvcs-autosync_with_the_assistant.mdwn
index 893408c2f..cfe422edb 100644
--- a/doc/tips/replacing_Sparkleshare_or_dvcs-autosync_with_the_assistant.mdwn
+++ b/doc/tips/replacing_Sparkleshare_or_dvcs-autosync_with_the_assistant.mdwn
@@ -8,11 +8,7 @@ thing, but even better!
 
 ----
 
-First, get git-annex version 4.20130329 or newer.
-
-----
-
-Let's suppose you're delveloping a video game, written in C. You have
+Let's suppose you're developing a video game, written in C. You have
 source code, and some large game assets. You want to ensure the source
 code is stored in git -- that's what git's for! And you want to store
 the game assets in the git annex -- to avod bloating your git repos with
@@ -24,20 +20,14 @@ file that is stored in the annex.
 
 	git config annex.largefiles "largerthan=100kb and not (include=*.c or include=*.h)"
 
+For more details about this configuration, see [[largefiles]].
+
 ----
 
 Now if you run `git annex add`, it will only add the large files to the
-annex. You can `git add` the small files directly to git.
-
-Note that in order to use `git add` on the small files, your repository
-needs to be in indirect mode, rather than [[direct mode]]. If it's in
-direct mode, `git add` will fail. You can fix that:
-
-	git annex indirect
-
-----
+annex; small files will be stored in git.
 
-A less manual option is to run `git annex assistant`. It will *automatically*
+Or, run `git annex assistant`. It will *automatically*
 add the large files to the annex, and store the small files in git.
 It'll notice every time you modify a file, and immediately commit it,
 too. And sync it out to other repositories you configure using `git annex
diff --git a/doc/tips/unlocked_files.mdwn b/doc/tips/unlocked_files.mdwn
index 038294c69..31f9e9756 100644
--- a/doc/tips/unlocked_files.mdwn
+++ b/doc/tips/unlocked_files.mdwn
@@ -60,9 +60,7 @@ to store the file contents, and the files will be left unlocked.
 [[!template id=note text="""
 Want `git add` to add some file contents to the annex, but store the contents of
 smaller files in git itself? Configure annex.largefiles to match the former.
-
-	git config annex.largefiles \
-		"largerthan=100kb and not include=*.c"
+See [[largefiles]].
 """]]
 
 	# cp ~/my_cool_big_file .