improve sync message in export edge case

sync: Better error message when unable to export to a remote because
remote.name.annex-tracking-branch is configured to a ref that does not
exist.

It does not suggest how to fix the problem because there are several
possible solutions: Change the git config to point to something that does
exist, git add some files, or put files on the special remote that will be
imported and so populate the ref.

I considered just silently not doing anything, which is what it does
when annex-tracking-branch = master and nothing has been committed to
master yet. But it seems better to be explicit about it, since this is a
fairly confusing situation to find yourself in.

Sponsored-By: Max Thoursie on Patreon

CHANGELOG

@@ -14,6 +14,9 @@ git-annex (8.20211124) UNRELEASED; urgency=medium
   * Improve git command queue flushing so that eg, addurl of several
     large files that take time to download will update the index for each
     file, rather than deferring the index updates to the end.
+  * sync: Better error message when unable to export to a remote because
+    remote.name.annex-tracking-branch is configured to a ref that does not
+    exist.
 
  -- Joey Hess <id@joeyh.name>  Tue, 23 Nov 2021 15:58:27 -0400
 

Command/Sync.hs

@@ -888,7 +888,7 @@ seekExportContent o rs (currbranch, _) = or <$> forM rs go
 			Export.closeDb
 			(\db -> Export.writeLockDbWhile db (go' r db))
 	go' r db = case remoteAnnexTrackingBranch (Remote.gitconfig r) of
-		Nothing -> nontracking r db
+		Nothing -> cannotupdateexport r db Nothing
 		Just b -> do
 			mtree <- inRepo $ Git.Ref.tree b
 			mtbcommitsha <- Command.Export.getExportCommit r b
@@ -897,33 +897,41 @@ seekExportContent o rs (currbranch, _) = or <$> forM rs go
 					filteredtree <- Command.Export.filterExport r tree
 					Command.Export.changeExport r db filteredtree
 					Command.Export.fillExport r db filteredtree mtbcommitsha
-				_ -> nontracking r db
+				_ -> cannotupdateexport r db (Just b)
 	
-	nontracking r db = do
+	cannotupdateexport r db mtb = do
 		exported <- getExport (Remote.uuid r)
-		maybe noop (warnnontracking r exported) currbranch
-		nontrackingfillexport r db (exportedTreeishes exported) Nothing
+		maybe noop (warncannotupdateexport r mtb exported) currbranch
+		fillexistingexport r db (exportedTreeishes exported) Nothing
 	
-	warnnontracking r exported currb = inRepo (Git.Ref.tree currb) >>= \case
-		Just currt | not (any (== currt) (exportedTreeishes exported)) ->
-			showLongNote $ unwords
-				[ "Not updating export to " ++ Remote.name r
-				, "to reflect changes to the tree, because export"
-				, "tracking is not enabled. "
-				, "(Set " ++ gitconfig ++ " to enable it.)"
-				]
-		_ -> noop
+	warncannotupdateexport r mtb exported currb = case mtb of
+		Nothing -> inRepo (Git.Ref.tree currb) >>= \case
+			Just currt | not (any (== currt) (exportedTreeishes exported)) ->
+				showLongNote $ unwords
+					[ notupdating
+					, "to reflect changes to the tree, because export"
+					, "tracking is not enabled. "
+					, "(Set " ++ gitconfig ++ " to enable it.)"
+					]
+			_ -> noop
+		Just b -> showLongNote $ unwords
+			[ notupdating
+			, "because " ++ Git.fromRef b ++ "does not exist."
+			, "(As configured by " ++ gitconfig ++ ")"
+			]
 	  where
 		gitconfig = show (remoteAnnexConfig r "tracking-branch")
+		notupdating = "Not updating export to " ++ Remote.name r
 
-	nontrackingfillexport _ _ [] _ = return False
-	nontrackingfillexport r db (tree:[]) mtbcommitsha = do
+	fillexistingexport _ _ [] _ = return False
+	fillexistingexport r db (tree:[]) mtbcommitsha = do
 		-- The tree was already filtered when it was exported, so
 		-- does not need be be filtered again now, when we're only
-		-- filling in any files that did not get transferred.
+		-- filling in any files that did not get transferred
+		-- to the existing exported tree.
 		let filteredtree = Command.Export.ExportFiltered tree
 		Command.Export.fillExport r db filteredtree mtbcommitsha
-	nontrackingfillexport r _ _ _ = do
+	fillexistingexport r _ _ _ = do
 		warnExportImportConflict r
 		return False
 

doc/forum/export_tracking_not_enabled_when_branch_is_set.mdwn

@@ -30,3 +30,5 @@ i get a result because i have it set
 this seems to be a bug, but i wanted to make sure i wasn't doing something wrong before submitting a bug report.
 
 [[!tag forumbug]]
+
+> [[done]] --[[Joey]]

doc/forum/export_tracking_not_enabled_when_branch_is_set/comment_2_12c90792bd8c0c37bc53806843583733._comment

@@ -3,16 +3,8 @@
  subject="""comment 2"""
  date="2021-12-23T17:45:07Z"
  content="""
-> Hmm, I think the most likely reason is that master:devices/motoE5
-> does not exist yet, so it fails to list the tree for it.
-
-Seems it is not that. I tried it and following
-[[tips/android_sync_with_adb]] works, and that tip
-has initremote followed by configuring annex-tracking-branch,
-followed by git-annex sync.
-
-Aha! I was able to reproduce it by following that tip, but only
-configure the remote with exporttree=yes, while leaving off the
+Aha! I was able to reproduce it by following [[tips/android_sync_with_adb]],
+but only configure the remote with exporttree=yes, while leaving off the
 importtree=yes.
 
 	git init foo
@@ -24,8 +16,17 @@ importtree=yes.
 	git annex add foo
 	git-annex sync --content d
 
-So the problem is that it is unable to read the export commit for the
-tracking branch, because it has not imported from the remote.
+Alternatively -- and I think this is probably what you did -- do include
+importtree=yes, but the special remote is actually empty, it does not
+include any files to import yet. And the directory you have configured to
+export does not exist in your repository.
 
-First running `git-annex export` does work around this problem.
+In both these cases, the export fails because it is unable to determine what
+to export to the remote, because the current branch does not contain the
+subdirectory that it's configured to export.
+
+I have fixed the warning message in this case, and the thing to do is just to
+create the subdirectory you configured it to export, and git add files to it.
+Or, in your case, you could put a file on the android device, which it would
+then import, and so get the subdirectory populated that way.
 """]]