Re: [PATCH] doc/cat-file: clarify description regarding various command forms

From: Jeff King <peff@peff.net>
Date: Oct 5, 2023, 17:18 UTC
Message-ID: <20231005171827.GC975921@coredump.intra.peff.net>
In-Reply-To: <20231005132018+0200.47596-stepnem@smrk.net>

On Thu, Oct 05, 2023 at 01:20:18PM +0200, Štěpán Němec wrote:

Show 12 quoted lines

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

Show 10 quoted lines

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