groupwanted: New command to set the groupwanted preferred content expression.

3 files changed, 34 insertions, 5 deletions

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 80dce0ddc..ca987b4e2 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -504,6 +504,21 @@ subdirectories).
   Without an expression, displays the current preferred content setting
   of the repository.
 
+* `groupwanted groupname [expression]`
+
+  Sets or displays the groupwanted expression. This will be used by
+  repositories that are in the group, and that have their preferred
+  content expression set to "groupwanted".
+
+  For example, to configure a group named redundantarchive, and
+  make repositories in the group want to contain 3 copies of every file:
+
+	git annex groupwanted redundantarchive "not (copies=redundantarchive:3)"
+	for repo in foo bar baz; do
+		git annex group $repo redundantarchive
+		git annex wanted $repo groupwanted
+	done
+
 * `schedule repository [expression]`
 
   When run with an expression, configures scheduled jobs to run at a
@@ -1375,7 +1390,9 @@ no equivilant to `--in`.
 
 When a repository is in one of the standard predefined groups, like "backup"
 and "client", setting its preferred content to "standard" will use a
-built-in preferred content expression developed for that group.
+built-in preferred content expression developed for that group. Or,
+setting its preferred content to "groupwanted" will make it use whatever
+groupwanted expression you set for the group.
 
 # SCHEDULED JOBS
 
diff --git a/doc/preferred_content.mdwn b/doc/preferred_content.mdwn
index f6071ea35..31e614919 100644
--- a/doc/preferred_content.mdwn
+++ b/doc/preferred_content.mdwn
@@ -125,8 +125,8 @@ But, you can do more complicated things, for example:
 
 The "groupwanted" keyword can be used to refer to a preferred content
 expression that is associated with a group. This is like the "standard"
-keyword, but you can set up groupwanted preferred content expressions
-using `git annex vicfg`.
+keyword, but you can configure the preferred content expressions
+using `git annex groupwanted`.
 
 Note that when writing a groupwanted preferred content expression,
 you can use all of the keywords listed above, including "standard".
@@ -134,7 +134,8 @@ you can use all of the keywords listed above, including "standard".
 
 For example, to make a variant of the standard client preferred content
 expression that does not want files in the "out" directory, you
-could set `groupwanted client = standard and exclude=out/*`.
+could run: `git annex groupwanted client "standard and exclude=out/*"`
+
 Then repositories that are in the client group and have their preferred
 content expression set to "groupwanted" will use that, while
 other client repositories that have their preferred content expression
@@ -144,6 +145,17 @@ Or, you could make a new group, with your own custom preferred content
 expression tuned for your needs, and every repository you put in this
 group and make its preferred content be "groupwanted" will use it.
 
+For example, the archive group only wants to archive 1 copy of each file,
+spread amoung every repository in the group.
+Here's how to configure a group named redundantarchive, that instead
+wants to contain 3 copies of each file:
+
+	git annex groupwanted redundantarchive "not (copies=redundantarchive:3)"
+	for repo in foo bar baz; do
+		git annex group $repo redundantarchive
+		git annex wanted $repo groupwanted
+	done
+
 ### difference: metadata matching
 
 This:
diff --git a/doc/preferred_content/standard_groups.mdwn b/doc/preferred_content/standard_groups.mdwn
index 5622dcb57..80f512d87 100644
--- a/doc/preferred_content/standard_groups.mdwn
+++ b/doc/preferred_content/standard_groups.mdwn
@@ -72,7 +72,7 @@ All content is wanted, unless it's already been archived somewhere else.
 `(not (copies=archive:1 or copies=smallarchive:1)) or approxlackingcopies=1`
 
 Note that if you want to archive multiple copies (not a bad idea!),
-you can set `groupwanted archive` to a version of 
+you can set `git-annex groupwanted archive` to a version of 
 the above preferred content expression with a larger number of copies
 than 1. Then make the archive repositories have a preferred
 content expression of "groupwanted" in order to use your modified