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.

9 files changed, 82 insertions, 49 deletions

diff --git a/Annex.hs b/Annex.hs
index 95709faec..2a372f158 100644
--- a/Annex.hs
+++ b/Annex.hs
@@ -98,7 +98,7 @@ data AnnexState = AnnexState
 	{ repo :: Git.Repo
 	, repoadjustment :: (Git.Repo -> IO Git.Repo)
 	, gitconfig :: GitConfig
-	, backends :: [BackendA Annex]
+	, backend :: Maybe (BackendA Annex)
 	, remotes :: [Types.Remote.RemoteA Annex]
 	, remoteannexstate :: M.Map UUID AnnexState
 	, output :: MessageState
@@ -149,7 +149,7 @@ newState c r = do
 		{ repo = r
 		, repoadjustment = return
 		, gitconfig = c
-		, backends = []
+		, backend = Nothing
 		, remotes = []
 		, remoteannexstate = M.empty
 		, output = def
diff --git a/Backend.hs b/Backend.hs
index da7d9f6e1..c39141f37 100644
--- a/Backend.hs
+++ b/Backend.hs
@@ -7,7 +7,7 @@
 
 module Backend (
 	list,
-	orderedList,
+	defaultBackend,
 	genKey,
 	getBackend,
 	chooseBackend,
@@ -33,40 +33,29 @@ import qualified Data.Map as M
 list :: [Backend]
 list = Backend.Hash.backends ++ Backend.WORM.backends ++ Backend.URL.backends
 
-{- List of backends in the order to try them when storing a new key. -}
-orderedList :: Annex [Backend]
-orderedList = do
-	l <- Annex.getState Annex.backends -- list is cached here
-	if not $ null l
-		then return l
-		else do
-			f <- Annex.getState Annex.forcebackend
-			case f of
-				Just name | not (null name) ->
-					return [lookupname name]
-				_ -> do
-					l' <- gen . annexBackends <$> Annex.getGitConfig
-					Annex.changeState $ \s -> s { Annex.backends = l' }
-					return l'
+{- Backend to use by default when generating a new key. -}
+defaultBackend :: Annex Backend
+defaultBackend = maybe cache return =<< Annex.getState Annex.backend
   where
-	gen [] = list
-	gen ns = map lookupname ns
+	cache = do
+		n <- maybe (annexBackend <$> Annex.getGitConfig) (return . Just)
+			=<< Annex.getState Annex.forcebackend
+		let b = case n of
+			Just name | valid name -> lookupname name
+			_ -> Prelude.head list
+		Annex.changeState $ \s -> s { Annex.backend = Just b }
+		return b
+	valid name = not (null name)
 	lookupname = lookupBackendVariety . parseKeyVariety
 
-{- Generates a key for a file, trying each backend in turn until one
- - accepts it. -}
+{- Generates a key for a file. -}
 genKey :: KeySource -> Maybe Backend -> Annex (Maybe (Key, Backend))
-genKey source trybackend = do
-	bs <- orderedList
-	let bs' = maybe bs (: bs) trybackend
-	genKey' bs' source
-genKey' :: [Backend] -> KeySource -> Annex (Maybe (Key, Backend))
-genKey' [] _ = return Nothing
-genKey' (b:bs) source = do
+genKey source preferredbackend = do
+	b <- maybe defaultBackend return preferredbackend
 	r <- B.getKey b source
-	case r of
-		Nothing -> genKey' bs source
-		Just k -> return $ Just (makesane k, b)
+	return $ case r of
+		Nothing -> Nothing
+		Just k -> Just (makesane k, b)
   where
 	-- keyNames should not contain newline characters.
 	makesane k = k { keyName = map fixbadchar (keyName k) }
@@ -82,13 +71,14 @@ getBackend file k = case maybeLookupBackendVariety (keyVariety k) of
 		return Nothing
 
 {- Looks up the backend that should be used for a file.
- - That can be configured on a per-file basis in the gitattributes file. -}
+ - That can be configured on a per-file basis in the gitattributes file,
+ - or forced with --backend. -}
 chooseBackend :: FilePath -> Annex (Maybe Backend)
 chooseBackend f = Annex.getState Annex.forcebackend >>= go
   where
-	go Nothing =  maybeLookupBackendVariety . parseKeyVariety
+	go Nothing = maybeLookupBackendVariety . parseKeyVariety
 		<$> checkAttr "annex.backend" f
-	go (Just _) = Just . Prelude.head <$> orderedList
+	go (Just _) = Just <$> defaultBackend
 
 {- Looks up a backend by variety. May fail if unsupported or disabled. -}
 lookupBackendVariety :: KeyVariety -> Backend
diff --git a/CHANGELOG b/CHANGELOG
index c1d9dc7b6..2bb2d08ab 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -22,6 +22,9 @@ git-annex (6.20170322) UNRELEASED; urgency=medium
   * git annex add -u now supported, analagous to git add -u
   * version: Added "dependency versions" line.
   * Keys marked as dead are now skipped by --all.
+  * annex.backend is the new name for what was annex.backends, and takes
+    a single key-value backend, rather than the unncessary and confusing
+    list. The old option still works if set.
 
  -- Joey Hess <id@joeyh.name>  Wed, 29 Mar 2017 12:41:46 -0400
 
diff --git a/Command/Migrate.hs b/Command/Migrate.hs
index 8dfee9814..8924b1780 100644
--- a/Command/Migrate.hs
+++ b/Command/Migrate.hs
@@ -36,15 +36,13 @@ start file key = do
 		Nothing -> stop
 		Just oldbackend -> do
 			exists <- inAnnex key
-			newbackend <- choosebackend =<< chooseBackend file
+			newbackend <- maybe defaultBackend return 
+				=<< chooseBackend file
 			if (newbackend /= oldbackend || upgradableKey oldbackend key || forced) && exists
 				then do
 					showStart "migrate" file
 					next $ perform file key oldbackend newbackend
 				else stop
-  where
-	choosebackend Nothing = Prelude.head <$> orderedList
-	choosebackend (Just backend) = return backend
 
 {- Checks if a key is upgradable to a newer representation.
  - 
diff --git a/Types/GitConfig.hs b/Types/GitConfig.hs
index da548d478..714038070 100644
--- a/Types/GitConfig.hs
+++ b/Types/GitConfig.hs
@@ -48,7 +48,7 @@ data GitConfig = GitConfig
 	, annexNumCopies :: Maybe NumCopies
 	, annexDiskReserve :: Integer
 	, annexDirect :: Bool
-	, annexBackends :: [String]
+	, annexBackend :: Maybe String
 	, annexQueueSize :: Maybe Int
 	, annexBloomCapacity :: Maybe Int
 	, annexBloomAccuracy :: Maybe Int
@@ -98,7 +98,12 @@ extractGitConfig r = GitConfig
 	, annexDiskReserve = fromMaybe onemegabyte $
 		readSize dataUnits =<< getmaybe (annex "diskreserve")
 	, annexDirect = getbool (annex "direct") False
-	, annexBackends = getwords (annex "backends")
+	, annexBackend = maybe
+		-- annex.backends is the old name of the option, still used
+		-- when annex.backend is not set.
+		(headMaybe $ getwords (annex "backends"))
+		Just
+		(getmaybe (annex "backend"))
 	, annexQueueSize = getmayberead (annex "queuesize")
 	, annexBloomCapacity = getmayberead (annex "bloomcapacity")
 	, annexBloomAccuracy = getmayberead (annex "bloomaccuracy")
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`