mirrors/git-annex
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

rework largefiles documentation

Browse source
This commit is contained in:
Joey Hess 2016-02-02 16:50:58 -04:00
parent 82bb1db75b
commit 8764dc43ed
Failed to extract signature
4 changed files with 85 additions and 79 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

73
doc/git-annex.mdwn
View file

@ -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.

67
doc/tips/largefiles.mdwn Normal file
View file

@ -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

20
doc/tips/replacing_Sparkleshare_or_dvcs-autosync_with_the_assistant.mdwn
View file

@ -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.
annex; small files will be stored in 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
----
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

4
doc/tips/unlocked_files.mdwn
View file

@ -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 .