rework largefiles documentation

1 files changed, 67 insertions, 0 deletions

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