From: Junio C Hamano <gitster@pobox•com>
To: "ahmed akef via GitGitGadget" <gitgitgadget@gmail•com>
Cc: git@vger•kernel.org, ahmed akef <aemed.akef.1@gmail•com>
Subject: Re: [PATCH v2] docs: explain the order of output in the batched mode of git-cat-file(1)
Date: Wed, 21 Aug 2024 10:19:14 -0700 [thread overview]
Message-ID: <xmqqa5h5ztd9.fsf@gitster.g> (raw)
In-Reply-To: <pull.1768.v2.git.git.1724234729288.gitgitgadget@gmail.com> (ahmed akef via GitGitGadget's message of "Wed, 21 Aug 2024 10:05:29 +0000")
"ahmed akef via GitGitGadget" <gitgitgadget@gmail•com> writes:
> If `--batch` or `--batch-check` is given, `cat-file` will read objects
> -from stdin, one per line, and print information about them. By default,
> -the whole line is considered as an object, as if it were fed to
> -linkgit:git-rev-parse[1].
> +from stdin, one per line, and print information about them in the same
> +order as they have been read from stdin. By default, the whole line is
> +considered as an object, as if it were fed to linkgit:git-rev-parse[1].
A few "Huh?" I had while reading the above.
* "as they have been read from stdin"; drop "from stdin" here, as
we already know we are talking about the mode that reads object
names from the standard input and there is no need to repeat it.
* "considered as an object" -> "considered to be an object name" or
"used as an object name" [*]. This primarily comes from my
spinal reflex against "consider as", plus my desire to be more
precise in terminology.
Thanks.
Nothing mentioned below should be part of this patch, but as I
noticed it while studying the current documentation to prepare this
review, I'll record them as #leftoverbits.
The description of how lines read from the standard input should
look like needs more work. Documentation on "--batch" says "the
input lines must specify the path, separated by whitespace", but is
it clear that it expects "<object name>", followed by a whitespace
(not necessarily a single SP), followed by "<path>"? Without prior
knowledge, I wouldn't be surprised if somebody read the text as
asking for paths separated by whitespace, e.g.
README.txt COPYING Makefile
that gives three paths. The text needs to be tightened to say
something like "must give the path after the object name, separated
by whitespace. The path is used to find the textconv and smudge
filter".
The section also says "See the section BATCH OUTPUT below for
details." but the section it refers to does not talk anything about
this whitespace thing. It also is unclear what would happen if the
input line says:
:COPYING Makefile
Would it apply the textconv/filters meant for Makefile to the blob
stored at COPYING in the index? If we say
:README.txt
would the command be smart enough to know that the blob came from
the path README.txt and apply the textconv/filters meant for that
path, without the input repeating the same information twice like:
:README.txt README.txt
or something silly like that?
[Reference]
* https://www.britannica.com/dictionary/eb/qa/consider-and-consider-as
next prev parent reply other threads:[~2024-08-21 17:19 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-08-21 9:28 [PATCH] docs: explain the order of output in the batched mode of git-cat-file(1) ahmed akef via GitGitGadget
2024-08-21 10:05 ` [PATCH v2] " ahmed akef via GitGitGadget
2024-08-21 17:19 ` Junio C Hamano [this message]
[not found] ` <CAH64z8+dScuQbvu1aHnodE7VpCvgU2djbJhQDff76iyeFtpdTw@mail.gmail.com>
[not found] ` <CAH64z8KUWSNii_U5k5fAz3q9cu34+pOWk2Rmw-60x7iOKOD8gQ@mail.gmail.com>
2024-08-22 7:31 ` Ahmed Akef
2024-08-22 15:07 ` Junio C Hamano
2024-08-22 19:50 ` [PATCH v3] " ahmed akef via GitGitGadget
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqa5h5ztd9.fsf@gitster.g \
--to=gitster@pobox$(echo .)com \
--cc=aemed.akef.1@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox