On Tue, Jul 19 2022, Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> writes: > >>> 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 :) > > True. What I am absolutely sure about is that the word is not > "format" X-<. It is the interface end-users interact with internals > of Git, with need similar to how "plugin" interfaces need to have > documentation for their users. My goal here is just to make this part of our documentation more accessible, so I don't care about the term. But this series also seems blocked on you not liking the term, so... A few ways I can think of to go forward: 1. Use "format", but explain that we're using it loosely. Perhaps with this on top? diff --git a/Documentation/git.txt b/Documentation/git.txt index 1980a0e29cd..9f8d7a3543e 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -343,7 +343,10 @@ User-facing file formats ------------------------ This documentation discusses file formats that users are expected to -edit. These can also be listed with 'git help --user-formats'. +edit. "Format" here refers more broadly to files and/or file contents +that the user is expected to edit or know about. + +These can also be listed with 'git help --user-formats'. include::cmds-userformats.txt[] 2. I could submit this without the "git help --user-formats" change for now, and just focus on --git-formats: Internal file formats and protocols: format-bundle The bundle file format format-chunk Chunk-based file formats format-commit-graph Git commit graph format format-index Git index format format-multi-pack-index The multi-pack-index file format format-pack Git pack format format-pack-cruft The cruft pack file format format-pack-protocol How packs are transferred over-the-wire format-protocol-capabilities Protocol v0 and v1 capabilities format-protocol-common Things common to various protocols format-protocol-http Git HTTP-based protocols format-protocol-v2 Git Wire Protocol, Version 2 format-signature Git cryptographic signature formats Do you have an objection to any of those being labeled "format"? I understood your comments above to not include those, i.e. that you took objection to githooks(5) in particular being in that new --user-formats category. 3. A re-roll of this series pretty much as-is (sans other fixes), but remove "githooks" from this re-categorization. 4. Come up with s/format/<something>/g, but I have no idea what that "something" would be. "Protocol?", After all a secret handshake is also a protocol....
