Normally commands like git annex add always add files to the annex, while git add adds files to git.

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 avoid bloating your git repos with possibly enormous files, but still version control them.

You could take care to use git annex add after changes to the assets, but it would be easy to slip up and git commit -a (which runs git add), checking your large assets into git. Configuring annex.largefiles saves you the bother of keeping things straight when adding files. Once you've told git-annex what files are large, both git annex add and git add/git commit -a will add the large files to the annex and the small files to git.

Other commands that use the annex.largefiles configuration include git annex import, git annex addurl, git annex importfeed, and the assistant.

examples

For example, let's make only files larger than 100 kb be added to the annex, and never *.c and *.h source code files.

git config annex.largefiles 'largerthan=100kb and not (include=*.c or include=*.h)'

That is a local configuration, so will only apply to your clone of the repository. To set a default that will apply to all clones, unless overridden, do this instead:

git annex config --set annex.largefiles 'largerthan=100kb and not (include=*.c or include=*.h)'

There's one other way to configure the same thing, you can put this in the .gitattributes file:

* annex.largefiles=largerthan=100kb
*.c annex.largefiles=nothing
*.h annex.largefiles=nothing

The syntax in .gitattributes is a bit different, because the .gitattributes matches files itself, and the values of attributes cannot contain spaces. So using .gitattributes for this is not recommended (but it does work for older versions of git-annex, where the git annex config setting does not). Any .gitattributes setting overrides the git annex config setting, but will be overridden by the git config setting.

Another example. If you wanted git add to put all files the annex in your local repository:

git config annex.largefiles anything

Or in all clones:

git annex config --set annex.largefiles anything

syntax

See git-annex-matching-expression for details about the syntax.

gitattributes format

Here's that example .gitattributes again:

* annex.largefiles=largerthan=100kb
*.c annex.largefiles=nothing
*.h annex.largefiles=nothing

The way that works is, *.c and *.h files have the annex.largefiles attribute set to "nothing", and so those files are never treated as large files. All other files use the other value, which checks the file size.

Since git attribute values cannot contain whitespace, when you need a more complicated annex.largefiles expression, you can instead parenthesize the terms of the annex.largefiles attribute. For example, this is the same as the git config shown earlier, shoehorned into a single git attribute:

* annex.largefiles=(largerthan=100kb)and(not((include=*.c)or(include=*.h)))

It's generally a better idea to use git annex config instead.

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 --force-large smallfile

converting git to annexed

When you have a file that is currently stored in git, and you want to convert that to be stored in the annex, here's how to accomplish that:

git rm --cached file
git annex add --force-large file
git commit file

This first removes the file from git's index cache, and then adds it back using git-annex. You can modify the file before the git-annex add step, perhaps replacing it with new larger content that necessitates git-annex.

The --force-large option needs git-annex version 7.20200202.7 or newer.

converting annexed to git

When you have a file that is currently stored in the annex, and you want to convert that to be stored in git, here's how to accomplish that:

git annex unlock file
git rm --cached file
git annex add --force-small file
git commit file

You can modify the file after unlocking it and before adding it to git. And this is probably a good idea if it was really a big file, so that you can replace its content with something smaller.

The --force-small option needs git-annex version 7.20200202.7 or newer.