On Thu, Oct 05, 2023 at 01:20:18PM +0200, Štěpán Němec wrote: > So how about we just butcher the DESCRIPTION completely; > [...] > DESCRIPTION > This command can operate in two modes, depending on whether an > option from the --batch family is specified. > > In non-batch mode, the command provides information on an object > named on the command line. > > In batch mode, arguments are read from standard input. > > [That's all for a summary, read the following sections for details.] Yeah, I think that is a big improvement over the status quo. I might also be worth starting with a single-sentence overview of what is common to both modes. Something like: Output the contents or details of one or more objects. This command can operate in two modes, depending on whether an option from the --batch family is specified. In non-batch mode, the command provides information on a single object given on the command line. In batch mode, arguments are read from standard input. > > I think this got a bit inaccurate with "--batch-command", which is a > > whole different mode itself compared to --batch and --batch-check. I > > don't think your patch is really making anything worse, but arguably > > there are three "major modes" here. > > This is not obvious to me (the "three major modes" part). AIUI it's > still mainly a batch (read from stdin) vs. non-batch (args on command > line) dichotomy. The details differ (just args vs. command + args), but > so does e.g. -e differ in providing information via exit code rather > than stdout. Yeah, I think you understand it correctly. But what the current text (both before and after your proposed patch) says about batch mode is: In batch mode, a list of objects (separated by linefeeds) is provided on stdin, [...] which I think is not really true of --batch-command. But the rewrite you suggest above takes care of that nicely, I think. > (But please note I'm not trying to pose as an expert here: this all > started with me coming to git-cat-file(1) to _learn_ about cat-file > and finding the description more than a little confusing.) That is a very valuable perspective. I am probably too much an expert in cat-file, and it has rotted my brain. ;) -Peff
