| Message ID | patch-v4-2.8-883c483d4e7-20220718T132911Z-avarab@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | git doc + "git help": move "format" docs from technical/* | expand |
Ævar Arnfjörð Bjarmason <avarab@gmail.com> 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. 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. > -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>. > @@ -26,8 +27,8 @@ printed on the standard output. > If the option `--guides` or `-g` is given, a list of the > Git concept guides is also printed on the standard output. > > -If a command, or a guide, is given, a manual page for that command or > -guide is brought up. The 'man' program is used by default for this > +If a command or other documentation is given, the relevant manual page > +will be brought up. The 'man' program is used by default for this Good.
On Mon, Jul 18 2022, Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@gmail.com> 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?
Ævar Arnfjörð Bjarmason <avarab@gmail.com> 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. > 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? I think <doc> is very good, much better than <name>, here.
On Tue, Jul 19 2022, Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@gmail.com> 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....
diff --git a/Documentation/Makefile b/Documentation/Makefile index 4f801f4e4c9..08b896a3c4c 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ cmds-synchingrepositories.txt \ cmds-synchelpers.txt \ cmds-guide.txt \ + cmds-userformats.txt \ cmds-purehelpers.txt \ cmds-foreignscminterface.txt diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 239c68db457..6c285709040 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -9,14 +9,15 @@ SYNOPSIS -------- [verse] 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases] -'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>] +'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>|<doc>] 'git help' [-g|--guides] 'git help' [-c|--config] +'git help' [--user-formats] DESCRIPTION ----------- -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' command and a list of the most commonly used Git commands are printed on the standard output. @@ -26,8 +27,8 @@ printed on the standard output. If the option `--guides` or `-g` is given, a list of the Git concept guides is also printed on the standard output. -If a command, or a guide, is given, a manual page for that command or -guide is brought up. The 'man' program is used by default for this +If a command or other documentation is given, the relevant manual page +will be brought up. The 'man' program is used by default for this purpose, but this can be overridden by other options or configuration variables. @@ -69,6 +70,10 @@ OPTIONS --guides:: Prints a list of the Git concept guides on the standard output. +--user-formats:: + Prints a list of the Git user-facing format documentation on + the standard output. + -i:: --info:: Display manual page for the command in the 'info' format. The diff --git a/Documentation/git.txt b/Documentation/git.txt index 302607a4967..9b03bbc3851 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -339,6 +339,13 @@ The following documentation pages are guides about Git concepts. include::cmds-guide.txt[] +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'. + +include::cmds-userformats.txt[] Configuration Mechanism ----------------------- diff --git a/Makefile b/Makefile index 04d0fd1fe60..e24db1d52e2 100644 --- a/Makefile +++ b/Makefile @@ -3489,6 +3489,7 @@ check-docs:: sed -e '1,/^### command list/d' \ -e '/^#/d' \ -e '/guide$$/d' \ + -e '/formats$$/d' \ -e 's/[ ].*//' \ -e 's/^/listed /' command-list.txt; \ $(MAKE) -C Documentation print-man1 | \ diff --git a/builtin/help.c b/builtin/help.c index 222f994f863..b0164b774c2 100644 --- a/builtin/help.c +++ b/builtin/help.c @@ -43,6 +43,7 @@ static enum help_action { HELP_ACTION_ALL = 1, HELP_ACTION_GUIDES, HELP_ACTION_CONFIG, + HELP_ACTION_USER_FORMATS, HELP_ACTION_CONFIG_FOR_COMPLETION, HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION, } cmd_mode; @@ -69,6 +70,8 @@ static struct option builtin_help_options[] = { OPT_CMDMODE('g', "guides", &cmd_mode, N_("print list of useful guides"), HELP_ACTION_GUIDES), + OPT_CMDMODE(0, "user-formats", &cmd_mode, N_("print list of user-facing file formats"), + HELP_ACTION_USER_FORMATS), OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"), HELP_ACTION_CONFIG), OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "", @@ -81,9 +84,10 @@ static struct option builtin_help_options[] = { static const char * const builtin_help_usage[] = { "git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]", - N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>]"), + N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"), "git help [-g|--guides]", "git help [-c|--config]", + "git help [--user-formats]", NULL }; @@ -654,6 +658,10 @@ int cmd_help(int argc, const char **argv, const char *prefix) opt_mode_usage(argc, "--config-for-completion", help_format); list_config_help(SHOW_CONFIG_VARS); return 0; + case HELP_ACTION_USER_FORMATS: + opt_mode_usage(argc, "--user-formats", help_format); + list_user_formats_help(); + return 0; case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION: opt_mode_usage(argc, "--config-sections-for-completion", help_format); diff --git a/command-list.txt b/command-list.txt index 9bd6f3c48f4..c1eace8f7ad 100644 --- a/command-list.txt +++ b/command-list.txt @@ -43,6 +43,10 @@ # specified here, which can only have "guide" attribute and nothing # else. # +# User-facing file formats such as documentation for the .gitmodules, +# .mailmap etc. files lives in man section 5. These entries can only +# have the "userformats" attribute and nothing else. +# ### command list (do not change this line) # command name category [category] [category] git-add mainporcelain worktree @@ -192,7 +196,7 @@ git-verify-tag ancillaryinterrogators git-whatchanged ancillaryinterrogators complete git-worktree mainporcelain git-write-tree plumbingmanipulators -gitattributes guide +gitattributes userformats gitcli guide gitcore-tutorial guide gitcredentials guide @@ -201,14 +205,14 @@ gitdiffcore guide giteveryday guide gitfaq guide gitglossary guide -githooks guide -gitignore guide +githooks userformats +gitignore userformats gitk mainporcelain -gitmailmap guide -gitmodules guide +gitmailmap userformats +gitmodules userformats gitnamespaces guide gitremote-helpers guide -gitrepository-layout guide +gitrepository-layout userformats gitrevisions guide gitsubmodules guide gittutorial guide diff --git a/help.c b/help.c index 24ac50f62fe..17ba210cf4e 100644 --- a/help.c +++ b/help.c @@ -38,6 +38,7 @@ static struct category_description main_categories[] = { { CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") }, { CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") }, { CAT_purehelpers, N_("Low-level Commands / Internal Helpers") }, + { CAT_userformats, N_("Git user-facing file formats") }, { 0, NULL } }; @@ -50,6 +51,7 @@ static const char *drop_prefix(const char *name, uint32_t category) switch (category) { case CAT_guide: + case CAT_userformats: if (!skip_prefix(name, "git", &new_name)) BUG("category #%d but no 'git' prefix?", category); return new_name; @@ -430,6 +432,16 @@ void list_guides_help(void) putchar('\n'); } +void list_user_formats_help(void) +{ + struct category_description catdesc[] = { + { CAT_userformats, N_("Git user-facing file formats:") }, + { 0, NULL } + }; + print_cmd_by_category(catdesc, NULL); + putchar('\n'); +} + static int get_alias(const char *var, const char *value, void *data) { struct string_list *list = data; diff --git a/help.h b/help.h index 971a3ad855a..d8b744178ec 100644 --- a/help.h +++ b/help.h @@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num) void list_common_cmds_help(void); void list_all_cmds_help(int show_external_commands, int show_aliases); void list_guides_help(void); +void list_user_formats_help(void); void list_all_main_cmds(struct string_list *list); void list_all_other_cmds(struct string_list *list); diff --git a/t/t0012-help.sh b/t/t0012-help.sh index 6c33a436901..91b5318aa32 100755 --- a/t/t0012-help.sh +++ b/t/t0012-help.sh @@ -44,6 +44,8 @@ test_expect_success 'invalid usage' ' test_expect_code 129 git help -g add && test_expect_code 129 git help -a -g && + test_expect_code 129 git help --user-formats add && + test_expect_code 129 git help -g -c && test_expect_code 129 git help --config-for-completion add && test_expect_code 129 git help --config-sections-for-completion add @@ -104,9 +106,9 @@ test_expect_success 'git help' ' test_i18ngrep "^ commit " help.output && test_i18ngrep "^ fetch " help.output ' + test_expect_success 'git help -g' ' git help -g >help.output && - test_i18ngrep "^ attributes " help.output && test_i18ngrep "^ everyday " help.output && test_i18ngrep "^ tutorial " help.output ' @@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' ' test_cmp expect test-browser.log ' +test_expect_success 'git help --user-formats' ' + git help --user-formats >help.output && + grep "^ attributes " help.output && + grep "^ mailmap " help.output +' + test_expect_success 'git help -c' ' git help -c >help.output && cat >expect <<-\EOF && @@ -220,6 +228,8 @@ test_expect_success "'git help -a' section spacing" ' Low-level Commands / Syncing Repositories Low-level Commands / Internal Helpers + + Git user-facing file formats EOF test_cmp expect actual '
Create a new "User-facing file formats" section in the main "git help git" manual page. The "Guides" section was added to the manual page in f442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense to list all that documentation. But placing e.g. "gitignore(5)" in it is stretching the meaning of what a "guide" is, ideally that section should list things similar to "giteveryday(7)" and "gitcore-tutorial(7)". 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. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> --- Documentation/Makefile | 1 + Documentation/git-help.txt | 13 +++++++++---- Documentation/git.txt | 7 +++++++ Makefile | 1 + builtin/help.c | 10 +++++++++- command-list.txt | 16 ++++++++++------ help.c | 12 ++++++++++++ help.h | 1 + t/t0012-help.sh | 12 +++++++++++- 9 files changed, 61 insertions(+), 12 deletions(-)