summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorGravatar Joey Hess <joey@kitenet.net>2012-10-08 13:16:53 -0400
committerGravatar Joey Hess <joey@kitenet.net>2012-10-08 13:16:53 -0400
commit45d50d8c27207fa09e5d3331683e1510df3f3bdd (patch)
tree4bc41f75b77aebd09f7343d9d5bca355d57f4536 /doc
parent7057ce97cce7622051815cf8dd6c8ddd5ac0f62c (diff)
wired preferred content up to get, copy, and drop --auto
Diffstat (limited to 'doc')
-rw-r--r--doc/git-annex.mdwn3
-rw-r--r--doc/preferred_content.mdwn37
-rw-r--r--doc/walkthrough/automatically_managing_content.mdwn5
3 files changed, 44 insertions, 1 deletions
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index abda54f76..5c762593e 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -502,7 +502,8 @@ subdirectories).
* --auto
Enables automatic mode. Commands that get, drop, or move file contents
- will only do so when needed to help satisfy the setting of annex.numcopies.
+ will only do so when needed to help satisfy the setting of annex.numcopies,
+ and preferred content configuration.
* --quiet
diff --git a/doc/preferred_content.mdwn b/doc/preferred_content.mdwn
new file mode 100644
index 000000000..7c7d11267
--- /dev/null
+++ b/doc/preferred_content.mdwn
@@ -0,0 +1,37 @@
+git-annex tries to ensure that the configured number of [[copies]] of your
+data always exist, and leaves it up to you to use commands like `git annex
+get` and `git annex drop` to move the content to the repositories you want
+to contain it. But sometimes, it can be good to have more fine-grained
+control over which repositories prefer to have which content. Configuring
+this allows `git annex get --auto`, `git annex drop --auto`, etc to do
+smarter things.
+
+Currently, preferred content settings can only be edited using `git
+annex vicfg`. Each repository can have its own settings, and other
+repositories may also try to honor those settings. So there's no local
+`.git/config` setting it.
+
+The idea is that you write an expression that files are matched against.
+If a file matches, it's preferred to have its content stored in the
+repository. If it doesn't, it's preferred to drop its content from
+the repository (if there are enough copies elsewhere).
+
+The expressions are very similar to the file matching options documented
+on the [[git-annex]] man page. At the command line, you can use those
+options in commands like this:
+
+ git annex get --include='*.mp3' --and -'(' --not --in=archive -')'
+
+The equivilant preferred content expression looks like this:
+
+ include=*.mp3 and (not in=archive)
+
+So, just remove the dashes, basically.
+
+Note that while --include and --exclude match files relative to the current
+directory, preferred content expressions always match files relative to the
+top of the git repository. Perhaps you put files into `out/` directories
+when you're done with them. Then you could configure your laptop to prefer
+to not retain those files, like this:
+
+ exclude=*/out/*
diff --git a/doc/walkthrough/automatically_managing_content.mdwn b/doc/walkthrough/automatically_managing_content.mdwn
index ef883efef..0080ebcb5 100644
--- a/doc/walkthrough/automatically_managing_content.mdwn
+++ b/doc/walkthrough/automatically_managing_content.mdwn
@@ -38,3 +38,8 @@ work toward having two copies of your files.
The --auto option can also be used with the copy command,
again this lets git-annex decide whether to actually copy content.
+
+The above shows how to use --auto to manage content based on the number
+of copies. It's also possible to configure, on a per-repository basis,
+which content is desired. Then --auto also takes that into account
+see [[preferred_content]] for details.