Subject: bug#73232: [PATCH] Allow vc-diff to suggest a default revision in vc-dir

From: Eli Zaretskii <[email-masked]>
Date: Sat, 14 Sep 2024 10:04:27 +0300

> Date: Sat, 14 Sep 2024 04:45:42 +0300
> Cc: [email-masked], [email-masked]
> From: Dmitry Gutov <[email-masked]>
> 
> Hi Spencer,
> 
> On 13/09/2024 19:25, Spencer Baugh via Bug reports for GNU Emacs, the 
> Swiss army knife of text editors wrote:
> > Concretely this has the effect that for the vc-git and vc-hg backends,
> > running C-u M-x vc-root-diff in vc-dir will have the same behavior as
> > running C-u M-x vc-root-diff in a clean file: The "Previous revision:"
> > prompt's default will be the revision before HEAD.
> 
> Is this consistent with the current behavior with files?
> 
> I mean, if there are any uncommitted changes in a file, we suggest the 
> current revision as the one to diff against.
> 
> But with a directory we can't so easily determine whether are 
> uncommitted changes, but in all likelihood, most of the time when you're 
> working on a new feature, there would be. So statistically speaking, 
> shouldn't we default to the "file with changes" behavior, suggesting the 
> HEAD revision?
> 
> I can see where you're coming from though -- that default isn't very 
> useful, one might as well not press C-u.
> 
> Maybe we should switch to suggesting the previous revision in the prompt 
> even when file has changes?
> 
> > * lisp/vc/vc.el (vc-diff-build-argument-list-internal): Move
> > file-directory-p check. (bug#73232)
> 
> Maybe this should mention reusing the value of backend too, for 
> completeness.
> 
> Also I wonder if it's okay to have a multi-paragraph description in the 
> commit message. CONTRIBUTE seems to suggest one paragraph (if any) 
> between the summary and the ChangeLog-style contents, but it doesn't 
> suggest moving any parts of the description to the bug tracker. But IDK, 
> for those who still read the changelog files (instead of using 
> vc-print-root-log) this might be too much for a short change. The 
> detailed description is great, though, so thanks.

I've modified CONTRIBUTE to not insist on "a paragraph".  (This is
exactly why I hate to codify stuff that is usually a no-brainer:
people tend to interpret each word and letter literally, as if they
were in a legally-binding document, and there's no end to complaints
and discussions about these unimportant details.)

My POV is that the description should be as clear and concise as
possible.  In most cases, there should be a bug report for the issue,
or some on-list discussion of it, and the gory details should be
described there, with only a reference left in the log message.  And,
of course, the important stuff that explains how the code works and
why it does something non-trivial should be in comments in the code.

IOW, I consider a long and very detailed description in the log
message a clear sign that something went wrong in the process: either
we didn't have the issue discussed in a place that can be referenced,
or the code needs to be cleaned-up or commented, or something else.
Git log is NOT the best place to document code changes.

> Eli and others, what do you think?

If you are asking about this bug report, then frankly I don't
understand the use case: when would a user want to invoke this command
with point on a directory?  Directories are never important items in
VC-related activities; files are.  When I'm looking at a tree with
changes, I'm never interested with directories, only with files.  It
is not a coincidence that "git status" will never say anything about
directories; e.g., if you create a directory, you will not see it in
the status, unlike a new file.

So I think I'd need to understand better the use case before I make up
my mind about this proposal.