{"thread":{"id":"60296","subject":"[PATCH] doc/cat-file: clarify description regarding various command forms","startedAt":"2023-10-03T08:32:02Z","lastAt":"2023-10-09T20:02:54Z","messageCount":11,"participants":["Štěpán Němec","Jeff King","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"482562","messageId":"20231003082513.3003520-1-stepnem@smrk.net","threadId":"60296","inReplyTo":null,"subject":"[PATCH] doc/cat-file: clarify description regarding various command forms","fromName":"Štěpán Němec","fromEmail":"stepnem@smrk.net","sentAt":"2023-10-03T08:25:13Z","receivedAt":"2023-10-03T08:32:02Z","isPatch":true,"sender":{"key":"stepnem@smrk.net","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"The DESCRIPTION's \"first form\" is actually the 1st, 2nd, 3rd and 5th\nform in SYNOPSIS, the \"second form\" is the 4th one.\n\nInterestingly, this state of affairs was introduced in\n97fe7250753b (cat-file docs: fix SYNOPSIS and \"-h\" output, 2021-12-28)\nwith the claim of \"Now the two will match again.\" (\"the two\" being\nDESCRIPTION and SYNOPSIS)...\n\nOrdinals are hard, let's try talking about batch and non-batch mode\ninstead.\n\nSigned-off-by: Štěpán Němec \n---\n Documentation/git-cat-file.txt | 7 +++++--\n 1 file changed, 5 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt\nindex 0e4936d18263..1957f90335a4 100644\n--- a/Documentation/git-cat-file.txt\n+++ b/Documentation/git-cat-file.txt\n@@ -20,12 +20,15 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-In its first form, the command provides the content or the type of an object in\n+This command can operate in two modes, depending on whether an option from\n+the `--batch` family is specified.\n+\n+In non-batch mode, the command provides the content or the type of an object in\n the repository. The type is required unless `-t` or `-p` is used to find the\n object type, or `-s` is used to find the object size, or `--textconv` or\n `--filters` is used (which imply type \"blob\").\n \n-In the second form, a list of objects (separated by linefeeds) is provided on\n+In batch mode, a list of objects (separated by linefeeds) is provided on\n stdin, and the SHA-1, type, and size of each object is printed on stdout. The\n output format can be overridden using the optional `` argument. If\n either `--textconv` or `--filters` was specified, the input is expected to\n\nbase-commit: d0e8084c65cbf949038ae4cc344ac2c2efd77415\n-- \n2.42.0\n\n"},{"id":"482596","messageId":"20231003200659.GC1562@coredump.intra.peff.net","threadId":"60296","inReplyTo":"20231003082513.3003520-1-stepnem@smrk.net","subject":"Re: [PATCH] doc/cat-file: clarify description regarding various command forms","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-10-03T20:06:59Z","receivedAt":"2023-10-03T20:07:03Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Oct 03, 2023 at 10:25:13AM +0200, Štěpán Němec wrote:\n\n> The DESCRIPTION's \"first form\" is actually the 1st, 2nd, 3rd and 5th\n> form in SYNOPSIS, the \"second form\" is the 4th one.\n> \n> Interestingly, this state of affairs was introduced in\n> 97fe7250753b (cat-file docs: fix SYNOPSIS and \"-h\" output, 2021-12-28)\n> with the claim of \"Now the two will match again.\" (\"the two\" being\n> DESCRIPTION and SYNOPSIS)...\n> \n> Ordinals are hard, let's try talking about batch and non-batch mode\n> instead.\n\nThanks, I think this is a good direction. Two things I noticed:\n\n> DESCRIPTION\n> -----------\n> -In its first form, the command provides the content or the type of an object in\n> +This command can operate in two modes, depending on whether an option from\n> +the `--batch` family is specified.\n> +\n> +In non-batch mode, the command provides the content or the type of an object in\n> the repository. The type is required unless `-t` or `-p` is used to find the\n> object type, or `-s` is used to find the object size, or `--textconv` or\n> `--filters` is used (which imply type \"blob\").\n\nThe existing text here is already a bit vague, considering the number of\noperations it covers (like \"-e\", for example, which is not showing \"the\ncontent or the type\" at all). But that is not new in your patch, and it\nis maybe even OK to be a bit vague here, and let the OPTIONS section\ncover the specifics.\n\n> -In the second form, a list of objects (separated by linefeeds) is provided on\n> +In batch mode, a list of objects (separated by linefeeds) is provided on\n> stdin, and the SHA-1, type, and size of each object is printed on stdout. The\n> output format can be overridden using the optional `` argument. If\n> either `--textconv` or `--filters` was specified, the input is expected to\n\nI think this got a bit inaccurate with \"--batch-command\", which is a\nwhole different mode itself compared to --batch and --batch-check. I\ndon't think your patch is really making anything worse, but arguably\nthere are three \"major modes\" here.\n\n-Peff\n"},{"id":"482683","messageId":"20231005132018+0200.47596-stepnem@smrk.net","threadId":"60296","inReplyTo":"20231003200659.GC1562@coredump.intra.peff.net","subject":"Re: [PATCH] doc/cat-file: clarify description regarding various command forms","fromName":"Štěpán Němec","fromEmail":"stepnem@smrk.net","sentAt":"2023-10-05T11:20:18Z","receivedAt":"2023-10-05T14:29:38Z","isPatch":true,"sender":{"key":"stepnem@smrk.net","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"On Tue, 3 Oct 2023 16:06:59 -0400\nJeff King wrote:\n\n>> DESCRIPTION\n>> -----------\n>> -In its first form, the command provides the content or the type of an object in\n>> +This command can operate in two modes, depending on whether an option from\n>> +the `--batch` family is specified.\n>> +\n>> +In non-batch mode, the command provides the content or the type of an object in\n>> the repository. The type is required unless `-t` or `-p` is used to find the\n>> object type, or `-s` is used to find the object size, or `--textconv` or\n>> `--filters` is used (which imply type \"blob\").\n>\n> The existing text here is already a bit vague, considering the number of\n> operations it covers (like \"-e\", for example, which is not showing \"the\n> content or the type\" at all). But that is not new in your patch, and it\n> is maybe even OK to be a bit vague here, and let the OPTIONS section\n> cover the specifics.\n\nSo how about we just butcher the DESCRIPTION completely; after all, the\ninformation it gives is not quite correct (other than what you already\nmentioned, e.g., -e is omitted in the \"type not required\" part; one is\nleft to wonder what refers to: you have to go read the OPTIONS\nand BATCH OUTPUT sections anyway), and the correct parts only duplicate\ninformation given in the following sections, providing opportunities to\nbecome out of date when the command and its documentation evolve:\n\nChanges (if we agree this is the way to go, I'll also update the --help\noutput):\n synopsis:\n - move the (--textconv | --filters) form before --batch, closer\n to the other non-batch forms\n - cosmetics: swap -t and -s, --filters and --textconv (sort\n alphabetically)\n description:\n - reformulate, omit vague/imprecise information better\n provided in the detailed options list\n\nSYNOPSIS\n git cat-file \n git cat-file (-e | -p) \n git cat-file (-s | -t) [--allow-unknown-type] \n git cat-file (--filters | --textconv)\n [: | --path= ]\n git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]\n [--buffer] [--follow-symlinks] [--unordered]\n [--filters | --textconv] [-Z]\n\nDESCRIPTION\n This command can operate in two modes, depending on whether an\n option from the --batch family is specified.\n\n In non-batch mode, the command provides information on an object\n named on the command line.\n\n In batch mode, arguments are read from standard input.\n\n[That's all for a summary, read the following sections for details.]\n\n>> -In the second form, a list of objects (separated by linefeeds) is provided on\n>> +In batch mode, a list of objects (separated by linefeeds) is provided on\n>> stdin, and the SHA-1, type, and size of each object is printed on stdout. The\n>> output format can be overridden using the optional `` argument. If\n>> either `--textconv` or `--filters` was specified, the input is expected to\n>\n> I think this got a bit inaccurate with \"--batch-command\", which is a\n> whole different mode itself compared to --batch and --batch-check. I\n> don't think your patch is really making anything worse, but arguably\n> there are three \"major modes\" here.\n\nThis is not obvious to me (the \"three major modes\" part). AIUI it's\nstill mainly a batch (read from stdin) vs. non-batch (args on command\nline) dichotomy. The details differ (just args vs. command + args), but\nso does e.g. -e differ in providing information via exit code rather\nthan stdout.\n\n(But please note I'm not trying to pose as an expert here: this all\nstarted with me coming to git-cat-file(1) to _learn_ about cat-file\nand finding the description more than a little confusing.)\n\n-- \nŠtěpán\n"},{"id":"482693","messageId":"20231005171827.GC975921@coredump.intra.peff.net","threadId":"60296","inReplyTo":"20231005132018+0200.47596-stepnem@smrk.net","subject":"Re: [PATCH] doc/cat-file: clarify description regarding various command forms","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-10-05T17:18:27Z","receivedAt":"2023-10-05T17:24:31Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Oct 05, 2023 at 01:20:18PM +0200, Štěpán Němec wrote:\n\n> So how about we just butcher the DESCRIPTION completely;\n> [...]\n> DESCRIPTION\n> This command can operate in two modes, depending on whether an\n> option from the --batch family is specified.\n> \n> In non-batch mode, the command provides information on an object\n> named on the command line.\n> \n> In batch mode, arguments are read from standard input.\n> \n> [That's all for a summary, read the following sections for details.]\n\nYeah, I think that is a big improvement over the status quo. I might\nalso be worth starting with a single-sentence overview of what is common\nto both modes. Something like:\n\n Output the contents or details of one or more objects. This command\n can operate in two modes, depending on whether an option from the\n --batch family is specified.\n\n In non-batch mode, the command provides information on a single object\n given on the command line.\n\n In batch mode, arguments are read from standard input.\n\n> > I think this got a bit inaccurate with \"--batch-command\", which is a\n> > whole different mode itself compared to --batch and --batch-check. I\n> > don't think your patch is really making anything worse, but arguably\n> > there are three \"major modes\" here.\n> \n> This is not obvious to me (the \"three major modes\" part). AIUI it's\n> still mainly a batch (read from stdin) vs. non-batch (args on command\n> line) dichotomy. The details differ (just args vs. command + args), but\n> so does e.g. -e differ in providing information via exit code rather\n> than stdout.\n\nYeah, I think you understand it correctly. But what the current text\n(both before and after your proposed patch) says about batch mode is:\n\n In batch mode, a list of objects (separated by linefeeds) is provided\n on stdin, [...]\n\nwhich I think is not really true of --batch-command. But the rewrite you\nsuggest above takes care of that nicely, I think.\n\n> (But please note I'm not trying to pose as an expert here: this all\n> started with me coming to git-cat-file(1) to _learn_ about cat-file\n> and finding the description more than a little confusing.)\n\nThat is a very valuable perspective. I am probably too much an expert in\ncat-file, and it has rotted my brain. ;)\n\n-Peff\n"},{"id":"482702","messageId":"20231005194852+0200.262756-stepnem@smrk.net","threadId":"60296","inReplyTo":"20231005171827.GC975921@coredump.intra.peff.net","subject":"Re: [PATCH] doc/cat-file: clarify description regarding various command forms","fromName":"Štěpán Němec","fromEmail":"stepnem@smrk.net","sentAt":"2023-10-05T17:48:52Z","receivedAt":"2023-10-05T17:49:43Z","isPatch":true,"sender":{"key":"stepnem@smrk.net","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"On Thu, 5 Oct 2023 13:18:27 -0400\nJeff King wrote:\n\n> On Thu, Oct 05, 2023 at 01:20:18PM +0200, Štěpán Němec wrote:\n>\n>> So how about we just butcher the DESCRIPTION completely;\n>> [...]\n>> DESCRIPTION\n>> This command can operate in two modes, depending on whether an\n>> option from the --batch family is specified.\n>> \n>> In non-batch mode, the command provides information on an object\n>> named on the command line.\n>> \n>> In batch mode, arguments are read from standard input.\n>> \n>> [That's all for a summary, read the following sections for details.]\n>\n> Yeah, I think that is a big improvement over the status quo. I might\n> also be worth starting with a single-sentence overview of what is common\n> to both modes. Something like:\n>\n> Output the contents or details of one or more objects. [...]\n\nI thought about that when proposing the rewrite, but feel that it would\nagain just duplicate what's said elsewhere, in this case even before,\nnot after, in the very first line of the man page:\n\n git-cat-file - Provide content or type and size information for\n repository objects\n\n> This command can operate in two modes, depending on whether an\n> option from the --batch family is specified.\n>\n> In non-batch mode, the command provides information on a single object\n> given on the command line.\n ^^^^^\nAny particular reason you prefer \"given\" to \"named\"? However absurd a\nnotion of giving an actual object on the command line might seem, to me\n\"named\" is better in that it leaves no room for such misinterpretation.\nAnd the description in OPTIONS talks about \"ways to spell\nobject names\", building on the same concept.\n\n-- \nŠtěpán\n"},{"id":"482716","messageId":"20231005210125.GA981206@coredump.intra.peff.net","threadId":"60296","inReplyTo":"20231005194852+0200.262756-stepnem@smrk.net","subject":"Re: [PATCH] doc/cat-file: clarify description regarding various command forms","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-10-05T21:01:25Z","receivedAt":"2023-10-05T21:01:35Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Oct 05, 2023 at 07:48:52PM +0200, Štěpán Němec wrote:\n\n> > Yeah, I think that is a big improvement over the status quo. I might\n> > also be worth starting with a single-sentence overview of what is common\n> > to both modes. Something like:\n> >\n> > Output the contents or details of one or more objects. [...]\n> \n> I thought about that when proposing the rewrite, but feel that it would\n> again just duplicate what's said elsewhere, in this case even before,\n> not after, in the very first line of the man page:\n> \n> git-cat-file - Provide content or type and size information for\n> repository objects\n\nAh, true, I was thinking that the DESCRIPTION section would be the first\nthing users would read, but I didn't notice the headline. I agree that\nwhat it says is probably sufficient (though arguably \"type and size\" is\nslightly inaccurate there; I said \"details\" in my proposed text but\nmaybe that is too vague).\n\n> > This command can operate in two modes, depending on whether an\n> > option from the --batch family is specified.\n> >\n> > In non-batch mode, the command provides information on a single object\n> > given on the command line.\n> ^^^^^\n> Any particular reason you prefer \"given\" to \"named\"? However absurd a\n> notion of giving an actual object on the command line might seem, to me\n> \"named\" is better in that it leaves no room for such misinterpretation.\n> And the description in OPTIONS talks about \"ways to spell\n> object names\", building on the same concept.\n\nNope, I didn't even do that replacement consciously (I was just fleshing\nout my example, and ended up deciding nothing else needed to be\nchanged). So \"named\" is fine by me.\n\nThanks.\n\n-Peff\n"},{"id":"482850","messageId":"20231009103651+0200.580831-stepnem@smrk.net","threadId":"60296","inReplyTo":"20231005210125.GA981206@coredump.intra.peff.net","subject":"Re: [PATCH] doc/cat-file: clarify description regarding various command forms","fromName":"Štěpán Němec","fromEmail":"stepnem@smrk.net","sentAt":"2023-10-09T08:36:51Z","receivedAt":"2023-10-09T08:37:05Z","isPatch":true,"sender":{"key":"stepnem@smrk.net","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"On Thu, 5 Oct 2023 17:01:25 -0400\nJeff King wrote:\n\n> On Thu, Oct 05, 2023 at 07:48:52PM +0200, Štěpán Němec wrote:\n>\n>> > Yeah, I think that is a big improvement over the status quo. I might\n>> > also be worth starting with a single-sentence overview of what is common\n>> > to both modes. Something like:\n>> >\n>> > Output the contents or details of one or more objects. [...]\n>> \n>> I thought about that when proposing the rewrite, but feel that it would\n>> again just duplicate what's said elsewhere, in this case even before,\n>> not after, in the very first line of the man page:\n>> \n>> git-cat-file - Provide content or type and size information for\n>> repository objects\n>\n> Ah, true, I was thinking that the DESCRIPTION section would be the first\n> thing users would read, but I didn't notice the headline. I agree that\n> what it says is probably sufficient (though arguably \"type and size\" is\n> slightly inaccurate there; I said \"details\" in my proposed text but\n> maybe that is too vague).\n\nWe could also leave the NAME vague(r) and put an additional sentence at\nthe beginning of DESCRIPTION:\n\nNAME\n git-cat-file - Provide contents or details of repository objects\n\nSYNOPSIS\n [...]\n\nDESCRIPTION\n Output the contents or other properties such as size, type or delta\n information of one or more objects.\n\n The command can operate [...]\n\n-- \nŠtěpán\n"},{"id":"482866","messageId":"20231009155603.GA3251575@coredump.intra.peff.net","threadId":"60296","inReplyTo":"20231009103651+0200.580831-stepnem@smrk.net","subject":"Re: [PATCH] doc/cat-file: clarify description regarding various command forms","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-10-09T15:56:03Z","receivedAt":"2023-10-09T15:56:08Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Oct 09, 2023 at 10:36:51AM +0200, Štěpán Němec wrote:\n\n> > Ah, true, I was thinking that the DESCRIPTION section would be the first\n> > thing users would read, but I didn't notice the headline. I agree that\n> > what it says is probably sufficient (though arguably \"type and size\" is\n> > slightly inaccurate there; I said \"details\" in my proposed text but\n> > maybe that is too vague).\n> \n> We could also leave the NAME vague(r) and put an additional sentence at\n> the beginning of DESCRIPTION:\n\nYup, that is a good suggestion. Do you want to wrap all of this\ndiscussion up as a patch?\n\n-Peff\n"},{"id":"482885","messageId":"20231009175604.2361700-1-stepnem@smrk.net","threadId":"60296","inReplyTo":"20231009155603.GA3251575@coredump.intra.peff.net","subject":"[PATCH] doc/cat-file: make synopsis and description less confusing","fromName":"Štěpán Němec","fromEmail":"stepnem@smrk.net","sentAt":"2023-10-09T17:56:04Z","receivedAt":"2023-10-09T17:56:15Z","isPatch":true,"sender":{"key":"stepnem@smrk.net","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"The DESCRIPTION's \"first form\" is actually the 1st, 2nd, 3rd and 5th\nform in SYNOPSIS, the \"second form\" is the 4th one.\n\nInterestingly, this state of affairs was introduced in\n97fe7250753b (cat-file docs: fix SYNOPSIS and \"-h\" output, 2021-12-28)\nwith the claim of \"Now the two will match again.\" (\"the two\" being\nDESCRIPTION and SYNOPSIS)...\n\nThe description also suffers from other correctness and clarity issues,\ne.g., the \"first form\" paragraph discusses -p, -s and -t, but leaves out\n-e, which is included in the corresponding SYNOPSIS section; the second\nparagraph mentions , which doesn't occur in SYNOPSIS at all, and\nof the three batch options, really only describes the behavior of\n--batch-check. Also the mention of \"drivers\" seems an implementation\ndetail not adding much clarity in a short summary (and isn't expanded\nupon in the rest of the man page, either).\n\nRather than trying to maintain one-to-one (or N-to-M) correspondence\nbetween the DESCRIPTION and SYNOPSIS forms, creating duplication and\nproviding opportunities for error, shorten the former into a concise\nsummary describing the two general modes of operation: batch and\nnon-batch, leaving details to the subsequent manual sections.\n\nWhile here, fix a grammar error in the description of -e and make the\nfollowing further minor improvements:\n\n NAME:\n shorten (\"content or type and size\" isn't the whole story; say\n \"details\" and leave the actual details to later sections)\n\n SYNOPSIS and --help:\n move the (--textconv | --filters) form before --batch, closer\n to the other non-batch forms\n\nSigned-off-by: Štěpán Němec \n---\nOn Mon, 09 Oct 2023 11:56:03 -0400\nJeff King wrote:\n\n> On Mon, Oct 09, 2023 at 10:36:51AM +0200, Štěpán Němec wrote:\n>\n>> > Ah, true, I was thinking that the DESCRIPTION section would be the first\n>> > thing users would read, but I didn't notice the headline. I agree that\n>> > what it says is probably sufficient (though arguably \"type and size\" is\n>> > slightly inaccurate there; I said \"details\" in my proposed text but\n>> > maybe that is too vague).\n>> \n>> We could also leave the NAME vague(r) and put an additional sentence at\n>> the beginning of DESCRIPTION:\n>\n> Yup, that is a good suggestion. Do you want to wrap all of this\n> discussion up as a patch?\n\nCertainly, here it is. I just wanted to hash out some of the details\nfirst and found the plain text more fit for that purpose.\n\nThanks.\n\nTo anyone not following the whole thread: this is a slightly more\nambitious version of [1] (\"[PATCH] doc/cat-file: clarify description\nregarding various command forms\"), intended to supersede it.\n\n[1]\nhttps://lore.kernel.org/git/20231003082513.3003520-1-stepnem@smrk.net/\n\n Documentation/git-cat-file.txt | 30 ++++++++++++++----------------\n builtin/cat-file.c | 4 ++--\n 2 files changed, 16 insertions(+), 18 deletions(-)\n\ndiff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt\nindex 0e4936d18263..bd95a6c10a7d 100644\n--- a/Documentation/git-cat-file.txt\n+++ b/Documentation/git-cat-file.txt\n@@ -3,8 +3,7 @@ git-cat-file(1)\n \n NAME\n ----\n-git-cat-file - Provide content or type and size information for repository objects\n-\n+git-cat-file - Provide contents or details of repository objects\n \n SYNOPSIS\n --------\n@@ -12,25 +11,24 @@ SYNOPSIS\n 'git cat-file' \n 'git cat-file' (-e | -p) \n 'git cat-file' (-t | -s) [--allow-unknown-type] \n+'git cat-file' (--textconv | --filters)\n+\t [: | --path= ]\n 'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects]\n \t [--buffer] [--follow-symlinks] [--unordered]\n \t [--textconv | --filters] [-Z]\n-'git cat-file' (--textconv | --filters)\n-\t [: | --path= ]\n \n DESCRIPTION\n -----------\n-In its first form, the command provides the content or the type of an object in\n-the repository. The type is required unless `-t` or `-p` is used to find the\n-object type, or `-s` is used to find the object size, or `--textconv` or\n-`--filters` is used (which imply type \"blob\").\n+Output the contents or other properties such as size, type or delta\n+information of one or more objects.\n \n-In the second form, a list of objects (separated by linefeeds) is provided on\n-stdin, and the SHA-1, type, and size of each object is printed on stdout. The\n-output format can be overridden using the optional `` argument. If\n-either `--textconv` or `--filters` was specified, the input is expected to\n-list the object names followed by the path name, separated by a single\n-whitespace, so that the appropriate drivers can be determined.\n+This command can operate in two modes, depending on whether an option\n+from the `--batch` family is specified.\n+\n+In non-batch mode, the command provides information on an object\n+named on the command line.\n+\n+In batch mode, arguments are read from standard input.\n \n OPTIONS\n -------\n@@ -51,8 +49,8 @@ OPTIONS\n \n -e::\n \tExit with zero status if `` exists and is a valid\n-\tobject. If `` is of an invalid format exit with non-zero and\n-\temits an error on stderr.\n+\tobject. If `` is of an invalid format, exit with non-zero\n+\tstatus and emit an error on stderr.\n \n -p::\n \tPretty-print the contents of `` based on its type.\ndiff --git a/builtin/cat-file.c b/builtin/cat-file.c\nindex 694c8538df2f..ea8ad601ecc0 100644\n--- a/builtin/cat-file.c\n+++ b/builtin/cat-file.c\n@@ -922,11 +922,11 @@ int cmd_cat_file(int argc, const char **argv, const char *prefix)\n \t\tN_(\"git cat-file \"),\n \t\tN_(\"git cat-file (-e | -p) \"),\n \t\tN_(\"git cat-file (-t | -s) [--allow-unknown-type] \"),\n+\t\tN_(\"git cat-file (--textconv | --filters)\\n\"\n+\t\t \" [: | --path= ]\"),\n \t\tN_(\"git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]\\n\"\n \t\t \" [--buffer] [--follow-symlinks] [--unordered]\\n\"\n \t\t \" [--textconv | --filters] [-Z]\"),\n-\t\tN_(\"git cat-file (--textconv | --filters)\\n\"\n-\t\t \" [: | --path= ]\"),\n \t\tNULL\n \t};\n \tconst struct option options[] = {\n\nbase-commit: 3a06386e314565108ad56a9bdb8f7b80ac52fb69\n-- \n2.42.0\n\n"},{"id":"482892","messageId":"20231009183352.GA3270793@coredump.intra.peff.net","threadId":"60296","inReplyTo":"20231009175604.2361700-1-stepnem@smrk.net","subject":"Re: [PATCH] doc/cat-file: make synopsis and description less confusing","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-10-09T18:33:52Z","receivedAt":"2023-10-09T18:34:01Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Oct 09, 2023 at 07:56:04PM +0200, Štěpán Němec wrote:\n\n> > Yup, that is a good suggestion. Do you want to wrap all of this\n> > discussion up as a patch?\n> \n> Certainly, here it is. I just wanted to hash out some of the details\n> first and found the plain text more fit for that purpose.\n\nThis looks good to me. Thanks for taking the time to collect and fix all\nof the issues.\n\n-Peff\n"},{"id":"482900","messageId":"xmqqil7fy36j.fsf@gitster.g","threadId":"60296","inReplyTo":"20231009183352.GA3270793@coredump.intra.peff.net","subject":"Re: [PATCH] doc/cat-file: make synopsis and description less confusing","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-09T20:02:44Z","receivedAt":"2023-10-09T20:02:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Mon, Oct 09, 2023 at 07:56:04PM +0200, Štěpán Němec wrote:\n>\n>> > Yup, that is a good suggestion. Do you want to wrap all of this\n>> > discussion up as a patch?\n>> \n>> Certainly, here it is. I just wanted to hash out some of the details\n>> first and found the plain text more fit for that purpose.\n>\n> This looks good to me. Thanks for taking the time to collect and fix all\n> of the issues.\n>\n> -Peff\n\nThanks, both. Will take a look.\n"}]}