Subject: Re: [PATCH v4 2/8] git docs: split "User-facing file formats" off from "Guides"

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Mon, 18 Jul 2022 20:41:39 +0200

On Mon, Jul 18 2022, Junio C Hamano wrote:

> Ævar Arnfjörð Bjarmason  <[email-masked]> writes:
>
>> We take a wide view of what's considered a "user format", it's not
>> just a file format, but e.g. githooks(5) also belongs, since the
>> layout of the ".git/hooks/" and the placement of hooks in it is
>> something the user might be expected to interact with.
>
> I am afraid it is a bit big a stretch.  Other documents that fall
> into the user-format category all have "format" the users must
> follow while writing the "contents" in the file.  ".gitignore" has
> certain format and syntax and the document describes what effect the
> file has, based on the contents of the file that follows the syntax.
>
> A hook can be written in any language, even though our UNIX lineage
> makes our samples all in written in the shell, so there is no
> "format" for the users to follow that we should force upon them.

The "format" I have in mind is the "shape" of the configuration,
i.e. that a hook goes in .git/hooks/<name>, not the contents of that
<name> itself.

So it's introducing a bit of a neologism, but I couldn't think of a
better one. Suggestions welcome. There is "gitrepository-layout(5)", but
calling this a "layout" seems odd.

I do think that things that users are expected to interact with on a
file-level (gitignore, gitmailmap etc.) and on the FS arrange in such a
way as to interact with git (gitignore) belong together under one hat.

So it's not perfect, but I think it sucks less than calling both
"gitmodules" and "giteverday" a "guide", which is the status quo.

> If we can come up with a word that is more appropriate than
> "format", it would be great.  If we do not place too much emphasis
> on "format", I agree that both "gitignore" and "githook" fall into
> the same category, because they define how the contents written in
> these files affect the operation of Git commands.

*nod*, another word would be most welcome :)

I do think that if we have --user-formats or --user-X it makes sense to
have to have that match the --git-X. I.e. the "format" of say the
commit-graph includes how we arrange those files on disk, just as is the
case with the hoks.

>> -With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
>> +With no options and no '<command>', '<guide>' or '<doc>' given, the synopsis of the 'git'
>
> At some point, we will have enough <doc> that it would probably
> become meaningless to treat <guide> as a separate class, no?
> Guides, user-supplied customization files, and implementation
> details of on-disk files that may help reimplementations of Git, all
> will become <doc>.

Maybe I should just use <name> here?