On Mon, Jul 18 2022, Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> 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?
