Re: [PATCH RFC 0/5] Introduce git-blame-tree(1) command

(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:

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.

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.)

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.

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.

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.