From 499d01412308da0cf031946e9d46fd9439f41add Mon Sep 17 00:00:00 2001
From: Joey Hess <joeyh@joeyh.name>
Date: Wed, 26 Jul 2023 15:29:23 -0400
Subject: [PATCH] improve match explanations

Using == and != proved too hard to read, so went with [TRUE] and [FALSE]
after the term. I would kind of liked to have used emojis for a green
check and red X, but probably that is too fancy to be a good idea.

Make --explain output be inside [ ] with whitespace around them, to
avoid it ending with eg "[FALSE]]" and to make it easier to visually
find the start of it.

Sponsored-by: Dartmouth College's DANDI project
---
 Limit.hs                                             |  7 ++++---
 Messages.hs                                          |  2 +-
 doc/git-annex-common-options.mdwn                    |  7 +++++++
 ...mment_2_71616074104ab70eb76ad5edb9207b5c._comment | 12 ++++++++++++
 4 files changed, 24 insertions(+), 4 deletions(-)
 create mode 100644 doc/todo/option_to_explain/comment_2_71616074104ab70eb76ad5edb9207b5c._comment

diff --git a/Limit.hs b/Limit.hs
index d11cbf28ac..bf1e85e69d 100644
--- a/Limit.hs
+++ b/Limit.hs
@@ -625,8 +625,9 @@ checkKey a (MatchingFile fi) = lookupFileKey fi >>= maybe (return False) a
 checkKey a (MatchingInfo p) = maybe (return False) a (providedKey p)
 checkKey a (MatchingUserInfo p) = a =<< getUserInfo (userProvidedKey p)
 
-matchDescSimple :: String -> Bool -> Utility.Matcher.MatchDesc
-matchDescSimple s b = Utility.Matcher.MatchDesc $ (if b then "" else "!") ++ s
+matchDescSimple :: String -> (Bool -> Utility.Matcher.MatchDesc)
+matchDescSimple s b = Utility.Matcher.MatchDesc $ s ++
+	if b then "[TRUE]" else "[FALSE]"
 
 (=?) :: String -> String -> (Bool -> Utility.Matcher.MatchDesc)
-k =? v = \b -> Utility.Matcher.MatchDesc $ k ++ (if b then "==" else "!=") ++ v
+k =? v = matchDescSimple (k ++ "=" ++ v)
diff --git a/Messages.hs b/Messages.hs
index 9559341b70..96c087e911 100644
--- a/Messages.hs
+++ b/Messages.hs
@@ -306,7 +306,7 @@ explain ai (Just msg) = do
 	when (Annex.explainenabled rd) $
 		let d = actionItemDesc ai
 		in outputMessage JSON.none id $
-			"[" <> (if d == mempty then "" else (d <> " ")) <> msg <> "]\n"
+			"[ " <> (if d == mempty then "" else (d <> " ")) <> msg <> " ]\n"
 explain _ _ = return ()
 
 {- Prevents any concurrent console access while running an action, so
diff --git a/doc/git-annex-common-options.mdwn b/doc/git-annex-common-options.mdwn
index f1ee17eab9..44412a982c 100644
--- a/doc/git-annex-common-options.mdwn
+++ b/doc/git-annex-common-options.mdwn
@@ -37,6 +37,13 @@ Most of these options are accepted by all git-annex commands.
   what to do. The explanations will be inside square brackets.
   For example, "[foo is not present here]"
 
+  This includes explanations of why preferred content expressions and
+  other similar expressions like annex.largefiles match or fail to match.
+  In these explanations, the expression is displayed, with each term
+  followed by "[TRUE]" or "[FALSE]" to indicate the value.
+  Irrelevant terms will be ommitted from the explanation, for example 
+  `"exclude=* and copies=1"` will be displayed as `"exclude=*[FALSE]"`
+
 * `--debug`
 
   Display debug messages to standard error.
diff --git a/doc/todo/option_to_explain/comment_2_71616074104ab70eb76ad5edb9207b5c._comment b/doc/todo/option_to_explain/comment_2_71616074104ab70eb76ad5edb9207b5c._comment
new file mode 100644
index 0000000000..cb9bdbe995
--- /dev/null
+++ b/doc/todo/option_to_explain/comment_2_71616074104ab70eb76ad5edb9207b5c._comment
@@ -0,0 +1,12 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 2"""
+ date="2023-07-26T19:31:40Z"
+ content="""
+--explain is implemented and expanations for preferred content expressions,
+annex.largefiles, and annex.addunlocked are now displayed.
+
+Leaving this open because I do think that explanations of numcopies and
+content presence checking should be added, as well as perhaps explanations
+of drop proofs.
+"""]]