Add an --explain option that displays human readable descriptions of why git-annex decides whether or not to transfer or drop a file. Eg:
git-annex get bar foo --explain
[bar is not present here]
[foo is present here]
get bar
git-get get --auto --explain baz meep
[baz is not present here]
(baz has 1 copy, and its numcopies is 2)
get baz
[meep is not present here]
[meep matches preferred content: include==* and exclude==archive/*]
get meep
git-annex drop --explain archive/foo
[archive/foo is present here]
[archive/foo has 2 copies, and its numcopies is 1]
[archive/foo does not march preferred content: include==* and exclude!=archive/*]
drop foo (checking origin...) ok
Implementation would be to output these extra lines when checking if content is present, and when checking if preferred content expressions match.
It could also display the actions taken while attempting to drop a file, and the drop safety proof that is constructed. --debug already contains that, but it could be made more human readable and included in --explain.
It should be possible, while matching a preferred content expression, to accumulate a version of it with "=" replaced by "==" and "!=" depending on whether a term matches. That seems clear enough to understand why it matched. What to do about terms like "present"? Maybe "!present" when it doesn't match?" And a term like "standard" would ideally expand out the included expression, eg: "standard(group==backup, include==*)"
--Joey
Sounds absolutely awesome! The new
git annex satisfywould also benefit from this.Also when thinking about a potential future
--dry-runmode that wouldn't actually do stuff but in combination with--explainwould display what it would do and why. I know dry-running can be nontrivial to implement, especially when actions change state. But imagine how cool it would be to dogit annex assist --dry-run --explainand to see what exactly it would do (what files go to git, which to the annex, what files will be copied where, etc.) 🤩--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.
--explain, this will be very helpful when debugging preferred content expressions and the like. 👏--explain now also shows when numcopies is taken into account when not dropping, eg
get --auto.When dropping, git-annex already explains when numcopies is not satisfied of course. As to displaying the drop safety proof, I think it's too much in the weeds for a user to want it explained? Users probably don't want to worry about the distinction between RecentlyVerifiedCopy and LockedCopy, for example; those details are git-annex's job. It already gives a well calibrated explanation when it can't drop, so explaining when it can drop seems unncessary.
I also looked at adding it for file content checking, but inAnnex is pretty core and is used in a lot of situations where --explain output would not be useful, eg after git-annex has downloaded a file, it will check inAnnex. While it would be possible to add something that explains that is only called when deciding whether to operate on a file, that would be an intrusive code change and would add complexity.
Also, while it can be confusing to users sometimes why eg
git-annex get foodoesn't output anything due to the file being present already, it seems like adding --explain output to that would generally not be useful to more experienced users. Explain needs to remain relatively concise, or it's just more debug output.So, closing this as completed, although of course more can be added to --explain later..