From 98475acf860d33e0482c37a68eca9e65aaadf986 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Tue, 2 Feb 2016 16:50:58 -0400 Subject: rework largefiles documentation --- doc/git-annex.mdwn | 73 ++++------------------ doc/tips/largefiles.mdwn | 67 ++++++++++++++++++++ ...eshare_or_dvcs-autosync_with_the_assistant.mdwn | 20 ++---- doc/tips/unlocked_files.mdwn | 4 +- 4 files changed, 85 insertions(+), 79 deletions(-) create mode 100644 doc/tips/largefiles.mdwn (limited to 'doc') 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 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 . + For details, see . # 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 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, - + 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 - + 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 . -- cgit v1.2.3