(I agree with Junio's reply to your message, so here I'm just going to
address the things that Junio didn't.)
I'll preface all this by restating my original point: If you really want
to implement this feature as a new command, please don't use "blame" in
that new command's name.
On 2025-05-14 10:42, Toon Claes wrote:
Personally I don't like the idea of the DWIM approach. I rather keep
following the UNIX philosophy and having each command do one thing well.
I think it weird to change behavior based on context.
You said earlier in this thread:
This distinction brings up a wrinkle in my proposed DWIMery: should
git blame path/to/file
show the annotated blamed lines of the file, or simply display the last
commit that changed the file?
For me this gives good motivation to not mix behavior of file-level and
line-level blames into a single command. If behavior in ambiguous, we
should avoid it.
The behavior is not ambiguous at all, it's simply context-dependent.
Like with "git add": We don't have "git add-tree" to add a directory of
files. Adding is adding, and so we make the "add" command handle all
types of adding.
Similarly, we don't need "blame-tree" to annotate a directory. Just
because annotating a single file has different output from annotating a
tree of files doesn't mean that we need two different verbs to annotate
either kind of object.
I can appreciate the convenience of being able to do that with "git
blame". I suggest adding an option for this specific case, like maybe
"--latest" (I don't feel strongly about the option's name).
What makes `git blame --latest` better than `git blame-tree`?
If a user wants to blame/annotate something -- a tree or a file -- it's
much easier for them to just use one command to blame whatever they
want. No need to discover a different command and read a whole new man
page to figure it out.
And all the people who already know about "git blame" get new and useful
behavior from their familiar command. They are much more likely to
discover that when it's built into "git blame" than if the new feature
is hiding under a different command.
Also, people who tab-complete commands will appreciate that
git bl<tab>
continues to complete to "git blame " instead of "git blame". (You
could argue that this is one way people might discover blame-tree, but I
think messing with completionists' muscle-memory is going to annoy them
more than help them.)
I agree that blaming is a well-(known) concept. I also agree that most
users would understand what blame-tree would do, *once they find it*.
I'm also not convinced why a option argument to an existing command
would be easier to discover than a new command. I think it's more an
issue of us advertising features, than commands being discoverable on
it's own.
Extending an existing command is an incremental way of making things
better for all the people who are already using that command. They are
more likely to discover the new behavior, either by spotting it when
they're checking the man page or, in this case, by accidentally passing
a directory to "git blame".
Hiding this in a new command makes it much less likely to be discovered
by current Git users.
Yes, it is an advertising issue. I don't consider Git to be a gold
standard for feature discoverability. So I don't think that simply
saying it's more of an advertising problem gets us anywhere, because so
far Git has failed miserably at advertising its commands.
Also, I think sacrificing usability because it makes the coding hard is
unfortunate.
Agreed, that was not a good motivation from my side to make.
I wrote:
Forgive me, but I think folding into git-blame(1) will also solidify
Git's reputation of obscurity.
Please elaborate.
As I mentioned above, I think having behavior of git-blame(1) depend on
the type of the argument (is it a dir or a file) is rather obscure.
I don't buy that. Many Unix commands give different outputs when run
against a file vs. a directory (try diff, for example). Even simple
things like "ls" will show a single line of output for a file but
multiple lines for a directory. You can argue that one line vs. many
isn't a drastic difference, but it *is* a difference. And there's a
reason why it's "ls -R" instead of "ls-tree": Listing is listing, so
"ls" fulfills all your listing needs.
The format of the output returned will be drastically different in both
cases, and having to machine-parse this might be tricky.
Machine-parsing output is a strawman.
First of all, even though "blame" is considered an ancillary command and
not officially listed as porcelain, it's also not plumbing and so it has
no obligation to make machines' lives easier.
Second, why do you think a script needs to parse both output formats?
Even if there are reasons to write such a script, how does having two
commands for the different formats help? Either way such a script's
author needs to deal with both formats. Furthermore, if I was
maintaining a script that already understands how to parse single-file
annotation:
git blame path/to/file | my-script
I would be quite happy for it to die horribly if someone ran it on the
output of a tree annotation.
As you say, in that pipe example teaching my-script how to tell what
kind of output it's receiving could be tricky. But I doubt that many
existing scripts that parse blame output are implemented as
pipe-readers. Rather, I think (yes, without any evidence) that most
script authors run the blame command directly as part of their script
and so they'll know what kind of output the command they're running will
generate (since they'll know what kind of arguments they're passing to
the commmand).
Folks who really need to write a pipe-reader can just teach their script
an argument identifying the kind of output to expect. Much easier, and
more robust, than making the code figure it out. Pipe-reading scripts
will need figure out something like this regardless of how we resolve
this discussion.
M.
