global numcopies setting

* numcopies: New command, sets global numcopies value that is seen by all
  clones of a repository.
* The annex.numcopies git config setting is deprecated. Once the numcopies
  command is used to set the global number of copies, any annex.numcopies
  git configs will be ignored.
* assistant: Make the prefs page set the global numcopies.

This global numcopies setting is needed to let preferred content
expressions operate on numcopies.

It's also convenient, because typically if you want git-annex to preserve N
copies of files in a repo, you want it to do that no matter which repo it's
running in. Making it global avoids needing to warn the user about gotchas
involving inconsistent annex.numcopies settings.
(See changes to doc/numcopies.mdwn.)

Added a new variety of git-annex branch log file, that holds only 1 value.
Will probably be useful for other stuff later.

This commit was sponsored by Nicolas Pouillard.

1 files changed, 31 insertions, 10 deletions

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index e8058720c..4e7bd2395 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -403,6 +403,20 @@ subdirectories).
   keyid+= and keyid-= with such remotes should be used with care, and
   make little sense except in cases like the revoked key example above.
 
+* `numcopies [N]`
+
+  Tells git-annex how many copies it should preserve of files, over all
+  repositories. The default is 1.
+
+  Run without a number to get the current value.
+
+  When git-annex is asked to drop a file, it first verifies that the
+  required number of copies can be satisfied amoung all the other
+  repositories that have a copy of the file.
+
+  This can be overridden on a per-file basis by the annex.numcopies setting
+  in .gitattributes files.
+
 * `trust [repository ...]`
 
   Records that a repository is trusted to not unexpectedly lose
@@ -828,7 +842,7 @@ subdirectories).
 * `--auto`
 
   Enable 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 numcopies,
   and preferred content configuration.
 
 * `--all`
@@ -883,7 +897,7 @@ subdirectories).
 
 * `--numcopies=n`
 
-  Overrides the `annex.numcopies` setting, forcing git-annex to ensure the
+  Overrides the numcopies setting, forcing git-annex to ensure the
   specified number of copies exist.
 
   Note that setting numcopies to 0 is very unsafe.
@@ -1117,12 +1131,6 @@ Here are all the supported configuration settings.
 
   A unique UUID for this repository (automatically set).
 
-* `annex.numcopies`
-
-  Number of copies of files to keep across all repositories. (default: 1)
-
-  Note that setting numcopies to 0 is very unsafe.
-
 * `annex.backends`
 
   Space-separated list of names of the key-value backends to use.
@@ -1151,6 +1159,17 @@ Here are all the supported configuration settings.
 
         	annex.largefiles = largerthan=100kb and not (include=*.c or include=*.h)
 
+* `annex.numcopies`
+
+  This is a deprecated setting. You should instead use the
+  `git annex numcopies` command to configure how many copies of files
+  are kept acros all repositories.
+
+  This config setting is only looked at when `git annex numcopies` has
+  never been configured.
+
+  Note that setting numcopies to 0 is very unsafe.
+
 * `annex.queuesize`
 
   git-annex builds a queue of git commands, in order to combine similar
@@ -1456,10 +1475,12 @@ but the SHA256E backend for ogg files:
 
 The numcopies setting can also be configured on a per-file-type basis via
 the `annex.numcopies` attribute in `.gitattributes` files. This overrides
-any value set using `annex.numcopies` in `.git/config`.
-For example, this makes two copies be needed for wav files:
+other numcopies settings.
+For example, this makes two copies be needed for wav files and 3 copies
+for flac files:
 
 	*.wav annex.numcopies=2
+	*.flac annex.numcopies=3
 
 Note that setting numcopies to 0 is very unsafe.