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

diff --git a/Limit.hs b/Limit.hs
index d11cbf28ac859d45a139daca45514a1f1603bbd3..bf1e85e69d2d4bc8e9fa2b515c4f49962f49c4b0 100644 (file)
--- 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 9559341b705bd8e36cabc8eaac053f81dd193570..96c087e91181fcad242b086683e1825073d92a20 100644 (file)
--- 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 f1ee17eab953ea54f5835c85c3faa14ae95d9cfe..44412a982c7c1e12cf5de8d840f26c8cb3728728 100644 (file)
--- 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 (file)
index 0000000..cb9bdbe
--- /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.
+"""]]