annex.backend is the new name for what was annex.backends

It takes a single key-value backend, rather than the unncessary and confusing list.
The old option still works if set.

Simplified some old old code too.

This commit was sponsored by Thomas Hochstein on Patreon.

4 files changed, 45 insertions, 8 deletions

diff --git a/doc/backends.mdwn b/doc/backends.mdwn
index f69f655d6..c5b047ecc 100644
--- a/doc/backends.mdwn
+++ b/doc/backends.mdwn
@@ -45,9 +45,8 @@ Note that the various 512 and 384 length hashes result in long paths,
 which are known to not work on Windows. If interoperability on Windows is a
 concern, avoid those.
 
-The `annex.backends` git-config setting can be used to list the backends
-git-annex should use when adding new files. The first one listed will
-be used.
+The `annex.backend` git-config setting can be used to configure the
+default backend to use when adding new files.
 
 For finer control of what backend is used when adding different types of
 files, the `.gitattributes` file can be used. The `annex.backend`
diff --git a/doc/forum/Can_git-annex-import_--clean-duplicates_honour_multiple_backends__63__/comment_1_5730767d5247e8997b4fa5b20c4cb281._comment b/doc/forum/Can_git-annex-import_--clean-duplicates_honour_multiple_backends__63__/comment_1_5730767d5247e8997b4fa5b20c4cb281._comment
new file mode 100644
index 000000000..1b6ebca99
--- /dev/null
+++ b/doc/forum/Can_git-annex-import_--clean-duplicates_honour_multiple_backends__63__/comment_1_5730767d5247e8997b4fa5b20c4cb281._comment
@@ -0,0 +1,35 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 1"""
+ date="2017-05-09T18:06:34Z"
+ content="""
+When git-annex is adding a file, a backend can chose to not
+generate any key, and then it will try the next backend in the list.
+
+The only backend that does that is the URL backend.
+So if someone lists URL first for some reason, it'll fall back to a backend
+that is usable. It could just as well crash in that edge case; the
+annex.backends UI happened before the needs of backends were perfectly
+understood. (As did the "backend" name...)
+
+Anyway, I see the use case, but.. `git annex import` actually honors
+annex.backend settings in .gitattributes before annex.backends in
+git-config. So, relying on it using the latter to make it check multiple
+backends won't always work. I don't think it would be good to complicate
+the .gitattributes annex.backends and --backend to support a list of
+backends.
+
+It seems it would be just as fast for you to run git-annex import once per
+backend, rather than compliciating it to try multiple backends. 
+
+I think that if annex.backends were not a list for historical reasons, 
+I'd be suggesting a small shell script is your best option. 
+
+And so rather than add a new feature just because annex.backends is
+historically a list, I'd rather perhaps deprecate annex.backends as
+unncessarily complicated, and make annex.backend be a single-backend
+setting. (Just did that.)
+
+Sorry this didn't quite go the way you wanted! If there is a disadvantage
+to the simple shell script option, please do let me know..
+"""]]
diff --git a/doc/git-annex-calckey.mdwn b/doc/git-annex-calckey.mdwn
index 340c03eed..c91e1a827 100644
--- a/doc/git-annex-calckey.mdwn
+++ b/doc/git-annex-calckey.mdwn
@@ -12,7 +12,7 @@ This plumbing-level command calculates the key that would be used
 to refer to a file. The file is not added to the annex by this command.
 The key is output to stdout.
 
-The backend used is the first listed in the annex.backends configuration
+The backend used is the one from the annex.backend configuration
 setting, which can be overridden by the --backend option.
 For example, to force use of the SHA1 backend:
 
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 44f3b94fc..8a841a941 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -827,13 +827,16 @@ Here are all the supported configuration settings.
 
   A unique UUID for this repository (automatically set).
 
-* `annex.backends`
+* `annex.backend`
 
-  Space-separated list of names of the key-value backends to use
-  when adding new files to the repository.
+  Name of the default key-value backend to use when adding new files
+  to the repository.
 
   This is overridden by annex annex.backend configuration in the
-  .gitattributes files.
+  .gitattributes files, and by the --backend option.
+
+  (This used to be named `annex.backends`, and that will still be used
+  if set.)
 
 * `annex.securehashesonly`