{"thread":{"id":"56715","subject":"[PATCH 1/2] git(1) docs: split \"User-facing file formats\" off from \"Guides\"","startedAt":"2021-10-15T02:05:42Z","lastAt":"2022-11-22T00:36:22Z","messageCount":112,"participants":["Ævar Arnfjörð Bjarmason","Eric Sunshine","Junio C Hamano","SZEDER Gábor","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"438806","messageId":"patch-1.2-19a8be1fc73-20211015T020351Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-0.2-00000000000-20211015T020351Z-avarab@gmail.com","subject":"[PATCH 1/2] git(1) docs: split \"User-facing file formats\" off from \"Guides\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-10-15T02:05:19Z","receivedAt":"2021-10-15T02:05:42Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"User-facing file formats\" section in the main \"git(1)\"\nmanual page. The \"Guides\" section was added to the manual page in\nf442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense\nto list all that documentation.\n\nBut placing e.g. \"gitignore(5)\" in it is stretching the meaning of\nwhat a \"guide\" is, ideally that section should list things similar to\n\"giteveryday(7)\" and \"gitcore-tutorial(7)\".\n\nWe take a wide view of what's considered a \"user format\", it's not\njust a file format, but e.g. githooks(5) also belongs, since the\nlayout of the \".git/hooks/\" and the placement of hooks in it is\nsomething the user might be expected to interact with.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-help.txt | 11 ++++++++---\n Documentation/git.txt | 7 +++++++\n Makefile | 1 +\n builtin/help.c | 8 ++++++++\n command-list.txt | 16 ++++++++++------\n help.c | 11 +++++++++++\n help.h | 1 +\n t/t0012-help.sh | 16 +++++++++++++++-\n 9 files changed, 62 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 2021568cd5a..8efed2e23e1 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -311,6 +311,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchingrepositories.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n+\tcmds-userformats.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\n \ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 96d5f598b4b..d47feca0d29 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -12,11 +12,12 @@ SYNOPSIS\n \t [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n+'git help' [--user-formats]\n \n DESCRIPTION\n -----------\n \n-With no options and no COMMAND or GUIDE given, the synopsis of the 'git'\n+With no options and no COMMAND or DOC given, the synopsis of the 'git'\n command and a list of the most commonly used Git commands are printed\n on the standard output.\n \n@@ -26,8 +27,8 @@ printed on the standard output.\n If the option `--guides` or `-g` is given, a list of the\n Git concept guides is also printed on the standard output.\n \n-If a command, or a guide, is given, a manual page for that command or\n-guide is brought up. The 'man' program is used by default for this\n+If a command or other documentation is given, the relevant manual page\n+will be brought up. The 'man' program is used by default for this\n purpose, but this can be overridden by other options or configuration\n variables.\n \n@@ -62,6 +63,10 @@ OPTIONS\n --guides::\n \tPrints a list of the Git concept guides on the standard output.\n \n+--user-formats::\n+\tPrints a list of the Git user-facing format documentation on\n+\tthe standard output.\n+\n -i::\n --info::\n \tDisplay manual page for the command in the 'info' format. The\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex d63c65e67d8..823977595c5 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -337,6 +337,13 @@ The following documentation pages are guides about Git concepts.\n \n include::cmds-guide.txt[]\n \n+User-facing file formats\n+------------------------\n+\n+This documentation discusses file formats that users are expected to\n+edit. These can also be listed with 'git help --user-formats'.\n+\n+include::cmds-userformats.txt[]\n \n Configuration Mechanism\n -----------------------\ndiff --git a/Makefile b/Makefile\nindex 060a8c46475..3956ed4b291 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -3312,6 +3312,7 @@ check-docs::\n \t\tsed -e '1,/^### command list/d' \\\n \t\t -e '/^#/d' \\\n \t\t -e '/guide$$/d' \\\n+\t\t -e '/formats$$/d' \\\n \t\t -e 's/[ \t].*//' \\\n \t\t -e 's/^/listed /' command-list.txt; \\\n \t\t$(MAKE) -C Documentation print-man1 | \\\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 75cd2fb407f..5e842ea5a26 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -43,6 +43,7 @@ static enum help_action {\n \tHELP_ACTION_ALL = 1,\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n+\tHELP_ACTION_USER_FORMATS,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -64,6 +65,8 @@ static struct option builtin_help_options[] = {\n \n \tOPT_CMDMODE('g', \"guides\", &cmd_mode, N_(\"print list of useful guides\"),\n \t\t HELP_ACTION_GUIDES),\n+\tOPT_CMDMODE(0, \"user-formats\", &cmd_mode, N_(\"print list of user-facing file formats\"),\n+\t\t HELP_ACTION_USER_FORMATS),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -79,6 +82,7 @@ static const char * const builtin_help_usage[] = {\n \t \" [[-i|--info] [-m|--man] [-w|--web]] []\"),\n \tN_(\"git help [-g|--guides]\"),\n \tN_(\"git help [-c|--config]\"),\n+\tN_(\"git help [--user-formats]\"),\n \tNULL\n };\n \n@@ -613,6 +617,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\tno_extra_argc(argc);\n \t\tlist_config_help(SHOW_CONFIG_VARS);\n \t\treturn 0;\n+\tcase HELP_ACTION_USER_FORMATS:\n+\t\tno_extra_argc(argc);\n+\t\tlist_user_formats_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\tno_extra_argc(argc);\n \t\tlist_config_help(SHOW_CONFIG_SECTIONS);\ndiff --git a/command-list.txt b/command-list.txt\nindex a289f09ed6f..5732ea437a8 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -43,6 +43,10 @@\n # specified here, which can only have \"guide\" attribute and nothing\n # else.\n #\n+# User-facing file formats such as documentation for the .gitmodules,\n+# .mailmap etc. files lives in man section 5. These entries can only\n+# have the \"userformats\" attribute and nothing else.\n+#\n ### command list (do not change this line, also do not change alignment)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -193,7 +197,7 @@ gitweb ancillaryinterrogators\n git-whatchanged ancillaryinterrogators complete\n git-worktree mainporcelain\n git-write-tree plumbingmanipulators\n-gitattributes guide\n+gitattributes userformats\n gitcli guide\n gitcore-tutorial guide\n gitcredentials guide\n@@ -202,13 +206,13 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitglossary guide\n-githooks guide\n-gitignore guide\n-gitmailmap guide\n-gitmodules guide\n+githooks userformats\n+gitignore userformats\n+gitmailmap userformats\n+gitmodules userformats\n gitnamespaces guide\n gitremote-helpers guide\n-gitrepository-layout guide\n+gitrepository-layout userformats\n gitrevisions guide\n gitsubmodules guide\n gittutorial-2 guide\ndiff --git a/help.c b/help.c\nindex 973e47cdc30..a7b5c909056 100644\n--- a/help.c\n+++ b/help.c\n@@ -37,6 +37,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_plumbinginterrogators, N_(\"Low-level Commands / Interrogators\") },\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n+\t{ CAT_userformats, N_(\"User-facing file formats\") },\n \t{ 0, NULL }\n };\n \n@@ -422,6 +423,16 @@ void list_guides_help(void)\n \tputchar('\\n');\n }\n \n+void list_user_formats_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_userformats, N_(\"The user-facing file formats are:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex 9d383f1a0b2..d01908078dc 100644\n--- a/help.h\n+++ b/help.h\n@@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num)\n void list_common_cmds_help(void);\n void list_all_cmds_help(void);\n void list_guides_help(void);\n+void list_user_formats_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex 91b68c74a15..6a20a7303f8 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -41,6 +41,8 @@ test_expect_success 'invalid usage' '\n \ttest_expect_code 129 git help -g add &&\n \ttest_expect_code 129 git help -a -g &&\n \n+\ttest_expect_code 129 git help --user-formats add &&\n+\n \ttest_expect_code 129 git help -g -c &&\n \ttest_expect_code 129 git help --config-for-completion add &&\n \ttest_expect_code 129 git help --config-sections-for-completion add\n@@ -78,9 +80,15 @@ test_expect_success 'git help' '\n \ttest_i18ngrep \"^ commit \" help.output &&\n \ttest_i18ngrep \"^ fetch \" help.output\n '\n+\n+test_expect_success 'git help -a' '\n+\tgit help -a >help.output &&\n+\tgrep \"^Main Porcelain Commands\" help.output &&\n+\tgrep \"^User-facing file formats\" help.output\n+'\n+\n test_expect_success 'git help -g' '\n \tgit help -g >help.output &&\n-\ttest_i18ngrep \"^ attributes \" help.output &&\n \ttest_i18ngrep \"^ everyday \" help.output &&\n \ttest_i18ngrep \"^ tutorial \" help.output\n '\n@@ -101,6 +109,12 @@ test_expect_success 'git help succeeds without git.html' '\n \ttest_cmp expect test-browser.log\n '\n \n+test_expect_success 'git help --formats' '\n+\tgit help --user-formats >help.output &&\n+\tgrep \"^ gitattributes \" help.output &&\n+\tgrep \"^ gitmailmap \" help.output\n+'\n+\n test_expect_success 'git help -c' '\n \tgit help -c >help.output &&\n \tcat >expect <<-\\EOF &&\n-- \n2.33.1.1338.g20da966911a\n\n"},{"id":"438807","messageId":"cover-0.2-00000000000-20211015T020351Z-avarab@gmail.com","threadId":"56715","inReplyTo":null,"subject":"[PATCH 0/2] git(1) doc + \"git help\": split-out user & git format docs","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-10-15T02:05:18Z","receivedAt":"2021-10-15T02:05:58Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"This series goes on top of tz/doc-link-to-bundle-format-fix (and my\nnewly-landed ab/help-config-vars) and creates new \"User-facing file\nformats\" and \"Git file and wire formats\" sections in the main git\nmanual page.\n\nMy main motivation here was to make the Documentation/technical/* docs\nmore discoverable and accessible.\n\n2/2 moves over the \"bundle-format.txt\" into a new gitformat-bundle(5)\nmanual page, allowing git-bundle(1) to link to it as another man page\n(no more links from man pages to generated HTML!).\n\nI've got pending patches to migrate all of the rest of the relevant\n\"format\" documentation in Documentation/technical/*, but setting up\nthe infrastructure for that first should be easier for reviewers to\nconsider.\n\nÆvar Arnfjörð Bjarmason (2):\n git(1) docs: split \"User-facing file formats\" off from \"Guides\"\n git(1) docs: create a \"Git file and wire formats\" section\n\n Documentation/Makefile | 4 +-\n Documentation/git-bundle.txt | 12 +++--\n Documentation/git-help.txt | 11 +++--\n Documentation/git.txt | 15 +++++++\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++---\n Documentation/lint-man-section-order.perl | 3 ++\n Makefile | 1 +\n builtin/help.c | 16 +++++++\n command-list.txt | 21 ++++++---\n help.c | 22 ++++++++++\n help.h | 2 +\n t/t0012-help.sh | 16 ++++++-\n 12 files changed, 145 insertions(+), 22 deletions(-)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (78%)\n\n-- \n2.33.1.1338.g20da966911a\n\n"},{"id":"438808","messageId":"patch-2.2-5e80ee09523-20211015T020351Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-0.2-00000000000-20211015T020351Z-avarab@gmail.com","subject":"[PATCH 2/2] git(1) docs: create a \"Git file and wire formats\" section","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-10-15T02:05:20Z","receivedAt":"2021-10-15T02:05:59Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"Git file and wire formats\" section in the main \"git(1)\"\nmanual page and start moving the documentation that now lives in\n\"Documentation/technical/*.git\" over to it. This compliments the newly\nadded and adjacent \"User-facing file formats\" section.\n\nThis makes the technical documentation more accessible and\ndiscoverable. Before this we wouldn't install it by default, and had\nno ability to build man page versions of them. The links to them from\nour existing documentation link to the generated HTML version of these\ndocs.\n\nSo let's start moving those over, starting with just the\n\"bundle-format.txt\" documentation added in 7378ec90e1c (doc: describe\nGit bundle format, 2020-02-07). We'll now have a new\ngitformat-bundle(5) man page.\n\nUnfortunately the syntax of the current Documentation/technical/*.txt\nis not the same (when it comes to section headings etc.) as our\nDocumentation/*.txt documentation, so change the relevant bits of\nsyntax as we're moving this over.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 3 +-\n Documentation/git-bundle.txt | 12 +++--\n Documentation/git.txt | 8 ++++\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++---\n Documentation/lint-man-section-order.perl | 3 ++\n builtin/help.c | 8 ++++\n command-list.txt | 5 +++\n help.c | 11 +++++\n help.h | 1 +\n 9 files changed, 83 insertions(+), 12 deletions(-)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (78%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 8efed2e23e1..cc4761df82e 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -21,6 +21,7 @@ MAN1_TXT += gitweb.txt\n \n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n+MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -90,7 +91,6 @@ SP_ARTICLES += $(API_DOCS)\n TECH_DOCS += MyFirstContribution\n TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n-TECH_DOCS += technical/bundle-format\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n TECH_DOCS += technical/index-format\n@@ -312,6 +312,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n \tcmds-userformats.txt \\\n+\tcmds-gitformats.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\n \ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 71b5ecabd1f..cc3c32f5c0d 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -56,10 +56,9 @@ using \"thin packs\" bundles created using exclusions are smaller in\n size. That they're \"thin\" under the hood is merely noted here as a\n curiosity, and as a reference to other documentation\n \n-See link:technical/bundle-format.html[the `bundle-format`\n-documentation] for more details and the discussion of \"thin pack\" in\n-link:technical/pack-format.html[the pack format documentation] for\n-further details.\n+See linkgit:gitformat-bundle[5] for more details and the discussion of\n+\"thin pack\" in link:technical/pack-format.html[the pack format\n+documentation] for further details.\n \n OPTIONS\n -------\n@@ -334,6 +333,11 @@ You can also see what references it offers:\n $ git ls-remote mybundle\n ----------------\n \n+FILE FORMAT\n+-----------\n+\n+See linkgit:gitformat-bundle[5].\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 823977595c5..0c77475d7a0 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -345,6 +345,14 @@ edit. These can also be listed with 'git help --user-formats'.\n \n include::cmds-userformats.txt[]\n \n+Git file and wire formats\n+-------------------------\n+\n+This documentation discusses the file and wire formats that git itself\n+uses. These can also be listed with 'git help --git-formats'.\n+\n+include::cmds-gitformats.txt[]\n+\n Configuration Mechanism\n -----------------------\n \ndiff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt\nsimilarity index 78%\nrename from Documentation/technical/bundle-format.txt\nrename to Documentation/gitformat-bundle.txt\nindex bac558d049a..3aa2242eb9d 100644\n--- a/Documentation/technical/bundle-format.txt\n+++ b/Documentation/gitformat-bundle.txt\n@@ -1,11 +1,33 @@\n-= Git bundle v2 format\n+gitformat-bundle(5)\n+===================\n \n-The Git bundle format is a format that represents both refs and Git objects.\n+NAME\n+----\n+gitformat-bundle - The bundle file format\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+*.bundle\n+*.bdl\n+\n+DESCRIPTION\n+-----------\n+\n+The Git bundle format is a format that represents both refs and Git\n+objects. A bundle is a header in a format similar to\n+linkgit:git-show-ref[1] followed by a pack in *.pack format.\n \n-== Format\n+The format is created and read by the linkgit:git-bundle[1] command,\n+and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1].\n+\n+\n+FORMAT\n+------\n \n We will use ABNF notation to define the Git bundle format. See\n-protocol-common.txt for the details.\n+link:technical/protocol-common.html for the details.\n \n A v2 bundle looks like this:\n \n@@ -36,7 +58,9 @@ value = *(%01-09 / %0b-FF)\n pack = ... ; packfile\n ----\n \n-== Semantics\n+\n+SEMANTICS\n+---------\n \n A Git bundle consists of several parts.\n \n@@ -62,15 +86,21 @@ In the bundle format, there can be a comment following a prerequisite obj-id.\n This is a comment and it has no specific meaning. The writer of the bundle MAY\n put any string here. The reader of the bundle MUST ignore the comment.\n \n-=== Note on the shallow clone and a Git bundle\n+Note on the shallow clone and a Git bundle\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n Note that the prerequisites does not represent a shallow-clone boundary. The\n semantics of the prerequisites and the shallow-clone boundaries are different,\n and the Git bundle v2 format cannot represent a shallow clone repository.\n \n-== Capabilities\n+CAPABILITIES\n+------------\n \n Because there is no opportunity for negotiation, unknown capabilities cause 'git\n bundle' to abort. The only known capability is `object-format`, which specifies\n the hash algorithm in use, and can take the same values as the\n `extensions.objectFormat` configuration value.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl\nindex b05f9156dd9..81f04b6f3a2 100755\n--- a/Documentation/lint-man-section-order.perl\n+++ b/Documentation/lint-man-section-order.perl\n@@ -32,6 +32,9 @@\n \t\t'SEE ALSO' => {\n \t\t\torder => $order++,\n \t\t},\n+\t\t'FILE FORMAT' => {\n+\t\t\torder => $order++,\n+\t\t},\n \t\t'GIT' => {\n \t\t\trequired => 1,\n \t\t\torder => $order++,\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 5e842ea5a26..54ff30a0d37 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -44,6 +44,7 @@ static enum help_action {\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n \tHELP_ACTION_USER_FORMATS,\n+\tHELP_ACTION_GIT_FORMATS,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -67,6 +68,8 @@ static struct option builtin_help_options[] = {\n \t\t HELP_ACTION_GUIDES),\n \tOPT_CMDMODE(0, \"user-formats\", &cmd_mode, N_(\"print list of user-facing file formats\"),\n \t\t HELP_ACTION_USER_FORMATS),\n+\tOPT_CMDMODE(0, \"git-formats\", &cmd_mode, N_(\"print list of Git's own file and network formats\"),\n+\t\t HELP_ACTION_GIT_FORMATS),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -83,6 +86,7 @@ static const char * const builtin_help_usage[] = {\n \tN_(\"git help [-g|--guides]\"),\n \tN_(\"git help [-c|--config]\"),\n \tN_(\"git help [--user-formats]\"),\n+\tN_(\"git help [--git-formats]\"),\n \tNULL\n };\n \n@@ -621,6 +625,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\tno_extra_argc(argc);\n \t\tlist_user_formats_help();\n \t\treturn 0;\n+\tcase HELP_ACTION_GIT_FORMATS:\n+\t\tno_extra_argc(argc);\n+\t\tlist_git_formats_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\tno_extra_argc(argc);\n \t\tlist_config_help(SHOW_CONFIG_SECTIONS);\ndiff --git a/command-list.txt b/command-list.txt\nindex 5732ea437a8..3cf09b9d9eb 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -47,6 +47,10 @@\n # .mailmap etc. files lives in man section 5. These entries can only\n # have the \"userformats\" attribute and nothing else.\n #\n+# Git's own file and network formats such as documentation for the\n+# *.bundle format lives in mn section 5. These entries can only have\n+# the \"gitformats\" attribute and nothing else.\n+#\n ### command list (do not change this line, also do not change alignment)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -210,6 +214,7 @@ githooks userformats\n gitignore userformats\n gitmailmap userformats\n gitmodules userformats\n+gitformat-bundle gitformats\n gitnamespaces guide\n gitremote-helpers guide\n gitrepository-layout userformats\ndiff --git a/help.c b/help.c\nindex a7b5c909056..7b97867cb96 100644\n--- a/help.c\n+++ b/help.c\n@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n \t{ CAT_userformats, N_(\"User-facing file formats\") },\n+\t{ CAT_gitformats, N_(\"Internal file- and wire formats formats\") },\n \t{ 0, NULL }\n };\n \n@@ -433,6 +434,16 @@ void list_user_formats_help(void)\n \tputchar('\\n');\n }\n \n+void list_git_formats_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_gitformats, N_(\"Git's internal file and network formats are:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex d01908078dc..1075235f367 100644\n--- a/help.h\n+++ b/help.h\n@@ -23,6 +23,7 @@ void list_common_cmds_help(void);\n void list_all_cmds_help(void);\n void list_guides_help(void);\n void list_user_formats_help(void);\n+void list_git_formats_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\n-- \n2.33.1.1338.g20da966911a\n\n"},{"id":"443908","messageId":"cover-v2-0.5-00000000000-20211212T194047Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-0.2-00000000000-20211015T020351Z-avarab@gmail.com","subject":"[PATCH v2 0/5] git doc + \"git help\": move \"format\" docs from technical/*","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-12-12T19:49:35Z","receivedAt":"2021-12-12T19:50:48Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"[This is a more meaty re-roll of [1]. It previously conflicted with\ntopics that have now landed. There is a trivial conflict here with\ntb/cruft-packs, but that one's easily solved (they both edit adjacent\nbut otherwise unrelated lines in Documentation/Makefile)]\n\nMost of git is documented in its manual pages, but we have various\n\"technical\" and \"howto\" docs that aren't built as manpages, only as\nHTML documentation.\n\nIn many cases that's sensible, e.g. we've got one-off mailing list\nposts in there, but in the case of documenting git's core file formats\nI think these belong in the main documentation space, especially as\nmany existing manual pages refer to these, but need to do so by\nlinking from \"man\" pages to \"*.html\" files the user may or may not\nhave locally.\n\nThis series starts out by creating a \"userformats\" category in our\ndocumentation. The documentation for \".gitignore\", \".gitattributes\",\n\".mailmap\" etc. is currently in the \"guides\" space. We now have a\n\"userformats\" space with file formats users are expected to interact\nwith:\n \n $ git help --user-formats\n \n The user-facing file formats are:\n gitattributes Defining attributes per path\n githooks Hooks used by Git\n gitignore Specifies intentionally untracked files to ignore\n gitmailmap Map author/committer names and/or E-Mail addresses\n gitmodules Defining submodule properties\n gitrepository-layout Git Repository Layout\n\nWe then have (the main meat of this series) a move of relevant\n\"internal\" and \"protocol\" formats over to the main documentation\nspace:\n\n $ git help --git-formats\n \n Git's internal file and network formats are:\n gitformat-bitmap The bitmap file format\n gitformat-bundle The bundle file format\n gitformat-chunk Chunk-based file formats\n gitformat-commit-graph Git commit graph format\n gitformat-index Git index format\n gitformat-pack-protocol How packs are transferred over-the-wire\n gitformat-protocol-capabilities Protocol v0 and v1 capabilities\n gitformat-protocol-common Things common to various protocols\n gitformat-protocol-v2 Git Wire Protocol, Version 2\n gitformat-signature Git cryptographic signature formats\n\nThis isn't all of them, there's some in-flight conflicts with other\n(trivial) changes to those files, so I've skipped them for now. Taylor\nalso has an in-flight series to add a new Documentation/technical/*\nseries. I'm planning on an eventual follow-up series (and have most of\nthe changes already) to move those over.\n\nThis also doesn't move over the part of the api-trace2.txt that deals\nwith the format users interact with, i.e. the JSON schema. I'm\nsubmitting other changes in that are currently, and will eventually\nloop around to moving that part over to this new \"gitformats\" space.\n\n1. https://lore.kernel.org/git/cover-0.2-00000000000-20211015T020351Z-avarab@gmail.com/\n\nÆvar Arnfjörð Bjarmason (5):\n git docs: split \"User-facing file formats\" off from \"Guides\"\n git docs: create a \"Git file and wire formats\" section\n docs: move commit-graph format docs to man section 5\n docs: move protocol-related docs to man section 5\n docs: move {index,signature,bitmap,chunk}-format docs to man section 5\n\n Documentation/Makefile | 19 ++++---\n Documentation/config/lsrefs.txt | 2 +-\n Documentation/config/protocol.txt | 2 +-\n Documentation/git-bundle.txt | 12 +++--\n Documentation/git-commit-graph.txt | 5 ++\n Documentation/git-help.txt | 13 +++--\n Documentation/git-upload-pack.txt | 5 +-\n Documentation/git.txt | 15 ++++++\n ...bitmap-format.txt => gitformat-bitmap.txt} | 38 +++++++++++---\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++---\n .../chunk-format.txt => gitformat-chunk.txt} | 25 ++++++++--\n ...-format.txt => gitformat-commit-graph.txt} | 49 +++++++++++++------\n .../index-format.txt => gitformat-index.txt} | 20 +++++++-\n ...otocol.txt => gitformat-pack-protocol.txt} | 22 +++++++--\n ...xt => gitformat-protocol-capabilities.txt} | 28 ++++++++---\n ...mmon.txt => gitformat-protocol-common.txt} | 23 ++++++++-\n ...tocol-v2.txt => gitformat-protocol-v2.txt} | 24 +++++++--\n ...ure-format.txt => gitformat-signature.txt} | 21 ++++++--\n Documentation/lint-man-section-order.perl | 3 ++\n Documentation/technical/api-simple-ipc.txt | 2 +-\n Documentation/technical/http-protocol.txt | 6 +--\n .../long-running-process-protocol.txt | 2 +-\n Documentation/technical/pack-format.txt | 2 +-\n Documentation/technical/partial-clone.txt | 2 +-\n Makefile | 1 +\n builtin/help.c | 16 ++++++\n command-list.txt | 30 +++++++++---\n help.c | 22 +++++++++\n help.h | 2 +\n t/t0012-help.sh | 16 +++++-\n t/t5551-http-fetch-smart.sh | 4 +-\n 31 files changed, 386 insertions(+), 89 deletions(-)\n rename Documentation/{technical/bitmap-format.txt => gitformat-bitmap.txt} (91%)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (78%)\n rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (91%)\n rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (86%)\n rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)\n rename Documentation/{technical/pack-protocol.txt => gitformat-pack-protocol.txt} (98%)\n rename Documentation/{technical/protocol-capabilities.txt => gitformat-protocol-capabilities.txt} (96%)\n rename Documentation/{technical/protocol-common.txt => gitformat-protocol-common.txt} (88%)\n rename Documentation/{technical/protocol-v2.txt => gitformat-protocol-v2.txt} (98%)\n rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)\n\nRange-diff against v1:\n1: 19a8be1fc73 ! 1: 960574b7f05 git(1) docs: split \"User-facing file formats\" off from \"Guides\"\n @@ Metadata\n Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - git(1) docs: split \"User-facing file formats\" off from \"Guides\"\n + git docs: split \"User-facing file formats\" off from \"Guides\"\n \n - Create a new \"User-facing file formats\" section in the main \"git(1)\"\n - manual page. The \"Guides\" section was added to the manual page in\n + Create a new \"User-facing file formats\" section in the main \"git help\n + git\" manual page. The \"Guides\" section was added to the manual page in\n f442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense\n to list all that documentation.\n \n @@ Documentation/Makefile: cmds_txt = cmds-ancillaryinterrogators.txt \\\n \n ## Documentation/git-help.txt ##\n @@ Documentation/git-help.txt: SYNOPSIS\n - \t [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE]\n + --------\n + [verse]\n + 'git help' [-a|--all [--[no-]verbose]]\n +-\t [[-i|--info] [-m|--man] [-w|--web]] [|]\n ++\t [[-i|--info] [-m|--man] [-w|--web]] [||]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n +'git help' [--user-formats]\n @@ Documentation/git-help.txt: SYNOPSIS\n DESCRIPTION\n -----------\n \n --With no options and no COMMAND or GUIDE given, the synopsis of the 'git'\n -+With no options and no COMMAND or DOC given, the synopsis of the 'git'\n +-With no options and no '' or '' given, the synopsis of the 'git'\n ++With no options and no '', '' or '' given, the synopsis of the 'git'\n command and a list of the most commonly used Git commands are printed\n on the standard output.\n \n @@ command-list.txt\n +# .mailmap etc. files lives in man section 5. These entries can only\n +# have the \"userformats\" attribute and nothing else.\n +#\n - ### command list (do not change this line, also do not change alignment)\n + ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n -@@ command-list.txt: gitweb ancillaryinterrogators\n +@@ command-list.txt: git-verify-tag ancillaryinterrogators\n git-whatchanged ancillaryinterrogators complete\n git-worktree mainporcelain\n git-write-tree plumbingmanipulators\n @@ command-list.txt: gitdiffcore guide\n gitglossary guide\n -githooks guide\n -gitignore guide\n --gitmailmap guide\n --gitmodules guide\n +githooks userformats\n +gitignore userformats\n + gitk mainporcelain\n +-gitmailmap guide\n +-gitmodules guide\n +gitmailmap userformats\n +gitmodules userformats\n gitnamespaces guide\n @@ command-list.txt: gitdiffcore guide\n +gitrepository-layout userformats\n gitrevisions guide\n gitsubmodules guide\n - gittutorial-2 guide\n + gittutorial guide\n \n ## help.c ##\n @@ help.c: static struct category_description main_categories[] = {\n2: 5e80ee09523 ! 2: b2d73f8c9da git(1) docs: create a \"Git file and wire formats\" section\n @@ Metadata\n Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - git(1) docs: create a \"Git file and wire formats\" section\n + git docs: create a \"Git file and wire formats\" section\n \n - Create a new \"Git file and wire formats\" section in the main \"git(1)\"\n - manual page and start moving the documentation that now lives in\n + Create a new \"Git file and wire formats\" section in the main \"git help\n + git\" manual page and start moving the documentation that now lives in\n \"Documentation/technical/*.git\" over to it. This compliments the newly\n added and adjacent \"User-facing file formats\" section.\n \n @@ Commit message\n So let's start moving those over, starting with just the\n \"bundle-format.txt\" documentation added in 7378ec90e1c (doc: describe\n Git bundle format, 2020-02-07). We'll now have a new\n - gitformat-bundle(5) man page.\n + gitformat-bundle(5) man page. Subsequent commits will move more git\n + internal format documentation over.\n \n Unfortunately the syntax of the current Documentation/technical/*.txt\n is not the same (when it comes to section headings etc.) as our\n @@ Documentation/Makefile: cmds_txt = cmds-ancillaryinterrogators.txt \\\n \n \n ## Documentation/git-bundle.txt ##\n -@@ Documentation/git-bundle.txt: using \"thin packs\" bundles created using exclusions are smaller in\n +@@ Documentation/git-bundle.txt: using \"thin packs\", bundles created using exclusions are smaller in\n size. That they're \"thin\" under the hood is merely noted here as a\n - curiosity, and as a reference to other documentation\n + curiosity, and as a reference to other documentation.\n \n -See link:technical/bundle-format.html[the `bundle-format`\n -documentation] for more details and the discussion of \"thin pack\" in\n @@ command-list.txt\n +# *.bundle format lives in mn section 5. These entries can only have\n +# the \"gitformats\" attribute and nothing else.\n +#\n - ### command list (do not change this line, also do not change alignment)\n + ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n -@@ command-list.txt: githooks userformats\n - gitignore userformats\n - gitmailmap userformats\n - gitmodules userformats\n +@@ command-list.txt: gitcvs-migration guide\n + gitdiffcore guide\n + giteveryday guide\n + gitfaq guide\n +gitformat-bundle gitformats\n - gitnamespaces guide\n - gitremote-helpers guide\n - gitrepository-layout userformats\n + gitglossary guide\n + githooks userformats\n + gitignore userformats\n \n ## help.c ##\n @@ help.c: static struct category_description main_categories[] = {\n-: ----------- > 3: 5abd59b807f docs: move commit-graph format docs to man section 5\n-: ----------- > 4: fb91009c18f docs: move protocol-related docs to man section 5\n-: ----------- > 5: 5cb41bb0dcb docs: move {index,signature,bitmap,chunk}-format docs to man section 5\n-- \n2.34.1.929.ge922d848c7a\n\n"},{"id":"443909","messageId":"patch-v2-1.5-960574b7f05-20211212T194047Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v2-0.5-00000000000-20211212T194047Z-avarab@gmail.com","subject":"[PATCH v2 1/5] git docs: split \"User-facing file formats\" off from \"Guides\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-12-12T19:49:36Z","receivedAt":"2021-12-12T19:50:51Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"User-facing file formats\" section in the main \"git help\ngit\" manual page. The \"Guides\" section was added to the manual page in\nf442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense\nto list all that documentation.\n\nBut placing e.g. \"gitignore(5)\" in it is stretching the meaning of\nwhat a \"guide\" is, ideally that section should list things similar to\n\"giteveryday(7)\" and \"gitcore-tutorial(7)\".\n\nWe take a wide view of what's considered a \"user format\", it's not\njust a file format, but e.g. githooks(5) also belongs, since the\nlayout of the \".git/hooks/\" and the placement of hooks in it is\nsomething the user might be expected to interact with.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-help.txt | 13 +++++++++----\n Documentation/git.txt | 7 +++++++\n Makefile | 1 +\n builtin/help.c | 8 ++++++++\n command-list.txt | 16 ++++++++++------\n help.c | 11 +++++++++++\n help.h | 1 +\n t/t0012-help.sh | 16 +++++++++++++++-\n 9 files changed, 63 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex ed656db2ae9..e973be97162 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -316,6 +316,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchingrepositories.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n+\tcmds-userformats.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\n \ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 44ea63cc6d3..32081f3030d 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -9,14 +9,15 @@ SYNOPSIS\n --------\n [verse]\n 'git help' [-a|--all [--[no-]verbose]]\n-\t [[-i|--info] [-m|--man] [-w|--web]] [|]\n+\t [[-i|--info] [-m|--man] [-w|--web]] [||]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n+'git help' [--user-formats]\n \n DESCRIPTION\n -----------\n \n-With no options and no '' or '' given, the synopsis of the 'git'\n+With no options and no '', '' or '' given, the synopsis of the 'git'\n command and a list of the most commonly used Git commands are printed\n on the standard output.\n \n@@ -26,8 +27,8 @@ printed on the standard output.\n If the option `--guides` or `-g` is given, a list of the\n Git concept guides is also printed on the standard output.\n \n-If a command, or a guide, is given, a manual page for that command or\n-guide is brought up. The 'man' program is used by default for this\n+If a command or other documentation is given, the relevant manual page\n+will be brought up. The 'man' program is used by default for this\n purpose, but this can be overridden by other options or configuration\n variables.\n \n@@ -62,6 +63,10 @@ OPTIONS\n --guides::\n \tPrints a list of the Git concept guides on the standard output.\n \n+--user-formats::\n+\tPrints a list of the Git user-facing format documentation on\n+\tthe standard output.\n+\n -i::\n --info::\n \tDisplay manual page for the command in the 'info' format. The\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 13f83a2a3a1..7a8be2991df 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -337,6 +337,13 @@ The following documentation pages are guides about Git concepts.\n \n include::cmds-guide.txt[]\n \n+User-facing file formats\n+------------------------\n+\n+This documentation discusses file formats that users are expected to\n+edit. These can also be listed with 'git help --user-formats'.\n+\n+include::cmds-userformats.txt[]\n \n Configuration Mechanism\n -----------------------\ndiff --git a/Makefile b/Makefile\nindex ed75ed422b5..c59fd6c2be9 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -3304,6 +3304,7 @@ check-docs::\n \t\tsed -e '1,/^### command list/d' \\\n \t\t -e '/^#/d' \\\n \t\t -e '/guide$$/d' \\\n+\t\t -e '/formats$$/d' \\\n \t\t -e 's/[ \t].*//' \\\n \t\t -e 's/^/listed /' command-list.txt; \\\n \t\t$(MAKE) -C Documentation print-man1 | \\\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 75cd2fb407f..5e842ea5a26 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -43,6 +43,7 @@ static enum help_action {\n \tHELP_ACTION_ALL = 1,\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n+\tHELP_ACTION_USER_FORMATS,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -64,6 +65,8 @@ static struct option builtin_help_options[] = {\n \n \tOPT_CMDMODE('g', \"guides\", &cmd_mode, N_(\"print list of useful guides\"),\n \t\t HELP_ACTION_GUIDES),\n+\tOPT_CMDMODE(0, \"user-formats\", &cmd_mode, N_(\"print list of user-facing file formats\"),\n+\t\t HELP_ACTION_USER_FORMATS),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -79,6 +82,7 @@ static const char * const builtin_help_usage[] = {\n \t \" [[-i|--info] [-m|--man] [-w|--web]] []\"),\n \tN_(\"git help [-g|--guides]\"),\n \tN_(\"git help [-c|--config]\"),\n+\tN_(\"git help [--user-formats]\"),\n \tNULL\n };\n \n@@ -613,6 +617,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\tno_extra_argc(argc);\n \t\tlist_config_help(SHOW_CONFIG_VARS);\n \t\treturn 0;\n+\tcase HELP_ACTION_USER_FORMATS:\n+\t\tno_extra_argc(argc);\n+\t\tlist_user_formats_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\tno_extra_argc(argc);\n \t\tlist_config_help(SHOW_CONFIG_SECTIONS);\ndiff --git a/command-list.txt b/command-list.txt\nindex 675c28f0bd0..e4118533e93 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -43,6 +43,10 @@\n # specified here, which can only have \"guide\" attribute and nothing\n # else.\n #\n+# User-facing file formats such as documentation for the .gitmodules,\n+# .mailmap etc. files lives in man section 5. These entries can only\n+# have the \"userformats\" attribute and nothing else.\n+#\n ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -191,7 +195,7 @@ git-verify-tag ancillaryinterrogators\n git-whatchanged ancillaryinterrogators complete\n git-worktree mainporcelain\n git-write-tree plumbingmanipulators\n-gitattributes guide\n+gitattributes userformats\n gitcli guide\n gitcore-tutorial guide\n gitcredentials guide\n@@ -200,14 +204,14 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitglossary guide\n-githooks guide\n-gitignore guide\n+githooks userformats\n+gitignore userformats\n gitk mainporcelain\n-gitmailmap guide\n-gitmodules guide\n+gitmailmap userformats\n+gitmodules userformats\n gitnamespaces guide\n gitremote-helpers guide\n-gitrepository-layout guide\n+gitrepository-layout userformats\n gitrevisions guide\n gitsubmodules guide\n gittutorial guide\ndiff --git a/help.c b/help.c\nindex 973e47cdc30..a7b5c909056 100644\n--- a/help.c\n+++ b/help.c\n@@ -37,6 +37,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_plumbinginterrogators, N_(\"Low-level Commands / Interrogators\") },\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n+\t{ CAT_userformats, N_(\"User-facing file formats\") },\n \t{ 0, NULL }\n };\n \n@@ -422,6 +423,16 @@ void list_guides_help(void)\n \tputchar('\\n');\n }\n \n+void list_user_formats_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_userformats, N_(\"The user-facing file formats are:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex 9d383f1a0b2..d01908078dc 100644\n--- a/help.h\n+++ b/help.h\n@@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num)\n void list_common_cmds_help(void);\n void list_all_cmds_help(void);\n void list_guides_help(void);\n+void list_user_formats_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex 91b68c74a15..6a20a7303f8 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -41,6 +41,8 @@ test_expect_success 'invalid usage' '\n \ttest_expect_code 129 git help -g add &&\n \ttest_expect_code 129 git help -a -g &&\n \n+\ttest_expect_code 129 git help --user-formats add &&\n+\n \ttest_expect_code 129 git help -g -c &&\n \ttest_expect_code 129 git help --config-for-completion add &&\n \ttest_expect_code 129 git help --config-sections-for-completion add\n@@ -78,9 +80,15 @@ test_expect_success 'git help' '\n \ttest_i18ngrep \"^ commit \" help.output &&\n \ttest_i18ngrep \"^ fetch \" help.output\n '\n+\n+test_expect_success 'git help -a' '\n+\tgit help -a >help.output &&\n+\tgrep \"^Main Porcelain Commands\" help.output &&\n+\tgrep \"^User-facing file formats\" help.output\n+'\n+\n test_expect_success 'git help -g' '\n \tgit help -g >help.output &&\n-\ttest_i18ngrep \"^ attributes \" help.output &&\n \ttest_i18ngrep \"^ everyday \" help.output &&\n \ttest_i18ngrep \"^ tutorial \" help.output\n '\n@@ -101,6 +109,12 @@ test_expect_success 'git help succeeds without git.html' '\n \ttest_cmp expect test-browser.log\n '\n \n+test_expect_success 'git help --formats' '\n+\tgit help --user-formats >help.output &&\n+\tgrep \"^ gitattributes \" help.output &&\n+\tgrep \"^ gitmailmap \" help.output\n+'\n+\n test_expect_success 'git help -c' '\n \tgit help -c >help.output &&\n \tcat >expect <<-\\EOF &&\n-- \n2.34.1.929.ge922d848c7a\n\n"},{"id":"443910","messageId":"patch-v2-2.5-b2d73f8c9da-20211212T194047Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v2-0.5-00000000000-20211212T194047Z-avarab@gmail.com","subject":"[PATCH v2 2/5] git docs: create a \"Git file and wire formats\" section","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-12-12T19:49:37Z","receivedAt":"2021-12-12T19:50:55Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"Git file and wire formats\" section in the main \"git help\ngit\" manual page and start moving the documentation that now lives in\n\"Documentation/technical/*.git\" over to it. This compliments the newly\nadded and adjacent \"User-facing file formats\" section.\n\nThis makes the technical documentation more accessible and\ndiscoverable. Before this we wouldn't install it by default, and had\nno ability to build man page versions of them. The links to them from\nour existing documentation link to the generated HTML version of these\ndocs.\n\nSo let's start moving those over, starting with just the\n\"bundle-format.txt\" documentation added in 7378ec90e1c (doc: describe\nGit bundle format, 2020-02-07). We'll now have a new\ngitformat-bundle(5) man page. Subsequent commits will move more git\ninternal format documentation over.\n\nUnfortunately the syntax of the current Documentation/technical/*.txt\nis not the same (when it comes to section headings etc.) as our\nDocumentation/*.txt documentation, so change the relevant bits of\nsyntax as we're moving this over.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 3 +-\n Documentation/git-bundle.txt | 12 +++--\n Documentation/git.txt | 8 ++++\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++---\n Documentation/lint-man-section-order.perl | 3 ++\n builtin/help.c | 8 ++++\n command-list.txt | 5 +++\n help.c | 11 +++++\n help.h | 1 +\n 9 files changed, 83 insertions(+), 12 deletions(-)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (78%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex e973be97162..fe8e1c56c7d 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -21,6 +21,7 @@ MAN1_TXT += gitweb.txt\n \n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n+MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -90,7 +91,6 @@ SP_ARTICLES += $(API_DOCS)\n TECH_DOCS += MyFirstContribution\n TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n-TECH_DOCS += technical/bundle-format\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n TECH_DOCS += technical/index-format\n@@ -317,6 +317,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n \tcmds-userformats.txt \\\n+\tcmds-gitformats.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\n \ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 72ab8139052..0ebf3301a0a 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -56,10 +56,9 @@ using \"thin packs\", bundles created using exclusions are smaller in\n size. That they're \"thin\" under the hood is merely noted here as a\n curiosity, and as a reference to other documentation.\n \n-See link:technical/bundle-format.html[the `bundle-format`\n-documentation] for more details and the discussion of \"thin pack\" in\n-link:technical/pack-format.html[the pack format documentation] for\n-further details.\n+See linkgit:gitformat-bundle[5] for more details and the discussion of\n+\"thin pack\" in link:technical/pack-format.html[the pack format\n+documentation] for further details.\n \n OPTIONS\n -------\n@@ -334,6 +333,11 @@ You can also see what references it offers:\n $ git ls-remote mybundle\n ----------------\n \n+FILE FORMAT\n+-----------\n+\n+See linkgit:gitformat-bundle[5].\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 7a8be2991df..75cce82915d 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -345,6 +345,14 @@ edit. These can also be listed with 'git help --user-formats'.\n \n include::cmds-userformats.txt[]\n \n+Git file and wire formats\n+-------------------------\n+\n+This documentation discusses the file and wire formats that git itself\n+uses. These can also be listed with 'git help --git-formats'.\n+\n+include::cmds-gitformats.txt[]\n+\n Configuration Mechanism\n -----------------------\n \ndiff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt\nsimilarity index 78%\nrename from Documentation/technical/bundle-format.txt\nrename to Documentation/gitformat-bundle.txt\nindex bac558d049a..3aa2242eb9d 100644\n--- a/Documentation/technical/bundle-format.txt\n+++ b/Documentation/gitformat-bundle.txt\n@@ -1,11 +1,33 @@\n-= Git bundle v2 format\n+gitformat-bundle(5)\n+===================\n \n-The Git bundle format is a format that represents both refs and Git objects.\n+NAME\n+----\n+gitformat-bundle - The bundle file format\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+*.bundle\n+*.bdl\n+\n+DESCRIPTION\n+-----------\n+\n+The Git bundle format is a format that represents both refs and Git\n+objects. A bundle is a header in a format similar to\n+linkgit:git-show-ref[1] followed by a pack in *.pack format.\n \n-== Format\n+The format is created and read by the linkgit:git-bundle[1] command,\n+and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1].\n+\n+\n+FORMAT\n+------\n \n We will use ABNF notation to define the Git bundle format. See\n-protocol-common.txt for the details.\n+link:technical/protocol-common.html for the details.\n \n A v2 bundle looks like this:\n \n@@ -36,7 +58,9 @@ value = *(%01-09 / %0b-FF)\n pack = ... ; packfile\n ----\n \n-== Semantics\n+\n+SEMANTICS\n+---------\n \n A Git bundle consists of several parts.\n \n@@ -62,15 +86,21 @@ In the bundle format, there can be a comment following a prerequisite obj-id.\n This is a comment and it has no specific meaning. The writer of the bundle MAY\n put any string here. The reader of the bundle MUST ignore the comment.\n \n-=== Note on the shallow clone and a Git bundle\n+Note on the shallow clone and a Git bundle\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n Note that the prerequisites does not represent a shallow-clone boundary. The\n semantics of the prerequisites and the shallow-clone boundaries are different,\n and the Git bundle v2 format cannot represent a shallow clone repository.\n \n-== Capabilities\n+CAPABILITIES\n+------------\n \n Because there is no opportunity for negotiation, unknown capabilities cause 'git\n bundle' to abort. The only known capability is `object-format`, which specifies\n the hash algorithm in use, and can take the same values as the\n `extensions.objectFormat` configuration value.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl\nindex 425377dfeb7..02408a0062f 100755\n--- a/Documentation/lint-man-section-order.perl\n+++ b/Documentation/lint-man-section-order.perl\n@@ -32,6 +32,9 @@\n \t\t'SEE ALSO' => {\n \t\t\torder => $order++,\n \t\t},\n+\t\t'FILE FORMAT' => {\n+\t\t\torder => $order++,\n+\t\t},\n \t\t'GIT' => {\n \t\t\trequired => 1,\n \t\t\torder => $order++,\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 5e842ea5a26..54ff30a0d37 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -44,6 +44,7 @@ static enum help_action {\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n \tHELP_ACTION_USER_FORMATS,\n+\tHELP_ACTION_GIT_FORMATS,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -67,6 +68,8 @@ static struct option builtin_help_options[] = {\n \t\t HELP_ACTION_GUIDES),\n \tOPT_CMDMODE(0, \"user-formats\", &cmd_mode, N_(\"print list of user-facing file formats\"),\n \t\t HELP_ACTION_USER_FORMATS),\n+\tOPT_CMDMODE(0, \"git-formats\", &cmd_mode, N_(\"print list of Git's own file and network formats\"),\n+\t\t HELP_ACTION_GIT_FORMATS),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -83,6 +86,7 @@ static const char * const builtin_help_usage[] = {\n \tN_(\"git help [-g|--guides]\"),\n \tN_(\"git help [-c|--config]\"),\n \tN_(\"git help [--user-formats]\"),\n+\tN_(\"git help [--git-formats]\"),\n \tNULL\n };\n \n@@ -621,6 +625,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\tno_extra_argc(argc);\n \t\tlist_user_formats_help();\n \t\treturn 0;\n+\tcase HELP_ACTION_GIT_FORMATS:\n+\t\tno_extra_argc(argc);\n+\t\tlist_git_formats_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\tno_extra_argc(argc);\n \t\tlist_config_help(SHOW_CONFIG_SECTIONS);\ndiff --git a/command-list.txt b/command-list.txt\nindex e4118533e93..40d27371228 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -47,6 +47,10 @@\n # .mailmap etc. files lives in man section 5. These entries can only\n # have the \"userformats\" attribute and nothing else.\n #\n+# Git's own file and network formats such as documentation for the\n+# *.bundle format lives in mn section 5. These entries can only have\n+# the \"gitformats\" attribute and nothing else.\n+#\n ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -203,6 +207,7 @@ gitcvs-migration guide\n gitdiffcore guide\n giteveryday guide\n gitfaq guide\n+gitformat-bundle gitformats\n gitglossary guide\n githooks userformats\n gitignore userformats\ndiff --git a/help.c b/help.c\nindex a7b5c909056..7b97867cb96 100644\n--- a/help.c\n+++ b/help.c\n@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n \t{ CAT_userformats, N_(\"User-facing file formats\") },\n+\t{ CAT_gitformats, N_(\"Internal file- and wire formats formats\") },\n \t{ 0, NULL }\n };\n \n@@ -433,6 +434,16 @@ void list_user_formats_help(void)\n \tputchar('\\n');\n }\n \n+void list_git_formats_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_gitformats, N_(\"Git's internal file and network formats are:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex d01908078dc..1075235f367 100644\n--- a/help.h\n+++ b/help.h\n@@ -23,6 +23,7 @@ void list_common_cmds_help(void);\n void list_all_cmds_help(void);\n void list_guides_help(void);\n void list_user_formats_help(void);\n+void list_git_formats_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\n-- \n2.34.1.929.ge922d848c7a\n\n"},{"id":"443911","messageId":"patch-v2-3.5-5abd59b807f-20211212T194047Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v2-0.5-00000000000-20211212T194047Z-avarab@gmail.com","subject":"[PATCH v2 3/5] docs: move commit-graph format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-12-12T19:49:38Z","receivedAt":"2021-12-12T19:51:01Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space.\n\nBy moving the documentation for the commit-graph format into man\nsection 5 and the new \"gitformats\" category. This change is split from\nsubsequent commits due to the relatively large amount of ASCIIDOC\nformatting changes that are required.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-commit-graph.txt | 5 ++\n ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------\n Documentation/technical/chunk-format.txt | 4 +-\n command-list.txt | 1 +\n 5 files changed, 41 insertions(+), 17 deletions(-)\n rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (87%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex fe8e1c56c7d..9483bde3420 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -22,6 +22,7 @@ MAN1_TXT += gitweb.txt\n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n+MAN5_TXT += gitformat-commit-graph.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex e1f48c95b3c..047decdb65b 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append\n ------------------------------------------------\n \n \n+FILE FORMAT\n+-----------\n+\n+see linkgit:gitformat-commit-graph[5].\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt\nsimilarity index 87%\nrename from Documentation/technical/commit-graph-format.txt\nrename to Documentation/gitformat-commit-graph.txt\nindex 87971c27dd7..25eb131dcd2 100644\n--- a/Documentation/technical/commit-graph-format.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -1,5 +1,18 @@\n-Git commit graph format\n-=======================\n+gitformat-commit-graph(5)\n+=========================\n+\n+NAME\n+----\n+gitformat-commit-graph - Git commit graph format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/info/commit-graph\n+$GIT_DIR/objects/info/commit-graphs/*\n+\n+DESCRIPTION\n+-----------\n \n The Git commit graph stores a list of commit OIDs and some associated\n metadata, including:\n@@ -30,7 +43,7 @@ and hash type.\n \n All multi-byte numbers are in network byte order.\n \n-HEADER:\n+=== HEADER:\n \n 4-byte signature:\n The signature is: {'C', 'G', 'P', 'H'}\n@@ -52,7 +65,7 @@ HEADER:\n We infer the length (H*B) of the Base Graphs chunk\n from this value.\n \n-CHUNK LOOKUP:\n+=== CHUNK LOOKUP:\n \n (C + 1) * 12 bytes listing the table of contents for the chunks:\n First 4 bytes describe the chunk id. Value 0 is a terminating label.\n@@ -68,17 +81,17 @@ CHUNK LOOKUP:\n these chunks may be given in any order. Chunks are required unless\n otherwise specified.\n \n-CHUNK DATA:\n+=== CHUNK DATA:\n \n- OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n+==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n The ith entry, F[i], stores the number of OIDs with first\n byte at most i. Thus F[255] stores the total\n number of commits (N).\n \n- OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n+==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n The OIDs for all commits in the graph, sorted in ascending order.\n \n- Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n+==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n * The first H bytes are for the OID of the root tree.\n * The next 8 bytes are for the positions of the first two parents\n of the ith commit. Stores value 0x70000000 if no parent in that\n@@ -93,7 +106,7 @@ CHUNK DATA:\n 2 bits of the lowest byte, storing the 33rd and 34th bit of the\n commit time.\n \n- Generation Data (ID: {'G', 'D', 'A', 'T' }) (N * 4 bytes) [Optional]\n+==== Generation Data (ID: {'G', 'D', 'A', 'T' }) (N * 4 bytes) [Optional]\n * This list of 4-byte values store corrected commit date offsets for the\n commits, arranged in the same order as commit data chunk.\n * If the corrected commit date offset cannot be stored within 31 bits,\n@@ -104,7 +117,7 @@ CHUNK DATA:\n by compatible versions of Git and in case of split commit-graph chains,\n the topmost layer also has Generation Data chunk.\n \n- Generation Data Overflow (ID: {'G', 'D', 'O', 'V' }) [Optional]\n+==== Generation Data Overflow (ID: {'G', 'D', 'O', 'V' }) [Optional]\n * This list of 8-byte values stores the corrected commit date offsets\n for commits with corrected commit date offsets that cannot be\n stored within 31 bits.\n@@ -112,7 +125,7 @@ CHUNK DATA:\n chunk is present and atleast one corrected commit date offset cannot\n be stored within 31 bits.\n \n- Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n+==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n This list of 4-byte values store the second through nth parents for\n all octopus merges. The second parent value in the commit data stores\n an array position within this list along with the most-significant bit\n@@ -120,14 +133,14 @@ CHUNK DATA:\n positions for the parents until reaching a value with the most-significant\n bit on. The other bits correspond to the position of the last parent.\n \n- Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n+==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters\n from commit 0 to commit i (inclusive) in lexicographic order. The Bloom\n filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header\n length), where BIDX[-1] is 0.\n * The BIDX chunk is ignored if the BDAT chunk is not present.\n \n- Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n+==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n * It starts with header consisting of three unsigned 32-bit integers:\n - Version of the hash algorithm being used. We currently only support\n \tvalue 1 which corresponds to the 32-bit version of the murmur3 hash\n@@ -147,12 +160,16 @@ CHUNK DATA:\n of length one, with either all bits set to zero or one respectively.\n * The BDAT chunk is present if and only if BIDX is present.\n \n- Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n+==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n This list of H-byte hashes describe a set of B commit-graph files that\n form a commit-graph chain. The graph position for the ith commit in this\n file's OID Lookup chunk is equal to i plus the number of commits in all\n base graphs. If B is non-zero, this chunk must exist.\n \n-TRAILER:\n+=== TRAILER:\n \n \tH-byte HASH-checksum of all of the above.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/chunk-format.txt b/Documentation/technical/chunk-format.txt\nindex 593614fceda..f36ce42f37c 100644\n--- a/Documentation/technical/chunk-format.txt\n+++ b/Documentation/technical/chunk-format.txt\n@@ -6,7 +6,7 @@ sections of the file. This allows structured access to a large file by\n scanning a small \"table of contents\" for the remaining data. This common\n format is used by the `commit-graph` and `multi-pack-index` files. See\n link:technical/pack-format.html[the `multi-pack-index` format] and\n-link:technical/commit-graph-format.html[the `commit-graph` format] for\n+the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n how they use the chunks to describe structured data.\n \n A chunk-based file format begins with some header information custom to\n@@ -108,7 +108,7 @@ for future formats:\n * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()`\n in `commit-graph.c` for how the chunk-format API is used to write and\n parse the commit-graph file format documented in\n- link:technical/commit-graph-format.html[the commit-graph file format].\n+ the commit-graph file format in linkgit:gitformat-commit-graph[5].\n \n * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n in `midx.c` for how the chunk-format API is used to write and\ndiff --git a/command-list.txt b/command-list.txt\nindex 40d27371228..f7dcc795e1e 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -208,6 +208,7 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle gitformats\n+gitformat-commit-graph gitformats\n gitglossary guide\n githooks userformats\n gitignore userformats\n-- \n2.34.1.929.ge922d848c7a\n\n"},{"id":"443912","messageId":"patch-v2-4.5-fb91009c18f-20211212T194047Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v2-0.5-00000000000-20211212T194047Z-avarab@gmail.com","subject":"[PATCH v2 4/5] docs: move protocol-related docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-12-12T19:49:39Z","receivedAt":"2021-12-12T19:51:04Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space. By moving\nthe things that discuss the protocol we can properly link from\ne.g. lsrefs.unborn and protocol.version documentation to a manpage we\nbuild by default.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 8 +++---\n Documentation/config/lsrefs.txt | 2 +-\n Documentation/config/protocol.txt | 2 +-\n Documentation/git-upload-pack.txt | 5 ++--\n Documentation/gitformat-bundle.txt | 2 +-\n ...otocol.txt => gitformat-pack-protocol.txt} | 22 +++++++++++++--\n ...xt => gitformat-protocol-capabilities.txt} | 28 +++++++++++++++----\n ...mmon.txt => gitformat-protocol-common.txt} | 23 +++++++++++++--\n ...tocol-v2.txt => gitformat-protocol-v2.txt} | 24 +++++++++++++---\n Documentation/technical/api-simple-ipc.txt | 2 +-\n Documentation/technical/http-protocol.txt | 6 ++--\n .../long-running-process-protocol.txt | 2 +-\n Documentation/technical/partial-clone.txt | 2 +-\n command-list.txt | 4 +++\n t/t5551-http-fetch-smart.sh | 4 +--\n 15 files changed, 103 insertions(+), 33 deletions(-)\n rename Documentation/{technical/pack-protocol.txt => gitformat-pack-protocol.txt} (98%)\n rename Documentation/{technical/protocol-capabilities.txt => gitformat-protocol-capabilities.txt} (96%)\n rename Documentation/{technical/protocol-common.txt => gitformat-protocol-common.txt} (88%)\n rename Documentation/{technical/protocol-v2.txt => gitformat-protocol-v2.txt} (98%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 9483bde3420..ba587b75a51 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -23,6 +23,10 @@ MAN1_TXT += gitweb.txt\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += gitformat-commit-graph.txt\n+MAN5_TXT += gitformat-pack-protocol.txt\n+MAN5_TXT += gitformat-protocol-capabilities.txt\n+MAN5_TXT += gitformat-protocol-common.txt\n+MAN5_TXT += gitformat-protocol-v2.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -99,12 +103,8 @@ TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n-TECH_DOCS += technical/pack-protocol\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\n-TECH_DOCS += technical/protocol-capabilities\n-TECH_DOCS += technical/protocol-common\n-TECH_DOCS += technical/protocol-v2\n TECH_DOCS += technical/racy-git\n TECH_DOCS += technical/reftable\n TECH_DOCS += technical/send-pack-pipeline\ndiff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.txt\nindex adeda0f24d3..e9efe498c01 100644\n--- a/Documentation/config/lsrefs.txt\n+++ b/Documentation/config/lsrefs.txt\n@@ -1,7 +1,7 @@\n lsrefs.unborn::\n \tMay be \"advertise\" (the default), \"allow\", or \"ignore\". If \"advertise\",\n \tthe server will respond to the client sending \"unborn\" (as described in\n-\tprotocol-v2.txt) and will advertise support for this feature during the\n+\tlinkgit:gitformat-protocol-v2[5]) and will advertise support for this feature during the\n \tprotocol v2 capability advertisement. \"allow\" is the same as\n \t\"advertise\" except that the server will not advertise support for this\n \tfeature; this is useful for load-balanced servers that cannot be\ndiff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt\nindex 756591d77b0..bf18a70a924 100644\n--- a/Documentation/config/protocol.txt\n+++ b/Documentation/config/protocol.txt\n@@ -58,6 +58,6 @@ protocol.version::\n * `1` - the original wire protocol with the addition of a version string\n in the initial response from the server.\n \n-* `2` - link:technical/protocol-v2.html[wire protocol version 2].\n+* `2` - Wire protocol version 2, see linkgit:gitformat-protocol-v2[5].\n \n --\ndiff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt\nindex 8f87b23ea86..754619222f6 100644\n--- a/Documentation/git-upload-pack.txt\n+++ b/Documentation/git-upload-pack.txt\n@@ -40,9 +40,8 @@ OPTIONS\n \tUsed by linkgit:git-http-backend[1] to serve up\n \t`$GIT_URL/info/refs?service=git-upload-pack` requests. See\n \t\"Smart Clients\" in link:technical/http-protocol.html[the HTTP\n-\ttransfer protocols] documentation and \"HTTP Transport\" in\n-\tlink:technical/protocol-v2.html[the Git Wire Protocol, Version\n-\t2] documentation. Also understood by\n+\ttransfer protocols] documentation and \"HTTP Transport\" in the\n+\tlinkgit:gitformat-protocol-v2[5] documentation. Also understood by\n \tlinkgit:git-receive-pack[1].\n \n ::\ndiff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.txt\nindex 3aa2242eb9d..614d51362c9 100644\n--- a/Documentation/gitformat-bundle.txt\n+++ b/Documentation/gitformat-bundle.txt\n@@ -27,7 +27,7 @@ FORMAT\n ------\n \n We will use ABNF notation to define the Git bundle format. See\n-link:technical/protocol-common.html for the details.\n+linkgit:gitformat-protocol-common[5] for the details.\n \n A v2 bundle looks like this:\n \ndiff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt\nsimilarity index 98%\nrename from Documentation/technical/pack-protocol.txt\nrename to Documentation/gitformat-pack-protocol.txt\nindex e13a2c064d1..b665af5b690 100644\n--- a/Documentation/technical/pack-protocol.txt\n+++ b/Documentation/gitformat-pack-protocol.txt\n@@ -1,5 +1,17 @@\n-Packfile transfer protocols\n-===========================\n+gitformat-pack-protocol(5)\n+==========================\n+\n+NAME\n+----\n+gitformat-pack-protocol - How packs are transferred over-the-wire\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n Git supports transferring data in packfiles over the ssh://, git://, http:// and\n file:// transports. There exist two sets of protocols, one for pushing\n@@ -18,7 +30,7 @@ pkt-line Format\n ---------------\n \n The descriptions below build on the pkt-line format described in\n-protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless\n+linkgit:gitformat-protocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless\n otherwise noted the usual pkt-line LF rules apply: the sender SHOULD\n include a LF, but the receiver MUST NOT complain if it is not present.\n \n@@ -707,3 +719,7 @@ An example client/server communication might look like this:\n S: 0018ok refs/heads/debug\\n\n S: 002ang refs/heads/master non-fast-forward\\n\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/gitformat-protocol-capabilities.txt\nsimilarity index 96%\nrename from Documentation/technical/protocol-capabilities.txt\nrename to Documentation/gitformat-protocol-capabilities.txt\nindex 9dfade930da..2e89f40ddb1 100644\n--- a/Documentation/technical/protocol-capabilities.txt\n+++ b/Documentation/gitformat-protocol-capabilities.txt\n@@ -1,8 +1,20 @@\n-Git Protocol Capabilities\n-=========================\n+gitformat-protocol-capabilities(5)\n+==================================\n+\n+NAME\n+----\n+gitformat-protocol-capabilities - Protocol v0 and v1 capabilities\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n NOTE: this document describes capabilities for versions 0 and 1 of the pack\n-protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]\n+protocol. For version 2, please refer to the linkgit:gitformat-protocol-v2[5]\n doc.\n \n Servers SHOULD support all capabilities defined in this document.\n@@ -77,7 +89,7 @@ interleaved with S-R-Q.\n multi_ack_detailed\n ------------------\n This is an extension of multi_ack that permits client to better\n-understand the server's in-memory state. See pack-protocol.txt,\n+understand the server's in-memory state. See linkgit:gitformat-pack-protocol[5],\n section \"Packfile Negotiation\" for more information.\n \n no-done\n@@ -281,7 +293,7 @@ a packfile upload and reference update. If the pushing client requests\n this capability, after unpacking and updating references the server\n will respond with whether the packfile unpacked successfully and if\n each reference was updated successfully. If any of those were not\n-successful, it will send back an error message. See pack-protocol.txt\n+successful, it will send back an error message. See linkgit:gitformat-pack-protocol[5]\n for example messages.\n \n report-status-v2\n@@ -292,7 +304,7 @@ adding new \"option\" directives in order to support reference rewritten by\n the \"proc-receive\" hook. The \"proc-receive\" hook may handle a command\n for a pseudo-reference which may create or update a reference with\n different name, new-oid, and old-oid. While the capability\n-'report-status' cannot report for such case. See pack-protocol.txt\n+'report-status' cannot report for such case. See linkgit:gitformat-pack-protocol[5]\n for details.\n \n delete-refs\n@@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The\n current implementation uses trace2 session IDs (see\n link:api-trace2.html[api-trace2] for details), but this may change and users of\n the session ID should not rely on this fact.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-common.txt b/Documentation/gitformat-protocol-common.txt\nsimilarity index 88%\nrename from Documentation/technical/protocol-common.txt\nrename to Documentation/gitformat-protocol-common.txt\nindex ecedb34bba5..6e1e1624e2d 100644\n--- a/Documentation/technical/protocol-common.txt\n+++ b/Documentation/gitformat-protocol-common.txt\n@@ -1,5 +1,20 @@\n-Documentation Common to Pack and Http Protocols\n-===============================================\n+gitformat-protocol-common(5)\n+============================\n+\n+NAME\n+----\n+gitformat-protocol-common - Things common to various protocols\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n+\n+This document sets defines things common to various over-the-wire\n+protocols and file formats used in Git.\n \n ABNF Notation\n -------------\n@@ -97,3 +112,7 @@ Examples (as C-style strings):\n \"000bfoobar\\n\" \"foobar\\n\"\n \"0004\" \"\"\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-v2.txt b/Documentation/gitformat-protocol-v2.txt\nsimilarity index 98%\nrename from Documentation/technical/protocol-v2.txt\nrename to Documentation/gitformat-protocol-v2.txt\nindex 8a877d27e23..ae4fcc84e37 100644\n--- a/Documentation/technical/protocol-v2.txt\n+++ b/Documentation/gitformat-protocol-v2.txt\n@@ -1,5 +1,17 @@\n-Git Wire Protocol, Version 2\n-============================\n+gitformat-protocol-v2(5)\n+========================\n+\n+NAME\n+----\n+gitformat-protocol-v2 - Git Wire Protocol, Version 2\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n This document presents a specification for a version 2 of Git's wire\n protocol. Protocol v2 will improve upon v1 in the following ways:\n@@ -26,7 +38,7 @@ Packet-Line Framing\n -------------------\n \n All communication is done using packet-line framing, just as in v1. See\n-`Documentation/technical/pack-protocol.txt` and\n+linkgit:gitformat-pack-protocol[5] and\n `Documentation/technical/protocol-common.txt` for more information.\n \n In protocol v2 these special packets will have the following semantics:\n@@ -42,7 +54,7 @@ Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`. More information can be\n-found in `pack-protocol.txt` and `http-protocol.txt`, as well as the\n+found in linkgit:gitformat-pack-protocol[5] and `http-protocol.txt`, as well as the\n `GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n@@ -566,3 +578,7 @@ and associated requested information, each separated by a single space.\n \tattr = \"size\"\n \n \tobj-info = obj-id SP obj-size\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt\nindex d79ad323e67..945c21bbc38 100644\n--- a/Documentation/technical/api-simple-ipc.txt\n+++ b/Documentation/technical/api-simple-ipc.txt\n@@ -78,7 +78,7 @@ client and an optional response message from the server. Both the\n client and server messages are unlimited in length and are terminated\n with a flush packet.\n \n-The pkt-line routines (Documentation/technical/protocol-common.txt)\n+The pkt-line routines (linkgit:gitformat-protocol-common[5])\n are used to simplify buffer management during message generation,\n transmission, and reception. A flush packet is used to mark the end\n of the message. This allows the sender to incrementally generate and\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt\nindex cc5126cfeda..9d9c7acd512 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/technical/http-protocol.txt\n@@ -222,7 +222,7 @@ smart server reply:\n S: 0000\n \n The client may send Extra Parameters (see\n-Documentation/technical/pack-protocol.txt) as a colon-separated string\n+linkgit:gitformat-pack-protocol[5]) as a colon-separated string\n in the Git-Protocol HTTP header.\n \n Uses the `--http-backend-info-refs` option to\n@@ -518,5 +518,5 @@ References\n \n http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n-link:technical/pack-protocol.html\n-link:technical/protocol-capabilities.html\n+linkgit:gitformat-pack-protocol[5]\n+linkgit:gitformat-protocol-capabilities[5]\ndiff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt\nindex aa0aa9af1c2..c6922ce6ccc 100644\n--- a/Documentation/technical/long-running-process-protocol.txt\n+++ b/Documentation/technical/long-running-process-protocol.txt\n@@ -3,7 +3,7 @@ Long-running process protocol\n \n This protocol is used when Git needs to communicate with an external\n process throughout the entire life of a single Git command. All\n-communication is in pkt-line format (see technical/protocol-common.txt)\n+communication is in pkt-line format (see linkgit:gitformat-protocol-common[5])\n over standard input and standard output.\n \n Handshake\ndiff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt\nindex a0dd7c66f24..957d6dfe375 100644\n--- a/Documentation/technical/partial-clone.txt\n+++ b/Documentation/technical/partial-clone.txt\n@@ -79,7 +79,7 @@ Design Details\n upload-pack negotiation.\n +\n This uses the existing capability discovery mechanism.\n-See \"filter\" in Documentation/technical/pack-protocol.txt.\n+See \"filter\" in linkgit:gitformat-pack-protocol[5].\n \n - Clients pass a \"filter-spec\" to clone and fetch which is passed to the\n server to request filtering during packfile construction.\ndiff --git a/command-list.txt b/command-list.txt\nindex f7dcc795e1e..f4d1f9c31b1 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -209,6 +209,10 @@ giteveryday guide\n gitfaq guide\n gitformat-bundle gitformats\n gitformat-commit-graph gitformats\n+gitformat-pack-protocol gitformats\n+gitformat-protocol-capabilities gitformats\n+gitformat-protocol-common gitformats\n+gitformat-protocol-v2 gitformats\n gitglossary guide\n githooks userformats\n gitignore userformats\ndiff --git a/t/t5551-http-fetch-smart.sh b/t/t5551-http-fetch-smart.sh\nindex f92c79c1326..a5ece8a33cc 100755\n--- a/t/t5551-http-fetch-smart.sh\n+++ b/t/t5551-http-fetch-smart.sh\n@@ -175,8 +175,8 @@ test_expect_success 'no-op half-auth fetch does not require a password' '\n \t# This is not possible with protocol v2, since both objects and refs\n \t# are obtained from the \"git-upload-pack\" path. A solution to this is\n \t# to teach the server and client to be able to inline ls-refs requests\n-\t# as an Extra Parameter (see pack-protocol.txt), so that \"info/refs\"\n-\t# can serve refs, just like it does in protocol v0.\n+\t# as an Extra Parameter (see \"git help gitformat-pack-protocol\"), so that\n+\t# \"info/refs\" can serve refs, just like it does in protocol v0.\n \tGIT_TEST_PROTOCOL_VERSION=0 git --git-dir=half-auth fetch &&\n \texpect_askpass none\n '\n-- \n2.34.1.929.ge922d848c7a\n\n"},{"id":"443913","messageId":"patch-v2-5.5-5cb41bb0dcb-20211212T194047Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v2-0.5-00000000000-20211212T194047Z-avarab@gmail.com","subject":"[PATCH v2 5/5] docs: move {index,signature,bitmap,chunk}-format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-12-12T19:49:40Z","receivedAt":"2021-12-12T19:51:07Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space.\n\nBy moving these we can properly link from the newly created\ngitformat-commit-graph do to a gitformat-chunk-format manpage we build\nby default. Let's also move the rest over for consistency.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 6 ++-\n ...bitmap-format.txt => gitformat-bitmap.txt} | 38 +++++++++++++++----\n .../chunk-format.txt => gitformat-chunk.txt} | 21 +++++++++-\n Documentation/gitformat-commit-graph.txt | 2 +-\n .../index-format.txt => gitformat-index.txt} | 20 +++++++++-\n ...ure-format.txt => gitformat-signature.txt} | 21 ++++++++--\n Documentation/technical/pack-format.txt | 2 +-\n command-list.txt | 4 ++\n 8 files changed, 97 insertions(+), 17 deletions(-)\n rename Documentation/{technical/bitmap-format.txt => gitformat-bitmap.txt} (91%)\n rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (94%)\n rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)\n rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex ba587b75a51..f8a84173667 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -21,12 +21,16 @@ MAN1_TXT += gitweb.txt\n \n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n+MAN5_TXT += gitformat-bitmap.txt\n MAN5_TXT += gitformat-bundle.txt\n+MAN5_TXT += gitformat-chunk.txt\n MAN5_TXT += gitformat-commit-graph.txt\n+MAN5_TXT += gitformat-index.txt\n MAN5_TXT += gitformat-pack-protocol.txt\n MAN5_TXT += gitformat-protocol-capabilities.txt\n MAN5_TXT += gitformat-protocol-common.txt\n MAN5_TXT += gitformat-protocol-v2.txt\n+MAN5_TXT += gitformat-signature.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -98,7 +102,6 @@ TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n-TECH_DOCS += technical/index-format\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-format\n@@ -109,7 +112,6 @@ TECH_DOCS += technical/racy-git\n TECH_DOCS += technical/reftable\n TECH_DOCS += technical/send-pack-pipeline\n TECH_DOCS += technical/shallow\n-TECH_DOCS += technical/signature-format\n TECH_DOCS += technical/trivial-merge\n SP_ARTICLES += $(TECH_DOCS)\n SP_ARTICLES += technical/api-index\ndiff --git a/Documentation/technical/bitmap-format.txt b/Documentation/gitformat-bitmap.txt\nsimilarity index 91%\nrename from Documentation/technical/bitmap-format.txt\nrename to Documentation/gitformat-bitmap.txt\nindex 04b3ec21785..b239dc5cbe1 100644\n--- a/Documentation/technical/bitmap-format.txt\n+++ b/Documentation/gitformat-bitmap.txt\n@@ -1,7 +1,25 @@\n-GIT bitmap v1 format\n-====================\n+gitformat-bitmap(5)\n+===================\n \n-== Pack and multi-pack bitmaps\n+NAME\n+----\n+gitformat-bitmap - The bitmap file format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/*.bitmap\n+\n+DESCRIPTION\n+-----------\n+\n+Bitmaps are a file format associated with .pack files. See\n+link:technical/pack-format.html[the pack format documentation] and\n+linkgit:git-pack-objects[1].\n+\n+== GIT bitmap v1 format\n+\n+=== Pack and multi-pack bitmaps\n \n Bitmaps store reachability information about the set of objects in a packfile,\n or a multi-pack index (MIDX). The former is defined obviously, and the latter is\n@@ -37,7 +55,7 @@ Certain bitmap extensions are supported (see: Appendix B). No extensions are\n required for bitmaps corresponding to packfiles. For bitmaps that correspond to\n MIDXs, both the bit-cache and rev-cache extensions are required.\n \n-== On-disk format\n+=== On-disk format\n \n \t- A header appears at the beginning:\n \n@@ -131,7 +149,8 @@ MIDXs, both the bit-cache and rev-cache extensions are required.\n \n \t\t- The compressed bitmap itself, see Appendix A.\n \n-== Appendix A: Serialization format for an EWAH bitmap\n+Appendix A - Serialization format for an EWAH bitmap\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n Ewah bitmaps are serialized in the same protocol as the JAVAEWAH\n library, making them backwards compatible with the JGit\n@@ -179,13 +198,14 @@ chunk. For efficient appending to the bitstream, the EWAH stores a\n pointer to the last RLW in the stream.\n \n \n-== Appendix B: Optional Bitmap Sections\n+Appendix B - Optional Bitmap Sections\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n These sections may or may not be present in the `.bitmap` file; their\n presence is indicated by the header flags section described above.\n \n Name-hash cache\n----------------\n+~~~~~~~~~~~~~~~\n \n If the BITMAP_OPT_HASH_CACHE flag is set, the end of the bitmap contains\n a cache of 32-bit values, one per object in the pack/MIDX. The value at\n@@ -205,3 +225,7 @@ Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag.\n If implementations want to choose a different hashing scheme, they are\n free to do so, but MUST allocate a new header flag (because comparing\n hashes made under two different schemes would be pointless).\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt\nsimilarity index 94%\nrename from Documentation/technical/chunk-format.txt\nrename to Documentation/gitformat-chunk.txt\nindex f36ce42f37c..8ddf21e3277 100644\n--- a/Documentation/technical/chunk-format.txt\n+++ b/Documentation/gitformat-chunk.txt\n@@ -1,5 +1,18 @@\n-Chunk-based file formats\n-========================\n+gitformat-chunk(5)\n+==================\n+\n+NAME\n+----\n+gitformat-chunk - Chunk-based file formats\n+\n+SYNOPSIS\n+--------\n+\n+Used by linkgit:gitformat-commit-graph[5] and the \"MIDX\" format (see\n+link:technical/pack-format.html[the pack format documentation]).\n+\n+DESCRIPTION\n+-----------\n \n Some file formats in Git use a common concept of \"chunks\" to describe\n sections of the file. This allows structured access to a large file by\n@@ -114,3 +127,7 @@ for future formats:\n in `midx.c` for how the chunk-format API is used to write and\n parse the multi-pack-index file format documented in\n link:technical/pack-format.html[the multi-pack-index file format].\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt\nindex 25eb131dcd2..5f839eda058 100644\n--- a/Documentation/gitformat-commit-graph.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -75,7 +75,7 @@ All multi-byte numbers are in network byte order.\n ID appears at most once.\n \n The CHUNK LOOKUP matches the table of contents from\n- link:technical/chunk-format.html[the chunk-based file format].\n+ the chunk-based file format, see linkgit:gitformat-chunk[5]\n \n The remaining data in the body is described one chunk at a time, and\n these chunks may be given in any order. Chunks are required unless\ndiff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt\nsimilarity index 98%\nrename from Documentation/technical/index-format.txt\nrename to Documentation/gitformat-index.txt\nindex 65da0daaa56..41491d2a075 100644\n--- a/Documentation/technical/index-format.txt\n+++ b/Documentation/gitformat-index.txt\n@@ -1,5 +1,19 @@\n+gitformat-index(5)\n+==================\n+\n+NAME\n+----\n+gitformat-index - Git index format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/index\n+\n+DESCRIPTION\n+-----------\n+\n Git index format\n-================\n \n == The Git index file has the following format\n \n@@ -404,3 +418,7 @@ The remaining data of each directory block is grouped by type:\n with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,\n tools should avoid interacting with a sparse index unless they understand\n this extension.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt\nsimilarity index 96%\nrename from Documentation/technical/signature-format.txt\nrename to Documentation/gitformat-signature.txt\nindex 166721be6f6..a249869fafa 100644\n--- a/Documentation/technical/signature-format.txt\n+++ b/Documentation/gitformat-signature.txt\n@@ -1,7 +1,18 @@\n-Git signature format\n-====================\n+gitformat-signature(5)\n+======================\n \n-== Overview\n+NAME\n+----\n+gitformat-signature - Git cryptographic signature formats\n+\n+SYNOPSIS\n+--------\n+[verse]\n+<[tag|commit] object header(s)>\n+\n+\n+DESCRIPTION\n+-----------\n \n Git uses cryptographic signatures in various places, currently objects (tags,\n commits, mergetags) and transactions (pushes). In every case, the command which\n@@ -200,3 +211,7 @@ Date: Wed Jun 15 09:13:29 2016 +0000\n # gpg: There is no indication that the signature belongs to the owner.\n # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt\nindex 8d2f42f29e5..79cc83aead0 100644\n--- a/Documentation/technical/pack-format.txt\n+++ b/Documentation/technical/pack-format.txt\n@@ -337,7 +337,7 @@ CHUNK LOOKUP:\n \t using the next chunk position if necessary.)\n \n \tThe CHUNK LOOKUP matches the table of contents from\n-\tlink:technical/chunk-format.html[the chunk-based file format].\n+\tthe chunk-based file format, see linkgit:gitformat-chunk[5].\n \n \tThe remaining data in the body is described one chunk at a time, and\n \tthese chunks may be given in any order. Chunks are required unless\ndiff --git a/command-list.txt b/command-list.txt\nindex f4d1f9c31b1..42093fd5a07 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -207,12 +207,16 @@ gitcvs-migration guide\n gitdiffcore guide\n giteveryday guide\n gitfaq guide\n+gitformat-bitmap gitformats\n gitformat-bundle gitformats\n+gitformat-chunk gitformats\n gitformat-commit-graph gitformats\n+gitformat-index gitformats\n gitformat-pack-protocol gitformats\n gitformat-protocol-capabilities gitformats\n gitformat-protocol-common gitformats\n gitformat-protocol-v2 gitformats\n+gitformat-signature gitformats\n gitglossary guide\n githooks userformats\n gitignore userformats\n-- \n2.34.1.929.ge922d848c7a\n\n"},{"id":"443935","messageId":"CAPig+cRb5G7y+Sn3+dQYQq51mTCDTUg1mcrGLjJJ3uoreJ0dsQ@mail.gmail.com","threadId":"56715","inReplyTo":"patch-v2-2.5-b2d73f8c9da-20211212T194047Z-avarab@gmail.com","subject":"Re: [PATCH v2 2/5] git docs: create a \"Git file and wire formats\" section","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-12-12T22:30:22Z","receivedAt":"2021-12-12T22:30:35Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sun, Dec 12, 2021 at 4:23 PM Ævar Arnfjörð Bjarmason\n wrote:\n> diff --git a/help.c b/help.c\n> @@ -38,6 +38,7 @@ static struct category_description main_categories[] = {\n> + { CAT_gitformats, N_(\"Internal file- and wire formats formats\") },\n\nShould this be: s/file-/file/ ?\n"},{"id":"443971","messageId":"211213.86y24o97bi.gmgdl@evledraar.gmail.com","threadId":"56715","inReplyTo":"CAPig+cRb5G7y+Sn3+dQYQq51mTCDTUg1mcrGLjJJ3uoreJ0dsQ@mail.gmail.com","subject":"Re: [PATCH v2 2/5] git docs: create a \"Git file and wire formats\" section","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-12-13T09:33:32Z","receivedAt":"2021-12-13T09:36:06Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Sun, Dec 12 2021, Eric Sunshine wrote:\n\n> On Sun, Dec 12, 2021 at 4:23 PM Ævar Arnfjörð Bjarmason\n> wrote:\n>> diff --git a/help.c b/help.c\n>> @@ -38,6 +38,7 @@ static struct category_description main_categories[] = {\n>> + { CAT_gitformats, N_(\"Internal file- and wire formats formats\") },\n>\n> Should this be: s/file-/file/ ?\n\nI meant to write it like that, i.e. as a shorthand for \"Internal file\nformats and wire formats\", but I see I included \"formats\" twice, which I\ndidn't intend to :)\n\nAnyway, it's probably best to just drop the \"-\" there, and of course get\nrid of the \"formats formats\" for just \"formats\".\n"},{"id":"458909","messageId":"patch-v3-1.7-929d9192828-20220712T195419Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com","subject":"[PATCH v3 1/7] git docs: split \"User-facing file formats\" off from \"Guides\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-12T20:06:56Z","receivedAt":"2022-07-12T20:07:18Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"User-facing file formats\" section in the main \"git help\ngit\" manual page. The \"Guides\" section was added to the manual page in\nf442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense\nto list all that documentation.\n\nBut placing e.g. \"gitignore(5)\" in it is stretching the meaning of\nwhat a \"guide\" is, ideally that section should list things similar to\n\"giteveryday(7)\" and \"gitcore-tutorial(7)\".\n\nWe take a wide view of what's considered a \"user format\", it's not\njust a file format, but e.g. githooks(5) also belongs, since the\nlayout of the \".git/hooks/\" and the placement of hooks in it is\nsomething the user might be expected to interact with.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-help.txt | 13 +++++++++----\n Documentation/git.txt | 7 +++++++\n Makefile | 1 +\n builtin/help.c | 10 +++++++++-\n command-list.txt | 16 ++++++++++------\n help.c | 17 ++++++++++++++++-\n help.h | 1 +\n t/t0012-help.sh | 12 +++++++++++-\n 9 files changed, 65 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 4f801f4e4c9..08b896a3c4c 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchingrepositories.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n+\tcmds-userformats.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\n \ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 239c68db457..6c285709040 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -9,14 +9,15 @@ SYNOPSIS\n --------\n [verse]\n 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\n-'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n+'git help' [[-i|--info] [-m|--man] [-w|--web]] [||]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n+'git help' [--user-formats]\n \n DESCRIPTION\n -----------\n \n-With no options and no '' or '' given, the synopsis of the 'git'\n+With no options and no '', '' or '' given, the synopsis of the 'git'\n command and a list of the most commonly used Git commands are printed\n on the standard output.\n \n@@ -26,8 +27,8 @@ printed on the standard output.\n If the option `--guides` or `-g` is given, a list of the\n Git concept guides is also printed on the standard output.\n \n-If a command, or a guide, is given, a manual page for that command or\n-guide is brought up. The 'man' program is used by default for this\n+If a command or other documentation is given, the relevant manual page\n+will be brought up. The 'man' program is used by default for this\n purpose, but this can be overridden by other options or configuration\n variables.\n \n@@ -69,6 +70,10 @@ OPTIONS\n --guides::\n \tPrints a list of the Git concept guides on the standard output.\n \n+--user-formats::\n+\tPrints a list of the Git user-facing format documentation on\n+\tthe standard output.\n+\n -i::\n --info::\n \tDisplay manual page for the command in the 'info' format. The\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 302607a4967..9b03bbc3851 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -339,6 +339,13 @@ The following documentation pages are guides about Git concepts.\n \n include::cmds-guide.txt[]\n \n+User-facing file formats\n+------------------------\n+\n+This documentation discusses file formats that users are expected to\n+edit. These can also be listed with 'git help --user-formats'.\n+\n+include::cmds-userformats.txt[]\n \n Configuration Mechanism\n -----------------------\ndiff --git a/Makefile b/Makefile\nindex 04d0fd1fe60..e24db1d52e2 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -3489,6 +3489,7 @@ check-docs::\n \t\tsed -e '1,/^### command list/d' \\\n \t\t -e '/^#/d' \\\n \t\t -e '/guide$$/d' \\\n+\t\t -e '/formats$$/d' \\\n \t\t -e 's/[ \t].*//' \\\n \t\t -e 's/^/listed /' command-list.txt; \\\n \t\t$(MAKE) -C Documentation print-man1 | \\\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 222f994f863..b0164b774c2 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -43,6 +43,7 @@ static enum help_action {\n \tHELP_ACTION_ALL = 1,\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n+\tHELP_ACTION_USER_FORMATS,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -69,6 +70,8 @@ static struct option builtin_help_options[] = {\n \n \tOPT_CMDMODE('g', \"guides\", &cmd_mode, N_(\"print list of useful guides\"),\n \t\t HELP_ACTION_GUIDES),\n+\tOPT_CMDMODE(0, \"user-formats\", &cmd_mode, N_(\"print list of user-facing file formats\"),\n+\t\t HELP_ACTION_USER_FORMATS),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -81,9 +84,10 @@ static struct option builtin_help_options[] = {\n \n static const char * const builtin_help_usage[] = {\n \t\"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n-\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] []\"),\n+\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [|]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n+\t\"git help [--user-formats]\",\n \tNULL\n };\n \n@@ -654,6 +658,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\topt_mode_usage(argc, \"--config-for-completion\", help_format);\n \t\tlist_config_help(SHOW_CONFIG_VARS);\n \t\treturn 0;\n+\tcase HELP_ACTION_USER_FORMATS:\n+\t\topt_mode_usage(argc, \"--user-formats\", help_format);\n+\t\tlist_user_formats_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n \t\t\t help_format);\ndiff --git a/command-list.txt b/command-list.txt\nindex 9bd6f3c48f4..c1eace8f7ad 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -43,6 +43,10 @@\n # specified here, which can only have \"guide\" attribute and nothing\n # else.\n #\n+# User-facing file formats such as documentation for the .gitmodules,\n+# .mailmap etc. files lives in man section 5. These entries can only\n+# have the \"userformats\" attribute and nothing else.\n+#\n ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -192,7 +196,7 @@ git-verify-tag ancillaryinterrogators\n git-whatchanged ancillaryinterrogators complete\n git-worktree mainporcelain\n git-write-tree plumbingmanipulators\n-gitattributes guide\n+gitattributes userformats\n gitcli guide\n gitcore-tutorial guide\n gitcredentials guide\n@@ -201,14 +205,14 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitglossary guide\n-githooks guide\n-gitignore guide\n+githooks userformats\n+gitignore userformats\n gitk mainporcelain\n-gitmailmap guide\n-gitmodules guide\n+gitmailmap userformats\n+gitmodules userformats\n gitnamespaces guide\n gitremote-helpers guide\n-gitrepository-layout guide\n+gitrepository-layout userformats\n gitrevisions guide\n gitsubmodules guide\n gittutorial guide\ndiff --git a/help.c b/help.c\nindex 41c41c2aa11..51bfc28661c 100644\n--- a/help.c\n+++ b/help.c\n@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_plumbinginterrogators, N_(\"Low-level Commands / Interrogators\") },\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n+\t{ CAT_userformats, N_(\"Git user-facing file formats\") },\n \t{ 0, NULL }\n };\n \n@@ -47,8 +48,12 @@ static const char *drop_prefix(const char *name, uint32_t category)\n \n \tif (skip_prefix(name, \"git-\", &new_name))\n \t\treturn new_name;\n-\tif (category == CAT_guide && skip_prefix(name, \"git\", &new_name))\n+\tswitch (category) {\n+\tcase CAT_guide:\n+\tcase CAT_userformats:\n+\t\tskip_prefix(name, \"git\", &new_name);\n \t\treturn new_name;\n+\t}\n \treturn name;\n \n }\n@@ -426,6 +431,16 @@ void list_guides_help(void)\n \tputchar('\\n');\n }\n \n+void list_user_formats_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_userformats, N_(\"Git user-facing file formats:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex 971a3ad855a..d8b744178ec 100644\n--- a/help.h\n+++ b/help.h\n@@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num)\n void list_common_cmds_help(void);\n void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n+void list_user_formats_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex 6c33a436901..91b5318aa32 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -44,6 +44,8 @@ test_expect_success 'invalid usage' '\n \ttest_expect_code 129 git help -g add &&\n \ttest_expect_code 129 git help -a -g &&\n \n+\ttest_expect_code 129 git help --user-formats add &&\n+\n \ttest_expect_code 129 git help -g -c &&\n \ttest_expect_code 129 git help --config-for-completion add &&\n \ttest_expect_code 129 git help --config-sections-for-completion add\n@@ -104,9 +106,9 @@ test_expect_success 'git help' '\n \ttest_i18ngrep \"^ commit \" help.output &&\n \ttest_i18ngrep \"^ fetch \" help.output\n '\n+\n test_expect_success 'git help -g' '\n \tgit help -g >help.output &&\n-\ttest_i18ngrep \"^ attributes \" help.output &&\n \ttest_i18ngrep \"^ everyday \" help.output &&\n \ttest_i18ngrep \"^ tutorial \" help.output\n '\n@@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' '\n \ttest_cmp expect test-browser.log\n '\n \n+test_expect_success 'git help --user-formats' '\n+\tgit help --user-formats >help.output &&\n+\tgrep \"^ attributes \" help.output &&\n+\tgrep \"^ mailmap \" help.output\n+'\n+\n test_expect_success 'git help -c' '\n \tgit help -c >help.output &&\n \tcat >expect <<-\\EOF &&\n@@ -220,6 +228,8 @@ test_expect_success \"'git help -a' section spacing\" '\n \tLow-level Commands / Syncing Repositories\n \n \tLow-level Commands / Internal Helpers\n+\n+\tGit user-facing file formats\n \tEOF\n \ttest_cmp expect actual\n '\n-- \n2.37.0.932.g7b7031e73bc\n\n"},{"id":"458910","messageId":"patch-v3-2.7-1fd57d5caf4-20220712T195419Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com","subject":"[PATCH v3 2/7] git docs: create a \"Git file formats and protocols\" section","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-12T20:06:57Z","receivedAt":"2022-07-12T20:07:19Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"Git file formats and protocols\" section in the main \"git help\ngit\" manual page and start moving the documentation that now lives in\n\"Documentation/technical/*.git\" over to it. This compliments the newly\nadded and adjacent \"User-facing file formats\" section.\n\nThis makes the technical documentation more accessible and\ndiscoverable. Before this we wouldn't install it by default, and had\nno ability to build man page versions of them. The links to them from\nour existing documentation link to the generated HTML version of these\ndocs.\n\nSo let's start moving those over, starting with just the\n\"bundle-format.txt\" documentation added in 7378ec90e1c (doc: describe\nGit bundle format, 2020-02-07). We'll now have a new\ngitformat-bundle(5) man page. Subsequent commits will move more git\ninternal format documentation over.\n\nUnfortunately the syntax of the current Documentation/technical/*.txt\nis not the same (when it comes to section headings etc.) as our\nDocumentation/*.txt documentation, so change the relevant bits of\nsyntax as we're moving this over.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 3 +-\n Documentation/git-bundle.txt | 12 +++--\n Documentation/git-help.txt | 1 +\n Documentation/git.txt | 8 ++++\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++---\n Documentation/lint-man-section-order.perl | 3 ++\n builtin/help.c | 8 ++++\n command-list.txt | 5 +++\n help.c | 12 +++++\n help.h | 1 +\n t/t0012-help.sh | 2 +\n 11 files changed, 87 insertions(+), 12 deletions(-)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 08b896a3c4c..404139274e7 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -24,6 +24,7 @@ MAN1_TXT += gitweb.txt\n \n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n+MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -95,7 +96,6 @@ TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n-TECH_DOCS += technical/bundle-format\n TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n@@ -291,6 +291,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n \tcmds-userformats.txt \\\n+\tcmds-gitformats.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\n \ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 7685b570455..1aeae09f082 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -56,10 +56,9 @@ using \"thin packs\", bundles created using exclusions are smaller in\n size. That they're \"thin\" under the hood is merely noted here as a\n curiosity, and as a reference to other documentation.\n \n-See link:technical/bundle-format.html[the `bundle-format`\n-documentation] for more details and the discussion of \"thin pack\" in\n-link:technical/pack-format.html[the pack format documentation] for\n-further details.\n+See linkgit:gitformat-bundle[5] for more details and the discussion of\n+\"thin pack\" in link:technical/pack-format.html[the pack format\n+documentation] for further details.\n \n OPTIONS\n -------\n@@ -337,6 +336,11 @@ You can also see what references it offers:\n $ git ls-remote mybundle\n ----------------\n \n+FILE FORMAT\n+-----------\n+\n+See linkgit:gitformat-bundle[5].\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 6c285709040..a91126ba802 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -13,6 +13,7 @@ SYNOPSIS\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n 'git help' [--user-formats]\n+'git help' [--git-formats]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 9b03bbc3851..1980a0e29cd 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -347,6 +347,14 @@ edit. These can also be listed with 'git help --user-formats'.\n \n include::cmds-userformats.txt[]\n \n+Git file formats and protocols\n+------------------------------\n+\n+This documentation discusses the file formats and protocols that git\n+itself uses. These can also be listed with 'git help --git-formats'.\n+\n+include::cmds-gitformats.txt[]\n+\n Configuration Mechanism\n -----------------------\n \ndiff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt\nsimilarity index 79%\nrename from Documentation/technical/bundle-format.txt\nrename to Documentation/gitformat-bundle.txt\nindex b9be8644cf5..6a9d9e5bf6f 100644\n--- a/Documentation/technical/bundle-format.txt\n+++ b/Documentation/gitformat-bundle.txt\n@@ -1,11 +1,33 @@\n-= Git bundle v2 format\n+gitformat-bundle(5)\n+===================\n \n-The Git bundle format is a format that represents both refs and Git objects.\n+NAME\n+----\n+gitformat-bundle - The bundle file format\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+*.bundle\n+*.bdl\n+\n+DESCRIPTION\n+-----------\n+\n+The Git bundle format is a format that represents both refs and Git\n+objects. A bundle is a header in a format similar to\n+linkgit:git-show-ref[1] followed by a pack in *.pack format.\n \n-== Format\n+The format is created and read by the linkgit:git-bundle[1] command,\n+and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1].\n+\n+\n+FORMAT\n+------\n \n We will use ABNF notation to define the Git bundle format. See\n-protocol-common.txt for the details.\n+link:technical/protocol-common.html for the details.\n \n A v2 bundle looks like this:\n \n@@ -36,7 +58,9 @@ value = *(%01-09 / %0b-FF)\n pack = ... ; packfile\n ----\n \n-== Semantics\n+\n+SEMANTICS\n+---------\n \n A Git bundle consists of several parts.\n \n@@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id.\n This is a comment and it has no specific meaning. The writer of the bundle MAY\n put any string here. The reader of the bundle MUST ignore the comment.\n \n-=== Note on the shallow clone and a Git bundle\n+Note on the shallow clone and a Git bundle\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n Note that the prerequisites does not represent a shallow-clone boundary. The\n semantics of the prerequisites and the shallow-clone boundaries are different,\n and the Git bundle v2 format cannot represent a shallow clone repository.\n \n-== Capabilities\n+CAPABILITIES\n+------------\n \n Because there is no opportunity for negotiation, unknown capabilities cause 'git\n bundle' to abort.\n@@ -79,3 +105,7 @@ bundle' to abort.\n * `filter` specifies an object filter as in the `--filter` option in\n linkgit:git-rev-list[1]. The resulting pack-file must be marked as a\n `.promisor` pack-file after it is unbundled.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl\nindex 425377dfeb7..02408a0062f 100755\n--- a/Documentation/lint-man-section-order.perl\n+++ b/Documentation/lint-man-section-order.perl\n@@ -32,6 +32,9 @@\n \t\t'SEE ALSO' => {\n \t\t\torder => $order++,\n \t\t},\n+\t\t'FILE FORMAT' => {\n+\t\t\torder => $order++,\n+\t\t},\n \t\t'GIT' => {\n \t\t\trequired => 1,\n \t\t\torder => $order++,\ndiff --git a/builtin/help.c b/builtin/help.c\nindex b0164b774c2..3ff2c5d17a7 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -44,6 +44,7 @@ static enum help_action {\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n \tHELP_ACTION_USER_FORMATS,\n+\tHELP_ACTION_GIT_FORMATS,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -72,6 +73,8 @@ static struct option builtin_help_options[] = {\n \t\t HELP_ACTION_GUIDES),\n \tOPT_CMDMODE(0, \"user-formats\", &cmd_mode, N_(\"print list of user-facing file formats\"),\n \t\t HELP_ACTION_USER_FORMATS),\n+\tOPT_CMDMODE(0, \"git-formats\", &cmd_mode, N_(\"print list of internal file formats and network protocols\"),\n+\t\t HELP_ACTION_GIT_FORMATS),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -88,6 +91,7 @@ static const char * const builtin_help_usage[] = {\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n \t\"git help [--user-formats]\",\n+\t\"git help [--git-formats]\",\n \tNULL\n };\n \n@@ -662,6 +666,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\topt_mode_usage(argc, \"--user-formats\", help_format);\n \t\tlist_user_formats_help();\n \t\treturn 0;\n+\tcase HELP_ACTION_GIT_FORMATS:\n+\t\topt_mode_usage(argc, \"--git-formats\", help_format);\n+\t\tlist_git_formats_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n \t\t\t help_format);\ndiff --git a/command-list.txt b/command-list.txt\nindex c1eace8f7ad..1794a7279bc 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -47,6 +47,10 @@\n # .mailmap etc. files lives in man section 5. These entries can only\n # have the \"userformats\" attribute and nothing else.\n #\n+# Git internal file formats and protocols, such as documentation for the\n+# *.bundle format lives in man section 5. These entries can only have\n+# the \"gitformats\" attribute and nothing else.\n+#\n ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -204,6 +208,7 @@ gitcvs-migration guide\n gitdiffcore guide\n giteveryday guide\n gitfaq guide\n+gitformat-bundle gitformats\n gitglossary guide\n githooks userformats\n gitignore userformats\ndiff --git a/help.c b/help.c\nindex 51bfc28661c..cce4dbb3f71 100644\n--- a/help.c\n+++ b/help.c\n@@ -39,6 +39,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n \t{ CAT_userformats, N_(\"Git user-facing file formats\") },\n+\t{ CAT_gitformats, N_(\"Git internal file formats and protocols\") },\n \t{ 0, NULL }\n };\n \n@@ -51,6 +52,7 @@ static const char *drop_prefix(const char *name, uint32_t category)\n \tswitch (category) {\n \tcase CAT_guide:\n \tcase CAT_userformats:\n+\tcase CAT_gitformats:\n \t\tskip_prefix(name, \"git\", &new_name);\n \t\treturn new_name;\n \t}\n@@ -441,6 +443,16 @@ void list_user_formats_help(void)\n \tputchar('\\n');\n }\n \n+void list_git_formats_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_gitformats, N_(\"Internal file formats and protocols:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex d8b744178ec..173bd890ce3 100644\n--- a/help.h\n+++ b/help.h\n@@ -23,6 +23,7 @@ void list_common_cmds_help(void);\n void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n void list_user_formats_help(void);\n+void list_git_formats_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex 91b5318aa32..0e291cb91e8 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -230,6 +230,8 @@ test_expect_success \"'git help -a' section spacing\" '\n \tLow-level Commands / Internal Helpers\n \n \tGit user-facing file formats\n+\n+\tGit internal file formats and protocols\n \tEOF\n \ttest_cmp expect actual\n '\n-- \n2.37.0.932.g7b7031e73bc\n\n"},{"id":"458912","messageId":"cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v2-0.5-00000000000-20211212T194047Z-avarab@gmail.com","subject":"[PATCH v3 0/7] git doc + \"git help\": move \"format\" docs from technical/*","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-12T20:06:55Z","receivedAt":"2022-07-12T20:07:22Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"This series improves the accessability of our documentation by moving\nmuch of the documentation about user and developer-facing \"formats\" to\nour main documentation namespace.\n\nI.e. they'll be installed as part of \"make install-doc\" etc, most of\nour docs avoid referring to these, and when they do they refer to the\nhtml versions. Now the manual pages will be self-contained, without\nany need to visit these in a browser.\n\nA \"user format\" is defined broadly as a file format (or similar) that\na user might need to interact with or edit. This contains some manual\npages that are now in --guides:\n\n\t$ git help --user-formats\n\tGit user-facing file formats:\n\t attributes Defining attributes per path\n\t hooks Hooks used by Git\n\t ignore Specifies intentionally untracked files to ignore\n\t mailmap Map author/committer names and/or E-Mail addresses\n\t modules Defining submodule properties\n\t repository-layout Git Repository Layout\n\nAll of that exists already, it's just in its own category now,\ni.e. not with the likes of \"tutorial\" etc.\n\nBut this is new, all of these docs were previously languishing in\nDocumentation/techical/, but are now built as manual pages:\n\n\t$ git help --git-formats\n\tInternal file formats and protocols:\n\t format-bundle The bundle file format\n\t format-chunk Chunk-based file formats\n\t format-commit-graph Git commit graph format\n\t format-index Git index format\n\t format-multi-pack-index The multi-pack-index file format\n\t format-pack Git pack format\n\t format-pack-bitmap The bitmap file format\n\t format-pack-cruft The cruft pack file format\n\t format-pack-protocol How packs are transferred over-the-wire\n\t format-protocol-capabilities Protocol v0 and v1 capabilities\n\t format-protocol-common Things common to various protocols\n\t format-protocol-http Git HTTP-based protocols\n\t format-protocol-v2 Git Wire Protocol, Version 2\n\t format-signature Git cryptographic signature formats\n\nSee [1] for the v2. This series took a while to re-roll because there\nhave been various painful conflicts in-flight work in\nDocumentation/techical/ in the interim. There's a minor conflict here\nwith ac/bitmap-lookup-table, see below:\n\nChanges since v2:\n\n * Fix SYNOPSIS, usage etc.\n * The --user-formats and --git-formats now skip the \"git\" prefix,\n like --guides did.\n * Updated the help descriptions / title sections (see range-diff)\n * The cruft pack format is now included, as well as this being\n re-rolled for other changes in Documentation/techical/\n * Moved all the pack formats under gitformat-pack-*\n * Fixed some more cross-links to the now-moved\n Documentation/techical/ docs.\n * Move more docs to --git-formats (which previously conflicted)\n\n1. https://lore.kernel.org/git/cover-v2-0.5-00000000000-20211212T194047Z-avarab@gmail.com/\n\nFor Junio: There's a conflict here with ac/bitmap-lookup-table in\n\"seen\", which can be solved thusly (remerge-diff output):\n\t\n\tdiff --git a/Documentation/gitformat-pack-bitmap.txt b/Documentation/gitformat-pack-bitmap.txt\n\tremerge CONFLICT (content): Merge conflict in Documentation/gitformat-pack-bitmap.txt\n\tindex b01a3a202e8..136fd0c1b71 100644\n\t--- a/Documentation/gitformat-pack-bitmap.txt\n\t+++ b/Documentation/gitformat-pack-bitmap.txt\n\t@@ -248,13 +248,8 @@ If implementations want to choose a different hashing scheme, they are\n\t free to do so, but MUST allocate a new header flag (because comparing\n\t hashes made under two different schemes would be pointless).\n\t \n\t-<<<<<<< aabdc4a4151 (docs: move multi-pack-index docs to man section 5):Documentation/gitformat-pack-bitmap.txt\n\t-GIT\n\t----\n\t-Part of the linkgit:git[1] suite\n\t-=======\n\t Commit lookup table\n\t--------------------\n\t+~~~~~~~~~~~~~~~~~~~\n\t \n\t If the BITMAP_OPT_LOOKUP_TABLE flag is set, the last `N * (4 + 8 + 4)`\n\t bytes (preceding the name-hash cache and trailing hash) of the `.bitmap`\n\t@@ -280,4 +275,7 @@ triplet is -\n\t \txor_row (4 byte integer, network byte order): ::\n\t \tThe position of the triplet whose bitmap is used to compress\n\t \tthis one, or `0xffffffff` if no such bitmap exists.\n\t->>>>>>> 135e1ec09aa (Merge branch 'sa/cat-file-mailmap' into seen):Documentation/technical/bitmap-format.txt\n\t+\n\t+GIT\n\t+---\n\t+Part of the linkgit:git[1] suite\n\nI.e. the new \"GIT\" section needs to come last (as check-docs will\nreport), but otherwise it's a union of the two, *except* that the\n\"Commit lookup table\" needs to use \"~\" for the section, not \"-\".\n\t\n\nÆvar Arnfjörð Bjarmason (7):\n git docs: split \"User-facing file formats\" off from \"Guides\"\n git docs: create a \"Git file formats and protocols\" section\n docs: move commit-graph format docs to man section 5\n docs: move protocol-related docs to man section 5\n docs: move pack format docs to man section 5\n docs: move http-protocol docs to man section 5\n docs: move multi-pack-index docs to man section 5\n\n Documentation/Makefile | 28 ++++++-----\n Documentation/config/lsrefs.txt | 2 +-\n Documentation/config/pack.txt | 2 +-\n Documentation/config/protocol.txt | 2 +-\n Documentation/git-bundle.txt | 11 +++--\n Documentation/git-commit-graph.txt | 5 ++\n Documentation/git-help.txt | 14 ++++--\n Documentation/git-multi-pack-index.txt | 7 +--\n Documentation/git-upload-pack.txt | 7 ++-\n Documentation/git.txt | 15 ++++++\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++---\n .../chunk-format.txt => gitformat-chunk.txt} | 27 ++++++++--\n ...-format.txt => gitformat-commit-graph.txt} | 49 +++++++++++++------\n .../index-format.txt => gitformat-index.txt} | 22 ++++++++-\n ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++-\n ...p-format.txt => gitformat-pack-bitmap.txt} | 38 +++++++++++---\n ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++-\n ...otocol.txt => gitformat-pack-protocol.txt} | 26 ++++++++--\n .../pack-format.txt => gitformat-pack.txt} | 39 +++++++++++++--\n ...xt => gitformat-protocol-capabilities.txt} | 28 ++++++++---\n ...mmon.txt => gitformat-protocol-common.txt} | 23 ++++++++-\n ...otocol.txt => gitformat-protocol-http.txt} | 35 ++++++++++---\n ...tocol-v2.txt => gitformat-protocol-v2.txt} | 26 ++++++++--\n ...ure-format.txt => gitformat-signature.txt} | 21 ++++++--\n .../howto/recover-corrupted-object-harder.txt | 2 +-\n Documentation/lint-man-section-order.perl | 3 ++\n Documentation/technical/api-simple-ipc.txt | 2 +-\n .../technical/hash-function-transition.txt | 2 +-\n .../long-running-process-protocol.txt | 2 +-\n Documentation/technical/partial-clone.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n Makefile | 1 +\n builtin/help.c | 18 ++++++-\n cache.h | 3 +-\n command-list.txt | 34 ++++++++++---\n help.c | 29 ++++++++++-\n help.h | 2 +\n pack-revindex.h | 2 +-\n t/t0012-help.sh | 14 +++++-\n t/t5551-http-fetch-smart.sh | 4 +-\n 40 files changed, 513 insertions(+), 122 deletions(-)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)\n rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (90%)\n rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (87%)\n rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)\n rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)\n rename Documentation/{technical/bitmap-format.txt => gitformat-pack-bitmap.txt} (91%)\n rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%)\n rename Documentation/{technical/pack-protocol.txt => gitformat-pack-protocol.txt} (98%)\n rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)\n rename Documentation/{technical/protocol-capabilities.txt => gitformat-protocol-capabilities.txt} (96%)\n rename Documentation/{technical/protocol-common.txt => gitformat-protocol-common.txt} (88%)\n rename Documentation/{technical/http-protocol.txt => gitformat-protocol-http.txt} (97%)\n rename Documentation/{technical/protocol-v2.txt => gitformat-protocol-v2.txt} (97%)\n rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)\n\nRange-diff against v2:\n1: 960574b7f05 ! 1: 929d9192828 git docs: split \"User-facing file formats\" off from \"Guides\"\n @@ Documentation/git-help.txt\n @@ Documentation/git-help.txt: SYNOPSIS\n --------\n [verse]\n - 'git help' [-a|--all [--[no-]verbose]]\n --\t [[-i|--info] [-m|--man] [-w|--web]] [|]\n -+\t [[-i|--info] [-m|--man] [-w|--web]] [||]\n + 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\n +-'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n ++'git help' [[-i|--info] [-m|--man] [-w|--web]] [||]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n +'git help' [--user-formats]\n @@ builtin/help.c: static struct option builtin_help_options[] = {\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n -@@ builtin/help.c: static const char * const builtin_help_usage[] = {\n - \t \" [[-i|--info] [-m|--man] [-w|--web]] []\"),\n - \tN_(\"git help [-g|--guides]\"),\n - \tN_(\"git help [-c|--config]\"),\n -+\tN_(\"git help [--user-formats]\"),\n +@@ builtin/help.c: static struct option builtin_help_options[] = {\n + \n + static const char * const builtin_help_usage[] = {\n + \t\"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n +-\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] []\"),\n ++\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [|]\"),\n + \t\"git help [-g|--guides]\",\n + \t\"git help [-c|--config]\",\n ++\t\"git help [--user-formats]\",\n \tNULL\n };\n \n @@ builtin/help.c: int cmd_help(int argc, const char **argv, const char *prefix)\n - \t\tno_extra_argc(argc);\n + \t\topt_mode_usage(argc, \"--config-for-completion\", help_format);\n \t\tlist_config_help(SHOW_CONFIG_VARS);\n \t\treturn 0;\n +\tcase HELP_ACTION_USER_FORMATS:\n -+\t\tno_extra_argc(argc);\n ++\t\topt_mode_usage(argc, \"--user-formats\", help_format);\n +\t\tlist_user_formats_help();\n +\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n - \t\tno_extra_argc(argc);\n - \t\tlist_config_help(SHOW_CONFIG_SECTIONS);\n + \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n + \t\t\t help_format);\n \n ## command-list.txt ##\n @@\n @@ help.c: static struct category_description main_categories[] = {\n \t{ CAT_plumbinginterrogators, N_(\"Low-level Commands / Interrogators\") },\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n -+\t{ CAT_userformats, N_(\"User-facing file formats\") },\n ++\t{ CAT_userformats, N_(\"Git user-facing file formats\") },\n \t{ 0, NULL }\n };\n \n +@@ help.c: static const char *drop_prefix(const char *name, uint32_t category)\n + \n + \tif (skip_prefix(name, \"git-\", &new_name))\n + \t\treturn new_name;\n +-\tif (category == CAT_guide && skip_prefix(name, \"git\", &new_name))\n ++\tswitch (category) {\n ++\tcase CAT_guide:\n ++\tcase CAT_userformats:\n ++\t\tskip_prefix(name, \"git\", &new_name);\n + \t\treturn new_name;\n ++\t}\n + \treturn name;\n + \n + }\n @@ help.c: void list_guides_help(void)\n \tputchar('\\n');\n }\n @@ help.c: void list_guides_help(void)\n +void list_user_formats_help(void)\n +{\n +\tstruct category_description catdesc[] = {\n -+\t\t{ CAT_userformats, N_(\"The user-facing file formats are:\") },\n ++\t\t{ CAT_userformats, N_(\"Git user-facing file formats:\") },\n +\t\t{ 0, NULL }\n +\t};\n +\tprint_cmd_by_category(catdesc, NULL);\n @@ help.c: void list_guides_help(void)\n ## help.h ##\n @@ help.h: static inline void mput_char(char c, unsigned int num)\n void list_common_cmds_help(void);\n - void list_all_cmds_help(void);\n + void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n +void list_user_formats_help(void);\n \n @@ t/t0012-help.sh: test_expect_success 'git help' '\n \ttest_i18ngrep \"^ commit \" help.output &&\n \ttest_i18ngrep \"^ fetch \" help.output\n '\n -+\n -+test_expect_success 'git help -a' '\n -+\tgit help -a >help.output &&\n -+\tgrep \"^Main Porcelain Commands\" help.output &&\n -+\tgrep \"^User-facing file formats\" help.output\n -+'\n +\n test_expect_success 'git help -g' '\n \tgit help -g >help.output &&\n @@ t/t0012-help.sh: test_expect_success 'git help succeeds without git.html' '\n \ttest_cmp expect test-browser.log\n '\n \n -+test_expect_success 'git help --formats' '\n ++test_expect_success 'git help --user-formats' '\n +\tgit help --user-formats >help.output &&\n -+\tgrep \"^ gitattributes \" help.output &&\n -+\tgrep \"^ gitmailmap \" help.output\n ++\tgrep \"^ attributes \" help.output &&\n ++\tgrep \"^ mailmap \" help.output\n +'\n +\n test_expect_success 'git help -c' '\n \tgit help -c >help.output &&\n \tcat >expect <<-\\EOF &&\n +@@ t/t0012-help.sh: test_expect_success \"'git help -a' section spacing\" '\n + \tLow-level Commands / Syncing Repositories\n + \n + \tLow-level Commands / Internal Helpers\n ++\n ++\tGit user-facing file formats\n + \tEOF\n + \ttest_cmp expect actual\n + '\n2: b2d73f8c9da ! 2: 1fd57d5caf4 git docs: create a \"Git file and wire formats\" section\n @@ Metadata\n Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - git docs: create a \"Git file and wire formats\" section\n + git docs: create a \"Git file formats and protocols\" section\n \n - Create a new \"Git file and wire formats\" section in the main \"git help\n + Create a new \"Git file formats and protocols\" section in the main \"git help\n git\" manual page and start moving the documentation that now lives in\n \"Documentation/technical/*.git\" over to it. This compliments the newly\n added and adjacent \"User-facing file formats\" section.\n @@ Documentation/Makefile: MAN1_TXT += gitweb.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n -@@ Documentation/Makefile: SP_ARTICLES += $(API_DOCS)\n - TECH_DOCS += MyFirstContribution\n - TECH_DOCS += MyFirstObjectWalk\n +@@ Documentation/Makefile: TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n + TECH_DOCS += ToolsForGit\n + TECH_DOCS += technical/bitmap-format\n -TECH_DOCS += technical/bundle-format\n + TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n - TECH_DOCS += technical/index-format\n @@ Documentation/Makefile: cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n @@ Documentation/git-bundle.txt: You can also see what references it offers:\n ---\n Part of the linkgit:git[1] suite\n \n + ## Documentation/git-help.txt ##\n +@@ Documentation/git-help.txt: SYNOPSIS\n + 'git help' [-g|--guides]\n + 'git help' [-c|--config]\n + 'git help' [--user-formats]\n ++'git help' [--git-formats]\n + \n + DESCRIPTION\n + -----------\n +\n ## Documentation/git.txt ##\n @@ Documentation/git.txt: edit. These can also be listed with 'git help --user-formats'.\n \n include::cmds-userformats.txt[]\n \n -+Git file and wire formats\n -+-------------------------\n ++Git file formats and protocols\n ++------------------------------\n +\n -+This documentation discusses the file and wire formats that git itself\n -+uses. These can also be listed with 'git help --git-formats'.\n ++This documentation discusses the file formats and protocols that git\n ++itself uses. These can also be listed with 'git help --git-formats'.\n +\n +include::cmds-gitformats.txt[]\n +\n @@ Documentation/gitformat-bundle.txt: In the bundle format, there can be a comment\n +------------\n \n Because there is no opportunity for negotiation, unknown capabilities cause 'git\n - bundle' to abort. The only known capability is `object-format`, which specifies\n - the hash algorithm in use, and can take the same values as the\n - `extensions.objectFormat` configuration value.\n + bundle' to abort.\n +@@ Documentation/gitformat-bundle.txt: bundle' to abort.\n + * `filter` specifies an object filter as in the `--filter` option in\n + linkgit:git-rev-list[1]. The resulting pack-file must be marked as a\n + `.promisor` pack-file after it is unbundled.\n +\n +GIT\n +---\n @@ builtin/help.c: static struct option builtin_help_options[] = {\n \t\t HELP_ACTION_GUIDES),\n \tOPT_CMDMODE(0, \"user-formats\", &cmd_mode, N_(\"print list of user-facing file formats\"),\n \t\t HELP_ACTION_USER_FORMATS),\n -+\tOPT_CMDMODE(0, \"git-formats\", &cmd_mode, N_(\"print list of Git's own file and network formats\"),\n ++\tOPT_CMDMODE(0, \"git-formats\", &cmd_mode, N_(\"print list of internal file formats and network protocols\"),\n +\t\t HELP_ACTION_GIT_FORMATS),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n @@ builtin/help.c: static const char * const builtin_help_usage[] = {\n - \tN_(\"git help [-g|--guides]\"),\n - \tN_(\"git help [-c|--config]\"),\n - \tN_(\"git help [--user-formats]\"),\n -+\tN_(\"git help [--git-formats]\"),\n + \t\"git help [-g|--guides]\",\n + \t\"git help [-c|--config]\",\n + \t\"git help [--user-formats]\",\n ++\t\"git help [--git-formats]\",\n \tNULL\n };\n \n @@ builtin/help.c: int cmd_help(int argc, const char **argv, const char *prefix)\n - \t\tno_extra_argc(argc);\n + \t\topt_mode_usage(argc, \"--user-formats\", help_format);\n \t\tlist_user_formats_help();\n \t\treturn 0;\n +\tcase HELP_ACTION_GIT_FORMATS:\n -+\t\tno_extra_argc(argc);\n ++\t\topt_mode_usage(argc, \"--git-formats\", help_format);\n +\t\tlist_git_formats_help();\n +\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n - \t\tno_extra_argc(argc);\n - \t\tlist_config_help(SHOW_CONFIG_SECTIONS);\n + \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n + \t\t\t help_format);\n \n ## command-list.txt ##\n @@\n # .mailmap etc. files lives in man section 5. These entries can only\n # have the \"userformats\" attribute and nothing else.\n #\n -+# Git's own file and network formats such as documentation for the\n -+# *.bundle format lives in mn section 5. These entries can only have\n ++# Git internal file formats and protocols, such as documentation for the\n ++# *.bundle format lives in man section 5. These entries can only have\n +# the \"gitformats\" attribute and nothing else.\n +#\n ### command list (do not change this line)\n @@ help.c\n @@ help.c: static struct category_description main_categories[] = {\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n - \t{ CAT_userformats, N_(\"User-facing file formats\") },\n -+\t{ CAT_gitformats, N_(\"Internal file- and wire formats formats\") },\n + \t{ CAT_userformats, N_(\"Git user-facing file formats\") },\n ++\t{ CAT_gitformats, N_(\"Git internal file formats and protocols\") },\n \t{ 0, NULL }\n };\n \n +@@ help.c: static const char *drop_prefix(const char *name, uint32_t category)\n + \tswitch (category) {\n + \tcase CAT_guide:\n + \tcase CAT_userformats:\n ++\tcase CAT_gitformats:\n + \t\tskip_prefix(name, \"git\", &new_name);\n + \t\treturn new_name;\n + \t}\n @@ help.c: void list_user_formats_help(void)\n \tputchar('\\n');\n }\n @@ help.c: void list_user_formats_help(void)\n +void list_git_formats_help(void)\n +{\n +\tstruct category_description catdesc[] = {\n -+\t\t{ CAT_gitformats, N_(\"Git's internal file and network formats are:\") },\n ++\t\t{ CAT_gitformats, N_(\"Internal file formats and protocols:\") },\n +\t\t{ 0, NULL }\n +\t};\n +\tprint_cmd_by_category(catdesc, NULL);\n @@ help.c: void list_user_formats_help(void)\n \n ## help.h ##\n @@ help.h: void list_common_cmds_help(void);\n - void list_all_cmds_help(void);\n + void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n void list_user_formats_help(void);\n +void list_git_formats_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\n +\n + ## t/t0012-help.sh ##\n +@@ t/t0012-help.sh: test_expect_success \"'git help -a' section spacing\" '\n + \tLow-level Commands / Internal Helpers\n + \n + \tGit user-facing file formats\n ++\n ++\tGit internal file formats and protocols\n + \tEOF\n + \ttest_cmp expect actual\n + '\n3: 5abd59b807f ! 3: d548c6aaba7 docs: move commit-graph format docs to man section 5\n @@ Documentation/gitformat-commit-graph.txt: CHUNK DATA:\n 2 bits of the lowest byte, storing the 33rd and 34th bit of the\n commit time.\n \n -- Generation Data (ID: {'G', 'D', 'A', 'T' }) (N * 4 bytes) [Optional]\n -+==== Generation Data (ID: {'G', 'D', 'A', 'T' }) (N * 4 bytes) [Optional]\n +- Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n ++==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n * This list of 4-byte values store corrected commit date offsets for the\n commits, arranged in the same order as commit data chunk.\n * If the corrected commit date offset cannot be stored within 31 bits,\n @@ Documentation/gitformat-commit-graph.txt: CHUNK DATA:\n by compatible versions of Git and in case of split commit-graph chains,\n the topmost layer also has Generation Data chunk.\n \n -- Generation Data Overflow (ID: {'G', 'D', 'O', 'V' }) [Optional]\n -+==== Generation Data Overflow (ID: {'G', 'D', 'O', 'V' }) [Optional]\n +- Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n ++==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n * This list of 8-byte values stores the corrected commit date offsets\n for commits with corrected commit date offsets that cannot be\n stored within 31 bits.\n @@ Documentation/gitformat-commit-graph.txt: CHUNK DATA:\n +=== TRAILER:\n \n \tH-byte HASH-checksum of all of the above.\n + \n +@@ Documentation/gitformat-commit-graph.txt: the number '2' in their chunk IDs because a previous version of Git wrote\n + possibly erroneous data in these chunks with the IDs \"GDAT\" and \"GDOV\". By\n + changing the IDs, newer versions of Git will silently ignore those older\n + chunks and write the new information without trusting the incorrect data.\n +\n +GIT\n +---\n4: fb91009c18f = 4: f404987f94d docs: move protocol-related docs to man section 5\n5: 5cb41bb0dcb ! 5: 6c46b4dccea docs: move {index,signature,bitmap,chunk}-format docs to man section 5\n @@ Metadata\n Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - docs: move {index,signature,bitmap,chunk}-format docs to man section 5\n + docs: move pack format docs to man section 5\n \n Continue the move of existing Documentation/technical/* protocol and\n - file-format documentation into our main documentation space.\n + file-format documentation into our main documentation space by moving\n + the various documentation pertaining to the *.pack format and related\n + files, and updating things that refer to it to link to the new\n + location.\n \n By moving these we can properly link from the newly created\n gitformat-commit-graph do to a gitformat-chunk-format manpage we build\n - by default. Let's also move the rest over for consistency.\n + by default.\n \n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/Makefile ##\n @@ Documentation/Makefile: MAN1_TXT += gitweb.txt\n - \n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n -+MAN5_TXT += gitformat-bitmap.txt\n MAN5_TXT += gitformat-bundle.txt\n +MAN5_TXT += gitformat-chunk.txt\n MAN5_TXT += gitformat-commit-graph.txt\n +MAN5_TXT += gitformat-index.txt\n ++MAN5_TXT += gitformat-pack-bitmap.txt\n ++MAN5_TXT += gitformat-pack-cruft.txt\n MAN5_TXT += gitformat-pack-protocol.txt\n ++MAN5_TXT += gitformat-pack.txt\n MAN5_TXT += gitformat-protocol-capabilities.txt\n MAN5_TXT += gitformat-protocol-common.txt\n MAN5_TXT += gitformat-protocol-v2.txt\n @@ Documentation/Makefile: MAN1_TXT += gitweb.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n -@@ Documentation/Makefile: TECH_DOCS += MyFirstObjectWalk\n +@@ Documentation/Makefile: TECH_DOCS += MyFirstContribution\n + TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n + TECH_DOCS += ToolsForGit\n +-TECH_DOCS += technical/bitmap-format\n +-TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n -TECH_DOCS += technical/index-format\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n - TECH_DOCS += technical/pack-format\n +-TECH_DOCS += technical/pack-format\n + TECH_DOCS += technical/pack-heuristics\n + TECH_DOCS += technical/parallel-checkout\n + TECH_DOCS += technical/partial-clone\n @@ Documentation/Makefile: TECH_DOCS += technical/racy-git\n TECH_DOCS += technical/reftable\n TECH_DOCS += technical/send-pack-pipeline\n @@ Documentation/Makefile: TECH_DOCS += technical/racy-git\n SP_ARTICLES += $(TECH_DOCS)\n SP_ARTICLES += technical/api-index\n \n - ## Documentation/technical/bitmap-format.txt => Documentation/gitformat-bitmap.txt ##\n + ## Documentation/config/pack.txt ##\n +@@ Documentation/config/pack.txt: permuted into their appropriate location when writing a new bitmap.\n + \n + pack.writeReverseIndex::\n + \tWhen true, git will write a corresponding .rev file (see:\n +-\tlink:../technical/pack-format.html[Documentation/technical/pack-format.txt])\n ++\tlinkgit:gitformat-pack[5])\n + \tfor each new packfile that it writes in all places except for\n + \tlinkgit:git-fast-import[1] and in the bulk checkin mechanism.\n + \tDefaults to false.\n +\n + ## Documentation/git-bundle.txt ##\n +@@ Documentation/git-bundle.txt: size. That they're \"thin\" under the hood is merely noted here as a\n + curiosity, and as a reference to other documentation.\n + \n + See linkgit:gitformat-bundle[5] for more details and the discussion of\n +-\"thin pack\" in link:technical/pack-format.html[the pack format\n +-documentation] for further details.\n ++\"thin pack\" in linkgit:gitformat-pack[5] for further details.\n + \n + OPTIONS\n + -------\n +\n + ## Documentation/git-multi-pack-index.txt ##\n +@@ Documentation/git-multi-pack-index.txt: $ git multi-pack-index verify\n + SEE ALSO\n + --------\n + See link:technical/multi-pack-index.html[The Multi-Pack-Index Design\n +-Document] and link:technical/pack-format.html[The Multi-Pack-Index\n +-Format] for more information on the multi-pack-index feature.\n ++Document] and linkgit:gitformat-pack[5] for more information on the\n ++multi-pack-index feature and its file format.\n + \n + \n + GIT\n +\n + ## Documentation/technical/chunk-format.txt => Documentation/gitformat-chunk.txt ##\n +@@\n +-Chunk-based file formats\n +-========================\n ++gitformat-chunk(5)\n ++==================\n ++\n ++NAME\n ++----\n ++gitformat-chunk - Chunk-based file formats\n ++\n ++SYNOPSIS\n ++--------\n ++\n ++Used by linkgit:gitformat-commit-graph[5] and the \"MIDX\" format (see\n ++the pack format documentation in linkgit:gitformat-pack[5]).\n ++\n ++DESCRIPTION\n ++-----------\n + \n + Some file formats in Git use a common concept of \"chunks\" to describe\n + sections of the file. This allows structured access to a large file by\n + scanning a small \"table of contents\" for the remaining data. This common\n + format is used by the `commit-graph` and `multi-pack-index` files. See\n +-link:technical/pack-format.html[the `multi-pack-index` format] and\n +-the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n ++the `multi-pack-index` format in linkgit:gitformat-pack[5] and\n ++link:technical/commit-graph-format.html[the `commit-graph` format] for\n + how they use the chunks to describe structured data.\n + \n + A chunk-based file format begins with some header information custom to\n +@@ Documentation/gitformat-chunk.txt: for future formats:\n + * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n + in `midx.c` for how the chunk-format API is used to write and\n + parse the multi-pack-index file format documented in\n +- link:technical/pack-format.html[the multi-pack-index file format].\n ++ the multi-pack-index file format section of linkgit:gitformat-pack[5].\n ++\n ++GIT\n ++---\n ++Part of the linkgit:git[1] suite\n +\n + ## Documentation/gitformat-commit-graph.txt ##\n +@@ Documentation/gitformat-commit-graph.txt: All multi-byte numbers are in network byte order.\n + ID appears at most once.\n + \n + The CHUNK LOOKUP matches the table of contents from\n +- link:technical/chunk-format.html[the chunk-based file format].\n ++ the chunk-based file format, see linkgit:gitformat-chunk[5]\n + \n + The remaining data in the body is described one chunk at a time, and\n + these chunks may be given in any order. Chunks are required unless\n +\n + ## Documentation/technical/index-format.txt => Documentation/gitformat-index.txt ##\n +@@\n ++gitformat-index(5)\n ++==================\n ++\n ++NAME\n ++----\n ++gitformat-index - Git index format\n ++\n ++SYNOPSIS\n ++--------\n ++[verse]\n ++$GIT_DIR/index\n ++\n ++DESCRIPTION\n ++-----------\n ++\n + Git index format\n +-================\n + \n + == The Git index file has the following format\n + \n +@@ Documentation/gitformat-index.txt: Git index format\n + entry is encoded as if the path name for the previous entry is an\n + empty string). At the beginning of an entry, an integer N in the\n + variable width encoding (the same encoding as the offset is encoded\n +- for OFS_DELTA pack entries; see pack-format.txt) is stored, followed\n ++ for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed\n + by a NUL-terminated string S. Removing N bytes from the end of the\n + path name for the previous entry, and replacing it with the string S\n + yields the path name for this entry.\n +@@ Documentation/gitformat-index.txt: The remaining data of each directory block is grouped by type:\n + with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,\n + tools should avoid interacting with a sparse index unless they understand\n + this extension.\n ++\n ++GIT\n ++---\n ++Part of the linkgit:git[1] suite\n +\n + ## Documentation/technical/bitmap-format.txt => Documentation/gitformat-pack-bitmap.txt ##\n @@\n -GIT bitmap v1 format\n -====================\n -+gitformat-bitmap(5)\n -+===================\n ++gitformat-pack-bitmap(5)\n ++========================\n \n -== Pack and multi-pack bitmaps\n +NAME\n +----\n -+gitformat-bitmap - The bitmap file format\n ++gitformat-pack-bitmap - The bitmap file format\n +\n +SYNOPSIS\n +--------\n +[verse]\n -+$GIT_DIR/objects/pack/*.bitmap\n ++$GIT_DIR/objects/pack/pack-*.bitmap\n +\n +DESCRIPTION\n +-----------\n +\n +Bitmaps are a file format associated with .pack files. See\n -+link:technical/pack-format.html[the pack format documentation] and\n ++the pack format documentation in linkgit:gitformat-pack[5] and\n +linkgit:git-pack-objects[1].\n +\n +== GIT bitmap v1 format\n @@ Documentation/technical/bitmap-format.txt => Documentation/gitformat-bitmap.txt\n \n Bitmaps store reachability information about the set of objects in a packfile,\n or a multi-pack index (MIDX). The former is defined obviously, and the latter is\n -@@ Documentation/gitformat-bitmap.txt: Certain bitmap extensions are supported (see: Appendix B). No extensions are\n +@@ Documentation/gitformat-pack-bitmap.txt: Certain bitmap extensions are supported (see: Appendix B). No extensions are\n required for bitmaps corresponding to packfiles. For bitmaps that correspond to\n MIDXs, both the bit-cache and rev-cache extensions are required.\n \n -== On-disk format\n +=== On-disk format\n \n - \t- A header appears at the beginning:\n - \n -@@ Documentation/gitformat-bitmap.txt: MIDXs, both the bit-cache and rev-cache extensions are required.\n + * A header appears at the beginning:\n \n - \t\t- The compressed bitmap itself, see Appendix A.\n +@@ Documentation/gitformat-pack-bitmap.txt: in the index.\n + \tTRAILER: ::\n + \t\tTrailing checksum of the preceding contents.\n \n -== Appendix A: Serialization format for an EWAH bitmap\n +Appendix A - Serialization format for an EWAH bitmap\n @@ Documentation/gitformat-bitmap.txt: MIDXs, both the bit-cache and rev-cache exte\n \n Ewah bitmaps are serialized in the same protocol as the JAVAEWAH\n library, making them backwards compatible with the JGit\n -@@ Documentation/gitformat-bitmap.txt: chunk. For efficient appending to the bitstream, the EWAH stores a\n +@@ Documentation/gitformat-pack-bitmap.txt: chunk. For efficient appending to the bitstream, the EWAH stores a\n pointer to the last RLW in the stream.\n \n \n @@ Documentation/gitformat-bitmap.txt: chunk. For efficient appending to the bitst\n \n If the BITMAP_OPT_HASH_CACHE flag is set, the end of the bitmap contains\n a cache of 32-bit values, one per object in the pack/MIDX. The value at\n -@@ Documentation/gitformat-bitmap.txt: Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag.\n +@@ Documentation/gitformat-pack-bitmap.txt: Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag.\n If implementations want to choose a different hashing scheme, they are\n free to do so, but MUST allocate a new header flag (because comparing\n hashes made under two different schemes would be pointless).\n @@ Documentation/gitformat-bitmap.txt: Note that this hashing scheme is tied to the\n +---\n +Part of the linkgit:git[1] suite\n \n - ## Documentation/technical/chunk-format.txt => Documentation/gitformat-chunk.txt ##\n + ## Documentation/technical/cruft-packs.txt => Documentation/gitformat-pack-cruft.txt ##\n @@\n --Chunk-based file formats\n --========================\n -+gitformat-chunk(5)\n -+==================\n +-= Cruft packs\n ++gitformat-pack-cruft(5)\n ++=======================\n +\n +NAME\n +----\n -+gitformat-chunk - Chunk-based file formats\n ++gitformat-pack-cruft - The cruft pack file format\n +\n +SYNOPSIS\n +--------\n -+\n -+Used by linkgit:gitformat-commit-graph[5] and the \"MIDX\" format (see\n -+link:technical/pack-format.html[the pack format documentation]).\n ++[verse]\n ++$GIT_DIR/objects/pack/pack-*.mtimes\n +\n +DESCRIPTION\n +-----------\n \n - Some file formats in Git use a common concept of \"chunks\" to describe\n - sections of the file. This allows structured access to a large file by\n -@@ Documentation/gitformat-chunk.txt: for future formats:\n - in `midx.c` for how the chunk-format API is used to write and\n - parse the multi-pack-index file format documented in\n - link:technical/pack-format.html[the multi-pack-index file format].\n + The cruft packs feature offer an alternative to Git's traditional mechanism of\n + removing unreachable objects. This document provides an overview of Git's\n +@@ Documentation/gitformat-pack-cruft.txt: same.\n + To remove unreachable objects from your repository, Git offers `git repack -Ad`\n + (see linkgit:git-repack[1]). Quoting from the documentation:\n + \n +-[quote]\n ++----\n + [...] unreachable objects in a previous pack become loose, unpacked objects,\n + instead of being left in the old pack. [...] loose unreachable objects will be\n + pruned according to normal expiry rules with the next 'git gc' invocation.\n ++----\n + \n + Unreachable objects aren't removed immediately, since doing so could race with\n + an incoming push which may reference an object which is about to be deleted.\n +@@ Documentation/gitformat-pack-cruft.txt: which aren't already stored in an earlier cruft pack) is significantly more\n + complicated to construct, and so aren't pursued here. The obvious drawback to\n + the current implementation is that the entire cruft pack must be re-written from\n + scratch.\n +\n +GIT\n +---\n +Part of the linkgit:git[1] suite\n \n - ## Documentation/gitformat-commit-graph.txt ##\n -@@ Documentation/gitformat-commit-graph.txt: All multi-byte numbers are in network byte order.\n - ID appears at most once.\n + ## Documentation/gitformat-pack-protocol.txt ##\n +@@ Documentation/gitformat-pack-protocol.txt: Now that the client and server have finished negotiation about what\n + the minimal amount of data that needs to be sent to the client is, the server\n + will construct and send the required data in packfile format.\n \n - The CHUNK LOOKUP matches the table of contents from\n -- link:technical/chunk-format.html[the chunk-based file format].\n -+ the chunk-based file format, see linkgit:gitformat-chunk[5]\n +-See pack-format.txt for what the packfile itself actually looks like.\n ++See linkgit:gitformat-pack[5] for what the packfile itself actually looks like.\n \n - The remaining data in the body is described one chunk at a time, and\n - these chunks may be given in any order. Chunks are required unless\n + If 'side-band' or 'side-band-64k' capabilities have been specified by\n + the client, the server will send the packfile data multiplexed.\n \n - ## Documentation/technical/index-format.txt => Documentation/gitformat-index.txt ##\n + ## Documentation/technical/pack-format.txt => Documentation/gitformat-pack.txt ##\n @@\n -+gitformat-index(5)\n -+==================\n +-Git pack format\n +-===============\n ++gitformat-pack(5)\n ++=================\n +\n +NAME\n +----\n -+gitformat-index - Git index format\n ++gitformat-pack - Git pack format\n ++\n +\n +SYNOPSIS\n +--------\n +[verse]\n -+$GIT_DIR/index\n ++$GIT_DIR/objects/pack/pack-*.{pack,idx}\n ++$GIT_DIR/objects/pack/pack-*.rev\n ++$GIT_DIR/objects/pack/multi-pack-index\n +\n +DESCRIPTION\n +-----------\n +\n - Git index format\n --================\n ++The Git pack format is now Git stores most of its primary repository\n ++data. Over the lietime af a repository loose objects (if any) and\n ++smaller packs are consolidated into larger pack(s). See\n ++linkgit:git-gc[1] and linkgit:git-pack-objects[1].\n ++\n ++The pack format is also used over-the-wire, see\n ++e.g. linkgit:gitformat-protocol-v2[5], as well as being a part of\n ++other container formats in the case of linkgit:gitformat-bundle[5].\n \n - == The Git index file has the following format\n + == Checksums and object IDs\n \n -@@ Documentation/gitformat-index.txt: The remaining data of each directory block is grouped by type:\n - with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,\n - tools should avoid interacting with a sparse index unless they understand\n - this extension.\n +@@ Documentation/gitformat-pack.txt: CHUNK LOOKUP:\n + \t using the next chunk position if necessary.)\n + \n + \tThe CHUNK LOOKUP matches the table of contents from\n +-\tlink:technical/chunk-format.html[the chunk-based file format].\n ++\tthe chunk-based file format, see linkgit:gitformat-chunk[5].\n + \n + \tThe remaining data in the body is described one chunk at a time, and\n + \tthese chunks may be given in any order. Chunks are required unless\n +@@ Documentation/gitformat-pack.txt: packs arranged in MIDX order (with the preferred pack coming first).\n + \n + The MIDX's reverse index is stored in the optional 'RIDX' chunk within\n + the MIDX itself.\n +\n +GIT\n +---\n @@ Documentation/gitformat-signature.txt: Date: Wed Jun 15 09:13:29 2016 +0000\n +---\n +Part of the linkgit:git[1] suite\n \n - ## Documentation/technical/pack-format.txt ##\n -@@ Documentation/technical/pack-format.txt: CHUNK LOOKUP:\n - \t using the next chunk position if necessary.)\n + ## Documentation/howto/recover-corrupted-object-harder.txt ##\n +@@ Documentation/howto/recover-corrupted-object-harder.txt: Note that the \"object\" file isn't fit for feeding straight to zlib; it\n + has the git packed object header, which is variable-length. We want to\n + strip that off so we can start playing with the zlib data directly. You\n + can either work your way through it manually (the format is described in\n +-link:../technical/pack-format.html[Documentation/technical/pack-format.txt]),\n ++linkgit:gitformat-pack[5]),\n + or you can walk through it in a debugger. I did the latter, creating a\n + valid pack like:\n \n - \tThe CHUNK LOOKUP matches the table of contents from\n --\tlink:technical/chunk-format.html[the chunk-based file format].\n -+\tthe chunk-based file format, see linkgit:gitformat-chunk[5].\n +\n + ## Documentation/technical/hash-function-transition.txt ##\n +@@ Documentation/technical/hash-function-transition.txt: SHA-1 content.\n + Object storage\n + ~~~~~~~~~~~~~~\n + Loose objects use zlib compression and packed objects use the packed\n +-format described in Documentation/technical/pack-format.txt, just like\n ++format described in linkgit:gitformat-pack[5], just like\n + today. The content that is compressed and stored uses SHA-256 content\n + instead of SHA-1 content.\n + \n +\n + ## Documentation/user-manual.txt ##\n +@@ Documentation/user-manual.txt: those \"loose\" objects.\n + You can save space and make Git faster by moving these loose objects in\n + to a \"pack file\", which stores a group of objects in an efficient\n + compressed format; the details of how pack files are formatted can be\n +-found in link:technical/pack-format.html[pack format].\n ++found in link:gitformat-pack[5].\n + \n + To put the loose objects into a pack, just run git repack:\n \n - \tThe remaining data in the body is described one chunk at a time, and\n - \tthese chunks may be given in any order. Chunks are required unless\n +\n + ## cache.h ##\n +@@ cache.h: extern struct index_state the_index;\n + \n + /*\n + * Values in this enum (except those outside the 3 bit range) are part\n +- * of pack file format. See Documentation/technical/pack-format.txt\n +- * for more information.\n ++ * of pack file format. See gitformat-pack(5) for more information.\n + */\n + enum object_type {\n + \tOBJ_BAD = -1,\n \n ## command-list.txt ##\n -@@ command-list.txt: gitcvs-migration guide\n - gitdiffcore guide\n +@@ command-list.txt: gitdiffcore guide\n giteveryday guide\n gitfaq guide\n -+gitformat-bitmap gitformats\n gitformat-bundle gitformats\n +gitformat-chunk gitformats\n gitformat-commit-graph gitformats\n +gitformat-index gitformats\n ++gitformat-pack gitformats\n ++gitformat-pack-bitmap gitformats\n ++gitformat-pack-cruft gitformats\n gitformat-pack-protocol gitformats\n gitformat-protocol-capabilities gitformats\n gitformat-protocol-common gitformats\n @@ command-list.txt: gitcvs-migration guide\n gitglossary guide\n githooks userformats\n gitignore userformats\n +\n + ## pack-revindex.h ##\n +@@\n + *\n + * - pack position refers to an object's position within a non-existent pack\n + * described by the MIDX. The pack structure is described in\n +- * Documentation/technical/pack-format.txt.\n ++ * gitformat-pack(5).\n + *\n + * It is effectively a concatanation of all packs in the MIDX (ordered by\n + * their numeric ID within the MIDX) in their original order within each\n-: ----------- > 6: 5cf8b526bff docs: move http-protocol docs to man section 5\n-: ----------- > 7: aabdc4a4151 docs: move multi-pack-index docs to man section 5\n-- \n2.37.0.932.g7b7031e73bc\n\n"},{"id":"458911","messageId":"patch-v3-3.7-d548c6aaba7-20220712T195419Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com","subject":"[PATCH v3 3/7] docs: move commit-graph format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-12T20:06:58Z","receivedAt":"2022-07-12T20:07:23Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space.\n\nBy moving the documentation for the commit-graph format into man\nsection 5 and the new \"gitformats\" category. This change is split from\nsubsequent commits due to the relatively large amount of ASCIIDOC\nformatting changes that are required.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-commit-graph.txt | 5 ++\n ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------\n Documentation/technical/chunk-format.txt | 4 +-\n command-list.txt | 1 +\n 5 files changed, 41 insertions(+), 17 deletions(-)\n rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (88%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 404139274e7..cc6870cce41 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -25,6 +25,7 @@ MAN1_TXT += gitweb.txt\n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n+MAN5_TXT += gitformat-commit-graph.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex e1f48c95b3c..047decdb65b 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append\n ------------------------------------------------\n \n \n+FILE FORMAT\n+-----------\n+\n+see linkgit:gitformat-commit-graph[5].\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt\nsimilarity index 88%\nrename from Documentation/technical/commit-graph-format.txt\nrename to Documentation/gitformat-commit-graph.txt\nindex 484b185ba98..108dc2295c0 100644\n--- a/Documentation/technical/commit-graph-format.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -1,5 +1,18 @@\n-Git commit graph format\n-=======================\n+gitformat-commit-graph(5)\n+=========================\n+\n+NAME\n+----\n+gitformat-commit-graph - Git commit graph format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/info/commit-graph\n+$GIT_DIR/objects/info/commit-graphs/*\n+\n+DESCRIPTION\n+-----------\n \n The Git commit graph stores a list of commit OIDs and some associated\n metadata, including:\n@@ -30,7 +43,7 @@ and hash type.\n \n All multi-byte numbers are in network byte order.\n \n-HEADER:\n+=== HEADER:\n \n 4-byte signature:\n The signature is: {'C', 'G', 'P', 'H'}\n@@ -52,7 +65,7 @@ HEADER:\n We infer the length (H*B) of the Base Graphs chunk\n from this value.\n \n-CHUNK LOOKUP:\n+=== CHUNK LOOKUP:\n \n (C + 1) * 12 bytes listing the table of contents for the chunks:\n First 4 bytes describe the chunk id. Value 0 is a terminating label.\n@@ -68,17 +81,17 @@ CHUNK LOOKUP:\n these chunks may be given in any order. Chunks are required unless\n otherwise specified.\n \n-CHUNK DATA:\n+=== CHUNK DATA:\n \n- OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n+==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n The ith entry, F[i], stores the number of OIDs with first\n byte at most i. Thus F[255] stores the total\n number of commits (N).\n \n- OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n+==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n The OIDs for all commits in the graph, sorted in ascending order.\n \n- Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n+==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n * The first H bytes are for the OID of the root tree.\n * The next 8 bytes are for the positions of the first two parents\n of the ith commit. Stores value 0x70000000 if no parent in that\n@@ -93,7 +106,7 @@ CHUNK DATA:\n 2 bits of the lowest byte, storing the 33rd and 34th bit of the\n commit time.\n \n- Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n+==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n * This list of 4-byte values store corrected commit date offsets for the\n commits, arranged in the same order as commit data chunk.\n * If the corrected commit date offset cannot be stored within 31 bits,\n@@ -104,7 +117,7 @@ CHUNK DATA:\n by compatible versions of Git and in case of split commit-graph chains,\n the topmost layer also has Generation Data chunk.\n \n- Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n+==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n * This list of 8-byte values stores the corrected commit date offsets\n for commits with corrected commit date offsets that cannot be\n stored within 31 bits.\n@@ -112,7 +125,7 @@ CHUNK DATA:\n chunk is present and atleast one corrected commit date offset cannot\n be stored within 31 bits.\n \n- Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n+==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n This list of 4-byte values store the second through nth parents for\n all octopus merges. The second parent value in the commit data stores\n an array position within this list along with the most-significant bit\n@@ -120,14 +133,14 @@ CHUNK DATA:\n positions for the parents until reaching a value with the most-significant\n bit on. The other bits correspond to the position of the last parent.\n \n- Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n+==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters\n from commit 0 to commit i (inclusive) in lexicographic order. The Bloom\n filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header\n length), where BIDX[-1] is 0.\n * The BIDX chunk is ignored if the BDAT chunk is not present.\n \n- Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n+==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n * It starts with header consisting of three unsigned 32-bit integers:\n - Version of the hash algorithm being used. We currently only support\n \tvalue 1 which corresponds to the 32-bit version of the murmur3 hash\n@@ -147,13 +160,13 @@ CHUNK DATA:\n of length one, with either all bits set to zero or one respectively.\n * The BDAT chunk is present if and only if BIDX is present.\n \n- Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n+==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n This list of H-byte hashes describe a set of B commit-graph files that\n form a commit-graph chain. The graph position for the ith commit in this\n file's OID Lookup chunk is equal to i plus the number of commits in all\n base graphs. If B is non-zero, this chunk must exist.\n \n-TRAILER:\n+=== TRAILER:\n \n \tH-byte HASH-checksum of all of the above.\n \n@@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote\n possibly erroneous data in these chunks with the IDs \"GDAT\" and \"GDOV\". By\n changing the IDs, newer versions of Git will silently ignore those older\n chunks and write the new information without trusting the incorrect data.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/chunk-format.txt b/Documentation/technical/chunk-format.txt\nindex 593614fceda..f36ce42f37c 100644\n--- a/Documentation/technical/chunk-format.txt\n+++ b/Documentation/technical/chunk-format.txt\n@@ -6,7 +6,7 @@ sections of the file. This allows structured access to a large file by\n scanning a small \"table of contents\" for the remaining data. This common\n format is used by the `commit-graph` and `multi-pack-index` files. See\n link:technical/pack-format.html[the `multi-pack-index` format] and\n-link:technical/commit-graph-format.html[the `commit-graph` format] for\n+the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n how they use the chunks to describe structured data.\n \n A chunk-based file format begins with some header information custom to\n@@ -108,7 +108,7 @@ for future formats:\n * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()`\n in `commit-graph.c` for how the chunk-format API is used to write and\n parse the commit-graph file format documented in\n- link:technical/commit-graph-format.html[the commit-graph file format].\n+ the commit-graph file format in linkgit:gitformat-commit-graph[5].\n \n * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n in `midx.c` for how the chunk-format API is used to write and\ndiff --git a/command-list.txt b/command-list.txt\nindex 1794a7279bc..66e6a0ba217 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -209,6 +209,7 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle gitformats\n+gitformat-commit-graph gitformats\n gitglossary guide\n githooks userformats\n gitignore userformats\n-- \n2.37.0.932.g7b7031e73bc\n\n"},{"id":"458913","messageId":"patch-v3-4.7-f404987f94d-20220712T195419Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com","subject":"[PATCH v3 4/7] docs: move protocol-related docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-12T20:06:59Z","receivedAt":"2022-07-12T20:07:41Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space. By moving\nthe things that discuss the protocol we can properly link from\ne.g. lsrefs.unborn and protocol.version documentation to a manpage we\nbuild by default.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 8 +++---\n Documentation/config/lsrefs.txt | 2 +-\n Documentation/config/protocol.txt | 2 +-\n Documentation/git-upload-pack.txt | 5 ++--\n Documentation/gitformat-bundle.txt | 2 +-\n ...otocol.txt => gitformat-pack-protocol.txt} | 22 +++++++++++++--\n ...xt => gitformat-protocol-capabilities.txt} | 28 +++++++++++++++----\n ...mmon.txt => gitformat-protocol-common.txt} | 23 +++++++++++++--\n ...tocol-v2.txt => gitformat-protocol-v2.txt} | 24 +++++++++++++---\n Documentation/technical/api-simple-ipc.txt | 2 +-\n Documentation/technical/http-protocol.txt | 6 ++--\n .../long-running-process-protocol.txt | 2 +-\n Documentation/technical/partial-clone.txt | 2 +-\n command-list.txt | 4 +++\n t/t5551-http-fetch-smart.sh | 4 +--\n 15 files changed, 103 insertions(+), 33 deletions(-)\n rename Documentation/{technical/pack-protocol.txt => gitformat-pack-protocol.txt} (98%)\n rename Documentation/{technical/protocol-capabilities.txt => gitformat-protocol-capabilities.txt} (96%)\n rename Documentation/{technical/protocol-common.txt => gitformat-protocol-common.txt} (88%)\n rename Documentation/{technical/protocol-v2.txt => gitformat-protocol-v2.txt} (98%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex cc6870cce41..adc1404d380 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -26,6 +26,10 @@ MAN1_TXT += gitweb.txt\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += gitformat-commit-graph.txt\n+MAN5_TXT += gitformat-pack-protocol.txt\n+MAN5_TXT += gitformat-protocol-capabilities.txt\n+MAN5_TXT += gitformat-protocol-common.txt\n+MAN5_TXT += gitformat-protocol-v2.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -105,12 +109,8 @@ TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n-TECH_DOCS += technical/pack-protocol\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\n-TECH_DOCS += technical/protocol-capabilities\n-TECH_DOCS += technical/protocol-common\n-TECH_DOCS += technical/protocol-v2\n TECH_DOCS += technical/racy-git\n TECH_DOCS += technical/reftable\n TECH_DOCS += technical/send-pack-pipeline\ndiff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.txt\nindex adeda0f24d3..e9efe498c01 100644\n--- a/Documentation/config/lsrefs.txt\n+++ b/Documentation/config/lsrefs.txt\n@@ -1,7 +1,7 @@\n lsrefs.unborn::\n \tMay be \"advertise\" (the default), \"allow\", or \"ignore\". If \"advertise\",\n \tthe server will respond to the client sending \"unborn\" (as described in\n-\tprotocol-v2.txt) and will advertise support for this feature during the\n+\tlinkgit:gitformat-protocol-v2[5]) and will advertise support for this feature during the\n \tprotocol v2 capability advertisement. \"allow\" is the same as\n \t\"advertise\" except that the server will not advertise support for this\n \tfeature; this is useful for load-balanced servers that cannot be\ndiff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt\nindex 756591d77b0..bf18a70a924 100644\n--- a/Documentation/config/protocol.txt\n+++ b/Documentation/config/protocol.txt\n@@ -58,6 +58,6 @@ protocol.version::\n * `1` - the original wire protocol with the addition of a version string\n in the initial response from the server.\n \n-* `2` - link:technical/protocol-v2.html[wire protocol version 2].\n+* `2` - Wire protocol version 2, see linkgit:gitformat-protocol-v2[5].\n \n --\ndiff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt\nindex 8f87b23ea86..754619222f6 100644\n--- a/Documentation/git-upload-pack.txt\n+++ b/Documentation/git-upload-pack.txt\n@@ -40,9 +40,8 @@ OPTIONS\n \tUsed by linkgit:git-http-backend[1] to serve up\n \t`$GIT_URL/info/refs?service=git-upload-pack` requests. See\n \t\"Smart Clients\" in link:technical/http-protocol.html[the HTTP\n-\ttransfer protocols] documentation and \"HTTP Transport\" in\n-\tlink:technical/protocol-v2.html[the Git Wire Protocol, Version\n-\t2] documentation. Also understood by\n+\ttransfer protocols] documentation and \"HTTP Transport\" in the\n+\tlinkgit:gitformat-protocol-v2[5] documentation. Also understood by\n \tlinkgit:git-receive-pack[1].\n \n ::\ndiff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.txt\nindex 6a9d9e5bf6f..3d60d9067e4 100644\n--- a/Documentation/gitformat-bundle.txt\n+++ b/Documentation/gitformat-bundle.txt\n@@ -27,7 +27,7 @@ FORMAT\n ------\n \n We will use ABNF notation to define the Git bundle format. See\n-link:technical/protocol-common.html for the details.\n+linkgit:gitformat-protocol-common[5] for the details.\n \n A v2 bundle looks like this:\n \ndiff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt\nsimilarity index 98%\nrename from Documentation/technical/pack-protocol.txt\nrename to Documentation/gitformat-pack-protocol.txt\nindex e13a2c064d1..b665af5b690 100644\n--- a/Documentation/technical/pack-protocol.txt\n+++ b/Documentation/gitformat-pack-protocol.txt\n@@ -1,5 +1,17 @@\n-Packfile transfer protocols\n-===========================\n+gitformat-pack-protocol(5)\n+==========================\n+\n+NAME\n+----\n+gitformat-pack-protocol - How packs are transferred over-the-wire\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n Git supports transferring data in packfiles over the ssh://, git://, http:// and\n file:// transports. There exist two sets of protocols, one for pushing\n@@ -18,7 +30,7 @@ pkt-line Format\n ---------------\n \n The descriptions below build on the pkt-line format described in\n-protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless\n+linkgit:gitformat-protocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless\n otherwise noted the usual pkt-line LF rules apply: the sender SHOULD\n include a LF, but the receiver MUST NOT complain if it is not present.\n \n@@ -707,3 +719,7 @@ An example client/server communication might look like this:\n S: 0018ok refs/heads/debug\\n\n S: 002ang refs/heads/master non-fast-forward\\n\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/gitformat-protocol-capabilities.txt\nsimilarity index 96%\nrename from Documentation/technical/protocol-capabilities.txt\nrename to Documentation/gitformat-protocol-capabilities.txt\nindex 9dfade930da..2e89f40ddb1 100644\n--- a/Documentation/technical/protocol-capabilities.txt\n+++ b/Documentation/gitformat-protocol-capabilities.txt\n@@ -1,8 +1,20 @@\n-Git Protocol Capabilities\n-=========================\n+gitformat-protocol-capabilities(5)\n+==================================\n+\n+NAME\n+----\n+gitformat-protocol-capabilities - Protocol v0 and v1 capabilities\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n NOTE: this document describes capabilities for versions 0 and 1 of the pack\n-protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]\n+protocol. For version 2, please refer to the linkgit:gitformat-protocol-v2[5]\n doc.\n \n Servers SHOULD support all capabilities defined in this document.\n@@ -77,7 +89,7 @@ interleaved with S-R-Q.\n multi_ack_detailed\n ------------------\n This is an extension of multi_ack that permits client to better\n-understand the server's in-memory state. See pack-protocol.txt,\n+understand the server's in-memory state. See linkgit:gitformat-pack-protocol[5],\n section \"Packfile Negotiation\" for more information.\n \n no-done\n@@ -281,7 +293,7 @@ a packfile upload and reference update. If the pushing client requests\n this capability, after unpacking and updating references the server\n will respond with whether the packfile unpacked successfully and if\n each reference was updated successfully. If any of those were not\n-successful, it will send back an error message. See pack-protocol.txt\n+successful, it will send back an error message. See linkgit:gitformat-pack-protocol[5]\n for example messages.\n \n report-status-v2\n@@ -292,7 +304,7 @@ adding new \"option\" directives in order to support reference rewritten by\n the \"proc-receive\" hook. The \"proc-receive\" hook may handle a command\n for a pseudo-reference which may create or update a reference with\n different name, new-oid, and old-oid. While the capability\n-'report-status' cannot report for such case. See pack-protocol.txt\n+'report-status' cannot report for such case. See linkgit:gitformat-pack-protocol[5]\n for details.\n \n delete-refs\n@@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The\n current implementation uses trace2 session IDs (see\n link:api-trace2.html[api-trace2] for details), but this may change and users of\n the session ID should not rely on this fact.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-common.txt b/Documentation/gitformat-protocol-common.txt\nsimilarity index 88%\nrename from Documentation/technical/protocol-common.txt\nrename to Documentation/gitformat-protocol-common.txt\nindex ecedb34bba5..6e1e1624e2d 100644\n--- a/Documentation/technical/protocol-common.txt\n+++ b/Documentation/gitformat-protocol-common.txt\n@@ -1,5 +1,20 @@\n-Documentation Common to Pack and Http Protocols\n-===============================================\n+gitformat-protocol-common(5)\n+============================\n+\n+NAME\n+----\n+gitformat-protocol-common - Things common to various protocols\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n+\n+This document sets defines things common to various over-the-wire\n+protocols and file formats used in Git.\n \n ABNF Notation\n -------------\n@@ -97,3 +112,7 @@ Examples (as C-style strings):\n \"000bfoobar\\n\" \"foobar\\n\"\n \"0004\" \"\"\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-v2.txt b/Documentation/gitformat-protocol-v2.txt\nsimilarity index 98%\nrename from Documentation/technical/protocol-v2.txt\nrename to Documentation/gitformat-protocol-v2.txt\nindex 8a877d27e23..ae4fcc84e37 100644\n--- a/Documentation/technical/protocol-v2.txt\n+++ b/Documentation/gitformat-protocol-v2.txt\n@@ -1,5 +1,17 @@\n-Git Wire Protocol, Version 2\n-============================\n+gitformat-protocol-v2(5)\n+========================\n+\n+NAME\n+----\n+gitformat-protocol-v2 - Git Wire Protocol, Version 2\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n This document presents a specification for a version 2 of Git's wire\n protocol. Protocol v2 will improve upon v1 in the following ways:\n@@ -26,7 +38,7 @@ Packet-Line Framing\n -------------------\n \n All communication is done using packet-line framing, just as in v1. See\n-`Documentation/technical/pack-protocol.txt` and\n+linkgit:gitformat-pack-protocol[5] and\n `Documentation/technical/protocol-common.txt` for more information.\n \n In protocol v2 these special packets will have the following semantics:\n@@ -42,7 +54,7 @@ Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`. More information can be\n-found in `pack-protocol.txt` and `http-protocol.txt`, as well as the\n+found in linkgit:gitformat-pack-protocol[5] and `http-protocol.txt`, as well as the\n `GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n@@ -566,3 +578,7 @@ and associated requested information, each separated by a single space.\n \tattr = \"size\"\n \n \tobj-info = obj-id SP obj-size\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt\nindex d79ad323e67..945c21bbc38 100644\n--- a/Documentation/technical/api-simple-ipc.txt\n+++ b/Documentation/technical/api-simple-ipc.txt\n@@ -78,7 +78,7 @@ client and an optional response message from the server. Both the\n client and server messages are unlimited in length and are terminated\n with a flush packet.\n \n-The pkt-line routines (Documentation/technical/protocol-common.txt)\n+The pkt-line routines (linkgit:gitformat-protocol-common[5])\n are used to simplify buffer management during message generation,\n transmission, and reception. A flush packet is used to mark the end\n of the message. This allows the sender to incrementally generate and\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt\nindex cc5126cfeda..9d9c7acd512 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/technical/http-protocol.txt\n@@ -222,7 +222,7 @@ smart server reply:\n S: 0000\n \n The client may send Extra Parameters (see\n-Documentation/technical/pack-protocol.txt) as a colon-separated string\n+linkgit:gitformat-pack-protocol[5]) as a colon-separated string\n in the Git-Protocol HTTP header.\n \n Uses the `--http-backend-info-refs` option to\n@@ -518,5 +518,5 @@ References\n \n http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n-link:technical/pack-protocol.html\n-link:technical/protocol-capabilities.html\n+linkgit:gitformat-pack-protocol[5]\n+linkgit:gitformat-protocol-capabilities[5]\ndiff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt\nindex aa0aa9af1c2..c6922ce6ccc 100644\n--- a/Documentation/technical/long-running-process-protocol.txt\n+++ b/Documentation/technical/long-running-process-protocol.txt\n@@ -3,7 +3,7 @@ Long-running process protocol\n \n This protocol is used when Git needs to communicate with an external\n process throughout the entire life of a single Git command. All\n-communication is in pkt-line format (see technical/protocol-common.txt)\n+communication is in pkt-line format (see linkgit:gitformat-protocol-common[5])\n over standard input and standard output.\n \n Handshake\ndiff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt\nindex 99f0eb30406..9d5199d5c6c 100644\n--- a/Documentation/technical/partial-clone.txt\n+++ b/Documentation/technical/partial-clone.txt\n@@ -79,7 +79,7 @@ Design Details\n upload-pack negotiation.\n +\n This uses the existing capability discovery mechanism.\n-See \"filter\" in Documentation/technical/pack-protocol.txt.\n+See \"filter\" in linkgit:gitformat-pack-protocol[5].\n \n - Clients pass a \"filter-spec\" to clone and fetch which is passed to the\n server to request filtering during packfile construction.\ndiff --git a/command-list.txt b/command-list.txt\nindex 66e6a0ba217..bec0fa690aa 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -210,6 +210,10 @@ giteveryday guide\n gitfaq guide\n gitformat-bundle gitformats\n gitformat-commit-graph gitformats\n+gitformat-pack-protocol gitformats\n+gitformat-protocol-capabilities gitformats\n+gitformat-protocol-common gitformats\n+gitformat-protocol-v2 gitformats\n gitglossary guide\n githooks userformats\n gitignore userformats\ndiff --git a/t/t5551-http-fetch-smart.sh b/t/t5551-http-fetch-smart.sh\nindex b9351a732f6..d17f77dda6f 100755\n--- a/t/t5551-http-fetch-smart.sh\n+++ b/t/t5551-http-fetch-smart.sh\n@@ -175,8 +175,8 @@ test_expect_success 'no-op half-auth fetch does not require a password' '\n \t# This is not possible with protocol v2, since both objects and refs\n \t# are obtained from the \"git-upload-pack\" path. A solution to this is\n \t# to teach the server and client to be able to inline ls-refs requests\n-\t# as an Extra Parameter (see pack-protocol.txt), so that \"info/refs\"\n-\t# can serve refs, just like it does in protocol v0.\n+\t# as an Extra Parameter (see \"git help gitformat-pack-protocol\"), so that\n+\t# \"info/refs\" can serve refs, just like it does in protocol v0.\n \tGIT_TEST_PROTOCOL_VERSION=0 git --git-dir=half-auth fetch &&\n \texpect_askpass none\n '\n-- \n2.37.0.932.g7b7031e73bc\n\n"},{"id":"458914","messageId":"patch-v3-5.7-6c46b4dccea-20220712T195419Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com","subject":"[PATCH v3 5/7] docs: move pack format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-12T20:07:00Z","receivedAt":"2022-07-12T20:07:45Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe various documentation pertaining to the *.pack format and related\nfiles, and updating things that refer to it to link to the new\nlocation.\n\nBy moving these we can properly link from the newly created\ngitformat-commit-graph do to a gitformat-chunk-format manpage we build\nby default.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 11 +++---\n Documentation/config/pack.txt | 2 +-\n Documentation/git-bundle.txt | 3 +-\n Documentation/git-multi-pack-index.txt | 4 +-\n .../chunk-format.txt => gitformat-chunk.txt} | 27 ++++++++++---\n Documentation/gitformat-commit-graph.txt | 2 +-\n .../index-format.txt => gitformat-index.txt} | 22 ++++++++++-\n ...p-format.txt => gitformat-pack-bitmap.txt} | 38 +++++++++++++++----\n ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++++-\n Documentation/gitformat-pack-protocol.txt | 2 +-\n .../pack-format.txt => gitformat-pack.txt} | 34 +++++++++++++++--\n ...ure-format.txt => gitformat-signature.txt} | 21 ++++++++--\n .../howto/recover-corrupted-object-harder.txt | 2 +-\n .../technical/hash-function-transition.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n cache.h | 3 +-\n command-list.txt | 6 +++\n pack-revindex.h | 2 +-\n 18 files changed, 165 insertions(+), 40 deletions(-)\n rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (90%)\n rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)\n rename Documentation/{technical/bitmap-format.txt => gitformat-pack-bitmap.txt} (91%)\n rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%)\n rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)\n rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex adc1404d380..64be37526c1 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -25,11 +25,17 @@ MAN1_TXT += gitweb.txt\n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n+MAN5_TXT += gitformat-chunk.txt\n MAN5_TXT += gitformat-commit-graph.txt\n+MAN5_TXT += gitformat-index.txt\n+MAN5_TXT += gitformat-pack-bitmap.txt\n+MAN5_TXT += gitformat-pack-cruft.txt\n MAN5_TXT += gitformat-pack-protocol.txt\n+MAN5_TXT += gitformat-pack.txt\n MAN5_TXT += gitformat-protocol-capabilities.txt\n MAN5_TXT += gitformat-protocol-common.txt\n MAN5_TXT += gitformat-protocol-v2.txt\n+MAN5_TXT += gitformat-signature.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -100,14 +106,10 @@ TECH_DOCS += MyFirstContribution\n TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n-TECH_DOCS += technical/bitmap-format\n-TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n-TECH_DOCS += technical/index-format\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n-TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\n@@ -115,7 +117,6 @@ TECH_DOCS += technical/racy-git\n TECH_DOCS += technical/reftable\n TECH_DOCS += technical/send-pack-pipeline\n TECH_DOCS += technical/shallow\n-TECH_DOCS += technical/signature-format\n TECH_DOCS += technical/trivial-merge\n SP_ARTICLES += $(TECH_DOCS)\n SP_ARTICLES += technical/api-index\ndiff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt\nindex ad7f73a1ead..3e581eab84a 100644\n--- a/Documentation/config/pack.txt\n+++ b/Documentation/config/pack.txt\n@@ -166,7 +166,7 @@ permuted into their appropriate location when writing a new bitmap.\n \n pack.writeReverseIndex::\n \tWhen true, git will write a corresponding .rev file (see:\n-\tlink:../technical/pack-format.html[Documentation/technical/pack-format.txt])\n+\tlinkgit:gitformat-pack[5])\n \tfor each new packfile that it writes in all places except for\n \tlinkgit:git-fast-import[1] and in the bulk checkin mechanism.\n \tDefaults to false.\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 1aeae09f082..4c6c41e1a09 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -57,8 +57,7 @@ size. That they're \"thin\" under the hood is merely noted here as a\n curiosity, and as a reference to other documentation.\n \n See linkgit:gitformat-bundle[5] for more details and the discussion of\n-\"thin pack\" in link:technical/pack-format.html[the pack format\n-documentation] for further details.\n+\"thin pack\" in linkgit:gitformat-pack[5] for further details.\n \n OPTIONS\n -------\ndiff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt\nindex c588fb91af1..a48c3d5ea63 100644\n--- a/Documentation/git-multi-pack-index.txt\n+++ b/Documentation/git-multi-pack-index.txt\n@@ -128,8 +128,8 @@ $ git multi-pack-index verify\n SEE ALSO\n --------\n See link:technical/multi-pack-index.html[The Multi-Pack-Index Design\n-Document] and link:technical/pack-format.html[The Multi-Pack-Index\n-Format] for more information on the multi-pack-index feature.\n+Document] and linkgit:gitformat-pack[5] for more information on the\n+multi-pack-index feature and its file format.\n \n \n GIT\ndiff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt\nsimilarity index 90%\nrename from Documentation/technical/chunk-format.txt\nrename to Documentation/gitformat-chunk.txt\nindex f36ce42f37c..784c5d987de 100644\n--- a/Documentation/technical/chunk-format.txt\n+++ b/Documentation/gitformat-chunk.txt\n@@ -1,12 +1,25 @@\n-Chunk-based file formats\n-========================\n+gitformat-chunk(5)\n+==================\n+\n+NAME\n+----\n+gitformat-chunk - Chunk-based file formats\n+\n+SYNOPSIS\n+--------\n+\n+Used by linkgit:gitformat-commit-graph[5] and the \"MIDX\" format (see\n+the pack format documentation in linkgit:gitformat-pack[5]).\n+\n+DESCRIPTION\n+-----------\n \n Some file formats in Git use a common concept of \"chunks\" to describe\n sections of the file. This allows structured access to a large file by\n scanning a small \"table of contents\" for the remaining data. This common\n format is used by the `commit-graph` and `multi-pack-index` files. See\n-link:technical/pack-format.html[the `multi-pack-index` format] and\n-the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n+the `multi-pack-index` format in linkgit:gitformat-pack[5] and\n+link:technical/commit-graph-format.html[the `commit-graph` format] for\n how they use the chunks to describe structured data.\n \n A chunk-based file format begins with some header information custom to\n@@ -113,4 +126,8 @@ for future formats:\n * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n in `midx.c` for how the chunk-format API is used to write and\n parse the multi-pack-index file format documented in\n- link:technical/pack-format.html[the multi-pack-index file format].\n+ the multi-pack-index file format section of linkgit:gitformat-pack[5].\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt\nindex 108dc2295c0..7324665716d 100644\n--- a/Documentation/gitformat-commit-graph.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -75,7 +75,7 @@ All multi-byte numbers are in network byte order.\n ID appears at most once.\n \n The CHUNK LOOKUP matches the table of contents from\n- link:technical/chunk-format.html[the chunk-based file format].\n+ the chunk-based file format, see linkgit:gitformat-chunk[5]\n \n The remaining data in the body is described one chunk at a time, and\n these chunks may be given in any order. Chunks are required unless\ndiff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt\nsimilarity index 98%\nrename from Documentation/technical/index-format.txt\nrename to Documentation/gitformat-index.txt\nindex 65da0daaa56..5f3ed10d2db 100644\n--- a/Documentation/technical/index-format.txt\n+++ b/Documentation/gitformat-index.txt\n@@ -1,5 +1,19 @@\n+gitformat-index(5)\n+==================\n+\n+NAME\n+----\n+gitformat-index - Git index format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/index\n+\n+DESCRIPTION\n+-----------\n+\n Git index format\n-================\n \n == The Git index file has the following format\n \n@@ -127,7 +141,7 @@ Git index format\n entry is encoded as if the path name for the previous entry is an\n empty string). At the beginning of an entry, an integer N in the\n variable width encoding (the same encoding as the offset is encoded\n- for OFS_DELTA pack entries; see pack-format.txt) is stored, followed\n+ for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed\n by a NUL-terminated string S. Removing N bytes from the end of the\n path name for the previous entry, and replacing it with the string S\n yields the path name for this entry.\n@@ -404,3 +418,7 @@ The remaining data of each directory block is grouped by type:\n with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,\n tools should avoid interacting with a sparse index unless they understand\n this extension.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/bitmap-format.txt b/Documentation/gitformat-pack-bitmap.txt\nsimilarity index 91%\nrename from Documentation/technical/bitmap-format.txt\nrename to Documentation/gitformat-pack-bitmap.txt\nindex a85f58f5153..942bdd020ca 100644\n--- a/Documentation/technical/bitmap-format.txt\n+++ b/Documentation/gitformat-pack-bitmap.txt\n@@ -1,7 +1,25 @@\n-GIT bitmap v1 format\n-====================\n+gitformat-pack-bitmap(5)\n+========================\n \n-== Pack and multi-pack bitmaps\n+NAME\n+----\n+gitformat-pack-bitmap - The bitmap file format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/pack-*.bitmap\n+\n+DESCRIPTION\n+-----------\n+\n+Bitmaps are a file format associated with .pack files. See\n+the pack format documentation in linkgit:gitformat-pack[5] and\n+linkgit:git-pack-objects[1].\n+\n+== GIT bitmap v1 format\n+\n+=== Pack and multi-pack bitmaps\n \n Bitmaps store reachability information about the set of objects in a packfile,\n or a multi-pack index (MIDX). The former is defined obviously, and the latter is\n@@ -37,7 +55,7 @@ Certain bitmap extensions are supported (see: Appendix B). No extensions are\n required for bitmaps corresponding to packfiles. For bitmaps that correspond to\n MIDXs, both the bit-cache and rev-cache extensions are required.\n \n-== On-disk format\n+=== On-disk format\n \n * A header appears at the beginning:\n \n@@ -142,7 +160,8 @@ in the index.\n \tTRAILER: ::\n \t\tTrailing checksum of the preceding contents.\n \n-== Appendix A: Serialization format for an EWAH bitmap\n+Appendix A - Serialization format for an EWAH bitmap\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n Ewah bitmaps are serialized in the same protocol as the JAVAEWAH\n library, making them backwards compatible with the JGit\n@@ -190,13 +209,14 @@ chunk. For efficient appending to the bitstream, the EWAH stores a\n pointer to the last RLW in the stream.\n \n \n-== Appendix B: Optional Bitmap Sections\n+Appendix B - Optional Bitmap Sections\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n These sections may or may not be present in the `.bitmap` file; their\n presence is indicated by the header flags section described above.\n \n Name-hash cache\n----------------\n+~~~~~~~~~~~~~~~\n \n If the BITMAP_OPT_HASH_CACHE flag is set, the end of the bitmap contains\n a cache of 32-bit values, one per object in the pack/MIDX. The value at\n@@ -216,3 +236,7 @@ Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag.\n If implementations want to choose a different hashing scheme, they are\n free to do so, but MUST allocate a new header flag (because comparing\n hashes made under two different schemes would be pointless).\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/cruft-packs.txt b/Documentation/gitformat-pack-cruft.txt\nsimilarity index 96%\nrename from Documentation/technical/cruft-packs.txt\nrename to Documentation/gitformat-pack-cruft.txt\nindex d81f3a8982f..908f752bd84 100644\n--- a/Documentation/technical/cruft-packs.txt\n+++ b/Documentation/gitformat-pack-cruft.txt\n@@ -1,4 +1,17 @@\n-= Cruft packs\n+gitformat-pack-cruft(5)\n+=======================\n+\n+NAME\n+----\n+gitformat-pack-cruft - The cruft pack file format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/pack-*.mtimes\n+\n+DESCRIPTION\n+-----------\n \n The cruft packs feature offer an alternative to Git's traditional mechanism of\n removing unreachable objects. This document provides an overview of Git's\n@@ -10,10 +23,11 @@ same.\n To remove unreachable objects from your repository, Git offers `git repack -Ad`\n (see linkgit:git-repack[1]). Quoting from the documentation:\n \n-[quote]\n+----\n [...] unreachable objects in a previous pack become loose, unpacked objects,\n instead of being left in the old pack. [...] loose unreachable objects will be\n pruned according to normal expiry rules with the next 'git gc' invocation.\n+----\n \n Unreachable objects aren't removed immediately, since doing so could race with\n an incoming push which may reference an object which is about to be deleted.\n@@ -121,3 +135,7 @@ which aren't already stored in an earlier cruft pack) is significantly more\n complicated to construct, and so aren't pursued here. The obvious drawback to\n the current implementation is that the entire cruft pack must be re-written from\n scratch.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt\nindex b665af5b690..f1bfd6705d9 100644\n--- a/Documentation/gitformat-pack-protocol.txt\n+++ b/Documentation/gitformat-pack-protocol.txt\n@@ -467,7 +467,7 @@ Now that the client and server have finished negotiation about what\n the minimal amount of data that needs to be sent to the client is, the server\n will construct and send the required data in packfile format.\n \n-See pack-format.txt for what the packfile itself actually looks like.\n+See linkgit:gitformat-pack[5] for what the packfile itself actually looks like.\n \n If 'side-band' or 'side-band-64k' capabilities have been specified by\n the client, the server will send the packfile data multiplexed.\ndiff --git a/Documentation/technical/pack-format.txt b/Documentation/gitformat-pack.txt\nsimilarity index 95%\nrename from Documentation/technical/pack-format.txt\nrename to Documentation/gitformat-pack.txt\nindex b520aa9c45b..5b21d0f2521 100644\n--- a/Documentation/technical/pack-format.txt\n+++ b/Documentation/gitformat-pack.txt\n@@ -1,5 +1,29 @@\n-Git pack format\n-===============\n+gitformat-pack(5)\n+=================\n+\n+NAME\n+----\n+gitformat-pack - Git pack format\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/pack-*.{pack,idx}\n+$GIT_DIR/objects/pack/pack-*.rev\n+$GIT_DIR/objects/pack/multi-pack-index\n+\n+DESCRIPTION\n+-----------\n+\n+The Git pack format is now Git stores most of its primary repository\n+data. Over the lietime af a repository loose objects (if any) and\n+smaller packs are consolidated into larger pack(s). See\n+linkgit:git-gc[1] and linkgit:git-pack-objects[1].\n+\n+The pack format is also used over-the-wire, see\n+e.g. linkgit:gitformat-protocol-v2[5], as well as being a part of\n+other container formats in the case of linkgit:gitformat-bundle[5].\n \n == Checksums and object IDs\n \n@@ -356,7 +380,7 @@ CHUNK LOOKUP:\n \t using the next chunk position if necessary.)\n \n \tThe CHUNK LOOKUP matches the table of contents from\n-\tlink:technical/chunk-format.html[the chunk-based file format].\n+\tthe chunk-based file format, see linkgit:gitformat-chunk[5].\n \n \tThe remaining data in the body is described one chunk at a time, and\n \tthese chunks may be given in any order. Chunks are required unless\n@@ -482,3 +506,7 @@ packs arranged in MIDX order (with the preferred pack coming first).\n \n The MIDX's reverse index is stored in the optional 'RIDX' chunk within\n the MIDX itself.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt\nsimilarity index 96%\nrename from Documentation/technical/signature-format.txt\nrename to Documentation/gitformat-signature.txt\nindex 166721be6f6..a249869fafa 100644\n--- a/Documentation/technical/signature-format.txt\n+++ b/Documentation/gitformat-signature.txt\n@@ -1,7 +1,18 @@\n-Git signature format\n-====================\n+gitformat-signature(5)\n+======================\n \n-== Overview\n+NAME\n+----\n+gitformat-signature - Git cryptographic signature formats\n+\n+SYNOPSIS\n+--------\n+[verse]\n+<[tag|commit] object header(s)>\n+\n+\n+DESCRIPTION\n+-----------\n \n Git uses cryptographic signatures in various places, currently objects (tags,\n commits, mergetags) and transactions (pushes). In every case, the command which\n@@ -200,3 +211,7 @@ Date: Wed Jun 15 09:13:29 2016 +0000\n # gpg: There is no indication that the signature belongs to the owner.\n # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.txt\nindex 8994e2559ea..5efb4fe81ff 100644\n--- a/Documentation/howto/recover-corrupted-object-harder.txt\n+++ b/Documentation/howto/recover-corrupted-object-harder.txt\n@@ -68,7 +68,7 @@ Note that the \"object\" file isn't fit for feeding straight to zlib; it\n has the git packed object header, which is variable-length. We want to\n strip that off so we can start playing with the zlib data directly. You\n can either work your way through it manually (the format is described in\n-link:../technical/pack-format.html[Documentation/technical/pack-format.txt]),\n+linkgit:gitformat-pack[5]),\n or you can walk through it in a debugger. I did the latter, creating a\n valid pack like:\n \ndiff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt\nindex 260224b0331..e2ac36dd210 100644\n--- a/Documentation/technical/hash-function-transition.txt\n+++ b/Documentation/technical/hash-function-transition.txt\n@@ -205,7 +205,7 @@ SHA-1 content.\n Object storage\n ~~~~~~~~~~~~~~\n Loose objects use zlib compression and packed objects use the packed\n-format described in Documentation/technical/pack-format.txt, just like\n+format described in linkgit:gitformat-pack[5], just like\n today. The content that is compressed and stored uses SHA-256 content\n instead of SHA-1 content.\n \ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 865074bed4e..ca9decdd952 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -3133,7 +3133,7 @@ those \"loose\" objects.\n You can save space and make Git faster by moving these loose objects in\n to a \"pack file\", which stores a group of objects in an efficient\n compressed format; the details of how pack files are formatted can be\n-found in link:technical/pack-format.html[pack format].\n+found in link:gitformat-pack[5].\n \n To put the loose objects into a pack, just run git repack:\n \ndiff --git a/cache.h b/cache.h\nindex ac5ab4ef9d3..82755c7c0aa 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -475,8 +475,7 @@ extern struct index_state the_index;\n \n /*\n * Values in this enum (except those outside the 3 bit range) are part\n- * of pack file format. See Documentation/technical/pack-format.txt\n- * for more information.\n+ * of pack file format. See gitformat-pack(5) for more information.\n */\n enum object_type {\n \tOBJ_BAD = -1,\ndiff --git a/command-list.txt b/command-list.txt\nindex bec0fa690aa..8cd64c34a7c 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -209,11 +209,17 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle gitformats\n+gitformat-chunk gitformats\n gitformat-commit-graph gitformats\n+gitformat-index gitformats\n+gitformat-pack gitformats\n+gitformat-pack-bitmap gitformats\n+gitformat-pack-cruft gitformats\n gitformat-pack-protocol gitformats\n gitformat-protocol-capabilities gitformats\n gitformat-protocol-common gitformats\n gitformat-protocol-v2 gitformats\n+gitformat-signature gitformats\n gitglossary guide\n githooks userformats\n gitignore userformats\ndiff --git a/pack-revindex.h b/pack-revindex.h\nindex 74f4eae668d..4974e75eb4d 100644\n--- a/pack-revindex.h\n+++ b/pack-revindex.h\n@@ -22,7 +22,7 @@\n *\n * - pack position refers to an object's position within a non-existent pack\n * described by the MIDX. The pack structure is described in\n- * Documentation/technical/pack-format.txt.\n+ * gitformat-pack(5).\n *\n * It is effectively a concatanation of all packs in the MIDX (ordered by\n * their numeric ID within the MIDX) in their original order within each\n-- \n2.37.0.932.g7b7031e73bc\n\n"},{"id":"458915","messageId":"patch-v3-6.7-5cf8b526bff-20220712T195419Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com","subject":"[PATCH v3 6/7] docs: move http-protocol docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-12T20:07:01Z","receivedAt":"2022-07-12T20:07:46Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe http-protocol.txt documentation over. I'm renaming it to\n\"protocol-http\" to be consistent with other things in the new\ngitformat-protocol-* namespace.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 2 +-\n Documentation/git-upload-pack.txt | 6 ++--\n Documentation/gitformat-pack-protocol.txt | 2 +-\n ...otocol.txt => gitformat-protocol-http.txt} | 29 ++++++++++++++++---\n Documentation/gitformat-protocol-v2.txt | 4 +--\n command-list.txt | 1 +\n 6 files changed, 33 insertions(+), 11 deletions(-)\n rename Documentation/{technical/http-protocol.txt => gitformat-protocol-http.txt} (98%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 64be37526c1..0e87d5151df 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -34,6 +34,7 @@ MAN5_TXT += gitformat-pack-protocol.txt\n MAN5_TXT += gitformat-pack.txt\n MAN5_TXT += gitformat-protocol-capabilities.txt\n MAN5_TXT += gitformat-protocol-common.txt\n+MAN5_TXT += gitformat-protocol-http.txt\n MAN5_TXT += gitformat-protocol-v2.txt\n MAN5_TXT += gitformat-signature.txt\n MAN5_TXT += githooks.txt\n@@ -107,7 +108,6 @@ TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/hash-function-transition\n-TECH_DOCS += technical/http-protocol\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-heuristics\ndiff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt\nindex 754619222f6..720697df3a0 100644\n--- a/Documentation/git-upload-pack.txt\n+++ b/Documentation/git-upload-pack.txt\n@@ -39,9 +39,9 @@ OPTIONS\n --http-backend-info-refs::\n \tUsed by linkgit:git-http-backend[1] to serve up\n \t`$GIT_URL/info/refs?service=git-upload-pack` requests. See\n-\t\"Smart Clients\" in link:technical/http-protocol.html[the HTTP\n-\ttransfer protocols] documentation and \"HTTP Transport\" in the\n-\tlinkgit:gitformat-protocol-v2[5] documentation. Also understood by\n+\t\"Smart Clients\" in linkgit:gitformat-protocol-http[5] and\n+\t\"HTTP Transport\" in link:technical/protocol-v2.html[the Git\n+\tWire Protocol, Version 2] documentation. Also understood by\n \tlinkgit:git-receive-pack[1].\n \n ::\ndiff --git a/Documentation/gitformat-pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt\nindex f1bfd6705d9..c82b926e661 100644\n--- a/Documentation/gitformat-pack-protocol.txt\n+++ b/Documentation/gitformat-pack-protocol.txt\n@@ -17,7 +17,7 @@ Git supports transferring data in packfiles over the ssh://, git://, http:// and\n file:// transports. There exist two sets of protocols, one for pushing\n data from a client to a server and another for fetching data from a\n server to a client. The three transports (ssh, git, file) use the same\n-protocol to transfer data. http is documented in http-protocol.txt.\n+protocol to transfer data. http is documented in linkgit:gitformat-protocol-http[5].\n \n The processes invoked in the canonical Git implementation are 'upload-pack'\n on the server side and 'fetch-pack' on the client side for fetching data;\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/gitformat-protocol-http.txt\nsimilarity index 98%\nrename from Documentation/technical/http-protocol.txt\nrename to Documentation/gitformat-protocol-http.txt\nindex 9d9c7acd512..b85fc86abf6 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/gitformat-protocol-http.txt\n@@ -1,5 +1,19 @@\n-HTTP transfer protocols\n-=======================\n+gitformat-protocol-http(5)\n+==========================\n+\n+NAME\n+----\n+gitformat-protocol-http - Git HTTP-based protocols\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+\n+DESCRIPTION\n+-----------\n \n Git supports two HTTP based transfer protocols. A \"dumb\" protocol\n which requires only a standard HTTP server on the server end of the\n@@ -512,11 +526,18 @@ the id obtained through ref discovery as old_id.\n \n TODO: Document this further.\n \n-\n-References\n+REFERENCES\n ----------\n \n http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n+\n+SEE ALSO\n+--------\n+\n linkgit:gitformat-pack-protocol[5]\n linkgit:gitformat-protocol-capabilities[5]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-protocol-v2.txt b/Documentation/gitformat-protocol-v2.txt\nindex ae4fcc84e37..e29bc4b6a68 100644\n--- a/Documentation/gitformat-protocol-v2.txt\n+++ b/Documentation/gitformat-protocol-v2.txt\n@@ -54,7 +54,7 @@ Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`. More information can be\n-found in linkgit:gitformat-pack-protocol[5] and `http-protocol.txt`, as well as the\n+found in linkgit:gitformat-pack-protocol[5] and linkgit:gitformat-protocol-http[5], as well as the\n `GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n@@ -78,7 +78,7 @@ HTTP Transport\n ~~~~~~~~~~~~~~\n \n When using the http:// or https:// transport a client makes a \"smart\"\n-info/refs request as described in `http-protocol.txt` and requests that\n+info/refs request as described in linkgit:gitformat-protocol-http[5] and requests that\n v2 be used by supplying \"version=2\" in the `Git-Protocol` header.\n \n C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0\ndiff --git a/command-list.txt b/command-list.txt\nindex 8cd64c34a7c..fad553784d9 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -218,6 +218,7 @@ gitformat-pack-cruft gitformats\n gitformat-pack-protocol gitformats\n gitformat-protocol-capabilities gitformats\n gitformat-protocol-common gitformats\n+gitformat-protocol-http gitformats\n gitformat-protocol-v2 gitformats\n gitformat-signature gitformats\n gitglossary guide\n-- \n2.37.0.932.g7b7031e73bc\n\n"},{"id":"458916","messageId":"patch-v3-7.7-aabdc4a4151-20220712T195419Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com","subject":"[PATCH v3 7/7] docs: move multi-pack-index docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-12T20:07:02Z","receivedAt":"2022-07-12T20:07:48Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe multi-pack-index documentation over.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 2 +-\n Documentation/git-multi-pack-index.txt | 5 +++--\n ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++++++++++++--\n Documentation/gitformat-pack.txt | 5 +++++\n command-list.txt | 1 +\n 5 files changed, 28 insertions(+), 5 deletions(-)\n rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 0e87d5151df..51c3e3a489a 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -28,6 +28,7 @@ MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += gitformat-chunk.txt\n MAN5_TXT += gitformat-commit-graph.txt\n MAN5_TXT += gitformat-index.txt\n+MAN5_TXT += gitformat-multi-pack-index.txt\n MAN5_TXT += gitformat-pack-bitmap.txt\n MAN5_TXT += gitformat-pack-cruft.txt\n MAN5_TXT += gitformat-pack-protocol.txt\n@@ -109,7 +110,6 @@ TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/long-running-process-protocol\n-TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-heuristics\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\ndiff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt\nindex a48c3d5ea63..a147e047c91 100644\n--- a/Documentation/git-multi-pack-index.txt\n+++ b/Documentation/git-multi-pack-index.txt\n@@ -127,8 +127,9 @@ $ git multi-pack-index verify\n \n SEE ALSO\n --------\n-See link:technical/multi-pack-index.html[The Multi-Pack-Index Design\n-Document] and linkgit:gitformat-pack[5] for more information on the\n+\n+See linkgit:git-multi-pack-index[1] and\n+linkgit:gitformat-multi-pack-index[5] for more information on the\n multi-pack-index feature and its file format.\n \n \ndiff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/gitformat-multi-pack-index.txt\nsimilarity index 94%\nrename from Documentation/technical/multi-pack-index.txt\nrename to Documentation/gitformat-multi-pack-index.txt\nindex f2221d2b441..3bca1e7b10d 100644\n--- a/Documentation/technical/multi-pack-index.txt\n+++ b/Documentation/gitformat-multi-pack-index.txt\n@@ -1,5 +1,17 @@\n-Multi-Pack-Index (MIDX) Design Notes\n-====================================\n+gitformat-multi-pack-index(5)\n+=============================\n+\n+NAME\n+----\n+gitformat-multi-pack-index - The multi-pack-index file format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/multi-pack-index\n+\n+DESCRIPTION\n+-----------\n \n The Git object directory contains a 'pack' directory containing\n packfiles (with suffix \".pack\") and pack-indexes (with suffix\n@@ -98,3 +110,7 @@ Related Links\n \n [2] https://lore.kernel.org/git/alpine.DEB.2.20.1803091557510.23109@alexmv-linux/\n Git Merge 2018 Contributor's summit notes (includes discussion of MIDX)\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt\nindex 5b21d0f2521..06b469c6944 100644\n--- a/Documentation/gitformat-pack.txt\n+++ b/Documentation/gitformat-pack.txt\n@@ -507,6 +507,11 @@ packs arranged in MIDX order (with the preferred pack coming first).\n The MIDX's reverse index is stored in the optional 'RIDX' chunk within\n the MIDX itself.\n \n+SEE ALSO\n+--------\n+\n+linkgit:gitformat-multi-pack-index[5]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/command-list.txt b/command-list.txt\nindex fad553784d9..685ce8077d3 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -212,6 +212,7 @@ gitformat-bundle gitformats\n gitformat-chunk gitformats\n gitformat-commit-graph gitformats\n gitformat-index gitformats\n+gitformat-multi-pack-index gitformats\n gitformat-pack gitformats\n gitformat-pack-bitmap gitformats\n gitformat-pack-cruft gitformats\n-- \n2.37.0.932.g7b7031e73bc\n\n"},{"id":"458930","messageId":"220713.86r12p4xwo.gmgdl@evledraar.gmail.com","threadId":"56715","inReplyTo":"patch-v3-1.7-929d9192828-20220712T195419Z-avarab@gmail.com","subject":"Re: [PATCH v3 1/7] git docs: split \"User-facing file formats\" off from \"Guides\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-13T01:09:59Z","receivedAt":"2022-07-13T01:14:06Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Tue, Jul 12 2022, Ævar Arnfjörð Bjarmason wrote:\n\n> @@ -47,8 +48,12 @@ static const char *drop_prefix(const char *name, uint32_t category)\n> \n> \tif (skip_prefix(name, \"git-\", &new_name))\n> \t\treturn new_name;\n> -\tif (category == CAT_guide && skip_prefix(name, \"git\", &new_name))\n> +\tswitch (category) {\n> +\tcase CAT_guide:\n> +\tcase CAT_userformats:\n> +\t\tskip_prefix(name, \"git\", &new_name);\n> \t\treturn new_name;\n> +\t}\n> \treturn name;\n> \n> }\n\nI noticed after submission that -fanalyzer complaints about this, since\naccording to it (and probably also coverity etc.) we could return a NULL\n\"new_name\" there, i.e. if the \"skip_prefix\" doesn't succeed.\n\nI'll guard this in the inevitable re-roll, but FWIW this isn't a logic\nerror now, it's just that the compiler can't see that.\n\nAll of these categories (and the one added in 2/7) have strings that\nstart with \"git\", so we'll never have a NULL \"new_name\" here, we always\nskip that prefix.\n\nOf course that depends on the relevant categories in command-list.txt\nhaving git* names, but we know that's the case, and that'll probably\nnever change. So I'll just have this BUG() out if the constraint is\nviolated.\n"},{"id":"459260","messageId":"cover-v4-0.8-00000000000-20220718T132911Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com","subject":"[PATCH v4 0/8] git doc + \"git help\": move \"format\" docs from technical/*","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-18T13:29:26Z","receivedAt":"2022-07-18T13:29:46Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"This series improves the discoverability of the technical/*\ndocumentation covering those \"formats\" where we interact with users\n(e.g. \"gitattributes\") by moving them to its own \"git help\" category.\n\nIt then moves various technical documentation from technical/* to our\nmain documentation namespace, allowing us to cross-link e.g. from\n\"git-bundle(1)\" to a new \"gitformat-bundle(5)\".\n\nSee the v3 CL[1] for more details.\n\nChanges since v3:\n\n * Made a condition that never happened but which -fanalyzer\n complained about a BUG() (required knowing about the nature of\n command-list.txt).\n\n * Ejected the conflict with ac/bitmap-lookup-table by punting on\n gitformat-pack-bitmap(5). We can migrate that later, but this way\n there's no conflicts with \"seen\".\n\n1. https://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/\n\nÆvar Arnfjörð Bjarmason (8):\n help.c: BUG() out if \"help --guides\" can't remove \"git\" prefixes\n git docs: split \"User-facing file formats\" off from \"Guides\"\n git docs: create a \"Git file formats and protocols\" section\n docs: move commit-graph format docs to man section 5\n docs: move protocol-related docs to man section 5\n docs: move pack format docs to man section 5\n docs: move http-protocol docs to man section 5\n docs: move multi-pack-index docs to man section 5\n\n Documentation/Makefile | 26 +++++-----\n Documentation/config/lsrefs.txt | 2 +-\n Documentation/config/pack.txt | 2 +-\n Documentation/config/protocol.txt | 2 +-\n Documentation/git-bundle.txt | 11 +++--\n Documentation/git-commit-graph.txt | 5 ++\n Documentation/git-help.txt | 14 ++++--\n Documentation/git-multi-pack-index.txt | 7 +--\n Documentation/git-upload-pack.txt | 7 ++-\n Documentation/git.txt | 15 ++++++\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++---\n .../chunk-format.txt => gitformat-chunk.txt} | 27 ++++++++--\n ...-format.txt => gitformat-commit-graph.txt} | 49 +++++++++++++------\n .../index-format.txt => gitformat-index.txt} | 22 ++++++++-\n ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++-\n ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++-\n ...otocol.txt => gitformat-pack-protocol.txt} | 26 ++++++++--\n .../pack-format.txt => gitformat-pack.txt} | 39 +++++++++++++--\n ...xt => gitformat-protocol-capabilities.txt} | 28 ++++++++---\n ...mmon.txt => gitformat-protocol-common.txt} | 23 ++++++++-\n ...otocol.txt => gitformat-protocol-http.txt} | 35 ++++++++++---\n ...tocol-v2.txt => gitformat-protocol-v2.txt} | 26 ++++++++--\n ...ure-format.txt => gitformat-signature.txt} | 21 ++++++--\n .../howto/recover-corrupted-object-harder.txt | 2 +-\n Documentation/lint-man-section-order.perl | 3 ++\n Documentation/technical/api-simple-ipc.txt | 2 +-\n .../technical/hash-function-transition.txt | 2 +-\n .../long-running-process-protocol.txt | 2 +-\n Documentation/technical/partial-clone.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n Makefile | 1 +\n builtin/help.c | 18 ++++++-\n cache.h | 3 +-\n command-list.txt | 33 ++++++++++---\n help.c | 32 +++++++++++-\n help.h | 2 +\n pack-revindex.h | 2 +-\n t/t0012-help.sh | 14 +++++-\n t/t5551-http-fetch-smart.sh | 4 +-\n 39 files changed, 482 insertions(+), 115 deletions(-)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)\n rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (90%)\n rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (87%)\n rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)\n rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)\n rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%)\n rename Documentation/{technical/pack-protocol.txt => gitformat-pack-protocol.txt} (98%)\n rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)\n rename Documentation/{technical/protocol-capabilities.txt => gitformat-protocol-capabilities.txt} (96%)\n rename Documentation/{technical/protocol-common.txt => gitformat-protocol-common.txt} (88%)\n rename Documentation/{technical/http-protocol.txt => gitformat-protocol-http.txt} (97%)\n rename Documentation/{technical/protocol-v2.txt => gitformat-protocol-v2.txt} (97%)\n rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)\n\nRange-diff against v3:\n-: ----------- > 1: 4428f0a6fb1 help.c: BUG() out if \"help --guides\" can't remove \"git\" prefixes\n1: 929d9192828 ! 2: 883c483d4e7 git docs: split \"User-facing file formats\" off from \"Guides\"\n @@ help.c: static struct category_description main_categories[] = {\n };\n \n @@ help.c: static const char *drop_prefix(const char *name, uint32_t category)\n - \n - \tif (skip_prefix(name, \"git-\", &new_name))\n - \t\treturn new_name;\n --\tif (category == CAT_guide && skip_prefix(name, \"git\", &new_name))\n -+\tswitch (category) {\n -+\tcase CAT_guide:\n + \tswitch (category)\n + \t{\n + \tcase CAT_guide:\n +\tcase CAT_userformats:\n -+\t\tskip_prefix(name, \"git\", &new_name);\n + \t\tif (!skip_prefix(name, \"git\", &new_name))\n + \t\t\tBUG(\"category #%d but no 'git' prefix?\", category);\n \t\treturn new_name;\n -+\t}\n - \treturn name;\n - \n - }\n @@ help.c: void list_guides_help(void)\n \tputchar('\\n');\n }\n2: 1fd57d5caf4 ! 3: d196bcd1db0 git docs: create a \"Git file formats and protocols\" section\n @@ help.c: static struct category_description main_categories[] = {\n };\n \n @@ help.c: static const char *drop_prefix(const char *name, uint32_t category)\n - \tswitch (category) {\n + \t{\n \tcase CAT_guide:\n \tcase CAT_userformats:\n +\tcase CAT_gitformats:\n - \t\tskip_prefix(name, \"git\", &new_name);\n + \t\tif (!skip_prefix(name, \"git\", &new_name))\n + \t\t\tBUG(\"category #%d but no 'git' prefix?\", category);\n \t\treturn new_name;\n - \t}\n @@ help.c: void list_user_formats_help(void)\n \tputchar('\\n');\n }\n3: d548c6aaba7 = 4: b59e001a4ca docs: move commit-graph format docs to man section 5\n4: f404987f94d = 5: 968aa977b67 docs: move protocol-related docs to man section 5\n5: 6c46b4dccea ! 6: 858ce9c6999 docs: move pack format docs to man section 5\n @@ Commit message\n gitformat-commit-graph do to a gitformat-chunk-format manpage we build\n by default.\n \n + Creating a \"gitformat-pack-bitmap\" from\n + \"Documentation/technical/bitmap-format\" might logically be part of\n + this change, but it's left out for now due to a conflict with the\n + in-flight ac/bitmap-lookup-table series.\n +\n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/Makefile ##\n @@ Documentation/Makefile: MAN1_TXT += gitweb.txt\n +MAN5_TXT += gitformat-chunk.txt\n MAN5_TXT += gitformat-commit-graph.txt\n +MAN5_TXT += gitformat-index.txt\n -+MAN5_TXT += gitformat-pack-bitmap.txt\n +MAN5_TXT += gitformat-pack-cruft.txt\n MAN5_TXT += gitformat-pack-protocol.txt\n +MAN5_TXT += gitformat-pack.txt\n @@ Documentation/Makefile: MAN1_TXT += gitweb.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n -@@ Documentation/Makefile: TECH_DOCS += MyFirstContribution\n - TECH_DOCS += MyFirstObjectWalk\n +@@ Documentation/Makefile: TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n --TECH_DOCS += technical/bitmap-format\n + TECH_DOCS += technical/bitmap-format\n -TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n @@ Documentation/gitformat-index.txt: The remaining data of each directory block is\n +\n +GIT\n +---\n -+Part of the linkgit:git[1] suite\n -\n - ## Documentation/technical/bitmap-format.txt => Documentation/gitformat-pack-bitmap.txt ##\n -@@\n --GIT bitmap v1 format\n --====================\n -+gitformat-pack-bitmap(5)\n -+========================\n - \n --== Pack and multi-pack bitmaps\n -+NAME\n -+----\n -+gitformat-pack-bitmap - The bitmap file format\n -+\n -+SYNOPSIS\n -+--------\n -+[verse]\n -+$GIT_DIR/objects/pack/pack-*.bitmap\n -+\n -+DESCRIPTION\n -+-----------\n -+\n -+Bitmaps are a file format associated with .pack files. See\n -+the pack format documentation in linkgit:gitformat-pack[5] and\n -+linkgit:git-pack-objects[1].\n -+\n -+== GIT bitmap v1 format\n -+\n -+=== Pack and multi-pack bitmaps\n - \n - Bitmaps store reachability information about the set of objects in a packfile,\n - or a multi-pack index (MIDX). The former is defined obviously, and the latter is\n -@@ Documentation/gitformat-pack-bitmap.txt: Certain bitmap extensions are supported (see: Appendix B). No extensions are\n - required for bitmaps corresponding to packfiles. For bitmaps that correspond to\n - MIDXs, both the bit-cache and rev-cache extensions are required.\n - \n --== On-disk format\n -+=== On-disk format\n - \n - * A header appears at the beginning:\n - \n -@@ Documentation/gitformat-pack-bitmap.txt: in the index.\n - \tTRAILER: ::\n - \t\tTrailing checksum of the preceding contents.\n - \n --== Appendix A: Serialization format for an EWAH bitmap\n -+Appendix A - Serialization format for an EWAH bitmap\n -+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n - \n - Ewah bitmaps are serialized in the same protocol as the JAVAEWAH\n - library, making them backwards compatible with the JGit\n -@@ Documentation/gitformat-pack-bitmap.txt: chunk. For efficient appending to the bitstream, the EWAH stores a\n - pointer to the last RLW in the stream.\n - \n - \n --== Appendix B: Optional Bitmap Sections\n -+Appendix B - Optional Bitmap Sections\n -+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n - \n - These sections may or may not be present in the `.bitmap` file; their\n - presence is indicated by the header flags section described above.\n - \n - Name-hash cache\n -----------------\n -+~~~~~~~~~~~~~~~\n - \n - If the BITMAP_OPT_HASH_CACHE flag is set, the end of the bitmap contains\n - a cache of 32-bit values, one per object in the pack/MIDX. The value at\n -@@ Documentation/gitformat-pack-bitmap.txt: Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag.\n - If implementations want to choose a different hashing scheme, they are\n - free to do so, but MUST allocate a new header flag (because comparing\n - hashes made under two different schemes would be pointless).\n -+\n -+GIT\n -+---\n +Part of the linkgit:git[1] suite\n \n ## Documentation/technical/cruft-packs.txt => Documentation/gitformat-pack-cruft.txt ##\n @@ command-list.txt: gitdiffcore guide\n gitformat-commit-graph gitformats\n +gitformat-index gitformats\n +gitformat-pack gitformats\n -+gitformat-pack-bitmap gitformats\n +gitformat-pack-cruft gitformats\n gitformat-pack-protocol gitformats\n gitformat-protocol-capabilities gitformats\n6: 5cf8b526bff ! 7: 499ee582644 docs: move http-protocol docs to man section 5\n @@ Documentation/Makefile: MAN5_TXT += gitformat-pack-protocol.txt\n MAN5_TXT += gitformat-protocol-v2.txt\n MAN5_TXT += gitformat-signature.txt\n MAN5_TXT += githooks.txt\n -@@ Documentation/Makefile: TECH_DOCS += MyFirstObjectWalk\n - TECH_DOCS += SubmittingPatches\n +@@ Documentation/Makefile: TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n + TECH_DOCS += technical/bitmap-format\n TECH_DOCS += technical/hash-function-transition\n -TECH_DOCS += technical/http-protocol\n TECH_DOCS += technical/long-running-process-protocol\n7: aabdc4a4151 ! 8: f186950e673 docs: move multi-pack-index docs to man section 5\n @@ Documentation/Makefile: MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += gitformat-commit-graph.txt\n MAN5_TXT += gitformat-index.txt\n +MAN5_TXT += gitformat-multi-pack-index.txt\n - MAN5_TXT += gitformat-pack-bitmap.txt\n MAN5_TXT += gitformat-pack-cruft.txt\n MAN5_TXT += gitformat-pack-protocol.txt\n -@@ Documentation/Makefile: TECH_DOCS += SubmittingPatches\n - TECH_DOCS += ToolsForGit\n + MAN5_TXT += gitformat-pack.txt\n +@@ Documentation/Makefile: TECH_DOCS += ToolsForGit\n + TECH_DOCS += technical/bitmap-format\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/long-running-process-protocol\n -TECH_DOCS += technical/multi-pack-index\n @@ command-list.txt: gitformat-bundle gitformats\n gitformat-index gitformats\n +gitformat-multi-pack-index gitformats\n gitformat-pack gitformats\n - gitformat-pack-bitmap gitformats\n gitformat-pack-cruft gitformats\n + gitformat-pack-protocol gitformats\n-- \n2.37.1.1032.gb00b5447790\n\n"},{"id":"459261","messageId":"patch-v4-1.8-4428f0a6fb1-20220718T132911Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v4-0.8-00000000000-20220718T132911Z-avarab@gmail.com","subject":"[PATCH v4 1/8] help.c: BUG() out if \"help --guides\" can't remove \"git\" prefixes","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-18T13:29:27Z","receivedAt":"2022-07-18T13:29:48Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Adjust code added in 929d9192828 (git docs: split \"User-facing file\nformats\" off from \"Guides\", 2021-06-04) to be more strict about the\nprefix trimming of the \"guides\" category.\n\nThere are no guides in the command-list.txt that don't start with\n\"git\", and we're unlikely to ever add any, if we do we can remove this\nBUG() invocation, but in the meantime this makes the intent more\nclear.\n\nWhile we're at it remove a stray newline that had been added after the\n\"return name;\" statement.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n help.c | 8 ++++++--\n 1 file changed, 6 insertions(+), 2 deletions(-)\n\ndiff --git a/help.c b/help.c\nindex 41c41c2aa11..24ac50f62fe 100644\n--- a/help.c\n+++ b/help.c\n@@ -47,10 +47,14 @@ static const char *drop_prefix(const char *name, uint32_t category)\n \n \tif (skip_prefix(name, \"git-\", &new_name))\n \t\treturn new_name;\n-\tif (category == CAT_guide && skip_prefix(name, \"git\", &new_name))\n+\tswitch (category)\n+\t{\n+\tcase CAT_guide:\n+\t\tif (!skip_prefix(name, \"git\", &new_name))\n+\t\t\tBUG(\"category #%d but no 'git' prefix?\", category);\n \t\treturn new_name;\n+\t}\n \treturn name;\n-\n }\n \n static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask)\n-- \n2.37.1.1032.gb00b5447790\n\n"},{"id":"459262","messageId":"patch-v4-2.8-883c483d4e7-20220718T132911Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v4-0.8-00000000000-20220718T132911Z-avarab@gmail.com","subject":"[PATCH v4 2/8] git docs: split \"User-facing file formats\" off from \"Guides\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-18T13:29:28Z","receivedAt":"2022-07-18T13:29:53Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"User-facing file formats\" section in the main \"git help\ngit\" manual page. The \"Guides\" section was added to the manual page in\nf442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense\nto list all that documentation.\n\nBut placing e.g. \"gitignore(5)\" in it is stretching the meaning of\nwhat a \"guide\" is, ideally that section should list things similar to\n\"giteveryday(7)\" and \"gitcore-tutorial(7)\".\n\nWe take a wide view of what's considered a \"user format\", it's not\njust a file format, but e.g. githooks(5) also belongs, since the\nlayout of the \".git/hooks/\" and the placement of hooks in it is\nsomething the user might be expected to interact with.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-help.txt | 13 +++++++++----\n Documentation/git.txt | 7 +++++++\n Makefile | 1 +\n builtin/help.c | 10 +++++++++-\n command-list.txt | 16 ++++++++++------\n help.c | 12 ++++++++++++\n help.h | 1 +\n t/t0012-help.sh | 12 +++++++++++-\n 9 files changed, 61 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 4f801f4e4c9..08b896a3c4c 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchingrepositories.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n+\tcmds-userformats.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\n \ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 239c68db457..6c285709040 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -9,14 +9,15 @@ SYNOPSIS\n --------\n [verse]\n 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\n-'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n+'git help' [[-i|--info] [-m|--man] [-w|--web]] [||]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n+'git help' [--user-formats]\n \n DESCRIPTION\n -----------\n \n-With no options and no '' or '' given, the synopsis of the 'git'\n+With no options and no '', '' or '' given, the synopsis of the 'git'\n command and a list of the most commonly used Git commands are printed\n on the standard output.\n \n@@ -26,8 +27,8 @@ printed on the standard output.\n If the option `--guides` or `-g` is given, a list of the\n Git concept guides is also printed on the standard output.\n \n-If a command, or a guide, is given, a manual page for that command or\n-guide is brought up. The 'man' program is used by default for this\n+If a command or other documentation is given, the relevant manual page\n+will be brought up. The 'man' program is used by default for this\n purpose, but this can be overridden by other options or configuration\n variables.\n \n@@ -69,6 +70,10 @@ OPTIONS\n --guides::\n \tPrints a list of the Git concept guides on the standard output.\n \n+--user-formats::\n+\tPrints a list of the Git user-facing format documentation on\n+\tthe standard output.\n+\n -i::\n --info::\n \tDisplay manual page for the command in the 'info' format. The\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 302607a4967..9b03bbc3851 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -339,6 +339,13 @@ The following documentation pages are guides about Git concepts.\n \n include::cmds-guide.txt[]\n \n+User-facing file formats\n+------------------------\n+\n+This documentation discusses file formats that users are expected to\n+edit. These can also be listed with 'git help --user-formats'.\n+\n+include::cmds-userformats.txt[]\n \n Configuration Mechanism\n -----------------------\ndiff --git a/Makefile b/Makefile\nindex 04d0fd1fe60..e24db1d52e2 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -3489,6 +3489,7 @@ check-docs::\n \t\tsed -e '1,/^### command list/d' \\\n \t\t -e '/^#/d' \\\n \t\t -e '/guide$$/d' \\\n+\t\t -e '/formats$$/d' \\\n \t\t -e 's/[ \t].*//' \\\n \t\t -e 's/^/listed /' command-list.txt; \\\n \t\t$(MAKE) -C Documentation print-man1 | \\\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 222f994f863..b0164b774c2 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -43,6 +43,7 @@ static enum help_action {\n \tHELP_ACTION_ALL = 1,\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n+\tHELP_ACTION_USER_FORMATS,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -69,6 +70,8 @@ static struct option builtin_help_options[] = {\n \n \tOPT_CMDMODE('g', \"guides\", &cmd_mode, N_(\"print list of useful guides\"),\n \t\t HELP_ACTION_GUIDES),\n+\tOPT_CMDMODE(0, \"user-formats\", &cmd_mode, N_(\"print list of user-facing file formats\"),\n+\t\t HELP_ACTION_USER_FORMATS),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -81,9 +84,10 @@ static struct option builtin_help_options[] = {\n \n static const char * const builtin_help_usage[] = {\n \t\"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n-\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] []\"),\n+\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [|]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n+\t\"git help [--user-formats]\",\n \tNULL\n };\n \n@@ -654,6 +658,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\topt_mode_usage(argc, \"--config-for-completion\", help_format);\n \t\tlist_config_help(SHOW_CONFIG_VARS);\n \t\treturn 0;\n+\tcase HELP_ACTION_USER_FORMATS:\n+\t\topt_mode_usage(argc, \"--user-formats\", help_format);\n+\t\tlist_user_formats_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n \t\t\t help_format);\ndiff --git a/command-list.txt b/command-list.txt\nindex 9bd6f3c48f4..c1eace8f7ad 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -43,6 +43,10 @@\n # specified here, which can only have \"guide\" attribute and nothing\n # else.\n #\n+# User-facing file formats such as documentation for the .gitmodules,\n+# .mailmap etc. files lives in man section 5. These entries can only\n+# have the \"userformats\" attribute and nothing else.\n+#\n ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -192,7 +196,7 @@ git-verify-tag ancillaryinterrogators\n git-whatchanged ancillaryinterrogators complete\n git-worktree mainporcelain\n git-write-tree plumbingmanipulators\n-gitattributes guide\n+gitattributes userformats\n gitcli guide\n gitcore-tutorial guide\n gitcredentials guide\n@@ -201,14 +205,14 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitglossary guide\n-githooks guide\n-gitignore guide\n+githooks userformats\n+gitignore userformats\n gitk mainporcelain\n-gitmailmap guide\n-gitmodules guide\n+gitmailmap userformats\n+gitmodules userformats\n gitnamespaces guide\n gitremote-helpers guide\n-gitrepository-layout guide\n+gitrepository-layout userformats\n gitrevisions guide\n gitsubmodules guide\n gittutorial guide\ndiff --git a/help.c b/help.c\nindex 24ac50f62fe..17ba210cf4e 100644\n--- a/help.c\n+++ b/help.c\n@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_plumbinginterrogators, N_(\"Low-level Commands / Interrogators\") },\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n+\t{ CAT_userformats, N_(\"Git user-facing file formats\") },\n \t{ 0, NULL }\n };\n \n@@ -50,6 +51,7 @@ static const char *drop_prefix(const char *name, uint32_t category)\n \tswitch (category)\n \t{\n \tcase CAT_guide:\n+\tcase CAT_userformats:\n \t\tif (!skip_prefix(name, \"git\", &new_name))\n \t\t\tBUG(\"category #%d but no 'git' prefix?\", category);\n \t\treturn new_name;\n@@ -430,6 +432,16 @@ void list_guides_help(void)\n \tputchar('\\n');\n }\n \n+void list_user_formats_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_userformats, N_(\"Git user-facing file formats:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex 971a3ad855a..d8b744178ec 100644\n--- a/help.h\n+++ b/help.h\n@@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num)\n void list_common_cmds_help(void);\n void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n+void list_user_formats_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex 6c33a436901..91b5318aa32 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -44,6 +44,8 @@ test_expect_success 'invalid usage' '\n \ttest_expect_code 129 git help -g add &&\n \ttest_expect_code 129 git help -a -g &&\n \n+\ttest_expect_code 129 git help --user-formats add &&\n+\n \ttest_expect_code 129 git help -g -c &&\n \ttest_expect_code 129 git help --config-for-completion add &&\n \ttest_expect_code 129 git help --config-sections-for-completion add\n@@ -104,9 +106,9 @@ test_expect_success 'git help' '\n \ttest_i18ngrep \"^ commit \" help.output &&\n \ttest_i18ngrep \"^ fetch \" help.output\n '\n+\n test_expect_success 'git help -g' '\n \tgit help -g >help.output &&\n-\ttest_i18ngrep \"^ attributes \" help.output &&\n \ttest_i18ngrep \"^ everyday \" help.output &&\n \ttest_i18ngrep \"^ tutorial \" help.output\n '\n@@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' '\n \ttest_cmp expect test-browser.log\n '\n \n+test_expect_success 'git help --user-formats' '\n+\tgit help --user-formats >help.output &&\n+\tgrep \"^ attributes \" help.output &&\n+\tgrep \"^ mailmap \" help.output\n+'\n+\n test_expect_success 'git help -c' '\n \tgit help -c >help.output &&\n \tcat >expect <<-\\EOF &&\n@@ -220,6 +228,8 @@ test_expect_success \"'git help -a' section spacing\" '\n \tLow-level Commands / Syncing Repositories\n \n \tLow-level Commands / Internal Helpers\n+\n+\tGit user-facing file formats\n \tEOF\n \ttest_cmp expect actual\n '\n-- \n2.37.1.1032.gb00b5447790\n\n"},{"id":"459263","messageId":"patch-v4-3.8-d196bcd1db0-20220718T132911Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v4-0.8-00000000000-20220718T132911Z-avarab@gmail.com","subject":"[PATCH v4 3/8] git docs: create a \"Git file formats and protocols\" section","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-18T13:29:29Z","receivedAt":"2022-07-18T13:29:55Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"Git file formats and protocols\" section in the main \"git help\ngit\" manual page and start moving the documentation that now lives in\n\"Documentation/technical/*.git\" over to it. This compliments the newly\nadded and adjacent \"User-facing file formats\" section.\n\nThis makes the technical documentation more accessible and\ndiscoverable. Before this we wouldn't install it by default, and had\nno ability to build man page versions of them. The links to them from\nour existing documentation link to the generated HTML version of these\ndocs.\n\nSo let's start moving those over, starting with just the\n\"bundle-format.txt\" documentation added in 7378ec90e1c (doc: describe\nGit bundle format, 2020-02-07). We'll now have a new\ngitformat-bundle(5) man page. Subsequent commits will move more git\ninternal format documentation over.\n\nUnfortunately the syntax of the current Documentation/technical/*.txt\nis not the same (when it comes to section headings etc.) as our\nDocumentation/*.txt documentation, so change the relevant bits of\nsyntax as we're moving this over.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 3 +-\n Documentation/git-bundle.txt | 12 +++--\n Documentation/git-help.txt | 1 +\n Documentation/git.txt | 8 ++++\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++---\n Documentation/lint-man-section-order.perl | 3 ++\n builtin/help.c | 8 ++++\n command-list.txt | 5 +++\n help.c | 12 +++++\n help.h | 1 +\n t/t0012-help.sh | 2 +\n 11 files changed, 87 insertions(+), 12 deletions(-)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 08b896a3c4c..404139274e7 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -24,6 +24,7 @@ MAN1_TXT += gitweb.txt\n \n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n+MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -95,7 +96,6 @@ TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n-TECH_DOCS += technical/bundle-format\n TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n@@ -291,6 +291,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n \tcmds-userformats.txt \\\n+\tcmds-gitformats.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\n \ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 7685b570455..1aeae09f082 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -56,10 +56,9 @@ using \"thin packs\", bundles created using exclusions are smaller in\n size. That they're \"thin\" under the hood is merely noted here as a\n curiosity, and as a reference to other documentation.\n \n-See link:technical/bundle-format.html[the `bundle-format`\n-documentation] for more details and the discussion of \"thin pack\" in\n-link:technical/pack-format.html[the pack format documentation] for\n-further details.\n+See linkgit:gitformat-bundle[5] for more details and the discussion of\n+\"thin pack\" in link:technical/pack-format.html[the pack format\n+documentation] for further details.\n \n OPTIONS\n -------\n@@ -337,6 +336,11 @@ You can also see what references it offers:\n $ git ls-remote mybundle\n ----------------\n \n+FILE FORMAT\n+-----------\n+\n+See linkgit:gitformat-bundle[5].\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 6c285709040..a91126ba802 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -13,6 +13,7 @@ SYNOPSIS\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n 'git help' [--user-formats]\n+'git help' [--git-formats]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 9b03bbc3851..1980a0e29cd 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -347,6 +347,14 @@ edit. These can also be listed with 'git help --user-formats'.\n \n include::cmds-userformats.txt[]\n \n+Git file formats and protocols\n+------------------------------\n+\n+This documentation discusses the file formats and protocols that git\n+itself uses. These can also be listed with 'git help --git-formats'.\n+\n+include::cmds-gitformats.txt[]\n+\n Configuration Mechanism\n -----------------------\n \ndiff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt\nsimilarity index 79%\nrename from Documentation/technical/bundle-format.txt\nrename to Documentation/gitformat-bundle.txt\nindex b9be8644cf5..6a9d9e5bf6f 100644\n--- a/Documentation/technical/bundle-format.txt\n+++ b/Documentation/gitformat-bundle.txt\n@@ -1,11 +1,33 @@\n-= Git bundle v2 format\n+gitformat-bundle(5)\n+===================\n \n-The Git bundle format is a format that represents both refs and Git objects.\n+NAME\n+----\n+gitformat-bundle - The bundle file format\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+*.bundle\n+*.bdl\n+\n+DESCRIPTION\n+-----------\n+\n+The Git bundle format is a format that represents both refs and Git\n+objects. A bundle is a header in a format similar to\n+linkgit:git-show-ref[1] followed by a pack in *.pack format.\n \n-== Format\n+The format is created and read by the linkgit:git-bundle[1] command,\n+and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1].\n+\n+\n+FORMAT\n+------\n \n We will use ABNF notation to define the Git bundle format. See\n-protocol-common.txt for the details.\n+link:technical/protocol-common.html for the details.\n \n A v2 bundle looks like this:\n \n@@ -36,7 +58,9 @@ value = *(%01-09 / %0b-FF)\n pack = ... ; packfile\n ----\n \n-== Semantics\n+\n+SEMANTICS\n+---------\n \n A Git bundle consists of several parts.\n \n@@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id.\n This is a comment and it has no specific meaning. The writer of the bundle MAY\n put any string here. The reader of the bundle MUST ignore the comment.\n \n-=== Note on the shallow clone and a Git bundle\n+Note on the shallow clone and a Git bundle\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n Note that the prerequisites does not represent a shallow-clone boundary. The\n semantics of the prerequisites and the shallow-clone boundaries are different,\n and the Git bundle v2 format cannot represent a shallow clone repository.\n \n-== Capabilities\n+CAPABILITIES\n+------------\n \n Because there is no opportunity for negotiation, unknown capabilities cause 'git\n bundle' to abort.\n@@ -79,3 +105,7 @@ bundle' to abort.\n * `filter` specifies an object filter as in the `--filter` option in\n linkgit:git-rev-list[1]. The resulting pack-file must be marked as a\n `.promisor` pack-file after it is unbundled.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl\nindex 425377dfeb7..02408a0062f 100755\n--- a/Documentation/lint-man-section-order.perl\n+++ b/Documentation/lint-man-section-order.perl\n@@ -32,6 +32,9 @@\n \t\t'SEE ALSO' => {\n \t\t\torder => $order++,\n \t\t},\n+\t\t'FILE FORMAT' => {\n+\t\t\torder => $order++,\n+\t\t},\n \t\t'GIT' => {\n \t\t\trequired => 1,\n \t\t\torder => $order++,\ndiff --git a/builtin/help.c b/builtin/help.c\nindex b0164b774c2..3ff2c5d17a7 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -44,6 +44,7 @@ static enum help_action {\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n \tHELP_ACTION_USER_FORMATS,\n+\tHELP_ACTION_GIT_FORMATS,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -72,6 +73,8 @@ static struct option builtin_help_options[] = {\n \t\t HELP_ACTION_GUIDES),\n \tOPT_CMDMODE(0, \"user-formats\", &cmd_mode, N_(\"print list of user-facing file formats\"),\n \t\t HELP_ACTION_USER_FORMATS),\n+\tOPT_CMDMODE(0, \"git-formats\", &cmd_mode, N_(\"print list of internal file formats and network protocols\"),\n+\t\t HELP_ACTION_GIT_FORMATS),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -88,6 +91,7 @@ static const char * const builtin_help_usage[] = {\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n \t\"git help [--user-formats]\",\n+\t\"git help [--git-formats]\",\n \tNULL\n };\n \n@@ -662,6 +666,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\topt_mode_usage(argc, \"--user-formats\", help_format);\n \t\tlist_user_formats_help();\n \t\treturn 0;\n+\tcase HELP_ACTION_GIT_FORMATS:\n+\t\topt_mode_usage(argc, \"--git-formats\", help_format);\n+\t\tlist_git_formats_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n \t\t\t help_format);\ndiff --git a/command-list.txt b/command-list.txt\nindex c1eace8f7ad..1794a7279bc 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -47,6 +47,10 @@\n # .mailmap etc. files lives in man section 5. These entries can only\n # have the \"userformats\" attribute and nothing else.\n #\n+# Git internal file formats and protocols, such as documentation for the\n+# *.bundle format lives in man section 5. These entries can only have\n+# the \"gitformats\" attribute and nothing else.\n+#\n ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -204,6 +208,7 @@ gitcvs-migration guide\n gitdiffcore guide\n giteveryday guide\n gitfaq guide\n+gitformat-bundle gitformats\n gitglossary guide\n githooks userformats\n gitignore userformats\ndiff --git a/help.c b/help.c\nindex 17ba210cf4e..68b1dc70aff 100644\n--- a/help.c\n+++ b/help.c\n@@ -39,6 +39,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n \t{ CAT_userformats, N_(\"Git user-facing file formats\") },\n+\t{ CAT_gitformats, N_(\"Git internal file formats and protocols\") },\n \t{ 0, NULL }\n };\n \n@@ -52,6 +53,7 @@ static const char *drop_prefix(const char *name, uint32_t category)\n \t{\n \tcase CAT_guide:\n \tcase CAT_userformats:\n+\tcase CAT_gitformats:\n \t\tif (!skip_prefix(name, \"git\", &new_name))\n \t\t\tBUG(\"category #%d but no 'git' prefix?\", category);\n \t\treturn new_name;\n@@ -442,6 +444,16 @@ void list_user_formats_help(void)\n \tputchar('\\n');\n }\n \n+void list_git_formats_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_gitformats, N_(\"Internal file formats and protocols:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex d8b744178ec..173bd890ce3 100644\n--- a/help.h\n+++ b/help.h\n@@ -23,6 +23,7 @@ void list_common_cmds_help(void);\n void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n void list_user_formats_help(void);\n+void list_git_formats_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex 91b5318aa32..0e291cb91e8 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -230,6 +230,8 @@ test_expect_success \"'git help -a' section spacing\" '\n \tLow-level Commands / Internal Helpers\n \n \tGit user-facing file formats\n+\n+\tGit internal file formats and protocols\n \tEOF\n \ttest_cmp expect actual\n '\n-- \n2.37.1.1032.gb00b5447790\n\n"},{"id":"459264","messageId":"patch-v4-4.8-b59e001a4ca-20220718T132911Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v4-0.8-00000000000-20220718T132911Z-avarab@gmail.com","subject":"[PATCH v4 4/8] docs: move commit-graph format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-18T13:29:30Z","receivedAt":"2022-07-18T13:29:56Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space.\n\nBy moving the documentation for the commit-graph format into man\nsection 5 and the new \"gitformats\" category. This change is split from\nsubsequent commits due to the relatively large amount of ASCIIDOC\nformatting changes that are required.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-commit-graph.txt | 5 ++\n ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------\n Documentation/technical/chunk-format.txt | 4 +-\n command-list.txt | 1 +\n 5 files changed, 41 insertions(+), 17 deletions(-)\n rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (88%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 404139274e7..cc6870cce41 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -25,6 +25,7 @@ MAN1_TXT += gitweb.txt\n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n+MAN5_TXT += gitformat-commit-graph.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex e1f48c95b3c..047decdb65b 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append\n ------------------------------------------------\n \n \n+FILE FORMAT\n+-----------\n+\n+see linkgit:gitformat-commit-graph[5].\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt\nsimilarity index 88%\nrename from Documentation/technical/commit-graph-format.txt\nrename to Documentation/gitformat-commit-graph.txt\nindex 484b185ba98..108dc2295c0 100644\n--- a/Documentation/technical/commit-graph-format.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -1,5 +1,18 @@\n-Git commit graph format\n-=======================\n+gitformat-commit-graph(5)\n+=========================\n+\n+NAME\n+----\n+gitformat-commit-graph - Git commit graph format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/info/commit-graph\n+$GIT_DIR/objects/info/commit-graphs/*\n+\n+DESCRIPTION\n+-----------\n \n The Git commit graph stores a list of commit OIDs and some associated\n metadata, including:\n@@ -30,7 +43,7 @@ and hash type.\n \n All multi-byte numbers are in network byte order.\n \n-HEADER:\n+=== HEADER:\n \n 4-byte signature:\n The signature is: {'C', 'G', 'P', 'H'}\n@@ -52,7 +65,7 @@ HEADER:\n We infer the length (H*B) of the Base Graphs chunk\n from this value.\n \n-CHUNK LOOKUP:\n+=== CHUNK LOOKUP:\n \n (C + 1) * 12 bytes listing the table of contents for the chunks:\n First 4 bytes describe the chunk id. Value 0 is a terminating label.\n@@ -68,17 +81,17 @@ CHUNK LOOKUP:\n these chunks may be given in any order. Chunks are required unless\n otherwise specified.\n \n-CHUNK DATA:\n+=== CHUNK DATA:\n \n- OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n+==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n The ith entry, F[i], stores the number of OIDs with first\n byte at most i. Thus F[255] stores the total\n number of commits (N).\n \n- OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n+==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n The OIDs for all commits in the graph, sorted in ascending order.\n \n- Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n+==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n * The first H bytes are for the OID of the root tree.\n * The next 8 bytes are for the positions of the first two parents\n of the ith commit. Stores value 0x70000000 if no parent in that\n@@ -93,7 +106,7 @@ CHUNK DATA:\n 2 bits of the lowest byte, storing the 33rd and 34th bit of the\n commit time.\n \n- Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n+==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n * This list of 4-byte values store corrected commit date offsets for the\n commits, arranged in the same order as commit data chunk.\n * If the corrected commit date offset cannot be stored within 31 bits,\n@@ -104,7 +117,7 @@ CHUNK DATA:\n by compatible versions of Git and in case of split commit-graph chains,\n the topmost layer also has Generation Data chunk.\n \n- Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n+==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n * This list of 8-byte values stores the corrected commit date offsets\n for commits with corrected commit date offsets that cannot be\n stored within 31 bits.\n@@ -112,7 +125,7 @@ CHUNK DATA:\n chunk is present and atleast one corrected commit date offset cannot\n be stored within 31 bits.\n \n- Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n+==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n This list of 4-byte values store the second through nth parents for\n all octopus merges. The second parent value in the commit data stores\n an array position within this list along with the most-significant bit\n@@ -120,14 +133,14 @@ CHUNK DATA:\n positions for the parents until reaching a value with the most-significant\n bit on. The other bits correspond to the position of the last parent.\n \n- Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n+==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters\n from commit 0 to commit i (inclusive) in lexicographic order. The Bloom\n filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header\n length), where BIDX[-1] is 0.\n * The BIDX chunk is ignored if the BDAT chunk is not present.\n \n- Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n+==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n * It starts with header consisting of three unsigned 32-bit integers:\n - Version of the hash algorithm being used. We currently only support\n \tvalue 1 which corresponds to the 32-bit version of the murmur3 hash\n@@ -147,13 +160,13 @@ CHUNK DATA:\n of length one, with either all bits set to zero or one respectively.\n * The BDAT chunk is present if and only if BIDX is present.\n \n- Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n+==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n This list of H-byte hashes describe a set of B commit-graph files that\n form a commit-graph chain. The graph position for the ith commit in this\n file's OID Lookup chunk is equal to i plus the number of commits in all\n base graphs. If B is non-zero, this chunk must exist.\n \n-TRAILER:\n+=== TRAILER:\n \n \tH-byte HASH-checksum of all of the above.\n \n@@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote\n possibly erroneous data in these chunks with the IDs \"GDAT\" and \"GDOV\". By\n changing the IDs, newer versions of Git will silently ignore those older\n chunks and write the new information without trusting the incorrect data.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/chunk-format.txt b/Documentation/technical/chunk-format.txt\nindex 593614fceda..f36ce42f37c 100644\n--- a/Documentation/technical/chunk-format.txt\n+++ b/Documentation/technical/chunk-format.txt\n@@ -6,7 +6,7 @@ sections of the file. This allows structured access to a large file by\n scanning a small \"table of contents\" for the remaining data. This common\n format is used by the `commit-graph` and `multi-pack-index` files. See\n link:technical/pack-format.html[the `multi-pack-index` format] and\n-link:technical/commit-graph-format.html[the `commit-graph` format] for\n+the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n how they use the chunks to describe structured data.\n \n A chunk-based file format begins with some header information custom to\n@@ -108,7 +108,7 @@ for future formats:\n * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()`\n in `commit-graph.c` for how the chunk-format API is used to write and\n parse the commit-graph file format documented in\n- link:technical/commit-graph-format.html[the commit-graph file format].\n+ the commit-graph file format in linkgit:gitformat-commit-graph[5].\n \n * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n in `midx.c` for how the chunk-format API is used to write and\ndiff --git a/command-list.txt b/command-list.txt\nindex 1794a7279bc..66e6a0ba217 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -209,6 +209,7 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle gitformats\n+gitformat-commit-graph gitformats\n gitglossary guide\n githooks userformats\n gitignore userformats\n-- \n2.37.1.1032.gb00b5447790\n\n"},{"id":"459265","messageId":"patch-v4-5.8-968aa977b67-20220718T132911Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v4-0.8-00000000000-20220718T132911Z-avarab@gmail.com","subject":"[PATCH v4 5/8] docs: move protocol-related docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-18T13:29:31Z","receivedAt":"2022-07-18T13:29:59Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space. By moving\nthe things that discuss the protocol we can properly link from\ne.g. lsrefs.unborn and protocol.version documentation to a manpage we\nbuild by default.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 8 +++---\n Documentation/config/lsrefs.txt | 2 +-\n Documentation/config/protocol.txt | 2 +-\n Documentation/git-upload-pack.txt | 5 ++--\n Documentation/gitformat-bundle.txt | 2 +-\n ...otocol.txt => gitformat-pack-protocol.txt} | 22 +++++++++++++--\n ...xt => gitformat-protocol-capabilities.txt} | 28 +++++++++++++++----\n ...mmon.txt => gitformat-protocol-common.txt} | 23 +++++++++++++--\n ...tocol-v2.txt => gitformat-protocol-v2.txt} | 24 +++++++++++++---\n Documentation/technical/api-simple-ipc.txt | 2 +-\n Documentation/technical/http-protocol.txt | 6 ++--\n .../long-running-process-protocol.txt | 2 +-\n Documentation/technical/partial-clone.txt | 2 +-\n command-list.txt | 4 +++\n t/t5551-http-fetch-smart.sh | 4 +--\n 15 files changed, 103 insertions(+), 33 deletions(-)\n rename Documentation/{technical/pack-protocol.txt => gitformat-pack-protocol.txt} (98%)\n rename Documentation/{technical/protocol-capabilities.txt => gitformat-protocol-capabilities.txt} (96%)\n rename Documentation/{technical/protocol-common.txt => gitformat-protocol-common.txt} (88%)\n rename Documentation/{technical/protocol-v2.txt => gitformat-protocol-v2.txt} (98%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex cc6870cce41..adc1404d380 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -26,6 +26,10 @@ MAN1_TXT += gitweb.txt\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += gitformat-commit-graph.txt\n+MAN5_TXT += gitformat-pack-protocol.txt\n+MAN5_TXT += gitformat-protocol-capabilities.txt\n+MAN5_TXT += gitformat-protocol-common.txt\n+MAN5_TXT += gitformat-protocol-v2.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -105,12 +109,8 @@ TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n-TECH_DOCS += technical/pack-protocol\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\n-TECH_DOCS += technical/protocol-capabilities\n-TECH_DOCS += technical/protocol-common\n-TECH_DOCS += technical/protocol-v2\n TECH_DOCS += technical/racy-git\n TECH_DOCS += technical/reftable\n TECH_DOCS += technical/send-pack-pipeline\ndiff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.txt\nindex adeda0f24d3..e9efe498c01 100644\n--- a/Documentation/config/lsrefs.txt\n+++ b/Documentation/config/lsrefs.txt\n@@ -1,7 +1,7 @@\n lsrefs.unborn::\n \tMay be \"advertise\" (the default), \"allow\", or \"ignore\". If \"advertise\",\n \tthe server will respond to the client sending \"unborn\" (as described in\n-\tprotocol-v2.txt) and will advertise support for this feature during the\n+\tlinkgit:gitformat-protocol-v2[5]) and will advertise support for this feature during the\n \tprotocol v2 capability advertisement. \"allow\" is the same as\n \t\"advertise\" except that the server will not advertise support for this\n \tfeature; this is useful for load-balanced servers that cannot be\ndiff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt\nindex 756591d77b0..bf18a70a924 100644\n--- a/Documentation/config/protocol.txt\n+++ b/Documentation/config/protocol.txt\n@@ -58,6 +58,6 @@ protocol.version::\n * `1` - the original wire protocol with the addition of a version string\n in the initial response from the server.\n \n-* `2` - link:technical/protocol-v2.html[wire protocol version 2].\n+* `2` - Wire protocol version 2, see linkgit:gitformat-protocol-v2[5].\n \n --\ndiff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt\nindex 8f87b23ea86..754619222f6 100644\n--- a/Documentation/git-upload-pack.txt\n+++ b/Documentation/git-upload-pack.txt\n@@ -40,9 +40,8 @@ OPTIONS\n \tUsed by linkgit:git-http-backend[1] to serve up\n \t`$GIT_URL/info/refs?service=git-upload-pack` requests. See\n \t\"Smart Clients\" in link:technical/http-protocol.html[the HTTP\n-\ttransfer protocols] documentation and \"HTTP Transport\" in\n-\tlink:technical/protocol-v2.html[the Git Wire Protocol, Version\n-\t2] documentation. Also understood by\n+\ttransfer protocols] documentation and \"HTTP Transport\" in the\n+\tlinkgit:gitformat-protocol-v2[5] documentation. Also understood by\n \tlinkgit:git-receive-pack[1].\n \n ::\ndiff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.txt\nindex 6a9d9e5bf6f..3d60d9067e4 100644\n--- a/Documentation/gitformat-bundle.txt\n+++ b/Documentation/gitformat-bundle.txt\n@@ -27,7 +27,7 @@ FORMAT\n ------\n \n We will use ABNF notation to define the Git bundle format. See\n-link:technical/protocol-common.html for the details.\n+linkgit:gitformat-protocol-common[5] for the details.\n \n A v2 bundle looks like this:\n \ndiff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt\nsimilarity index 98%\nrename from Documentation/technical/pack-protocol.txt\nrename to Documentation/gitformat-pack-protocol.txt\nindex e13a2c064d1..b665af5b690 100644\n--- a/Documentation/technical/pack-protocol.txt\n+++ b/Documentation/gitformat-pack-protocol.txt\n@@ -1,5 +1,17 @@\n-Packfile transfer protocols\n-===========================\n+gitformat-pack-protocol(5)\n+==========================\n+\n+NAME\n+----\n+gitformat-pack-protocol - How packs are transferred over-the-wire\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n Git supports transferring data in packfiles over the ssh://, git://, http:// and\n file:// transports. There exist two sets of protocols, one for pushing\n@@ -18,7 +30,7 @@ pkt-line Format\n ---------------\n \n The descriptions below build on the pkt-line format described in\n-protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless\n+linkgit:gitformat-protocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless\n otherwise noted the usual pkt-line LF rules apply: the sender SHOULD\n include a LF, but the receiver MUST NOT complain if it is not present.\n \n@@ -707,3 +719,7 @@ An example client/server communication might look like this:\n S: 0018ok refs/heads/debug\\n\n S: 002ang refs/heads/master non-fast-forward\\n\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/gitformat-protocol-capabilities.txt\nsimilarity index 96%\nrename from Documentation/technical/protocol-capabilities.txt\nrename to Documentation/gitformat-protocol-capabilities.txt\nindex 9dfade930da..2e89f40ddb1 100644\n--- a/Documentation/technical/protocol-capabilities.txt\n+++ b/Documentation/gitformat-protocol-capabilities.txt\n@@ -1,8 +1,20 @@\n-Git Protocol Capabilities\n-=========================\n+gitformat-protocol-capabilities(5)\n+==================================\n+\n+NAME\n+----\n+gitformat-protocol-capabilities - Protocol v0 and v1 capabilities\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n NOTE: this document describes capabilities for versions 0 and 1 of the pack\n-protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]\n+protocol. For version 2, please refer to the linkgit:gitformat-protocol-v2[5]\n doc.\n \n Servers SHOULD support all capabilities defined in this document.\n@@ -77,7 +89,7 @@ interleaved with S-R-Q.\n multi_ack_detailed\n ------------------\n This is an extension of multi_ack that permits client to better\n-understand the server's in-memory state. See pack-protocol.txt,\n+understand the server's in-memory state. See linkgit:gitformat-pack-protocol[5],\n section \"Packfile Negotiation\" for more information.\n \n no-done\n@@ -281,7 +293,7 @@ a packfile upload and reference update. If the pushing client requests\n this capability, after unpacking and updating references the server\n will respond with whether the packfile unpacked successfully and if\n each reference was updated successfully. If any of those were not\n-successful, it will send back an error message. See pack-protocol.txt\n+successful, it will send back an error message. See linkgit:gitformat-pack-protocol[5]\n for example messages.\n \n report-status-v2\n@@ -292,7 +304,7 @@ adding new \"option\" directives in order to support reference rewritten by\n the \"proc-receive\" hook. The \"proc-receive\" hook may handle a command\n for a pseudo-reference which may create or update a reference with\n different name, new-oid, and old-oid. While the capability\n-'report-status' cannot report for such case. See pack-protocol.txt\n+'report-status' cannot report for such case. See linkgit:gitformat-pack-protocol[5]\n for details.\n \n delete-refs\n@@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The\n current implementation uses trace2 session IDs (see\n link:api-trace2.html[api-trace2] for details), but this may change and users of\n the session ID should not rely on this fact.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-common.txt b/Documentation/gitformat-protocol-common.txt\nsimilarity index 88%\nrename from Documentation/technical/protocol-common.txt\nrename to Documentation/gitformat-protocol-common.txt\nindex ecedb34bba5..6e1e1624e2d 100644\n--- a/Documentation/technical/protocol-common.txt\n+++ b/Documentation/gitformat-protocol-common.txt\n@@ -1,5 +1,20 @@\n-Documentation Common to Pack and Http Protocols\n-===============================================\n+gitformat-protocol-common(5)\n+============================\n+\n+NAME\n+----\n+gitformat-protocol-common - Things common to various protocols\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n+\n+This document sets defines things common to various over-the-wire\n+protocols and file formats used in Git.\n \n ABNF Notation\n -------------\n@@ -97,3 +112,7 @@ Examples (as C-style strings):\n \"000bfoobar\\n\" \"foobar\\n\"\n \"0004\" \"\"\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-v2.txt b/Documentation/gitformat-protocol-v2.txt\nsimilarity index 98%\nrename from Documentation/technical/protocol-v2.txt\nrename to Documentation/gitformat-protocol-v2.txt\nindex 8a877d27e23..ae4fcc84e37 100644\n--- a/Documentation/technical/protocol-v2.txt\n+++ b/Documentation/gitformat-protocol-v2.txt\n@@ -1,5 +1,17 @@\n-Git Wire Protocol, Version 2\n-============================\n+gitformat-protocol-v2(5)\n+========================\n+\n+NAME\n+----\n+gitformat-protocol-v2 - Git Wire Protocol, Version 2\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n This document presents a specification for a version 2 of Git's wire\n protocol. Protocol v2 will improve upon v1 in the following ways:\n@@ -26,7 +38,7 @@ Packet-Line Framing\n -------------------\n \n All communication is done using packet-line framing, just as in v1. See\n-`Documentation/technical/pack-protocol.txt` and\n+linkgit:gitformat-pack-protocol[5] and\n `Documentation/technical/protocol-common.txt` for more information.\n \n In protocol v2 these special packets will have the following semantics:\n@@ -42,7 +54,7 @@ Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`. More information can be\n-found in `pack-protocol.txt` and `http-protocol.txt`, as well as the\n+found in linkgit:gitformat-pack-protocol[5] and `http-protocol.txt`, as well as the\n `GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n@@ -566,3 +578,7 @@ and associated requested information, each separated by a single space.\n \tattr = \"size\"\n \n \tobj-info = obj-id SP obj-size\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt\nindex d79ad323e67..945c21bbc38 100644\n--- a/Documentation/technical/api-simple-ipc.txt\n+++ b/Documentation/technical/api-simple-ipc.txt\n@@ -78,7 +78,7 @@ client and an optional response message from the server. Both the\n client and server messages are unlimited in length and are terminated\n with a flush packet.\n \n-The pkt-line routines (Documentation/technical/protocol-common.txt)\n+The pkt-line routines (linkgit:gitformat-protocol-common[5])\n are used to simplify buffer management during message generation,\n transmission, and reception. A flush packet is used to mark the end\n of the message. This allows the sender to incrementally generate and\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt\nindex cc5126cfeda..9d9c7acd512 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/technical/http-protocol.txt\n@@ -222,7 +222,7 @@ smart server reply:\n S: 0000\n \n The client may send Extra Parameters (see\n-Documentation/technical/pack-protocol.txt) as a colon-separated string\n+linkgit:gitformat-pack-protocol[5]) as a colon-separated string\n in the Git-Protocol HTTP header.\n \n Uses the `--http-backend-info-refs` option to\n@@ -518,5 +518,5 @@ References\n \n http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n-link:technical/pack-protocol.html\n-link:technical/protocol-capabilities.html\n+linkgit:gitformat-pack-protocol[5]\n+linkgit:gitformat-protocol-capabilities[5]\ndiff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt\nindex aa0aa9af1c2..c6922ce6ccc 100644\n--- a/Documentation/technical/long-running-process-protocol.txt\n+++ b/Documentation/technical/long-running-process-protocol.txt\n@@ -3,7 +3,7 @@ Long-running process protocol\n \n This protocol is used when Git needs to communicate with an external\n process throughout the entire life of a single Git command. All\n-communication is in pkt-line format (see technical/protocol-common.txt)\n+communication is in pkt-line format (see linkgit:gitformat-protocol-common[5])\n over standard input and standard output.\n \n Handshake\ndiff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt\nindex 99f0eb30406..9d5199d5c6c 100644\n--- a/Documentation/technical/partial-clone.txt\n+++ b/Documentation/technical/partial-clone.txt\n@@ -79,7 +79,7 @@ Design Details\n upload-pack negotiation.\n +\n This uses the existing capability discovery mechanism.\n-See \"filter\" in Documentation/technical/pack-protocol.txt.\n+See \"filter\" in linkgit:gitformat-pack-protocol[5].\n \n - Clients pass a \"filter-spec\" to clone and fetch which is passed to the\n server to request filtering during packfile construction.\ndiff --git a/command-list.txt b/command-list.txt\nindex 66e6a0ba217..bec0fa690aa 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -210,6 +210,10 @@ giteveryday guide\n gitfaq guide\n gitformat-bundle gitformats\n gitformat-commit-graph gitformats\n+gitformat-pack-protocol gitformats\n+gitformat-protocol-capabilities gitformats\n+gitformat-protocol-common gitformats\n+gitformat-protocol-v2 gitformats\n gitglossary guide\n githooks userformats\n gitignore userformats\ndiff --git a/t/t5551-http-fetch-smart.sh b/t/t5551-http-fetch-smart.sh\nindex b9351a732f6..d17f77dda6f 100755\n--- a/t/t5551-http-fetch-smart.sh\n+++ b/t/t5551-http-fetch-smart.sh\n@@ -175,8 +175,8 @@ test_expect_success 'no-op half-auth fetch does not require a password' '\n \t# This is not possible with protocol v2, since both objects and refs\n \t# are obtained from the \"git-upload-pack\" path. A solution to this is\n \t# to teach the server and client to be able to inline ls-refs requests\n-\t# as an Extra Parameter (see pack-protocol.txt), so that \"info/refs\"\n-\t# can serve refs, just like it does in protocol v0.\n+\t# as an Extra Parameter (see \"git help gitformat-pack-protocol\"), so that\n+\t# \"info/refs\" can serve refs, just like it does in protocol v0.\n \tGIT_TEST_PROTOCOL_VERSION=0 git --git-dir=half-auth fetch &&\n \texpect_askpass none\n '\n-- \n2.37.1.1032.gb00b5447790\n\n"},{"id":"459266","messageId":"patch-v4-7.8-499ee582644-20220718T132911Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v4-0.8-00000000000-20220718T132911Z-avarab@gmail.com","subject":"[PATCH v4 7/8] docs: move http-protocol docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-18T13:29:33Z","receivedAt":"2022-07-18T13:30:00Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe http-protocol.txt documentation over. I'm renaming it to\n\"protocol-http\" to be consistent with other things in the new\ngitformat-protocol-* namespace.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 2 +-\n Documentation/git-upload-pack.txt | 6 ++--\n Documentation/gitformat-pack-protocol.txt | 2 +-\n ...otocol.txt => gitformat-protocol-http.txt} | 29 ++++++++++++++++---\n Documentation/gitformat-protocol-v2.txt | 4 +--\n command-list.txt | 1 +\n 6 files changed, 33 insertions(+), 11 deletions(-)\n rename Documentation/{technical/http-protocol.txt => gitformat-protocol-http.txt} (98%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex b4d2361dfc7..44757823e96 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -33,6 +33,7 @@ MAN5_TXT += gitformat-pack-protocol.txt\n MAN5_TXT += gitformat-pack.txt\n MAN5_TXT += gitformat-protocol-capabilities.txt\n MAN5_TXT += gitformat-protocol-common.txt\n+MAN5_TXT += gitformat-protocol-http.txt\n MAN5_TXT += gitformat-protocol-v2.txt\n MAN5_TXT += gitformat-signature.txt\n MAN5_TXT += githooks.txt\n@@ -107,7 +108,6 @@ TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n TECH_DOCS += technical/hash-function-transition\n-TECH_DOCS += technical/http-protocol\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-heuristics\ndiff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt\nindex 754619222f6..720697df3a0 100644\n--- a/Documentation/git-upload-pack.txt\n+++ b/Documentation/git-upload-pack.txt\n@@ -39,9 +39,9 @@ OPTIONS\n --http-backend-info-refs::\n \tUsed by linkgit:git-http-backend[1] to serve up\n \t`$GIT_URL/info/refs?service=git-upload-pack` requests. See\n-\t\"Smart Clients\" in link:technical/http-protocol.html[the HTTP\n-\ttransfer protocols] documentation and \"HTTP Transport\" in the\n-\tlinkgit:gitformat-protocol-v2[5] documentation. Also understood by\n+\t\"Smart Clients\" in linkgit:gitformat-protocol-http[5] and\n+\t\"HTTP Transport\" in link:technical/protocol-v2.html[the Git\n+\tWire Protocol, Version 2] documentation. Also understood by\n \tlinkgit:git-receive-pack[1].\n \n ::\ndiff --git a/Documentation/gitformat-pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt\nindex f1bfd6705d9..c82b926e661 100644\n--- a/Documentation/gitformat-pack-protocol.txt\n+++ b/Documentation/gitformat-pack-protocol.txt\n@@ -17,7 +17,7 @@ Git supports transferring data in packfiles over the ssh://, git://, http:// and\n file:// transports. There exist two sets of protocols, one for pushing\n data from a client to a server and another for fetching data from a\n server to a client. The three transports (ssh, git, file) use the same\n-protocol to transfer data. http is documented in http-protocol.txt.\n+protocol to transfer data. http is documented in linkgit:gitformat-protocol-http[5].\n \n The processes invoked in the canonical Git implementation are 'upload-pack'\n on the server side and 'fetch-pack' on the client side for fetching data;\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/gitformat-protocol-http.txt\nsimilarity index 98%\nrename from Documentation/technical/http-protocol.txt\nrename to Documentation/gitformat-protocol-http.txt\nindex 9d9c7acd512..b85fc86abf6 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/gitformat-protocol-http.txt\n@@ -1,5 +1,19 @@\n-HTTP transfer protocols\n-=======================\n+gitformat-protocol-http(5)\n+==========================\n+\n+NAME\n+----\n+gitformat-protocol-http - Git HTTP-based protocols\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+\n+DESCRIPTION\n+-----------\n \n Git supports two HTTP based transfer protocols. A \"dumb\" protocol\n which requires only a standard HTTP server on the server end of the\n@@ -512,11 +526,18 @@ the id obtained through ref discovery as old_id.\n \n TODO: Document this further.\n \n-\n-References\n+REFERENCES\n ----------\n \n http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n+\n+SEE ALSO\n+--------\n+\n linkgit:gitformat-pack-protocol[5]\n linkgit:gitformat-protocol-capabilities[5]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-protocol-v2.txt b/Documentation/gitformat-protocol-v2.txt\nindex ae4fcc84e37..e29bc4b6a68 100644\n--- a/Documentation/gitformat-protocol-v2.txt\n+++ b/Documentation/gitformat-protocol-v2.txt\n@@ -54,7 +54,7 @@ Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`. More information can be\n-found in linkgit:gitformat-pack-protocol[5] and `http-protocol.txt`, as well as the\n+found in linkgit:gitformat-pack-protocol[5] and linkgit:gitformat-protocol-http[5], as well as the\n `GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n@@ -78,7 +78,7 @@ HTTP Transport\n ~~~~~~~~~~~~~~\n \n When using the http:// or https:// transport a client makes a \"smart\"\n-info/refs request as described in `http-protocol.txt` and requests that\n+info/refs request as described in linkgit:gitformat-protocol-http[5] and requests that\n v2 be used by supplying \"version=2\" in the `Git-Protocol` header.\n \n C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0\ndiff --git a/command-list.txt b/command-list.txt\nindex c364557fe09..c87b07e779c 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -217,6 +217,7 @@ gitformat-pack-cruft gitformats\n gitformat-pack-protocol gitformats\n gitformat-protocol-capabilities gitformats\n gitformat-protocol-common gitformats\n+gitformat-protocol-http gitformats\n gitformat-protocol-v2 gitformats\n gitformat-signature gitformats\n gitglossary guide\n-- \n2.37.1.1032.gb00b5447790\n\n"},{"id":"459267","messageId":"patch-v4-8.8-f186950e673-20220718T132911Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v4-0.8-00000000000-20220718T132911Z-avarab@gmail.com","subject":"[PATCH v4 8/8] docs: move multi-pack-index docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-18T13:29:34Z","receivedAt":"2022-07-18T13:30:17Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe multi-pack-index documentation over.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 2 +-\n Documentation/git-multi-pack-index.txt | 5 +++--\n ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++++++++++++--\n Documentation/gitformat-pack.txt | 5 +++++\n command-list.txt | 1 +\n 5 files changed, 28 insertions(+), 5 deletions(-)\n rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 44757823e96..984d86a96d3 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -28,6 +28,7 @@ MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += gitformat-chunk.txt\n MAN5_TXT += gitformat-commit-graph.txt\n MAN5_TXT += gitformat-index.txt\n+MAN5_TXT += gitformat-multi-pack-index.txt\n MAN5_TXT += gitformat-pack-cruft.txt\n MAN5_TXT += gitformat-pack-protocol.txt\n MAN5_TXT += gitformat-pack.txt\n@@ -109,7 +110,6 @@ TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/long-running-process-protocol\n-TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-heuristics\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\ndiff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt\nindex a48c3d5ea63..a147e047c91 100644\n--- a/Documentation/git-multi-pack-index.txt\n+++ b/Documentation/git-multi-pack-index.txt\n@@ -127,8 +127,9 @@ $ git multi-pack-index verify\n \n SEE ALSO\n --------\n-See link:technical/multi-pack-index.html[The Multi-Pack-Index Design\n-Document] and linkgit:gitformat-pack[5] for more information on the\n+\n+See linkgit:git-multi-pack-index[1] and\n+linkgit:gitformat-multi-pack-index[5] for more information on the\n multi-pack-index feature and its file format.\n \n \ndiff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/gitformat-multi-pack-index.txt\nsimilarity index 94%\nrename from Documentation/technical/multi-pack-index.txt\nrename to Documentation/gitformat-multi-pack-index.txt\nindex f2221d2b441..3bca1e7b10d 100644\n--- a/Documentation/technical/multi-pack-index.txt\n+++ b/Documentation/gitformat-multi-pack-index.txt\n@@ -1,5 +1,17 @@\n-Multi-Pack-Index (MIDX) Design Notes\n-====================================\n+gitformat-multi-pack-index(5)\n+=============================\n+\n+NAME\n+----\n+gitformat-multi-pack-index - The multi-pack-index file format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/multi-pack-index\n+\n+DESCRIPTION\n+-----------\n \n The Git object directory contains a 'pack' directory containing\n packfiles (with suffix \".pack\") and pack-indexes (with suffix\n@@ -98,3 +110,7 @@ Related Links\n \n [2] https://lore.kernel.org/git/alpine.DEB.2.20.1803091557510.23109@alexmv-linux/\n Git Merge 2018 Contributor's summit notes (includes discussion of MIDX)\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt\nindex 5b21d0f2521..06b469c6944 100644\n--- a/Documentation/gitformat-pack.txt\n+++ b/Documentation/gitformat-pack.txt\n@@ -507,6 +507,11 @@ packs arranged in MIDX order (with the preferred pack coming first).\n The MIDX's reverse index is stored in the optional 'RIDX' chunk within\n the MIDX itself.\n \n+SEE ALSO\n+--------\n+\n+linkgit:gitformat-multi-pack-index[5]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/command-list.txt b/command-list.txt\nindex c87b07e779c..a802f5b3369 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -212,6 +212,7 @@ gitformat-bundle gitformats\n gitformat-chunk gitformats\n gitformat-commit-graph gitformats\n gitformat-index gitformats\n+gitformat-multi-pack-index gitformats\n gitformat-pack gitformats\n gitformat-pack-cruft gitformats\n gitformat-pack-protocol gitformats\n-- \n2.37.1.1032.gb00b5447790\n\n"},{"id":"459268","messageId":"patch-v4-6.8-858ce9c6999-20220718T132911Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v4-0.8-00000000000-20220718T132911Z-avarab@gmail.com","subject":"[PATCH v4 6/8] docs: move pack format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-18T13:29:32Z","receivedAt":"2022-07-18T13:30:20Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe various documentation pertaining to the *.pack format and related\nfiles, and updating things that refer to it to link to the new\nlocation.\n\nBy moving these we can properly link from the newly created\ngitformat-commit-graph do to a gitformat-chunk-format manpage we build\nby default.\n\nCreating a \"gitformat-pack-bitmap\" from\n\"Documentation/technical/bitmap-format\" might logically be part of\nthis change, but it's left out for now due to a conflict with the\nin-flight ac/bitmap-lookup-table series.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 9 ++---\n Documentation/config/pack.txt | 2 +-\n Documentation/git-bundle.txt | 3 +-\n Documentation/git-multi-pack-index.txt | 4 +--\n .../chunk-format.txt => gitformat-chunk.txt} | 27 ++++++++++++---\n Documentation/gitformat-commit-graph.txt | 2 +-\n .../index-format.txt => gitformat-index.txt} | 22 ++++++++++--\n ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++++--\n Documentation/gitformat-pack-protocol.txt | 2 +-\n .../pack-format.txt => gitformat-pack.txt} | 34 +++++++++++++++++--\n ...ure-format.txt => gitformat-signature.txt} | 21 ++++++++++--\n .../howto/recover-corrupted-object-harder.txt | 2 +-\n .../technical/hash-function-transition.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n cache.h | 3 +-\n command-list.txt | 5 +++\n pack-revindex.h | 2 +-\n 17 files changed, 132 insertions(+), 32 deletions(-)\n rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (90%)\n rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)\n rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%)\n rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)\n rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex adc1404d380..b4d2361dfc7 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -25,11 +25,16 @@ MAN1_TXT += gitweb.txt\n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n+MAN5_TXT += gitformat-chunk.txt\n MAN5_TXT += gitformat-commit-graph.txt\n+MAN5_TXT += gitformat-index.txt\n+MAN5_TXT += gitformat-pack-cruft.txt\n MAN5_TXT += gitformat-pack-protocol.txt\n+MAN5_TXT += gitformat-pack.txt\n MAN5_TXT += gitformat-protocol-capabilities.txt\n MAN5_TXT += gitformat-protocol-common.txt\n MAN5_TXT += gitformat-protocol-v2.txt\n+MAN5_TXT += gitformat-signature.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -101,13 +106,10 @@ TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n-TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n-TECH_DOCS += technical/index-format\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n-TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\n@@ -115,7 +117,6 @@ TECH_DOCS += technical/racy-git\n TECH_DOCS += technical/reftable\n TECH_DOCS += technical/send-pack-pipeline\n TECH_DOCS += technical/shallow\n-TECH_DOCS += technical/signature-format\n TECH_DOCS += technical/trivial-merge\n SP_ARTICLES += $(TECH_DOCS)\n SP_ARTICLES += technical/api-index\ndiff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt\nindex ad7f73a1ead..3e581eab84a 100644\n--- a/Documentation/config/pack.txt\n+++ b/Documentation/config/pack.txt\n@@ -166,7 +166,7 @@ permuted into their appropriate location when writing a new bitmap.\n \n pack.writeReverseIndex::\n \tWhen true, git will write a corresponding .rev file (see:\n-\tlink:../technical/pack-format.html[Documentation/technical/pack-format.txt])\n+\tlinkgit:gitformat-pack[5])\n \tfor each new packfile that it writes in all places except for\n \tlinkgit:git-fast-import[1] and in the bulk checkin mechanism.\n \tDefaults to false.\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 1aeae09f082..4c6c41e1a09 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -57,8 +57,7 @@ size. That they're \"thin\" under the hood is merely noted here as a\n curiosity, and as a reference to other documentation.\n \n See linkgit:gitformat-bundle[5] for more details and the discussion of\n-\"thin pack\" in link:technical/pack-format.html[the pack format\n-documentation] for further details.\n+\"thin pack\" in linkgit:gitformat-pack[5] for further details.\n \n OPTIONS\n -------\ndiff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt\nindex c588fb91af1..a48c3d5ea63 100644\n--- a/Documentation/git-multi-pack-index.txt\n+++ b/Documentation/git-multi-pack-index.txt\n@@ -128,8 +128,8 @@ $ git multi-pack-index verify\n SEE ALSO\n --------\n See link:technical/multi-pack-index.html[The Multi-Pack-Index Design\n-Document] and link:technical/pack-format.html[The Multi-Pack-Index\n-Format] for more information on the multi-pack-index feature.\n+Document] and linkgit:gitformat-pack[5] for more information on the\n+multi-pack-index feature and its file format.\n \n \n GIT\ndiff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt\nsimilarity index 90%\nrename from Documentation/technical/chunk-format.txt\nrename to Documentation/gitformat-chunk.txt\nindex f36ce42f37c..784c5d987de 100644\n--- a/Documentation/technical/chunk-format.txt\n+++ b/Documentation/gitformat-chunk.txt\n@@ -1,12 +1,25 @@\n-Chunk-based file formats\n-========================\n+gitformat-chunk(5)\n+==================\n+\n+NAME\n+----\n+gitformat-chunk - Chunk-based file formats\n+\n+SYNOPSIS\n+--------\n+\n+Used by linkgit:gitformat-commit-graph[5] and the \"MIDX\" format (see\n+the pack format documentation in linkgit:gitformat-pack[5]).\n+\n+DESCRIPTION\n+-----------\n \n Some file formats in Git use a common concept of \"chunks\" to describe\n sections of the file. This allows structured access to a large file by\n scanning a small \"table of contents\" for the remaining data. This common\n format is used by the `commit-graph` and `multi-pack-index` files. See\n-link:technical/pack-format.html[the `multi-pack-index` format] and\n-the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n+the `multi-pack-index` format in linkgit:gitformat-pack[5] and\n+link:technical/commit-graph-format.html[the `commit-graph` format] for\n how they use the chunks to describe structured data.\n \n A chunk-based file format begins with some header information custom to\n@@ -113,4 +126,8 @@ for future formats:\n * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n in `midx.c` for how the chunk-format API is used to write and\n parse the multi-pack-index file format documented in\n- link:technical/pack-format.html[the multi-pack-index file format].\n+ the multi-pack-index file format section of linkgit:gitformat-pack[5].\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt\nindex 108dc2295c0..7324665716d 100644\n--- a/Documentation/gitformat-commit-graph.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -75,7 +75,7 @@ All multi-byte numbers are in network byte order.\n ID appears at most once.\n \n The CHUNK LOOKUP matches the table of contents from\n- link:technical/chunk-format.html[the chunk-based file format].\n+ the chunk-based file format, see linkgit:gitformat-chunk[5]\n \n The remaining data in the body is described one chunk at a time, and\n these chunks may be given in any order. Chunks are required unless\ndiff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt\nsimilarity index 98%\nrename from Documentation/technical/index-format.txt\nrename to Documentation/gitformat-index.txt\nindex 65da0daaa56..5f3ed10d2db 100644\n--- a/Documentation/technical/index-format.txt\n+++ b/Documentation/gitformat-index.txt\n@@ -1,5 +1,19 @@\n+gitformat-index(5)\n+==================\n+\n+NAME\n+----\n+gitformat-index - Git index format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/index\n+\n+DESCRIPTION\n+-----------\n+\n Git index format\n-================\n \n == The Git index file has the following format\n \n@@ -127,7 +141,7 @@ Git index format\n entry is encoded as if the path name for the previous entry is an\n empty string). At the beginning of an entry, an integer N in the\n variable width encoding (the same encoding as the offset is encoded\n- for OFS_DELTA pack entries; see pack-format.txt) is stored, followed\n+ for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed\n by a NUL-terminated string S. Removing N bytes from the end of the\n path name for the previous entry, and replacing it with the string S\n yields the path name for this entry.\n@@ -404,3 +418,7 @@ The remaining data of each directory block is grouped by type:\n with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,\n tools should avoid interacting with a sparse index unless they understand\n this extension.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/cruft-packs.txt b/Documentation/gitformat-pack-cruft.txt\nsimilarity index 96%\nrename from Documentation/technical/cruft-packs.txt\nrename to Documentation/gitformat-pack-cruft.txt\nindex d81f3a8982f..908f752bd84 100644\n--- a/Documentation/technical/cruft-packs.txt\n+++ b/Documentation/gitformat-pack-cruft.txt\n@@ -1,4 +1,17 @@\n-= Cruft packs\n+gitformat-pack-cruft(5)\n+=======================\n+\n+NAME\n+----\n+gitformat-pack-cruft - The cruft pack file format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/pack-*.mtimes\n+\n+DESCRIPTION\n+-----------\n \n The cruft packs feature offer an alternative to Git's traditional mechanism of\n removing unreachable objects. This document provides an overview of Git's\n@@ -10,10 +23,11 @@ same.\n To remove unreachable objects from your repository, Git offers `git repack -Ad`\n (see linkgit:git-repack[1]). Quoting from the documentation:\n \n-[quote]\n+----\n [...] unreachable objects in a previous pack become loose, unpacked objects,\n instead of being left in the old pack. [...] loose unreachable objects will be\n pruned according to normal expiry rules with the next 'git gc' invocation.\n+----\n \n Unreachable objects aren't removed immediately, since doing so could race with\n an incoming push which may reference an object which is about to be deleted.\n@@ -121,3 +135,7 @@ which aren't already stored in an earlier cruft pack) is significantly more\n complicated to construct, and so aren't pursued here. The obvious drawback to\n the current implementation is that the entire cruft pack must be re-written from\n scratch.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt\nindex b665af5b690..f1bfd6705d9 100644\n--- a/Documentation/gitformat-pack-protocol.txt\n+++ b/Documentation/gitformat-pack-protocol.txt\n@@ -467,7 +467,7 @@ Now that the client and server have finished negotiation about what\n the minimal amount of data that needs to be sent to the client is, the server\n will construct and send the required data in packfile format.\n \n-See pack-format.txt for what the packfile itself actually looks like.\n+See linkgit:gitformat-pack[5] for what the packfile itself actually looks like.\n \n If 'side-band' or 'side-band-64k' capabilities have been specified by\n the client, the server will send the packfile data multiplexed.\ndiff --git a/Documentation/technical/pack-format.txt b/Documentation/gitformat-pack.txt\nsimilarity index 95%\nrename from Documentation/technical/pack-format.txt\nrename to Documentation/gitformat-pack.txt\nindex b520aa9c45b..5b21d0f2521 100644\n--- a/Documentation/technical/pack-format.txt\n+++ b/Documentation/gitformat-pack.txt\n@@ -1,5 +1,29 @@\n-Git pack format\n-===============\n+gitformat-pack(5)\n+=================\n+\n+NAME\n+----\n+gitformat-pack - Git pack format\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/pack-*.{pack,idx}\n+$GIT_DIR/objects/pack/pack-*.rev\n+$GIT_DIR/objects/pack/multi-pack-index\n+\n+DESCRIPTION\n+-----------\n+\n+The Git pack format is now Git stores most of its primary repository\n+data. Over the lietime af a repository loose objects (if any) and\n+smaller packs are consolidated into larger pack(s). See\n+linkgit:git-gc[1] and linkgit:git-pack-objects[1].\n+\n+The pack format is also used over-the-wire, see\n+e.g. linkgit:gitformat-protocol-v2[5], as well as being a part of\n+other container formats in the case of linkgit:gitformat-bundle[5].\n \n == Checksums and object IDs\n \n@@ -356,7 +380,7 @@ CHUNK LOOKUP:\n \t using the next chunk position if necessary.)\n \n \tThe CHUNK LOOKUP matches the table of contents from\n-\tlink:technical/chunk-format.html[the chunk-based file format].\n+\tthe chunk-based file format, see linkgit:gitformat-chunk[5].\n \n \tThe remaining data in the body is described one chunk at a time, and\n \tthese chunks may be given in any order. Chunks are required unless\n@@ -482,3 +506,7 @@ packs arranged in MIDX order (with the preferred pack coming first).\n \n The MIDX's reverse index is stored in the optional 'RIDX' chunk within\n the MIDX itself.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt\nsimilarity index 96%\nrename from Documentation/technical/signature-format.txt\nrename to Documentation/gitformat-signature.txt\nindex 166721be6f6..a249869fafa 100644\n--- a/Documentation/technical/signature-format.txt\n+++ b/Documentation/gitformat-signature.txt\n@@ -1,7 +1,18 @@\n-Git signature format\n-====================\n+gitformat-signature(5)\n+======================\n \n-== Overview\n+NAME\n+----\n+gitformat-signature - Git cryptographic signature formats\n+\n+SYNOPSIS\n+--------\n+[verse]\n+<[tag|commit] object header(s)>\n+\n+\n+DESCRIPTION\n+-----------\n \n Git uses cryptographic signatures in various places, currently objects (tags,\n commits, mergetags) and transactions (pushes). In every case, the command which\n@@ -200,3 +211,7 @@ Date: Wed Jun 15 09:13:29 2016 +0000\n # gpg: There is no indication that the signature belongs to the owner.\n # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.txt\nindex 8994e2559ea..5efb4fe81ff 100644\n--- a/Documentation/howto/recover-corrupted-object-harder.txt\n+++ b/Documentation/howto/recover-corrupted-object-harder.txt\n@@ -68,7 +68,7 @@ Note that the \"object\" file isn't fit for feeding straight to zlib; it\n has the git packed object header, which is variable-length. We want to\n strip that off so we can start playing with the zlib data directly. You\n can either work your way through it manually (the format is described in\n-link:../technical/pack-format.html[Documentation/technical/pack-format.txt]),\n+linkgit:gitformat-pack[5]),\n or you can walk through it in a debugger. I did the latter, creating a\n valid pack like:\n \ndiff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt\nindex 260224b0331..e2ac36dd210 100644\n--- a/Documentation/technical/hash-function-transition.txt\n+++ b/Documentation/technical/hash-function-transition.txt\n@@ -205,7 +205,7 @@ SHA-1 content.\n Object storage\n ~~~~~~~~~~~~~~\n Loose objects use zlib compression and packed objects use the packed\n-format described in Documentation/technical/pack-format.txt, just like\n+format described in linkgit:gitformat-pack[5], just like\n today. The content that is compressed and stored uses SHA-256 content\n instead of SHA-1 content.\n \ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 865074bed4e..ca9decdd952 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -3133,7 +3133,7 @@ those \"loose\" objects.\n You can save space and make Git faster by moving these loose objects in\n to a \"pack file\", which stores a group of objects in an efficient\n compressed format; the details of how pack files are formatted can be\n-found in link:technical/pack-format.html[pack format].\n+found in link:gitformat-pack[5].\n \n To put the loose objects into a pack, just run git repack:\n \ndiff --git a/cache.h b/cache.h\nindex ac5ab4ef9d3..82755c7c0aa 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -475,8 +475,7 @@ extern struct index_state the_index;\n \n /*\n * Values in this enum (except those outside the 3 bit range) are part\n- * of pack file format. See Documentation/technical/pack-format.txt\n- * for more information.\n+ * of pack file format. See gitformat-pack(5) for more information.\n */\n enum object_type {\n \tOBJ_BAD = -1,\ndiff --git a/command-list.txt b/command-list.txt\nindex bec0fa690aa..c364557fe09 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -209,11 +209,16 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle gitformats\n+gitformat-chunk gitformats\n gitformat-commit-graph gitformats\n+gitformat-index gitformats\n+gitformat-pack gitformats\n+gitformat-pack-cruft gitformats\n gitformat-pack-protocol gitformats\n gitformat-protocol-capabilities gitformats\n gitformat-protocol-common gitformats\n gitformat-protocol-v2 gitformats\n+gitformat-signature gitformats\n gitglossary guide\n githooks userformats\n gitignore userformats\ndiff --git a/pack-revindex.h b/pack-revindex.h\nindex 74f4eae668d..4974e75eb4d 100644\n--- a/pack-revindex.h\n+++ b/pack-revindex.h\n@@ -22,7 +22,7 @@\n *\n * - pack position refers to an object's position within a non-existent pack\n * described by the MIDX. The pack structure is described in\n- * Documentation/technical/pack-format.txt.\n+ * gitformat-pack(5).\n *\n * It is effectively a concatanation of all packs in the MIDX (ordered by\n * their numeric ID within the MIDX) in their original order within each\n-- \n2.37.1.1032.gb00b5447790\n\n"},{"id":"459297","messageId":"xmqqy1wqqs3j.fsf@gitster.g","threadId":"56715","inReplyTo":"cover-v4-0.8-00000000000-20220718T132911Z-avarab@gmail.com","subject":"Re: [PATCH v4 0/8] git doc + \"git help\": move \"format\" docs from technical/*","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-18T16:54:24Z","receivedAt":"2022-07-18T16:54:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> This series improves the discoverability of the technical/*\n> documentation covering those \"formats\" where we interact with users\n> (e.g. \"gitattributes\") by moving them to its own \"git help\" category.\n>\n> It then moves various technical documentation from technical/* to our\n> main documentation namespace, allowing us to cross-link e.g. from\n> \"git-bundle(1)\" to a new \"gitformat-bundle(5)\".\n\nThis may be a good direction to go in in the longer term, but there\nare already topics in flight that change these documents. Luckily\nnone in 'next' yet, but there are two that have been in 'seen' and\nneed to coordinate with this change.\n\n\n"},{"id":"459300","messageId":"xmqqr12iqrp0.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-v4-1.8-4428f0a6fb1-20220718T132911Z-avarab@gmail.com","subject":"Re: [PATCH v4 1/8] help.c: BUG() out if \"help --guides\" can't remove \"git\" prefixes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-18T17:03:07Z","receivedAt":"2022-07-18T17:03:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Adjust code added in 929d9192828 (git docs: split \"User-facing file\n> formats\" off from \"Guides\", 2021-06-04) to be more strict about the\n> prefix trimming of the \"guides\" category.\n>\n> There are no guides in the command-list.txt that don't start with\n> \"git\", and we're unlikely to ever add any, if we do we can remove this\n> BUG() invocation, but in the meantime this makes the intent more\n> clear.\n\nThe observation is good.\n\n> \tif (skip_prefix(name, \"git-\", &new_name))\n> \t\treturn new_name;\n> -\tif (category == CAT_guide && skip_prefix(name, \"git\", &new_name))\n> +\tswitch (category)\n> +\t{\n> +\tcase CAT_guide:\n> +\t\tif (!skip_prefix(name, \"git\", &new_name))\n> +\t\t\tBUG(\"category #%d but no 'git' prefix?\", category);\n> \t\treturn new_name;\n> +\t}\n> \treturn name;\n> -\n> }\n\nIf we were to use \"switch\", can we have the opening brace on the\nsame line, like all other switch statements?\n\nI suspect that we should avoid losing information, perhaps the most\nstraight-forward implementation would be without \"switch\", like so\n\n\tif (category == CAT_guide) {\n\t\tif (skip_prefix(name, \"git\", &new_name))\n\t\t\treturn new_name;\n\t\tBUG(\"CAT_guide category but no 'git' prefix? '%s'\", name);\n\t}\n\treturn name;\n\neven if we plan to add more categories that would remove the prefix\nand we insist the prefix to be there?\n\n> static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask)\n"},{"id":"459302","messageId":"xmqqlesqqr1v.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-v4-2.8-883c483d4e7-20220718T132911Z-avarab@gmail.com","subject":"Re: [PATCH v4 2/8] git docs: split \"User-facing file formats\" off from \"Guides\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-18T17:17:00Z","receivedAt":"2022-07-18T17:17:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> We take a wide view of what's considered a \"user format\", it's not\n> just a file format, but e.g. githooks(5) also belongs, since the\n> layout of the \".git/hooks/\" and the placement of hooks in it is\n> something the user might be expected to interact with.\n\nI am afraid it is a bit big a stretch. Other documents that fall\ninto the user-format category all have \"format\" the users must\nfollow while writing the \"contents\" in the file. \".gitignore\" has\ncertain format and syntax and the document describes what effect the\nfile has, based on the contents of the file that follows the syntax.\n\nA hook can be written in any language, even though our UNIX lineage\nmakes our samples all in written in the shell, so there is no\n\"format\" for the users to follow that we should force upon them.\n\nIf we can come up with a word that is more appropriate than\n\"format\", it would be great. If we do not place too much emphasis\non \"format\", I agree that both \"gitignore\" and \"githook\" fall into\nthe same category, because they define how the contents written in\nthese files affect the operation of Git commands.\n\n> -With no options and no '' or '' given, the synopsis of the 'git'\n> +With no options and no '', '' or '' given, the synopsis of the 'git'\n\nAt some point, we will have enough that it would probably\nbecome meaningless to treat as a separate class, no?\nGuides, user-supplied customization files, and implementation\ndetails of on-disk files that may help reimplementations of Git, all\nwill become .\n\n> @@ -26,8 +27,8 @@ printed on the standard output.\n> If the option `--guides` or `-g` is given, a list of the\n> Git concept guides is also printed on the standard output.\n> \n> -If a command, or a guide, is given, a manual page for that command or\n> -guide is brought up. The 'man' program is used by default for this\n> +If a command or other documentation is given, the relevant manual page\n> +will be brought up. The 'man' program is used by default for this\n\nGood.\n"},{"id":"459308","messageId":"220718.86r12iw9jg.gmgdl@evledraar.gmail.com","threadId":"56715","inReplyTo":"xmqqy1wqqs3j.fsf@gitster.g","subject":"Re: [PATCH v4 0/8] git doc + \"git help\": move \"format\" docs from technical/*","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-18T17:58:00Z","receivedAt":"2022-07-18T18:38:51Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Mon, Jul 18 2022, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason writes:\n>\n>> This series improves the discoverability of the technical/*\n>> documentation covering those \"formats\" where we interact with users\n>> (e.g. \"gitattributes\") by moving them to its own \"git help\" category.\n>>\n>> It then moves various technical documentation from technical/* to our\n>> main documentation namespace, allowing us to cross-link e.g. from\n>> \"git-bundle(1)\" to a new \"gitformat-bundle(5)\".\n>\n> This may be a good direction to go in in the longer term, but there\n> are already topics in flight that change these documents. Luckily\n> none in 'next' yet, but there are two that have been in 'seen' and\n> need to coordinate with this change.\n\nThe v4 merges cleanly for me, unless there's a semantic conflict you've\nspotted that I've missed.\n\nBut I assume you mean a \"seen\" you haven't pushed out yet, which\nincludes SZEDER's change here:\nhttps://lore.kernel.org/git/220718.86cze2y22q.gmgdl@evledraar.gmail.com/\n\nI sent out the v3 with a merge resolution for the only conflict at the\ntime:\nhttps://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/\n\nBut as noted in the v4 CL I thought I'd make even that trivial conflict\ngo away in v4, but it looks like I'll need to roll a v5.\n\nI don't want to make it a hassle for you to carry this topic, and I have\nwaited a few months to submit this, as there were always various\nDocumentation/technical/ changes in-flight.\n\nWould you prefer to have this entirely conflict free, or to have me\nsolve the (small) conflicts locally and note the resolution (per\n--remerge-diff) in the CLs?\n"},{"id":"459309","messageId":"220718.86mtd6w90v.gmgdl@evledraar.gmail.com","threadId":"56715","inReplyTo":"xmqqlesqqr1v.fsf@gitster.g","subject":"Re: [PATCH v4 2/8] git docs: split \"User-facing file formats\" off from \"Guides\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-18T18:41:39Z","receivedAt":"2022-07-18T18:49:59Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Mon, Jul 18 2022, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason writes:\n>\n>> We take a wide view of what's considered a \"user format\", it's not\n>> just a file format, but e.g. githooks(5) also belongs, since the\n>> layout of the \".git/hooks/\" and the placement of hooks in it is\n>> something the user might be expected to interact with.\n>\n> I am afraid it is a bit big a stretch. Other documents that fall\n> into the user-format category all have \"format\" the users must\n> follow while writing the \"contents\" in the file. \".gitignore\" has\n> certain format and syntax and the document describes what effect the\n> file has, based on the contents of the file that follows the syntax.\n>\n> A hook can be written in any language, even though our UNIX lineage\n> makes our samples all in written in the shell, so there is no\n> \"format\" for the users to follow that we should force upon them.\n\nThe \"format\" I have in mind is the \"shape\" of the configuration,\ni.e. that a hook goes in .git/hooks/, not the contents of that\n itself.\n\nSo it's introducing a bit of a neologism, but I couldn't think of a\nbetter one. Suggestions welcome. There is \"gitrepository-layout(5)\", but\ncalling this a \"layout\" seems odd.\n\nI do think that things that users are expected to interact with on a\nfile-level (gitignore, gitmailmap etc.) and on the FS arrange in such a\nway as to interact with git (gitignore) belong together under one hat.\n\nSo it's not perfect, but I think it sucks less than calling both\n\"gitmodules\" and \"giteverday\" a \"guide\", which is the status quo.\n\n> If we can come up with a word that is more appropriate than\n> \"format\", it would be great. If we do not place too much emphasis\n> on \"format\", I agree that both \"gitignore\" and \"githook\" fall into\n> the same category, because they define how the contents written in\n> these files affect the operation of Git commands.\n\n*nod*, another word would be most welcome :)\n\nI do think that if we have --user-formats or --user-X it makes sense to\nhave to have that match the --git-X. I.e. the \"format\" of say the\ncommit-graph includes how we arrange those files on disk, just as is the\ncase with the hoks.\n\n>> -With no options and no '' or '' given, the synopsis of the 'git'\n>> +With no options and no '', '' or '' given, the synopsis of the 'git'\n>\n> At some point, we will have enough that it would probably\n> become meaningless to treat as a separate class, no?\n> Guides, user-supplied customization files, and implementation\n> details of on-disk files that may help reimplementations of Git, all\n> will become .\n\nMaybe I should just use here?\n"},{"id":"459485","messageId":"xmqqcze0664f.fsf@gitster.g","threadId":"56715","inReplyTo":"220718.86mtd6w90v.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH v4 2/8] git docs: split \"User-facing file formats\" off from \"Guides\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-19T23:21:36Z","receivedAt":"2022-07-19T23:21:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n>> If we can come up with a word that is more appropriate than\n>> \"format\", it would be great. If we do not place too much emphasis\n>> on \"format\", I agree that both \"gitignore\" and \"githook\" fall into\n>> the same category, because they define how the contents written in\n>> these files affect the operation of Git commands.\n>\n> *nod*, another word would be most welcome :)\n\nTrue. What I am absolutely sure about is that the word is not\n\"format\" X-<. It is the interface end-users interact with internals\nof Git, with need similar to how \"plugin\" interfaces need to have\ndocumentation for their users.\n\n> I do think that if we have --user-formats or --user-X it makes sense to\n> have to have that match the --git-X. I.e. the \"format\" of say the\n> commit-graph includes how we arrange those files on disk, just as is the\n> case with the hoks.\n>\n>>> -With no options and no '' or '' given, the synopsis of the 'git'\n>>> +With no options and no '', '' or '' given, the synopsis of the 'git'\n>>\n>> At some point, we will have enough that it would probably\n>> become meaningless to treat as a separate class, no?\n>> Guides, user-supplied customization files, and implementation\n>> details of on-disk files that may help reimplementations of Git, all\n>> will become .\n>\n> Maybe I should just use here?\n\nI think is very good, much better than , here.\n"},{"id":"459583","messageId":"220721.864jzbueg5.gmgdl@evledraar.gmail.com","threadId":"56715","inReplyTo":"xmqqcze0664f.fsf@gitster.g","subject":"Re: [PATCH v4 2/8] git docs: split \"User-facing file formats\" off from \"Guides\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-21T07:02:00Z","receivedAt":"2022-07-21T07:12:33Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Tue, Jul 19 2022, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason writes:\n>\n>>> If we can come up with a word that is more appropriate than\n>>> \"format\", it would be great. If we do not place too much emphasis\n>>> on \"format\", I agree that both \"gitignore\" and \"githook\" fall into\n>>> the same category, because they define how the contents written in\n>>> these files affect the operation of Git commands.\n>>\n>> *nod*, another word would be most welcome :)\n>\n> True. What I am absolutely sure about is that the word is not\n> \"format\" X-<. It is the interface end-users interact with internals\n> of Git, with need similar to how \"plugin\" interfaces need to have\n> documentation for their users.\n\nMy goal here is just to make this part of our documentation more\naccessible, so I don't care about the term. But this series also seems\nblocked on you not liking the term, so...\n\nA few ways I can think of to go forward:\n\n1. Use \"format\", but explain that we're using it loosely. Perhaps with\n this on top?\n\t\n\tdiff --git a/Documentation/git.txt b/Documentation/git.txt\n\tindex 1980a0e29cd..9f8d7a3543e 100644\n\t--- a/Documentation/git.txt\n\t+++ b/Documentation/git.txt\n\t@@ -343,7 +343,10 @@ User-facing file formats\n\t ------------------------\n\t \n\t This documentation discusses file formats that users are expected to\n\t-edit. These can also be listed with 'git help --user-formats'.\n\t+edit. \"Format\" here refers more broadly to files and/or file contents\n\t+that the user is expected to edit or know about.\n\t+\n\t+These can also be listed with 'git help --user-formats'.\n\t \n\t include::cmds-userformats.txt[]\n\n2. I could submit this without the \"git help --user-formats\" change for\n now, and just focus on --git-formats:\n\t\n\tInternal file formats and protocols:\n\t format-bundle The bundle file format\n\t format-chunk Chunk-based file formats\n\t format-commit-graph Git commit graph format\n\t format-index Git index format\n\t format-multi-pack-index The multi-pack-index file format\n\t format-pack Git pack format\n\t format-pack-cruft The cruft pack file format\n\t format-pack-protocol How packs are transferred over-the-wire\n\t format-protocol-capabilities Protocol v0 and v1 capabilities\n\t format-protocol-common Things common to various protocols\n\t format-protocol-http Git HTTP-based protocols\n\t format-protocol-v2 Git Wire Protocol, Version 2\n\t format-signature Git cryptographic signature formats\n\n Do you have an objection to any of those being labeled \"format\"? I\n understood your comments above to not include those, i.e. that you\n took objection to githooks(5) in particular being in that new\n --user-formats category.\n\n3. A re-roll of this series pretty much as-is (sans other fixes), but\n remove \"githooks\" from this re-categorization.\n\n4. Come up with s/format//g, but I have no idea what that\n \"something\" would be. \"Protocol?\", After all a secret handshake is\n also a protocol....\n"},{"id":"459584","messageId":"220721.86zgh3szu4.gmgdl@evledraar.gmail.com","threadId":"56715","inReplyTo":"220718.86r12iw9jg.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH v4 0/8] git doc + \"git help\": move \"format\" docs from technical/*","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-21T07:12:33Z","receivedAt":"2022-07-21T07:13:29Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Mon, Jul 18 2022, Ævar Arnfjörð Bjarmason wrote:\n\n> On Mon, Jul 18 2022, Junio C Hamano wrote:\n>\n>> Ævar Arnfjörð Bjarmason writes:\n>>\n>>> This series improves the discoverability of the technical/*\n>>> documentation covering those \"formats\" where we interact with users\n>>> (e.g. \"gitattributes\") by moving them to its own \"git help\" category.\n>>>\n>>> It then moves various technical documentation from technical/* to our\n>>> main documentation namespace, allowing us to cross-link e.g. from\n>>> \"git-bundle(1)\" to a new \"gitformat-bundle(5)\".\n>>\n>> This may be a good direction to go in in the longer term, but there\n>> are already topics in flight that change these documents. Luckily\n>> none in 'next' yet, but there are two that have been in 'seen' and\n>> need to coordinate with this change.\n>\n> The v4 merges cleanly for me, unless there's a semantic conflict you've\n> spotted that I've missed.\n>\n> But I assume you mean a \"seen\" you haven't pushed out yet, which\n> includes SZEDER's change here:\n> https://lore.kernel.org/git/220718.86cze2y22q.gmgdl@evledraar.gmail.com/\n>\n> I sent out the v3 with a merge resolution for the only conflict at the\n> time:\n> https://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/\n>\n> But as noted in the v4 CL I thought I'd make even that trivial conflict\n> go away in v4, but it looks like I'll need to roll a v5.\n>\n> I don't want to make it a hassle for you to carry this topic, and I have\n> waited a few months to submit this, as there were always various\n> Documentation/technical/ changes in-flight.\n>\n> Would you prefer to have this entirely conflict free, or to have me\n> solve the (small) conflicts locally and note the resolution (per\n> --remerge-diff) in the CLs?\n\nFWIW this merges cleanly with \"seen\" due to the magic of \"git merge\",\ni.e. even with the rename we resolve the conflict with SZEDER's work\nsmoothly.\n\nBut there's other reasons to re-roll, just say'n for when you eventually\n(hopefully) pick up such a re-roll ...\n"},{"id":"459643","messageId":"patch-v5-1.9-b0bb29bb131-20220721T160721Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com","subject":"[PATCH v5 1/9] help.c: BUG() out if \"help --guides\" can't remove \"git\" prefixes","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-21T16:13:50Z","receivedAt":"2022-07-21T16:15:15Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Adjust code added in 929d9192828 (git docs: split \"User-facing file\nformats\" off from \"Guides\", 2021-06-04) to be more strict about the\nprefix trimming of the \"guides\" category.\n\nThere are no guides in the command-list.txt that don't start with\n\"git\", and we're unlikely to ever add any, if we do we can remove this\nBUG() invocation, but in the meantime this makes the intent more\nclear.\n\nWhile we're at it remove a stray newline that had been added after the\n\"return name;\" statement.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n help.c | 10 ++++++++--\n 1 file changed, 8 insertions(+), 2 deletions(-)\n\ndiff --git a/help.c b/help.c\nindex 41c41c2aa11..80d516abb0b 100644\n--- a/help.c\n+++ b/help.c\n@@ -44,13 +44,19 @@ static struct category_description main_categories[] = {\n static const char *drop_prefix(const char *name, uint32_t category)\n {\n \tconst char *new_name;\n+\tconst char *prefix;\n \n \tif (skip_prefix(name, \"git-\", &new_name))\n \t\treturn new_name;\n-\tif (category == CAT_guide && skip_prefix(name, \"git\", &new_name))\n+\tswitch (category) {\n+\tcase CAT_guide:\n+\t\tprefix = \"git\";\n+\t\tif (!skip_prefix(name, prefix, &new_name))\n+\t\t\tBUG(\"'%s' in category #%d should have '%s' prefix\",\n+\t\t\t name, category, prefix);\n \t\treturn new_name;\n+\t}\n \treturn name;\n-\n }\n \n static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask)\n-- \n2.37.1.1095.g64a1e8362fd\n\n"},{"id":"459644","messageId":"cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v4-0.8-00000000000-20220718T132911Z-avarab@gmail.com","subject":"[PATCH v5 0/9] docs: create & use \"(user|developer) interfaces\" categories","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-21T16:13:49Z","receivedAt":"2022-07-21T16:15:17Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"See v3[1] for lofty goals. The changes since v4 are mainly to rename\nthe \"user formats\" and \"developer formats\" to \"user interfaces\" and\n\"developer interfaces\".\n\nNow:\n\n\t$ ./git help --user-interfaces\n\tUser-facing repository, command and file interfaces:\n\t attributes Defining attributes per path\n\t cli Git command-line interface and conventions\n\t hooks Hooks used by Git\n\t ignore Specifies intentionally untracked files to ignore\n\t mailmap Map author/committer names and/or E-Mail addresses\n\t modules Defining submodule properties\n\t repository-layout Git Repository Layout\n\t revisions Specifying revisions and ranges for Git\n\nThe addition of \"gitcli\" and \"gitrevisions\" is new. I.e. per git-help(1):\n\n\tIn-repository file interfaces such as `.git/info/exclude` are\n\tdocumented here (see linkgit:gitrepository-layout[5]), as well as\n\tin-tree configuration such as `.mailmap` (see linkgit:gitmailmap[5]).\n\n\tThis section of the documentation also covers general or widespread\n\tuser-interface conventions (e.g. linkgit:gitcli[7]), and\n\tpseudo-configuration such as the file-based `.git/hooks/*` interface\n\tdescribed in linkgit:githooks[5].\n\nAnd for \"--developer-interfaces\" (I wondered about calling this --apis):\n\n\t$ ./git help --developer-interfaces\n\tFile formats, protocols and other developer interfaces:\n\t format-bundle The bundle file format\n\t format-chunk Chunk-based file formats\n\t format-commit-graph Git commit graph format\n\t format-index Git index format\n\t format-multi-pack-index The multi-pack-index file format\n\t format-pack Git pack format\n\t format-pack-cruft The cruft pack file format\n\t format-signature Git cryptographic signature formats\n\t protocol-capabilities Protocol v0 and v1 capabilities\n\t protocol-common Things common to various protocols\n\t protocol-http Git HTTP-based protocols\n\t protocol-pack How packs are transferred over-the-wire\n\t protocol-v2 Git Wire Protocol, Version 2\n\nI.e.:\n\n * The name of the new \"user\" category refers generally to \"user\n interfaces\", and as the description notes we'll cover user-editable\n files, UX conventions etc. there.\n\n * Not all the \"--developer-interfaces\" start with \"gitformat\"\n anymore, now it's \"gitformat\" for e.g. the bundle format, but\n \"gitprotocol\" for things that have to do with the protocol.\n\n This also solves an ugly wart: Before we had\n \"gitformat-pack-protocol\" (protocol) and \"gitformat-pack\" (*.pack\n files).\n\nOther changes:\n\n * Changed the \" or \" to just say \", and it's now a\n split-off 2/9.\n\n * Fixed some links to the new docs, and added missing ones.\n\n * There was no \"--developer-interfaces\" section in the git-help(1)\n docs (or \"--git-formats\") before).\n\n1. https://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/\n\nÆvar Arnfjörð Bjarmason (9):\n help.c: BUG() out if \"help --guides\" can't remove \"git\" prefixes\n git help doc: use \"\" instead of \"\"\n git docs: add a category for user-facing file, repo and command UX\n git docs: add a category for file formats, protocols and interfaces\n docs: move commit-graph format docs to man section 5\n docs: move protocol-related docs to man section 5\n docs: move pack format docs to man section 5\n docs: move http-protocol docs to man section 5\n docs: move multi-pack-index docs to man section 5\n\n Documentation/Makefile | 26 +++++-----\n Documentation/config/lsrefs.txt | 2 +-\n Documentation/config/pack.txt | 2 +-\n Documentation/config/protocol.txt | 2 +-\n Documentation/git-bundle.txt | 13 +++--\n Documentation/git-commit-graph.txt | 5 ++\n Documentation/git-help.txt | 27 ++++++++--\n Documentation/git-multi-pack-index.txt | 6 +--\n Documentation/git-upload-pack.txt | 7 ++-\n Documentation/git.txt | 17 +++++++\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++---\n .../chunk-format.txt => gitformat-chunk.txt} | 29 ++++++++---\n ...-format.txt => gitformat-commit-graph.txt} | 49 +++++++++++++------\n .../index-format.txt => gitformat-index.txt} | 22 ++++++++-\n ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++-\n ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++-\n .../pack-format.txt => gitformat-pack.txt} | 39 +++++++++++++--\n ...ure-format.txt => gitformat-signature.txt} | 21 ++++++--\n ...ities.txt => gitprotocol-capabilities.txt} | 28 ++++++++---\n ...ocol-common.txt => gitprotocol-common.txt} | 23 ++++++++-\n ...http-protocol.txt => gitprotocol-http.txt} | 35 ++++++++++---\n ...pack-protocol.txt => gitprotocol-pack.txt} | 28 ++++++++---\n .../protocol-v2.txt => gitprotocol-v2.txt} | 27 +++++++---\n .../howto/recover-corrupted-object-harder.txt | 2 +-\n Documentation/lint-man-section-order.perl | 3 ++\n Documentation/technical/api-simple-ipc.txt | 2 +-\n .../technical/hash-function-transition.txt | 2 +-\n .../long-running-process-protocol.txt | 2 +-\n Documentation/technical/packfile-uri.txt | 2 +-\n Documentation/technical/partial-clone.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n Makefile | 1 +\n builtin/help.c | 20 +++++++-\n cache.h | 3 +-\n command-list.txt | 38 +++++++++++---\n help.c | 34 ++++++++++++-\n help.h | 2 +\n pack-revindex.h | 2 +-\n refspec.h | 2 +-\n t/t0012-help.sh | 14 +++++-\n t/t5551-http-fetch-smart.sh | 4 +-\n 41 files changed, 508 insertions(+), 123 deletions(-)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)\n rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (89%)\n rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (87%)\n rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)\n rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)\n rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%)\n rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)\n rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)\n rename Documentation/{technical/protocol-capabilities.txt => gitprotocol-capabilities.txt} (96%)\n rename Documentation/{technical/protocol-common.txt => gitprotocol-common.txt} (89%)\n rename Documentation/{technical/http-protocol.txt => gitprotocol-http.txt} (97%)\n rename Documentation/{technical/pack-protocol.txt => gitprotocol-pack.txt} (98%)\n rename Documentation/{technical/protocol-v2.txt => gitprotocol-v2.txt} (97%)\n\nRange-diff against v4:\n 1: 4428f0a6fb1 ! 1: b0bb29bb131 help.c: BUG() out if \"help --guides\" can't remove \"git\" prefixes\n @@ Commit message\n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## help.c ##\n -@@ help.c: static const char *drop_prefix(const char *name, uint32_t category)\n +@@ help.c: static struct category_description main_categories[] = {\n + static const char *drop_prefix(const char *name, uint32_t category)\n + {\n + \tconst char *new_name;\n ++\tconst char *prefix;\n \n \tif (skip_prefix(name, \"git-\", &new_name))\n \t\treturn new_name;\n -\tif (category == CAT_guide && skip_prefix(name, \"git\", &new_name))\n -+\tswitch (category)\n -+\t{\n ++\tswitch (category) {\n +\tcase CAT_guide:\n -+\t\tif (!skip_prefix(name, \"git\", &new_name))\n -+\t\t\tBUG(\"category #%d but no 'git' prefix?\", category);\n ++\t\tprefix = \"git\";\n ++\t\tif (!skip_prefix(name, prefix, &new_name))\n ++\t\t\tBUG(\"'%s' in category #%d should have '%s' prefix\",\n ++\t\t\t name, category, prefix);\n \t\treturn new_name;\n +\t}\n \treturn name;\n -: ----------- > 2: 2ec00f81552 git help doc: use \"\" instead of \"\"\n 2: 883c483d4e7 ! 3: 31be7d01c50 git docs: split \"User-facing file formats\" off from \"Guides\"\n @@ Metadata\n Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - git docs: split \"User-facing file formats\" off from \"Guides\"\n + git docs: add a category for user-facing file, repo and command UX\n \n - Create a new \"User-facing file formats\" section in the main \"git help\n - git\" manual page. The \"Guides\" section was added to the manual page in\n - f442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense\n - to list all that documentation.\n + Create a new \"Repository, command and file interfaces\" section in the\n + main \"git help git\" manual page. Move things that belong under this\n + new criteria from the generic \"Guides\" section.\n +\n + The \"Guides\" section was added in f442f28a81b (git.txt: add list of\n + guides, 2020-08-05). It makes sense to have e.g. \"giteveryday(7)\" and\n + \"gitfaq(7)\" listed under \"Guides\".\n \n But placing e.g. \"gitignore(5)\" in it is stretching the meaning of\n what a \"guide\" is, ideally that section should list things similar to\n \"giteveryday(7)\" and \"gitcore-tutorial(7)\".\n \n - We take a wide view of what's considered a \"user format\", it's not\n - just a file format, but e.g. githooks(5) also belongs, since the\n - layout of the \".git/hooks/\" and the placement of hooks in it is\n - something the user might be expected to interact with.\n + An alternate name that was considered for this new section was \"User\n + formats\", for consistency with the nomenclature used for man section 5\n + in general. My man(1) lists it as \"File formats and conventions,\n + e.g. /etc/passwd\".\n +\n + So calling this \"git help --formats\" or \"git help --user-formats\"\n + would make sense for e.g. gitignore(5), but would be stretching it\n + somewhat for githooks(5), and would seem really suspect for the likes\n + of gitcli(7).\n +\n + Let's instead pick a name that's closer to the generic term \"User\n + interface\", which is really what this documentation discusses: General\n + user-interface documentation that doesn't obviously belong elsewhere.\n \n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n @@ Documentation/Makefile: cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchingrepositories.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n -+\tcmds-userformats.txt \\\n ++\tcmds-userinterfaces.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\n \n \n ## Documentation/git-help.txt ##\n @@ Documentation/git-help.txt: SYNOPSIS\n - --------\n - [verse]\n - 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\n --'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n -+'git help' [[-i|--info] [-m|--man] [-w|--web]] [||]\n + 'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n -+'git help' [--user-formats]\n ++'git help' [--user-interfaces]\n \n DESCRIPTION\n -----------\n - \n --With no options and no '' or '' given, the synopsis of the 'git'\n -+With no options and no '', '' or '' given, the synopsis of the 'git'\n - command and a list of the most commonly used Git commands are printed\n - on the standard output.\n - \n -@@ Documentation/git-help.txt: printed on the standard output.\n - If the option `--guides` or `-g` is given, a list of the\n - Git concept guides is also printed on the standard output.\n - \n --If a command, or a guide, is given, a manual page for that command or\n --guide is brought up. The 'man' program is used by default for this\n -+If a command or other documentation is given, the relevant manual page\n -+will be brought up. The 'man' program is used by default for this\n - purpose, but this can be overridden by other options or configuration\n - variables.\n - \n @@ Documentation/git-help.txt: OPTIONS\n --guides::\n \tPrints a list of the Git concept guides on the standard output.\n \n -+--user-formats::\n -+\tPrints a list of the Git user-facing format documentation on\n -+\tthe standard output.\n ++--user-interfaces::\n ++\tPrints a list of the repository, command and file interfaces\n ++\tdocumentation on the standard output.\n +++\n ++In-repository file interfaces such as `.git/info/exclude` are\n ++documented here (see linkgit:gitrepository-layout[5]), as well as\n ++in-tree configuration such as `.mailmap` (see linkgit:gitmailmap[5]).\n +++\n ++This section of the documentation also covers general or widespread\n ++user-interface conventions (e.g. linkgit:gitcli[7]), and\n ++pseudo-configuration such as the file-based `.git/hooks/*` interface\n ++described in linkgit:githooks[5].\n +\n -i::\n --info::\n @@ Documentation/git.txt: The following documentation pages are guides about Git co\n \n include::cmds-guide.txt[]\n \n -+User-facing file formats\n -+------------------------\n ++Repository, command and file interfaces\n ++---------------------------------------\n +\n -+This documentation discusses file formats that users are expected to\n -+edit. These can also be listed with 'git help --user-formats'.\n ++This documentation discusses repository and command interfaces which\n ++users are expected to interact with directly. See `--user-formats` in\n ++linkgit:git-help[1] for more details on the critera.\n +\n -+include::cmds-userformats.txt[]\n ++include::cmds-userinterfaces.txt[]\n \n Configuration Mechanism\n -----------------------\n @@ Makefile: check-docs::\n \t\tsed -e '1,/^### command list/d' \\\n \t\t -e '/^#/d' \\\n \t\t -e '/guide$$/d' \\\n -+\t\t -e '/formats$$/d' \\\n ++\t\t -e '/interfaces$$/d' \\\n \t\t -e 's/[ \t].*//' \\\n \t\t -e 's/^/listed /' command-list.txt; \\\n \t\t$(MAKE) -C Documentation print-man1 | \\\n @@ builtin/help.c: static enum help_action {\n \tHELP_ACTION_ALL = 1,\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n -+\tHELP_ACTION_USER_FORMATS,\n ++\tHELP_ACTION_USER_INTERFACES,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n @@ builtin/help.c: static struct option builtin_help_options[] = {\n \n \tOPT_CMDMODE('g', \"guides\", &cmd_mode, N_(\"print list of useful guides\"),\n \t\t HELP_ACTION_GUIDES),\n -+\tOPT_CMDMODE(0, \"user-formats\", &cmd_mode, N_(\"print list of user-facing file formats\"),\n -+\t\t HELP_ACTION_USER_FORMATS),\n ++\tOPT_CMDMODE(0, \"user-interfaces\", &cmd_mode,\n ++\t\t N_(\"print list of user-facing repository, command and file interfaces\"),\n ++\t\t HELP_ACTION_USER_INTERFACES),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n -@@ builtin/help.c: static struct option builtin_help_options[] = {\n - \n - static const char * const builtin_help_usage[] = {\n - \t\"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n --\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] []\"),\n -+\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [|]\"),\n +@@ builtin/help.c: static const char * const builtin_help_usage[] = {\n + \tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [|]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n -+\t\"git help [--user-formats]\",\n ++\t\"git help [--user-interfaces]\",\n \tNULL\n };\n \n @@ builtin/help.c: int cmd_help(int argc, const char **argv, const char *prefix)\n \t\topt_mode_usage(argc, \"--config-for-completion\", help_format);\n \t\tlist_config_help(SHOW_CONFIG_VARS);\n \t\treturn 0;\n -+\tcase HELP_ACTION_USER_FORMATS:\n -+\t\topt_mode_usage(argc, \"--user-formats\", help_format);\n -+\t\tlist_user_formats_help();\n ++\tcase HELP_ACTION_USER_INTERFACES:\n ++\t\topt_mode_usage(argc, \"--user-interfaces\", help_format);\n ++\t\tlist_user_interfaces_help();\n +\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n @@ command-list.txt\n # specified here, which can only have \"guide\" attribute and nothing\n # else.\n #\n -+# User-facing file formats such as documentation for the .gitmodules,\n -+# .mailmap etc. files lives in man section 5. These entries can only\n -+# have the \"userformats\" attribute and nothing else.\n ++# User-facing repository, command and file interfaces such as\n ++# documentation for the .gitmodules, .mailmap etc. files lives in man\n ++# sections 5 and 7. These entries can only have the \"userinterfaces\"\n ++# attribute and nothing else.\n +#\n ### command list (do not change this line)\n # command name category [category] [category]\n @@ command-list.txt: git-verify-tag ancillaryinterrogators\n git-worktree mainporcelain\n git-write-tree plumbingmanipulators\n -gitattributes guide\n -+gitattributes userformats\n - gitcli guide\n +-gitcli guide\n ++gitattributes userinterfaces\n ++gitcli userinterfaces\n gitcore-tutorial guide\n gitcredentials guide\n + gitcvs-migration guide\n @@ command-list.txt: gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitglossary guide\n -githooks guide\n -gitignore guide\n -+githooks userformats\n -+gitignore userformats\n ++githooks userinterfaces\n ++gitignore userinterfaces\n gitk mainporcelain\n -gitmailmap guide\n -gitmodules guide\n -+gitmailmap userformats\n -+gitmodules userformats\n ++gitmailmap userinterfaces\n ++gitmodules userinterfaces\n gitnamespaces guide\n gitremote-helpers guide\n -gitrepository-layout guide\n -+gitrepository-layout userformats\n - gitrevisions guide\n +-gitrevisions guide\n ++gitrepository-layout userinterfaces\n ++gitrevisions userinterfaces\n gitsubmodules guide\n gittutorial guide\n + gittutorial-2 guide\n \n ## help.c ##\n @@ help.c: static struct category_description main_categories[] = {\n \t{ CAT_plumbinginterrogators, N_(\"Low-level Commands / Interrogators\") },\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n -+\t{ CAT_userformats, N_(\"Git user-facing file formats\") },\n ++\t{ CAT_userinterfaces, N_(\"User-facing repository, command and file interfaces\") },\n \t{ 0, NULL }\n };\n \n @@ help.c: static const char *drop_prefix(const char *name, uint32_t category)\n - \tswitch (category)\n - \t{\n - \tcase CAT_guide:\n -+\tcase CAT_userformats:\n - \t\tif (!skip_prefix(name, \"git\", &new_name))\n - \t\t\tBUG(\"category #%d but no 'git' prefix?\", category);\n \t\treturn new_name;\n + \tswitch (category) {\n + \tcase CAT_guide:\n ++\tcase CAT_userinterfaces:\n + \t\tprefix = \"git\";\n + \t\tif (!skip_prefix(name, prefix, &new_name))\n + \t\t\tBUG(\"'%s' in category #%d should have '%s' prefix\",\n @@ help.c: void list_guides_help(void)\n \tputchar('\\n');\n }\n \n -+void list_user_formats_help(void)\n ++void list_user_interfaces_help(void)\n +{\n +\tstruct category_description catdesc[] = {\n -+\t\t{ CAT_userformats, N_(\"Git user-facing file formats:\") },\n ++\t\t{ CAT_userinterfaces, N_(\"User-facing repository, command and file interfaces:\") },\n +\t\t{ 0, NULL }\n +\t};\n +\tprint_cmd_by_category(catdesc, NULL);\n @@ help.h: static inline void mput_char(char c, unsigned int num)\n void list_common_cmds_help(void);\n void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n -+void list_user_formats_help(void);\n ++void list_user_interfaces_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\n @@ t/t0012-help.sh: test_expect_success 'invalid usage' '\n \ttest_expect_code 129 git help -g add &&\n \ttest_expect_code 129 git help -a -g &&\n \n -+\ttest_expect_code 129 git help --user-formats add &&\n ++\ttest_expect_code 129 git help --user-interfaces add &&\n +\n \ttest_expect_code 129 git help -g -c &&\n \ttest_expect_code 129 git help --config-for-completion add &&\n @@ t/t0012-help.sh: test_expect_success 'git help succeeds without git.html' '\n \ttest_cmp expect test-browser.log\n '\n \n -+test_expect_success 'git help --user-formats' '\n -+\tgit help --user-formats >help.output &&\n ++test_expect_success 'git help --user-interfaces' '\n ++\tgit help --user-interfaces >help.output &&\n +\tgrep \"^ attributes \" help.output &&\n +\tgrep \"^ mailmap \" help.output\n +'\n @@ t/t0012-help.sh: test_expect_success \"'git help -a' section spacing\" '\n \n \tLow-level Commands / Internal Helpers\n +\n -+\tGit user-facing file formats\n ++\tUser-facing repository, command and file interfaces\n \tEOF\n \ttest_cmp expect actual\n '\n 3: d196bcd1db0 ! 4: a7310898866 git docs: create a \"Git file formats and protocols\" section\n @@ Metadata\n Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - git docs: create a \"Git file formats and protocols\" section\n + git docs: add a category for file formats, protocols and interfaces\n \n - Create a new \"Git file formats and protocols\" section in the main \"git help\n - git\" manual page and start moving the documentation that now lives in\n - \"Documentation/technical/*.git\" over to it. This compliments the newly\n - added and adjacent \"User-facing file formats\" section.\n + Create a new \"File formats, protocols and other developer interfaces\"\n + section in the main \"git help git\" manual page and start moving the\n + documentation that now lives in \"Documentation/technical/*.git\" over\n + to it. This compliments the newly added and adjacent \"Repository,\n + command and file interfaces\" section.\n \n This makes the technical documentation more accessible and\n discoverable. Before this we wouldn't install it by default, and had\n @@ Documentation/Makefile: TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n @@ Documentation/Makefile: cmds_txt = cmds-ancillaryinterrogators.txt \\\n + \tcmds-synchingrepositories.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n - \tcmds-userformats.txt \\\n -+\tcmds-gitformats.txt \\\n ++\tcmds-developerinterfaces.txt \\\n + \tcmds-userinterfaces.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\n - \n \n ## Documentation/git-bundle.txt ##\n @@ Documentation/git-bundle.txt: using \"thin packs\", bundles created using exclusions are smaller in\n @@ Documentation/git-bundle.txt: using \"thin packs\", bundles created using exclusio\n \n OPTIONS\n -------\n +@@ Documentation/git-bundle.txt: verify ::\n + \tcommits exist and are fully linked in the current repository.\n + \tThen, 'git bundle' prints a list of missing commits, if any.\n + \tFinally, information about additional capabilities, such as \"object\n +-\tfilter\", is printed. See \"Capabilities\" in link:technical/bundle-format.html\n ++\tfilter\", is printed. See \"Capabilities\" in linkgit:gitformat-bundle[5]\n + \tfor more information. The exit code is zero for success, but will\n + \tbe nonzero if the bundle file is invalid.\n + \n @@ Documentation/git-bundle.txt: You can also see what references it offers:\n $ git ls-remote mybundle\n ----------------\n @@ Documentation/git-help.txt\n @@ Documentation/git-help.txt: SYNOPSIS\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n - 'git help' [--user-formats]\n -+'git help' [--git-formats]\n + 'git help' [--user-interfaces]\n ++'git help' [--developer-interfaces]\n \n DESCRIPTION\n -----------\n +@@ Documentation/git-help.txt: user-interface conventions (e.g. linkgit:gitcli[7]), and\n + pseudo-configuration such as the file-based `.git/hooks/*` interface\n + described in linkgit:githooks[5].\n + \n ++--developer-interfaces::\n ++\tPrint list of file formats, protocols and other developer\n ++\tinterfaces documentation on the standard output.\n ++\n + -i::\n + --info::\n + \tDisplay manual page for the command in the 'info' format. The\n \n ## Documentation/git.txt ##\n -@@ Documentation/git.txt: edit. These can also be listed with 'git help --user-formats'.\n +@@ Documentation/git.txt: linkgit:git-help[1] for more details on the critera.\n \n - include::cmds-userformats.txt[]\n + include::cmds-userinterfaces.txt[]\n \n -+Git file formats and protocols\n -+------------------------------\n ++File formats, protocols and other developer interfaces\n ++------------------------------------------------------\n +\n -+This documentation discusses the file formats and protocols that git\n -+itself uses. These can also be listed with 'git help --git-formats'.\n ++This documentation discusses file formats, over-the-wire protocols and\n ++other git developer interfaces. See `--developer-interfaces` in\n ++linkgit:git-help[1].\n +\n -+include::cmds-gitformats.txt[]\n ++include::cmds-developerinterfaces.txt[]\n +\n Configuration Mechanism\n -----------------------\n @@ builtin/help.c\n @@ builtin/help.c: static enum help_action {\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n - \tHELP_ACTION_USER_FORMATS,\n -+\tHELP_ACTION_GIT_FORMATS,\n + \tHELP_ACTION_USER_INTERFACES,\n ++\tHELP_ACTION_DEVELOPER_INTERFACES,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n @@ builtin/help.c: static struct option builtin_help_options[] = {\n - \t\t HELP_ACTION_GUIDES),\n - \tOPT_CMDMODE(0, \"user-formats\", &cmd_mode, N_(\"print list of user-facing file formats\"),\n - \t\t HELP_ACTION_USER_FORMATS),\n -+\tOPT_CMDMODE(0, \"git-formats\", &cmd_mode, N_(\"print list of internal file formats and network protocols\"),\n -+\t\t HELP_ACTION_GIT_FORMATS),\n + \tOPT_CMDMODE(0, \"user-interfaces\", &cmd_mode,\n + \t\t N_(\"print list of user-facing repository, command and file interfaces\"),\n + \t\t HELP_ACTION_USER_INTERFACES),\n ++\tOPT_CMDMODE(0, \"developer-interfaces\", &cmd_mode,\n ++\t\t N_(\"print list of file formats, protocols and other developer interfaces\"),\n ++\t\t HELP_ACTION_DEVELOPER_INTERFACES),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n @@ builtin/help.c: static const char * const builtin_help_usage[] = {\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n - \t\"git help [--user-formats]\",\n -+\t\"git help [--git-formats]\",\n + \t\"git help [--user-interfaces]\",\n ++\t\"git help [--developer-interfaces]\",\n \tNULL\n };\n \n @@ builtin/help.c: int cmd_help(int argc, const char **argv, const char *prefix)\n - \t\topt_mode_usage(argc, \"--user-formats\", help_format);\n - \t\tlist_user_formats_help();\n + \t\topt_mode_usage(argc, \"--user-interfaces\", help_format);\n + \t\tlist_user_interfaces_help();\n \t\treturn 0;\n -+\tcase HELP_ACTION_GIT_FORMATS:\n -+\t\topt_mode_usage(argc, \"--git-formats\", help_format);\n -+\t\tlist_git_formats_help();\n ++\tcase HELP_ACTION_DEVELOPER_INTERFACES:\n ++\t\topt_mode_usage(argc, \"--developer-interfaces\", help_format);\n ++\t\tlist_developer_interfaces_help();\n +\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n @@ builtin/help.c: int cmd_help(int argc, const char **argv, const char *prefix)\n \n ## command-list.txt ##\n @@\n - # .mailmap etc. files lives in man section 5. These entries can only\n - # have the \"userformats\" attribute and nothing else.\n + # sections 5 and 7. These entries can only have the \"userinterfaces\"\n + # attribute and nothing else.\n #\n -+# Git internal file formats and protocols, such as documentation for the\n ++# Git's file formats and protocols, such as documentation for the\n +# *.bundle format lives in man section 5. These entries can only have\n -+# the \"gitformats\" attribute and nothing else.\n ++# the \"developerinterfaces\" attribute and nothing else.\n +#\n ### command list (do not change this line)\n # command name category [category] [category]\n @@ command-list.txt: gitcvs-migration guide\n gitdiffcore guide\n giteveryday guide\n gitfaq guide\n -+gitformat-bundle gitformats\n ++gitformat-bundle developerinterfaces\n gitglossary guide\n - githooks userformats\n - gitignore userformats\n + githooks userinterfaces\n + gitignore userinterfaces\n \n ## help.c ##\n @@ help.c: static struct category_description main_categories[] = {\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n - \t{ CAT_userformats, N_(\"Git user-facing file formats\") },\n -+\t{ CAT_gitformats, N_(\"Git internal file formats and protocols\") },\n + \t{ CAT_userinterfaces, N_(\"User-facing repository, command and file interfaces\") },\n ++\t{ CAT_developerinterfaces, N_(\"Developer-facing file file formats, protocols and interfaces\") },\n \t{ 0, NULL }\n };\n \n @@ help.c: static const char *drop_prefix(const char *name, uint32_t category)\n - \t{\n + \tswitch (category) {\n \tcase CAT_guide:\n - \tcase CAT_userformats:\n -+\tcase CAT_gitformats:\n - \t\tif (!skip_prefix(name, \"git\", &new_name))\n - \t\t\tBUG(\"category #%d but no 'git' prefix?\", category);\n - \t\treturn new_name;\n -@@ help.c: void list_user_formats_help(void)\n + \tcase CAT_userinterfaces:\n ++\tcase CAT_developerinterfaces:\n + \t\tprefix = \"git\";\n + \t\tif (!skip_prefix(name, prefix, &new_name))\n + \t\t\tBUG(\"'%s' in category #%d should have '%s' prefix\",\n +@@ help.c: void list_user_interfaces_help(void)\n \tputchar('\\n');\n }\n \n -+void list_git_formats_help(void)\n ++void list_developer_interfaces_help(void)\n +{\n +\tstruct category_description catdesc[] = {\n -+\t\t{ CAT_gitformats, N_(\"Internal file formats and protocols:\") },\n ++\t\t{ CAT_developerinterfaces, N_(\"File formats, protocols and other developer interfaces:\") },\n +\t\t{ 0, NULL }\n +\t};\n +\tprint_cmd_by_category(catdesc, NULL);\n @@ help.h\n @@ help.h: void list_common_cmds_help(void);\n void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n - void list_user_formats_help(void);\n -+void list_git_formats_help(void);\n + void list_user_interfaces_help(void);\n ++void list_developer_interfaces_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\n @@ t/t0012-help.sh\n @@ t/t0012-help.sh: test_expect_success \"'git help -a' section spacing\" '\n \tLow-level Commands / Internal Helpers\n \n - \tGit user-facing file formats\n + \tUser-facing repository, command and file interfaces\n +\n -+\tGit internal file formats and protocols\n ++\tDeveloper-facing file file formats, protocols and interfaces\n \tEOF\n \ttest_cmp expect actual\n '\n 4: b59e001a4ca ! 5: 62f9020a72d docs: move commit-graph format docs to man section 5\n @@ Commit message\n file-format documentation into our main documentation space.\n \n By moving the documentation for the commit-graph format into man\n - section 5 and the new \"gitformats\" category. This change is split from\n - subsequent commits due to the relatively large amount of ASCIIDOC\n - formatting changes that are required.\n + section 5 and the new \"developerinterfaces\" category. This change is\n + split from subsequent commits due to the relatively large amount of\n + ASCIIDOC formatting changes that are required.\n \n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n @@ command-list.txt\n @@ command-list.txt: gitdiffcore guide\n giteveryday guide\n gitfaq guide\n - gitformat-bundle gitformats\n -+gitformat-commit-graph gitformats\n + gitformat-bundle developerinterfaces\n ++gitformat-bundle developerinterfaces\n ++gitformat-commit-graph developerinterfaces\n gitglossary guide\n - githooks userformats\n - gitignore userformats\n + githooks userinterfaces\n + gitignore userinterfaces\n 5: 968aa977b67 ! 6: 019ec8cf73c docs: move protocol-related docs to man section 5\n @@ Commit message\n e.g. lsrefs.unborn and protocol.version documentation to a manpage we\n build by default.\n \n + So far we have been using the \"gitformat-\" prefix for the\n + documentation we've been moving over from Documentation/technical/*,\n + but for protocol documentation let's use \"gitprotocol-*\".\n +\n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/Makefile ##\n -@@ Documentation/Makefile: MAN1_TXT += gitweb.txt\n - MAN5_TXT += gitattributes.txt\n - MAN5_TXT += gitformat-bundle.txt\n - MAN5_TXT += gitformat-commit-graph.txt\n -+MAN5_TXT += gitformat-pack-protocol.txt\n -+MAN5_TXT += gitformat-protocol-capabilities.txt\n -+MAN5_TXT += gitformat-protocol-common.txt\n -+MAN5_TXT += gitformat-protocol-v2.txt\n - MAN5_TXT += githooks.txt\n +@@ Documentation/Makefile: MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n + MAN5_TXT += gitmodules.txt\n ++MAN5_TXT += gitprotocol-capabilities.txt\n ++MAN5_TXT += gitprotocol-common.txt\n ++MAN5_TXT += gitprotocol-pack.txt\n ++MAN5_TXT += gitprotocol-v2.txt\n + MAN5_TXT += gitrepository-layout.txt\n + MAN5_TXT += gitweb.conf.txt\n + \n @@ Documentation/Makefile: TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-format\n @@ Documentation/config/lsrefs.txt\n \tMay be \"advertise\" (the default), \"allow\", or \"ignore\". If \"advertise\",\n \tthe server will respond to the client sending \"unborn\" (as described in\n -\tprotocol-v2.txt) and will advertise support for this feature during the\n -+\tlinkgit:gitformat-protocol-v2[5]) and will advertise support for this feature during the\n ++\tlinkgit:gitprotocol-v2[5]) and will advertise support for this feature during the\n \tprotocol v2 capability advertisement. \"allow\" is the same as\n \t\"advertise\" except that the server will not advertise support for this\n \tfeature; this is useful for load-balanced servers that cannot be\n @@ Documentation/config/protocol.txt: protocol.version::\n in the initial response from the server.\n \n -* `2` - link:technical/protocol-v2.html[wire protocol version 2].\n -+* `2` - Wire protocol version 2, see linkgit:gitformat-protocol-v2[5].\n ++* `2` - Wire protocol version 2, see linkgit:gitprotocol-v2[5].\n \n --\n \n @@ Documentation/git-upload-pack.txt: OPTIONS\n -\tlink:technical/protocol-v2.html[the Git Wire Protocol, Version\n -\t2] documentation. Also understood by\n +\ttransfer protocols] documentation and \"HTTP Transport\" in the\n -+\tlinkgit:gitformat-protocol-v2[5] documentation. Also understood by\n ++\tlinkgit:gitprotocol-v2[5] documentation. Also understood by\n \tlinkgit:git-receive-pack[1].\n \n ::\n @@ Documentation/gitformat-bundle.txt: FORMAT\n \n We will use ABNF notation to define the Git bundle format. See\n -link:technical/protocol-common.html for the details.\n -+linkgit:gitformat-protocol-common[5] for the details.\n ++linkgit:gitprotocol-common[5] for the details.\n \n A v2 bundle looks like this:\n \n \n - ## Documentation/technical/pack-protocol.txt => Documentation/gitformat-pack-protocol.txt ##\n -@@\n --Packfile transfer protocols\n --===========================\n -+gitformat-pack-protocol(5)\n -+==========================\n -+\n -+NAME\n -+----\n -+gitformat-pack-protocol - How packs are transferred over-the-wire\n -+\n -+SYNOPSIS\n -+--------\n -+[verse]\n -+\n -+\n -+DESCRIPTION\n -+-----------\n - \n - Git supports transferring data in packfiles over the ssh://, git://, http:// and\n - file:// transports. There exist two sets of protocols, one for pushing\n -@@ Documentation/gitformat-pack-protocol.txt: pkt-line Format\n - ---------------\n - \n - The descriptions below build on the pkt-line format described in\n --protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless\n -+linkgit:gitformat-protocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless\n - otherwise noted the usual pkt-line LF rules apply: the sender SHOULD\n - include a LF, but the receiver MUST NOT complain if it is not present.\n - \n -@@ Documentation/gitformat-pack-protocol.txt: An example client/server communication might look like this:\n - S: 0018ok refs/heads/debug\\n\n - S: 002ang refs/heads/master non-fast-forward\\n\n - ----\n -+\n -+GIT\n -+---\n -+Part of the linkgit:git[1] suite\n -\n - ## Documentation/technical/protocol-capabilities.txt => Documentation/gitformat-protocol-capabilities.txt ##\n + ## Documentation/technical/protocol-capabilities.txt => Documentation/gitprotocol-capabilities.txt ##\n @@\n -Git Protocol Capabilities\n -=========================\n -+gitformat-protocol-capabilities(5)\n -+==================================\n ++gitprotocol-capabilities(5)\n ++===========================\n +\n +NAME\n +----\n -+gitformat-protocol-capabilities - Protocol v0 and v1 capabilities\n ++gitprotocol-capabilities - Protocol v0 and v1 capabilities\n +\n +SYNOPSIS\n +--------\n @@ Documentation/technical/protocol-capabilities.txt => Documentation/gitformat-pro\n \n NOTE: this document describes capabilities for versions 0 and 1 of the pack\n -protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]\n -+protocol. For version 2, please refer to the linkgit:gitformat-protocol-v2[5]\n ++protocol. For version 2, please refer to the linkgit:gitprotocol-v2[5]\n doc.\n \n Servers SHOULD support all capabilities defined in this document.\n -@@ Documentation/gitformat-protocol-capabilities.txt: interleaved with S-R-Q.\n +@@ Documentation/gitprotocol-capabilities.txt: interleaved with S-R-Q.\n multi_ack_detailed\n ------------------\n This is an extension of multi_ack that permits client to better\n -understand the server's in-memory state. See pack-protocol.txt,\n -+understand the server's in-memory state. See linkgit:gitformat-pack-protocol[5],\n ++understand the server's in-memory state. See linkgit:gitprotocol-pack[5],\n section \"Packfile Negotiation\" for more information.\n \n no-done\n -@@ Documentation/gitformat-protocol-capabilities.txt: a packfile upload and reference update. If the pushing client requests\n +@@ Documentation/gitprotocol-capabilities.txt: a packfile upload and reference update. If the pushing client requests\n this capability, after unpacking and updating references the server\n will respond with whether the packfile unpacked successfully and if\n each reference was updated successfully. If any of those were not\n -successful, it will send back an error message. See pack-protocol.txt\n -+successful, it will send back an error message. See linkgit:gitformat-pack-protocol[5]\n ++successful, it will send back an error message. See linkgit:gitprotocol-pack[5]\n for example messages.\n \n report-status-v2\n -@@ Documentation/gitformat-protocol-capabilities.txt: adding new \"option\" directives in order to support reference rewritten by\n +@@ Documentation/gitprotocol-capabilities.txt: adding new \"option\" directives in order to support reference rewritten by\n the \"proc-receive\" hook. The \"proc-receive\" hook may handle a command\n for a pseudo-reference which may create or update a reference with\n different name, new-oid, and old-oid. While the capability\n -'report-status' cannot report for such case. See pack-protocol.txt\n -+'report-status' cannot report for such case. See linkgit:gitformat-pack-protocol[5]\n ++'report-status' cannot report for such case. See linkgit:gitprotocol-pack[5]\n for details.\n \n delete-refs\n -@@ Documentation/gitformat-protocol-capabilities.txt: packet-line, and must not contain non-printable or whitespace characters. The\n +@@ Documentation/gitprotocol-capabilities.txt: packet-line, and must not contain non-printable or whitespace characters. The\n current implementation uses trace2 session IDs (see\n link:api-trace2.html[api-trace2] for details), but this may change and users of\n the session ID should not rely on this fact.\n @@ Documentation/gitformat-protocol-capabilities.txt: packet-line, and must not con\n +---\n +Part of the linkgit:git[1] suite\n \n - ## Documentation/technical/protocol-common.txt => Documentation/gitformat-protocol-common.txt ##\n + ## Documentation/technical/protocol-common.txt => Documentation/gitprotocol-common.txt ##\n @@\n -Documentation Common to Pack and Http Protocols\n -===============================================\n -+gitformat-protocol-common(5)\n -+============================\n ++gitprotocol-common(5)\n ++=====================\n +\n +NAME\n +----\n -+gitformat-protocol-common - Things common to various protocols\n ++gitprotocol-common - Things common to various protocols\n +\n +SYNOPSIS\n +--------\n @@ Documentation/technical/protocol-common.txt => Documentation/gitformat-protocol-\n \n ABNF Notation\n -------------\n -@@ Documentation/gitformat-protocol-common.txt: Examples (as C-style strings):\n +@@ Documentation/gitprotocol-common.txt: Examples (as C-style strings):\n \"000bfoobar\\n\" \"foobar\\n\"\n \"0004\" \"\"\n ----\n @@ Documentation/gitformat-protocol-common.txt: Examples (as C-style strings):\n +---\n +Part of the linkgit:git[1] suite\n \n - ## Documentation/technical/protocol-v2.txt => Documentation/gitformat-protocol-v2.txt ##\n + ## Documentation/technical/pack-protocol.txt => Documentation/gitprotocol-pack.txt ##\n +@@\n +-Packfile transfer protocols\n +-===========================\n ++gitprotocol-pack(5)\n ++===================\n ++\n ++NAME\n ++----\n ++gitprotocol-pack - How packs are transferred over-the-wire\n ++\n ++SYNOPSIS\n ++--------\n ++[verse]\n ++\n ++\n ++DESCRIPTION\n ++-----------\n + \n + Git supports transferring data in packfiles over the ssh://, git://, http:// and\n + file:// transports. There exist two sets of protocols, one for pushing\n +@@ Documentation/gitprotocol-pack.txt: pkt-line Format\n + ---------------\n + \n + The descriptions below build on the pkt-line format described in\n +-protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless\n ++linkgit:gitprotocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless\n + otherwise noted the usual pkt-line LF rules apply: the sender SHOULD\n + include a LF, but the receiver MUST NOT complain if it is not present.\n + \n +@@ Documentation/gitprotocol-pack.txt: Each Extra Parameter takes the form of `=` or ``.\n + \n + Servers that receive any such Extra Parameters MUST ignore all\n + unrecognized keys. Currently, the only Extra Parameter recognized is\n +-\"version\" with a value of '1' or '2'. See protocol-v2.txt for more\n ++\"version\" with a value of '1' or '2'. See linkgit:gitprotocol-v2[5] for more\n + information on protocol version 2.\n + \n + Git Transport\n +@@ Documentation/gitprotocol-pack.txt: An example client/server communication might look like this:\n + S: 0018ok refs/heads/debug\\n\n + S: 002ang refs/heads/master non-fast-forward\\n\n + ----\n ++\n ++GIT\n ++---\n ++Part of the linkgit:git[1] suite\n +\n + ## Documentation/technical/protocol-v2.txt => Documentation/gitprotocol-v2.txt ##\n @@\n -Git Wire Protocol, Version 2\n -============================\n -+gitformat-protocol-v2(5)\n -+========================\n ++gitprotocol-v2(5)\n ++=================\n +\n +NAME\n +----\n -+gitformat-protocol-v2 - Git Wire Protocol, Version 2\n ++gitprotocol-v2 - Git Wire Protocol, Version 2\n +\n +SYNOPSIS\n +--------\n @@ Documentation/technical/protocol-v2.txt => Documentation/gitformat-protocol-v2.t\n \n This document presents a specification for a version 2 of Git's wire\n protocol. Protocol v2 will improve upon v1 in the following ways:\n -@@ Documentation/gitformat-protocol-v2.txt: Packet-Line Framing\n +@@ Documentation/gitprotocol-v2.txt: Packet-Line Framing\n -------------------\n \n All communication is done using packet-line framing, just as in v1. See\n -`Documentation/technical/pack-protocol.txt` and\n -+linkgit:gitformat-pack-protocol[5] and\n - `Documentation/technical/protocol-common.txt` for more information.\n +-`Documentation/technical/protocol-common.txt` for more information.\n ++linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-common[5] for more information.\n \n In protocol v2 these special packets will have the following semantics:\n -@@ Documentation/gitformat-protocol-v2.txt: Initial Client Request\n + \n +@@ Documentation/gitprotocol-v2.txt: Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`. More information can be\n -found in `pack-protocol.txt` and `http-protocol.txt`, as well as the\n -+found in linkgit:gitformat-pack-protocol[5] and `http-protocol.txt`, as well as the\n ++found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the\n `GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n -@@ Documentation/gitformat-protocol-v2.txt: and associated requested information, each separated by a single space.\n +@@ Documentation/gitprotocol-v2.txt: and associated requested information, each separated by a single space.\n \tattr = \"size\"\n \n \tobj-info = obj-id SP obj-size\n @@ Documentation/technical/api-simple-ipc.txt: client and an optional response mess\n with a flush packet.\n \n -The pkt-line routines (Documentation/technical/protocol-common.txt)\n -+The pkt-line routines (linkgit:gitformat-protocol-common[5])\n ++The pkt-line routines (linkgit:gitprotocol-common[5])\n are used to simplify buffer management during message generation,\n transmission, and reception. A flush packet is used to mark the end\n of the message. This allows the sender to incrementally generate and\n @@ Documentation/technical/http-protocol.txt: smart server reply:\n \n The client may send Extra Parameters (see\n -Documentation/technical/pack-protocol.txt) as a colon-separated string\n -+linkgit:gitformat-pack-protocol[5]) as a colon-separated string\n ++linkgit:gitprotocol-pack[5]) as a colon-separated string\n in the Git-Protocol HTTP header.\n \n Uses the `--http-backend-info-refs` option to\n @@ Documentation/technical/http-protocol.txt: References\n http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n -link:technical/pack-protocol.html\n -link:technical/protocol-capabilities.html\n -+linkgit:gitformat-pack-protocol[5]\n -+linkgit:gitformat-protocol-capabilities[5]\n ++linkgit:gitprotocol-pack[5]\n ++linkgit:gitprotocol-capabilities[5]\n \n ## Documentation/technical/long-running-process-protocol.txt ##\n @@ Documentation/technical/long-running-process-protocol.txt: Long-running process protocol\n @@ Documentation/technical/long-running-process-protocol.txt: Long-running process\n This protocol is used when Git needs to communicate with an external\n process throughout the entire life of a single Git command. All\n -communication is in pkt-line format (see technical/protocol-common.txt)\n -+communication is in pkt-line format (see linkgit:gitformat-protocol-common[5])\n ++communication is in pkt-line format (see linkgit:gitprotocol-common[5])\n over standard input and standard output.\n \n Handshake\n \n + ## Documentation/technical/packfile-uri.txt ##\n +@@ Documentation/technical/packfile-uri.txt: a `packfile-uris` argument, the server MAY send a `packfile-uris` section\n + directly before the `packfile` section (right after `wanted-refs` if it is\n + sent) containing URIs of any of the given protocols. The URIs point to\n + packfiles that use only features that the client has declared that it supports\n +-(e.g. ofs-delta and thin-pack). See protocol-v2.txt for the documentation of\n ++(e.g. ofs-delta and thin-pack). See linkgit:gitprotocol-v2[5] for the documentation of\n + this section.\n + \n + Clients should then download and index all the given URIs (in addition to\n +\n ## Documentation/technical/partial-clone.txt ##\n @@ Documentation/technical/partial-clone.txt: Design Details\n upload-pack negotiation.\n +\n This uses the existing capability discovery mechanism.\n -See \"filter\" in Documentation/technical/pack-protocol.txt.\n -+See \"filter\" in linkgit:gitformat-pack-protocol[5].\n ++See \"filter\" in linkgit:gitprotocol-pack[5].\n \n - Clients pass a \"filter-spec\" to clone and fetch which is passed to the\n server to request filtering during packfile construction.\n \n ## command-list.txt ##\n -@@ command-list.txt: giteveryday guide\n +@@ command-list.txt: gitdiffcore guide\n + giteveryday guide\n gitfaq guide\n - gitformat-bundle gitformats\n - gitformat-commit-graph gitformats\n -+gitformat-pack-protocol gitformats\n -+gitformat-protocol-capabilities gitformats\n -+gitformat-protocol-common gitformats\n -+gitformat-protocol-v2 gitformats\n + gitformat-bundle developerinterfaces\n +-gitformat-bundle developerinterfaces\n + gitformat-commit-graph developerinterfaces\n gitglossary guide\n - githooks userformats\n - gitignore userformats\n + githooks userinterfaces\n +@@ command-list.txt: gitk mainporcelain\n + gitmailmap userinterfaces\n + gitmodules userinterfaces\n + gitnamespaces guide\n ++gitprotocol-capabilities developerinterfaces\n ++gitprotocol-common developerinterfaces\n ++gitprotocol-pack developerinterfaces\n ++gitprotocol-v2 developerinterfaces\n + gitremote-helpers guide\n + gitrepository-layout userinterfaces\n + gitrevisions userinterfaces\n +\n + ## refspec.h ##\n +@@ refspec.h: int valid_remote_name(const char *name);\n + struct strvec;\n + /*\n + * Determine what values to pass to the peer in ref-prefix lines\n +- * (see Documentation/technical/protocol-v2.txt).\n ++ * (see linkgit:gitprotocol-v2[5]).\n + */\n + void refspec_ref_prefixes(const struct refspec *rs,\n + \t\t\t struct strvec *ref_prefixes);\n \n ## t/t5551-http-fetch-smart.sh ##\n @@ t/t5551-http-fetch-smart.sh: test_expect_success 'no-op half-auth fetch does not require a password' '\n 6: 858ce9c6999 ! 7: 5b081e6637a docs: move pack format docs to man section 5\n @@ Documentation/Makefile: MAN1_TXT += gitweb.txt\n MAN5_TXT += gitformat-commit-graph.txt\n +MAN5_TXT += gitformat-index.txt\n +MAN5_TXT += gitformat-pack-cruft.txt\n - MAN5_TXT += gitformat-pack-protocol.txt\n +MAN5_TXT += gitformat-pack.txt\n - MAN5_TXT += gitformat-protocol-capabilities.txt\n - MAN5_TXT += gitformat-protocol-common.txt\n - MAN5_TXT += gitformat-protocol-v2.txt\n +MAN5_TXT += gitformat-signature.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n @@ Documentation/technical/chunk-format.txt => Documentation/gitformat-chunk.txt\n scanning a small \"table of contents\" for the remaining data. This common\n format is used by the `commit-graph` and `multi-pack-index` files. See\n -link:technical/pack-format.html[the `multi-pack-index` format] and\n --the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n +the `multi-pack-index` format in linkgit:gitformat-pack[5] and\n -+link:technical/commit-graph-format.html[the `commit-graph` format] for\n + the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n how they use the chunks to describe structured data.\n \n - A chunk-based file format begins with some header information custom to\n @@ Documentation/gitformat-chunk.txt: for future formats:\n * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n in `midx.c` for how the chunk-format API is used to write and\n @@ Documentation/gitformat-pack-cruft.txt: which aren't already stored in an earlie\n +---\n +Part of the linkgit:git[1] suite\n \n - ## Documentation/gitformat-pack-protocol.txt ##\n -@@ Documentation/gitformat-pack-protocol.txt: Now that the client and server have finished negotiation about what\n - the minimal amount of data that needs to be sent to the client is, the server\n - will construct and send the required data in packfile format.\n - \n --See pack-format.txt for what the packfile itself actually looks like.\n -+See linkgit:gitformat-pack[5] for what the packfile itself actually looks like.\n - \n - If 'side-band' or 'side-band-64k' capabilities have been specified by\n - the client, the server will send the packfile data multiplexed.\n -\n ## Documentation/technical/pack-format.txt => Documentation/gitformat-pack.txt ##\n @@\n -Git pack format\n @@ Documentation/technical/pack-format.txt => Documentation/gitformat-pack.txt\n +linkgit:git-gc[1] and linkgit:git-pack-objects[1].\n +\n +The pack format is also used over-the-wire, see\n -+e.g. linkgit:gitformat-protocol-v2[5], as well as being a part of\n ++e.g. linkgit:gitprotocol-v2[5], as well as being a part of\n +other container formats in the case of linkgit:gitformat-bundle[5].\n \n == Checksums and object IDs\n @@ Documentation/gitformat-signature.txt: Date: Wed Jun 15 09:13:29 2016 +0000\n +---\n +Part of the linkgit:git[1] suite\n \n + ## Documentation/gitprotocol-pack.txt ##\n +@@ Documentation/gitprotocol-pack.txt: Now that the client and server have finished negotiation about what\n + the minimal amount of data that needs to be sent to the client is, the server\n + will construct and send the required data in packfile format.\n + \n +-See pack-format.txt for what the packfile itself actually looks like.\n ++See linkgit:gitformat-pack[5] for what the packfile itself actually looks like.\n + \n + If 'side-band' or 'side-band-64k' capabilities have been specified by\n + the client, the server will send the packfile data multiplexed.\n +\n ## Documentation/howto/recover-corrupted-object-harder.txt ##\n @@ Documentation/howto/recover-corrupted-object-harder.txt: Note that the \"object\" file isn't fit for feeding straight to zlib; it\n has the git packed object header, which is variable-length. We want to\n @@ command-list.txt\n @@ command-list.txt: gitdiffcore guide\n giteveryday guide\n gitfaq guide\n - gitformat-bundle gitformats\n -+gitformat-chunk gitformats\n - gitformat-commit-graph gitformats\n -+gitformat-index gitformats\n -+gitformat-pack gitformats\n -+gitformat-pack-cruft gitformats\n - gitformat-pack-protocol gitformats\n - gitformat-protocol-capabilities gitformats\n - gitformat-protocol-common gitformats\n - gitformat-protocol-v2 gitformats\n -+gitformat-signature gitformats\n + gitformat-bundle developerinterfaces\n ++gitformat-chunk developerinterfaces\n + gitformat-commit-graph developerinterfaces\n ++gitformat-index developerinterfaces\n ++gitformat-pack developerinterfaces\n ++gitformat-pack-cruft developerinterfaces\n ++gitformat-signature developerinterfaces\n gitglossary guide\n - githooks userformats\n - gitignore userformats\n + githooks userinterfaces\n + gitignore userinterfaces\n \n ## pack-revindex.h ##\n @@\n 7: 499ee582644 ! 8: 8f8214addfd docs: move http-protocol docs to man section 5\n @@ Commit message\n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/Makefile ##\n -@@ Documentation/Makefile: MAN5_TXT += gitformat-pack-protocol.txt\n - MAN5_TXT += gitformat-pack.txt\n - MAN5_TXT += gitformat-protocol-capabilities.txt\n - MAN5_TXT += gitformat-protocol-common.txt\n -+MAN5_TXT += gitformat-protocol-http.txt\n - MAN5_TXT += gitformat-protocol-v2.txt\n - MAN5_TXT += gitformat-signature.txt\n - MAN5_TXT += githooks.txt\n +@@ Documentation/Makefile: MAN5_TXT += gitmailmap.txt\n + MAN5_TXT += gitmodules.txt\n + MAN5_TXT += gitprotocol-capabilities.txt\n + MAN5_TXT += gitprotocol-common.txt\n ++MAN5_TXT += gitprotocol-http.txt\n + MAN5_TXT += gitprotocol-pack.txt\n + MAN5_TXT += gitprotocol-v2.txt\n + MAN5_TXT += gitrepository-layout.txt\n @@ Documentation/Makefile: TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n @@ Documentation/git-upload-pack.txt: OPTIONS\n \t`$GIT_URL/info/refs?service=git-upload-pack` requests. See\n -\t\"Smart Clients\" in link:technical/http-protocol.html[the HTTP\n -\ttransfer protocols] documentation and \"HTTP Transport\" in the\n --\tlinkgit:gitformat-protocol-v2[5] documentation. Also understood by\n -+\t\"Smart Clients\" in linkgit:gitformat-protocol-http[5] and\n -+\t\"HTTP Transport\" in link:technical/protocol-v2.html[the Git\n -+\tWire Protocol, Version 2] documentation. Also understood by\n +-\tlinkgit:gitprotocol-v2[5] documentation. Also understood by\n ++\t\"Smart Clients\" in linkgit:gitprotocol-http[5] and \"HTTP\n ++\tTransport\" in in the linkgit:gitprotocol-v2[5]\n ++\tdocumentation. Also understood by\n \tlinkgit:git-receive-pack[1].\n \n ::\n \n - ## Documentation/gitformat-pack-protocol.txt ##\n -@@ Documentation/gitformat-pack-protocol.txt: Git supports transferring data in packfiles over the ssh://, git://, http:// and\n - file:// transports. There exist two sets of protocols, one for pushing\n - data from a client to a server and another for fetching data from a\n - server to a client. The three transports (ssh, git, file) use the same\n --protocol to transfer data. http is documented in http-protocol.txt.\n -+protocol to transfer data. http is documented in linkgit:gitformat-protocol-http[5].\n - \n - The processes invoked in the canonical Git implementation are 'upload-pack'\n - on the server side and 'fetch-pack' on the client side for fetching data;\n -\n - ## Documentation/technical/http-protocol.txt => Documentation/gitformat-protocol-http.txt ##\n + ## Documentation/technical/http-protocol.txt => Documentation/gitprotocol-http.txt ##\n @@\n -HTTP transfer protocols\n -=======================\n -+gitformat-protocol-http(5)\n -+==========================\n ++gitprotocol-http(5)\n ++===================\n +\n +NAME\n +----\n -+gitformat-protocol-http - Git HTTP-based protocols\n ++gitprotocol-http - Git HTTP-based protocols\n +\n +\n +SYNOPSIS\n @@ Documentation/technical/http-protocol.txt => Documentation/gitformat-protocol-ht\n \n Git supports two HTTP based transfer protocols. A \"dumb\" protocol\n which requires only a standard HTTP server on the server end of the\n -@@ Documentation/gitformat-protocol-http.txt: the id obtained through ref discovery as old_id.\n +@@ Documentation/gitprotocol-http.txt: the id obtained through ref discovery as old_id.\n \n TODO: Document this further.\n \n @@ Documentation/gitformat-protocol-http.txt: the id obtained through ref discovery\n +SEE ALSO\n +--------\n +\n - linkgit:gitformat-pack-protocol[5]\n - linkgit:gitformat-protocol-capabilities[5]\n + linkgit:gitprotocol-pack[5]\n + linkgit:gitprotocol-capabilities[5]\n +\n +GIT\n +---\n +Part of the linkgit:git[1] suite\n \n - ## Documentation/gitformat-protocol-v2.txt ##\n -@@ Documentation/gitformat-protocol-v2.txt: Initial Client Request\n + ## Documentation/gitprotocol-pack.txt ##\n +@@ Documentation/gitprotocol-pack.txt: Git supports transferring data in packfiles over the ssh://, git://, http:// and\n + file:// transports. There exist two sets of protocols, one for pushing\n + data from a client to a server and another for fetching data from a\n + server to a client. The three transports (ssh, git, file) use the same\n +-protocol to transfer data. http is documented in http-protocol.txt.\n ++protocol to transfer data. http is documented in linkgit:gitprotocol-http[5].\n + \n + The processes invoked in the canonical Git implementation are 'upload-pack'\n + on the server side and 'fetch-pack' on the client side for fetching data;\n +\n + ## Documentation/gitprotocol-v2.txt ##\n +@@ Documentation/gitprotocol-v2.txt: Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`. More information can be\n --found in linkgit:gitformat-pack-protocol[5] and `http-protocol.txt`, as well as the\n -+found in linkgit:gitformat-pack-protocol[5] and linkgit:gitformat-protocol-http[5], as well as the\n +-found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the\n ++found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the\n `GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n -@@ Documentation/gitformat-protocol-v2.txt: HTTP Transport\n +@@ Documentation/gitprotocol-v2.txt: HTTP Transport\n ~~~~~~~~~~~~~~\n \n When using the http:// or https:// transport a client makes a \"smart\"\n -info/refs request as described in `http-protocol.txt` and requests that\n -+info/refs request as described in linkgit:gitformat-protocol-http[5] and requests that\n ++info/refs request as described in linkgit:gitprotocol-http[5] and requests that\n v2 be used by supplying \"version=2\" in the `Git-Protocol` header.\n \n C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0\n \n ## command-list.txt ##\n -@@ command-list.txt: gitformat-pack-cruft gitformats\n - gitformat-pack-protocol gitformats\n - gitformat-protocol-capabilities gitformats\n - gitformat-protocol-common gitformats\n -+gitformat-protocol-http gitformats\n - gitformat-protocol-v2 gitformats\n - gitformat-signature gitformats\n - gitglossary guide\n +@@ command-list.txt: gitmodules userinterfaces\n + gitnamespaces guide\n + gitprotocol-capabilities developerinterfaces\n + gitprotocol-common developerinterfaces\n ++gitprotocol-http developerinterfaces\n + gitprotocol-pack developerinterfaces\n + gitprotocol-v2 developerinterfaces\n + gitremote-helpers guide\n 8: f186950e673 ! 9: 19601ac36a2 docs: move multi-pack-index docs to man section 5\n @@ Documentation/Makefile: MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += gitformat-index.txt\n +MAN5_TXT += gitformat-multi-pack-index.txt\n MAN5_TXT += gitformat-pack-cruft.txt\n - MAN5_TXT += gitformat-pack-protocol.txt\n MAN5_TXT += gitformat-pack.txt\n + MAN5_TXT += gitformat-signature.txt\n @@ Documentation/Makefile: TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n TECH_DOCS += technical/hash-function-transition\n @@ Documentation/git-multi-pack-index.txt: $ git multi-pack-index verify\n --------\n -See link:technical/multi-pack-index.html[The Multi-Pack-Index Design\n -Document] and linkgit:gitformat-pack[5] for more information on the\n -+\n +See linkgit:git-multi-pack-index[1] and\n +linkgit:gitformat-multi-pack-index[5] for more information on the\n multi-pack-index feature and its file format.\n @@ Documentation/gitformat-pack.txt: packs arranged in MIDX order (with the preferr\n Part of the linkgit:git[1] suite\n \n ## command-list.txt ##\n -@@ command-list.txt: gitformat-bundle gitformats\n - gitformat-chunk gitformats\n - gitformat-commit-graph gitformats\n - gitformat-index gitformats\n -+gitformat-multi-pack-index gitformats\n - gitformat-pack gitformats\n - gitformat-pack-cruft gitformats\n - gitformat-pack-protocol gitformats\n +@@ command-list.txt: gitformat-bundle developerinterfaces\n + gitformat-chunk developerinterfaces\n + gitformat-commit-graph developerinterfaces\n + gitformat-index developerinterfaces\n ++gitformat-multi-pack-index developerinterfaces\n + gitformat-pack developerinterfaces\n + gitformat-pack-cruft developerinterfaces\n + gitformat-signature developerinterfaces\n-- \n2.37.1.1095.g64a1e8362fd\n\n"},{"id":"459645","messageId":"patch-v5-2.9-2ec00f81552-20220721T160721Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com","subject":"[PATCH v5 2/9] git help doc: use \"\" instead of \"\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-21T16:13:51Z","receivedAt":"2022-07-21T16:15:19Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Replace the use of \"\" originally introduced (as \"GUIDE\") in\na133737b809 (doc: include --guide option description for \"git help\",\n2013-04-02) with the more generic \"\". The \"\" placeholder is\nmore generic, and one we'll be able to use as we introduce new\ndocumentation categories.\n\nLet's also add \"\" to the \"git help -h\" output, when it was made\nto use parse_option() in in 41eb33bd0cb (help: use parseopt,\n2008-02-24).\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-help.txt | 8 ++++----\n builtin/help.c | 2 +-\n 2 files changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 239c68db457..bead763fd29 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -9,14 +9,14 @@ SYNOPSIS\n --------\n [verse]\n 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\n-'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n+'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n \n DESCRIPTION\n -----------\n \n-With no options and no '' or '' given, the synopsis of the 'git'\n+With no options and no '' or '' given, the synopsis of the 'git'\n command and a list of the most commonly used Git commands are printed\n on the standard output.\n \n@@ -26,8 +26,8 @@ printed on the standard output.\n If the option `--guides` or `-g` is given, a list of the\n Git concept guides is also printed on the standard output.\n \n-If a command, or a guide, is given, a manual page for that command or\n-guide is brought up. The 'man' program is used by default for this\n+If a command or other documentation is given, the relevant manual page\n+will be brought up. The 'man' program is used by default for this\n purpose, but this can be overridden by other options or configuration\n variables.\n \ndiff --git a/builtin/help.c b/builtin/help.c\nindex 222f994f863..dec82d1be27 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -81,7 +81,7 @@ static struct option builtin_help_options[] = {\n \n static const char * const builtin_help_usage[] = {\n \t\"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n-\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] []\"),\n+\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [|]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n \tNULL\n-- \n2.37.1.1095.g64a1e8362fd\n\n"},{"id":"459646","messageId":"patch-v5-3.9-31be7d01c50-20220721T160721Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com","subject":"[PATCH v5 3/9] git docs: add a category for user-facing file, repo and command UX","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-21T16:13:52Z","receivedAt":"2022-07-21T16:15:20Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"Repository, command and file interfaces\" section in the\nmain \"git help git\" manual page. Move things that belong under this\nnew criteria from the generic \"Guides\" section.\n\nThe \"Guides\" section was added in f442f28a81b (git.txt: add list of\nguides, 2020-08-05). It makes sense to have e.g. \"giteveryday(7)\" and\n\"gitfaq(7)\" listed under \"Guides\".\n\nBut placing e.g. \"gitignore(5)\" in it is stretching the meaning of\nwhat a \"guide\" is, ideally that section should list things similar to\n\"giteveryday(7)\" and \"gitcore-tutorial(7)\".\n\nAn alternate name that was considered for this new section was \"User\nformats\", for consistency with the nomenclature used for man section 5\nin general. My man(1) lists it as \"File formats and conventions,\ne.g. /etc/passwd\".\n\nSo calling this \"git help --formats\" or \"git help --user-formats\"\nwould make sense for e.g. gitignore(5), but would be stretching it\nsomewhat for githooks(5), and would seem really suspect for the likes\nof gitcli(7).\n\nLet's instead pick a name that's closer to the generic term \"User\ninterface\", which is really what this documentation discusses: General\nuser-interface documentation that doesn't obviously belong elsewhere.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-help.txt | 14 ++++++++++++++\n Documentation/git.txt | 8 ++++++++\n Makefile | 1 +\n builtin/help.c | 9 +++++++++\n command-list.txt | 21 +++++++++++++--------\n help.c | 12 ++++++++++++\n help.h | 1 +\n t/t0012-help.sh | 12 +++++++++++-\n 9 files changed, 70 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 4f801f4e4c9..28eb940a9b8 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchingrepositories.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n+\tcmds-userinterfaces.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\n \ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex bead763fd29..4eb03bd6c38 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -12,6 +12,7 @@ SYNOPSIS\n 'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n+'git help' [--user-interfaces]\n \n DESCRIPTION\n -----------\n@@ -69,6 +70,19 @@ OPTIONS\n --guides::\n \tPrints a list of the Git concept guides on the standard output.\n \n+--user-interfaces::\n+\tPrints a list of the repository, command and file interfaces\n+\tdocumentation on the standard output.\n++\n+In-repository file interfaces such as `.git/info/exclude` are\n+documented here (see linkgit:gitrepository-layout[5]), as well as\n+in-tree configuration such as `.mailmap` (see linkgit:gitmailmap[5]).\n++\n+This section of the documentation also covers general or widespread\n+user-interface conventions (e.g. linkgit:gitcli[7]), and\n+pseudo-configuration such as the file-based `.git/hooks/*` interface\n+described in linkgit:githooks[5].\n+\n -i::\n --info::\n \tDisplay manual page for the command in the 'info' format. The\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 302607a4967..f69d32e1e79 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -339,6 +339,14 @@ The following documentation pages are guides about Git concepts.\n \n include::cmds-guide.txt[]\n \n+Repository, command and file interfaces\n+---------------------------------------\n+\n+This documentation discusses repository and command interfaces which\n+users are expected to interact with directly. See `--user-formats` in\n+linkgit:git-help[1] for more details on the critera.\n+\n+include::cmds-userinterfaces.txt[]\n \n Configuration Mechanism\n -----------------------\ndiff --git a/Makefile b/Makefile\nindex 1624471badc..ea0ef7df734 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -3532,6 +3532,7 @@ check-docs::\n \t\tsed -e '1,/^### command list/d' \\\n \t\t -e '/^#/d' \\\n \t\t -e '/guide$$/d' \\\n+\t\t -e '/interfaces$$/d' \\\n \t\t -e 's/[ \t].*//' \\\n \t\t -e 's/^/listed /' command-list.txt; \\\n \t\t$(MAKE) -C Documentation print-man1 | \\\ndiff --git a/builtin/help.c b/builtin/help.c\nindex dec82d1be27..1ab1c8a0dd7 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -43,6 +43,7 @@ static enum help_action {\n \tHELP_ACTION_ALL = 1,\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n+\tHELP_ACTION_USER_INTERFACES,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -69,6 +70,9 @@ static struct option builtin_help_options[] = {\n \n \tOPT_CMDMODE('g', \"guides\", &cmd_mode, N_(\"print list of useful guides\"),\n \t\t HELP_ACTION_GUIDES),\n+\tOPT_CMDMODE(0, \"user-interfaces\", &cmd_mode,\n+\t\t N_(\"print list of user-facing repository, command and file interfaces\"),\n+\t\t HELP_ACTION_USER_INTERFACES),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -84,6 +88,7 @@ static const char * const builtin_help_usage[] = {\n \tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [|]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n+\t\"git help [--user-interfaces]\",\n \tNULL\n };\n \n@@ -654,6 +659,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\topt_mode_usage(argc, \"--config-for-completion\", help_format);\n \t\tlist_config_help(SHOW_CONFIG_VARS);\n \t\treturn 0;\n+\tcase HELP_ACTION_USER_INTERFACES:\n+\t\topt_mode_usage(argc, \"--user-interfaces\", help_format);\n+\t\tlist_user_interfaces_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n \t\t\t help_format);\ndiff --git a/command-list.txt b/command-list.txt\nindex 9bd6f3c48f4..1d45303e14c 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -43,6 +43,11 @@\n # specified here, which can only have \"guide\" attribute and nothing\n # else.\n #\n+# User-facing repository, command and file interfaces such as\n+# documentation for the .gitmodules, .mailmap etc. files lives in man\n+# sections 5 and 7. These entries can only have the \"userinterfaces\"\n+# attribute and nothing else.\n+#\n ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -192,8 +197,8 @@ git-verify-tag ancillaryinterrogators\n git-whatchanged ancillaryinterrogators complete\n git-worktree mainporcelain\n git-write-tree plumbingmanipulators\n-gitattributes guide\n-gitcli guide\n+gitattributes userinterfaces\n+gitcli userinterfaces\n gitcore-tutorial guide\n gitcredentials guide\n gitcvs-migration guide\n@@ -201,15 +206,15 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitglossary guide\n-githooks guide\n-gitignore guide\n+githooks userinterfaces\n+gitignore userinterfaces\n gitk mainporcelain\n-gitmailmap guide\n-gitmodules guide\n+gitmailmap userinterfaces\n+gitmodules userinterfaces\n gitnamespaces guide\n gitremote-helpers guide\n-gitrepository-layout guide\n-gitrevisions guide\n+gitrepository-layout userinterfaces\n+gitrevisions userinterfaces\n gitsubmodules guide\n gittutorial guide\n gittutorial-2 guide\ndiff --git a/help.c b/help.c\nindex 80d516abb0b..a2ceda1723d 100644\n--- a/help.c\n+++ b/help.c\n@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_plumbinginterrogators, N_(\"Low-level Commands / Interrogators\") },\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n+\t{ CAT_userinterfaces, N_(\"User-facing repository, command and file interfaces\") },\n \t{ 0, NULL }\n };\n \n@@ -50,6 +51,7 @@ static const char *drop_prefix(const char *name, uint32_t category)\n \t\treturn new_name;\n \tswitch (category) {\n \tcase CAT_guide:\n+\tcase CAT_userinterfaces:\n \t\tprefix = \"git\";\n \t\tif (!skip_prefix(name, prefix, &new_name))\n \t\t\tBUG(\"'%s' in category #%d should have '%s' prefix\",\n@@ -432,6 +434,16 @@ void list_guides_help(void)\n \tputchar('\\n');\n }\n \n+void list_user_interfaces_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_userinterfaces, N_(\"User-facing repository, command and file interfaces:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex 971a3ad855a..243104c27a7 100644\n--- a/help.h\n+++ b/help.h\n@@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num)\n void list_common_cmds_help(void);\n void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n+void list_user_interfaces_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex 6c33a436901..bee5ed12203 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -44,6 +44,8 @@ test_expect_success 'invalid usage' '\n \ttest_expect_code 129 git help -g add &&\n \ttest_expect_code 129 git help -a -g &&\n \n+\ttest_expect_code 129 git help --user-interfaces add &&\n+\n \ttest_expect_code 129 git help -g -c &&\n \ttest_expect_code 129 git help --config-for-completion add &&\n \ttest_expect_code 129 git help --config-sections-for-completion add\n@@ -104,9 +106,9 @@ test_expect_success 'git help' '\n \ttest_i18ngrep \"^ commit \" help.output &&\n \ttest_i18ngrep \"^ fetch \" help.output\n '\n+\n test_expect_success 'git help -g' '\n \tgit help -g >help.output &&\n-\ttest_i18ngrep \"^ attributes \" help.output &&\n \ttest_i18ngrep \"^ everyday \" help.output &&\n \ttest_i18ngrep \"^ tutorial \" help.output\n '\n@@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' '\n \ttest_cmp expect test-browser.log\n '\n \n+test_expect_success 'git help --user-interfaces' '\n+\tgit help --user-interfaces >help.output &&\n+\tgrep \"^ attributes \" help.output &&\n+\tgrep \"^ mailmap \" help.output\n+'\n+\n test_expect_success 'git help -c' '\n \tgit help -c >help.output &&\n \tcat >expect <<-\\EOF &&\n@@ -220,6 +228,8 @@ test_expect_success \"'git help -a' section spacing\" '\n \tLow-level Commands / Syncing Repositories\n \n \tLow-level Commands / Internal Helpers\n+\n+\tUser-facing repository, command and file interfaces\n \tEOF\n \ttest_cmp expect actual\n '\n-- \n2.37.1.1095.g64a1e8362fd\n\n"},{"id":"459647","messageId":"patch-v5-4.9-a7310898866-20220721T160721Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com","subject":"[PATCH v5 4/9] git docs: add a category for file formats, protocols and interfaces","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-21T16:13:53Z","receivedAt":"2022-07-21T16:15:37Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"File formats, protocols and other developer interfaces\"\nsection in the main \"git help git\" manual page and start moving the\ndocumentation that now lives in \"Documentation/technical/*.git\" over\nto it. This compliments the newly added and adjacent \"Repository,\ncommand and file interfaces\" section.\n\nThis makes the technical documentation more accessible and\ndiscoverable. Before this we wouldn't install it by default, and had\nno ability to build man page versions of them. The links to them from\nour existing documentation link to the generated HTML version of these\ndocs.\n\nSo let's start moving those over, starting with just the\n\"bundle-format.txt\" documentation added in 7378ec90e1c (doc: describe\nGit bundle format, 2020-02-07). We'll now have a new\ngitformat-bundle(5) man page. Subsequent commits will move more git\ninternal format documentation over.\n\nUnfortunately the syntax of the current Documentation/technical/*.txt\nis not the same (when it comes to section headings etc.) as our\nDocumentation/*.txt documentation, so change the relevant bits of\nsyntax as we're moving this over.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 3 +-\n Documentation/git-bundle.txt | 14 +++---\n Documentation/git-help.txt | 5 +++\n Documentation/git.txt | 9 ++++\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++---\n Documentation/lint-man-section-order.perl | 3 ++\n builtin/help.c | 9 ++++\n command-list.txt | 5 +++\n help.c | 12 +++++\n help.h | 1 +\n t/t0012-help.sh | 2 +\n 11 files changed, 94 insertions(+), 13 deletions(-)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 28eb940a9b8..1a4a545f44a 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -24,6 +24,7 @@ MAN1_TXT += gitweb.txt\n \n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n+MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -95,7 +96,6 @@ TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n-TECH_DOCS += technical/bundle-format\n TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchingrepositories.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n+\tcmds-developerinterfaces.txt \\\n \tcmds-userinterfaces.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 7685b570455..f0b1282b918 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -56,10 +56,9 @@ using \"thin packs\", bundles created using exclusions are smaller in\n size. That they're \"thin\" under the hood is merely noted here as a\n curiosity, and as a reference to other documentation.\n \n-See link:technical/bundle-format.html[the `bundle-format`\n-documentation] for more details and the discussion of \"thin pack\" in\n-link:technical/pack-format.html[the pack format documentation] for\n-further details.\n+See linkgit:gitformat-bundle[5] for more details and the discussion of\n+\"thin pack\" in link:technical/pack-format.html[the pack format\n+documentation] for further details.\n \n OPTIONS\n -------\n@@ -77,7 +76,7 @@ verify ::\n \tcommits exist and are fully linked in the current repository.\n \tThen, 'git bundle' prints a list of missing commits, if any.\n \tFinally, information about additional capabilities, such as \"object\n-\tfilter\", is printed. See \"Capabilities\" in link:technical/bundle-format.html\n+\tfilter\", is printed. See \"Capabilities\" in linkgit:gitformat-bundle[5]\n \tfor more information. The exit code is zero for success, but will\n \tbe nonzero if the bundle file is invalid.\n \n@@ -337,6 +336,11 @@ You can also see what references it offers:\n $ git ls-remote mybundle\n ----------------\n \n+FILE FORMAT\n+-----------\n+\n+See linkgit:gitformat-bundle[5].\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 4eb03bd6c38..2b0b5e390dc 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -13,6 +13,7 @@ SYNOPSIS\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n 'git help' [--user-interfaces]\n+'git help' [--developer-interfaces]\n \n DESCRIPTION\n -----------\n@@ -83,6 +84,10 @@ user-interface conventions (e.g. linkgit:gitcli[7]), and\n pseudo-configuration such as the file-based `.git/hooks/*` interface\n described in linkgit:githooks[5].\n \n+--developer-interfaces::\n+\tPrint list of file formats, protocols and other developer\n+\tinterfaces documentation on the standard output.\n+\n -i::\n --info::\n \tDisplay manual page for the command in the 'info' format. The\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex f69d32e1e79..f064951b5c4 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -348,6 +348,15 @@ linkgit:git-help[1] for more details on the critera.\n \n include::cmds-userinterfaces.txt[]\n \n+File formats, protocols and other developer interfaces\n+------------------------------------------------------\n+\n+This documentation discusses file formats, over-the-wire protocols and\n+other git developer interfaces. See `--developer-interfaces` in\n+linkgit:git-help[1].\n+\n+include::cmds-developerinterfaces.txt[]\n+\n Configuration Mechanism\n -----------------------\n \ndiff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt\nsimilarity index 79%\nrename from Documentation/technical/bundle-format.txt\nrename to Documentation/gitformat-bundle.txt\nindex b9be8644cf5..6a9d9e5bf6f 100644\n--- a/Documentation/technical/bundle-format.txt\n+++ b/Documentation/gitformat-bundle.txt\n@@ -1,11 +1,33 @@\n-= Git bundle v2 format\n+gitformat-bundle(5)\n+===================\n \n-The Git bundle format is a format that represents both refs and Git objects.\n+NAME\n+----\n+gitformat-bundle - The bundle file format\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+*.bundle\n+*.bdl\n+\n+DESCRIPTION\n+-----------\n+\n+The Git bundle format is a format that represents both refs and Git\n+objects. A bundle is a header in a format similar to\n+linkgit:git-show-ref[1] followed by a pack in *.pack format.\n \n-== Format\n+The format is created and read by the linkgit:git-bundle[1] command,\n+and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1].\n+\n+\n+FORMAT\n+------\n \n We will use ABNF notation to define the Git bundle format. See\n-protocol-common.txt for the details.\n+link:technical/protocol-common.html for the details.\n \n A v2 bundle looks like this:\n \n@@ -36,7 +58,9 @@ value = *(%01-09 / %0b-FF)\n pack = ... ; packfile\n ----\n \n-== Semantics\n+\n+SEMANTICS\n+---------\n \n A Git bundle consists of several parts.\n \n@@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id.\n This is a comment and it has no specific meaning. The writer of the bundle MAY\n put any string here. The reader of the bundle MUST ignore the comment.\n \n-=== Note on the shallow clone and a Git bundle\n+Note on the shallow clone and a Git bundle\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n Note that the prerequisites does not represent a shallow-clone boundary. The\n semantics of the prerequisites and the shallow-clone boundaries are different,\n and the Git bundle v2 format cannot represent a shallow clone repository.\n \n-== Capabilities\n+CAPABILITIES\n+------------\n \n Because there is no opportunity for negotiation, unknown capabilities cause 'git\n bundle' to abort.\n@@ -79,3 +105,7 @@ bundle' to abort.\n * `filter` specifies an object filter as in the `--filter` option in\n linkgit:git-rev-list[1]. The resulting pack-file must be marked as a\n `.promisor` pack-file after it is unbundled.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl\nindex 425377dfeb7..02408a0062f 100755\n--- a/Documentation/lint-man-section-order.perl\n+++ b/Documentation/lint-man-section-order.perl\n@@ -32,6 +32,9 @@\n \t\t'SEE ALSO' => {\n \t\t\torder => $order++,\n \t\t},\n+\t\t'FILE FORMAT' => {\n+\t\t\torder => $order++,\n+\t\t},\n \t\t'GIT' => {\n \t\t\trequired => 1,\n \t\t\torder => $order++,\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 1ab1c8a0dd7..09ac4289f13 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -44,6 +44,7 @@ static enum help_action {\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n \tHELP_ACTION_USER_INTERFACES,\n+\tHELP_ACTION_DEVELOPER_INTERFACES,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -73,6 +74,9 @@ static struct option builtin_help_options[] = {\n \tOPT_CMDMODE(0, \"user-interfaces\", &cmd_mode,\n \t\t N_(\"print list of user-facing repository, command and file interfaces\"),\n \t\t HELP_ACTION_USER_INTERFACES),\n+\tOPT_CMDMODE(0, \"developer-interfaces\", &cmd_mode,\n+\t\t N_(\"print list of file formats, protocols and other developer interfaces\"),\n+\t\t HELP_ACTION_DEVELOPER_INTERFACES),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -89,6 +93,7 @@ static const char * const builtin_help_usage[] = {\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n \t\"git help [--user-interfaces]\",\n+\t\"git help [--developer-interfaces]\",\n \tNULL\n };\n \n@@ -663,6 +668,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\topt_mode_usage(argc, \"--user-interfaces\", help_format);\n \t\tlist_user_interfaces_help();\n \t\treturn 0;\n+\tcase HELP_ACTION_DEVELOPER_INTERFACES:\n+\t\topt_mode_usage(argc, \"--developer-interfaces\", help_format);\n+\t\tlist_developer_interfaces_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n \t\t\t help_format);\ndiff --git a/command-list.txt b/command-list.txt\nindex 1d45303e14c..1950c4ccd9c 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -48,6 +48,10 @@\n # sections 5 and 7. These entries can only have the \"userinterfaces\"\n # attribute and nothing else.\n #\n+# Git's file formats and protocols, such as documentation for the\n+# *.bundle format lives in man section 5. These entries can only have\n+# the \"developerinterfaces\" attribute and nothing else.\n+#\n ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -205,6 +209,7 @@ gitcvs-migration guide\n gitdiffcore guide\n giteveryday guide\n gitfaq guide\n+gitformat-bundle developerinterfaces\n gitglossary guide\n githooks userinterfaces\n gitignore userinterfaces\ndiff --git a/help.c b/help.c\nindex a2ceda1723d..71f1c905d1c 100644\n--- a/help.c\n+++ b/help.c\n@@ -39,6 +39,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n \t{ CAT_userinterfaces, N_(\"User-facing repository, command and file interfaces\") },\n+\t{ CAT_developerinterfaces, N_(\"Developer-facing file file formats, protocols and interfaces\") },\n \t{ 0, NULL }\n };\n \n@@ -52,6 +53,7 @@ static const char *drop_prefix(const char *name, uint32_t category)\n \tswitch (category) {\n \tcase CAT_guide:\n \tcase CAT_userinterfaces:\n+\tcase CAT_developerinterfaces:\n \t\tprefix = \"git\";\n \t\tif (!skip_prefix(name, prefix, &new_name))\n \t\t\tBUG(\"'%s' in category #%d should have '%s' prefix\",\n@@ -444,6 +446,16 @@ void list_user_interfaces_help(void)\n \tputchar('\\n');\n }\n \n+void list_developer_interfaces_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_developerinterfaces, N_(\"File formats, protocols and other developer interfaces:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex 243104c27a7..af073a7a026 100644\n--- a/help.h\n+++ b/help.h\n@@ -23,6 +23,7 @@ void list_common_cmds_help(void);\n void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n void list_user_interfaces_help(void);\n+void list_developer_interfaces_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex bee5ed12203..4ed2f242eb2 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -230,6 +230,8 @@ test_expect_success \"'git help -a' section spacing\" '\n \tLow-level Commands / Internal Helpers\n \n \tUser-facing repository, command and file interfaces\n+\n+\tDeveloper-facing file file formats, protocols and interfaces\n \tEOF\n \ttest_cmp expect actual\n '\n-- \n2.37.1.1095.g64a1e8362fd\n\n"},{"id":"459648","messageId":"patch-v5-5.9-62f9020a72d-20220721T160721Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com","subject":"[PATCH v5 5/9] docs: move commit-graph format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-21T16:13:54Z","receivedAt":"2022-07-21T16:15:41Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space.\n\nBy moving the documentation for the commit-graph format into man\nsection 5 and the new \"developerinterfaces\" category. This change is\nsplit from subsequent commits due to the relatively large amount of\nASCIIDOC formatting changes that are required.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-commit-graph.txt | 5 ++\n ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------\n Documentation/technical/chunk-format.txt | 4 +-\n command-list.txt | 2 +\n 5 files changed, 42 insertions(+), 17 deletions(-)\n rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (88%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 1a4a545f44a..e7bd72bb84e 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -25,6 +25,7 @@ MAN1_TXT += gitweb.txt\n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n+MAN5_TXT += gitformat-commit-graph.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex e1f48c95b3c..047decdb65b 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append\n ------------------------------------------------\n \n \n+FILE FORMAT\n+-----------\n+\n+see linkgit:gitformat-commit-graph[5].\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt\nsimilarity index 88%\nrename from Documentation/technical/commit-graph-format.txt\nrename to Documentation/gitformat-commit-graph.txt\nindex 484b185ba98..108dc2295c0 100644\n--- a/Documentation/technical/commit-graph-format.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -1,5 +1,18 @@\n-Git commit graph format\n-=======================\n+gitformat-commit-graph(5)\n+=========================\n+\n+NAME\n+----\n+gitformat-commit-graph - Git commit graph format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/info/commit-graph\n+$GIT_DIR/objects/info/commit-graphs/*\n+\n+DESCRIPTION\n+-----------\n \n The Git commit graph stores a list of commit OIDs and some associated\n metadata, including:\n@@ -30,7 +43,7 @@ and hash type.\n \n All multi-byte numbers are in network byte order.\n \n-HEADER:\n+=== HEADER:\n \n 4-byte signature:\n The signature is: {'C', 'G', 'P', 'H'}\n@@ -52,7 +65,7 @@ HEADER:\n We infer the length (H*B) of the Base Graphs chunk\n from this value.\n \n-CHUNK LOOKUP:\n+=== CHUNK LOOKUP:\n \n (C + 1) * 12 bytes listing the table of contents for the chunks:\n First 4 bytes describe the chunk id. Value 0 is a terminating label.\n@@ -68,17 +81,17 @@ CHUNK LOOKUP:\n these chunks may be given in any order. Chunks are required unless\n otherwise specified.\n \n-CHUNK DATA:\n+=== CHUNK DATA:\n \n- OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n+==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n The ith entry, F[i], stores the number of OIDs with first\n byte at most i. Thus F[255] stores the total\n number of commits (N).\n \n- OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n+==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n The OIDs for all commits in the graph, sorted in ascending order.\n \n- Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n+==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n * The first H bytes are for the OID of the root tree.\n * The next 8 bytes are for the positions of the first two parents\n of the ith commit. Stores value 0x70000000 if no parent in that\n@@ -93,7 +106,7 @@ CHUNK DATA:\n 2 bits of the lowest byte, storing the 33rd and 34th bit of the\n commit time.\n \n- Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n+==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n * This list of 4-byte values store corrected commit date offsets for the\n commits, arranged in the same order as commit data chunk.\n * If the corrected commit date offset cannot be stored within 31 bits,\n@@ -104,7 +117,7 @@ CHUNK DATA:\n by compatible versions of Git and in case of split commit-graph chains,\n the topmost layer also has Generation Data chunk.\n \n- Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n+==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n * This list of 8-byte values stores the corrected commit date offsets\n for commits with corrected commit date offsets that cannot be\n stored within 31 bits.\n@@ -112,7 +125,7 @@ CHUNK DATA:\n chunk is present and atleast one corrected commit date offset cannot\n be stored within 31 bits.\n \n- Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n+==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n This list of 4-byte values store the second through nth parents for\n all octopus merges. The second parent value in the commit data stores\n an array position within this list along with the most-significant bit\n@@ -120,14 +133,14 @@ CHUNK DATA:\n positions for the parents until reaching a value with the most-significant\n bit on. The other bits correspond to the position of the last parent.\n \n- Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n+==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters\n from commit 0 to commit i (inclusive) in lexicographic order. The Bloom\n filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header\n length), where BIDX[-1] is 0.\n * The BIDX chunk is ignored if the BDAT chunk is not present.\n \n- Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n+==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n * It starts with header consisting of three unsigned 32-bit integers:\n - Version of the hash algorithm being used. We currently only support\n \tvalue 1 which corresponds to the 32-bit version of the murmur3 hash\n@@ -147,13 +160,13 @@ CHUNK DATA:\n of length one, with either all bits set to zero or one respectively.\n * The BDAT chunk is present if and only if BIDX is present.\n \n- Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n+==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n This list of H-byte hashes describe a set of B commit-graph files that\n form a commit-graph chain. The graph position for the ith commit in this\n file's OID Lookup chunk is equal to i plus the number of commits in all\n base graphs. If B is non-zero, this chunk must exist.\n \n-TRAILER:\n+=== TRAILER:\n \n \tH-byte HASH-checksum of all of the above.\n \n@@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote\n possibly erroneous data in these chunks with the IDs \"GDAT\" and \"GDOV\". By\n changing the IDs, newer versions of Git will silently ignore those older\n chunks and write the new information without trusting the incorrect data.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/chunk-format.txt b/Documentation/technical/chunk-format.txt\nindex 593614fceda..f36ce42f37c 100644\n--- a/Documentation/technical/chunk-format.txt\n+++ b/Documentation/technical/chunk-format.txt\n@@ -6,7 +6,7 @@ sections of the file. This allows structured access to a large file by\n scanning a small \"table of contents\" for the remaining data. This common\n format is used by the `commit-graph` and `multi-pack-index` files. See\n link:technical/pack-format.html[the `multi-pack-index` format] and\n-link:technical/commit-graph-format.html[the `commit-graph` format] for\n+the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n how they use the chunks to describe structured data.\n \n A chunk-based file format begins with some header information custom to\n@@ -108,7 +108,7 @@ for future formats:\n * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()`\n in `commit-graph.c` for how the chunk-format API is used to write and\n parse the commit-graph file format documented in\n- link:technical/commit-graph-format.html[the commit-graph file format].\n+ the commit-graph file format in linkgit:gitformat-commit-graph[5].\n \n * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n in `midx.c` for how the chunk-format API is used to write and\ndiff --git a/command-list.txt b/command-list.txt\nindex 1950c4ccd9c..44e244a76f6 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -210,6 +210,8 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle developerinterfaces\n+gitformat-bundle developerinterfaces\n+gitformat-commit-graph developerinterfaces\n gitglossary guide\n githooks userinterfaces\n gitignore userinterfaces\n-- \n2.37.1.1095.g64a1e8362fd\n\n"},{"id":"459649","messageId":"patch-v5-6.9-019ec8cf73c-20220721T160721Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com","subject":"[PATCH v5 6/9] docs: move protocol-related docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-21T16:13:55Z","receivedAt":"2022-07-21T16:15:44Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space. By moving\nthe things that discuss the protocol we can properly link from\ne.g. lsrefs.unborn and protocol.version documentation to a manpage we\nbuild by default.\n\nSo far we have been using the \"gitformat-\" prefix for the\ndocumentation we've been moving over from Documentation/technical/*,\nbut for protocol documentation let's use \"gitprotocol-*\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 8 +++---\n Documentation/config/lsrefs.txt | 2 +-\n Documentation/config/protocol.txt | 2 +-\n Documentation/git-upload-pack.txt | 5 ++--\n Documentation/gitformat-bundle.txt | 2 +-\n ...ities.txt => gitprotocol-capabilities.txt} | 28 +++++++++++++++----\n ...ocol-common.txt => gitprotocol-common.txt} | 23 +++++++++++++--\n ...pack-protocol.txt => gitprotocol-pack.txt} | 24 +++++++++++++---\n .../protocol-v2.txt => gitprotocol-v2.txt} | 25 +++++++++++++----\n Documentation/technical/api-simple-ipc.txt | 2 +-\n Documentation/technical/http-protocol.txt | 6 ++--\n .../long-running-process-protocol.txt | 2 +-\n Documentation/technical/packfile-uri.txt | 2 +-\n Documentation/technical/partial-clone.txt | 2 +-\n command-list.txt | 5 +++-\n refspec.h | 2 +-\n t/t5551-http-fetch-smart.sh | 4 +--\n 17 files changed, 106 insertions(+), 38 deletions(-)\n rename Documentation/{technical/protocol-capabilities.txt => gitprotocol-capabilities.txt} (96%)\n rename Documentation/{technical/protocol-common.txt => gitprotocol-common.txt} (89%)\n rename Documentation/{technical/pack-protocol.txt => gitprotocol-pack.txt} (98%)\n rename Documentation/{technical/protocol-v2.txt => gitprotocol-v2.txt} (98%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex e7bd72bb84e..b53f3c12843 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -30,6 +30,10 @@ MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n MAN5_TXT += gitmodules.txt\n+MAN5_TXT += gitprotocol-capabilities.txt\n+MAN5_TXT += gitprotocol-common.txt\n+MAN5_TXT += gitprotocol-pack.txt\n+MAN5_TXT += gitprotocol-v2.txt\n MAN5_TXT += gitrepository-layout.txt\n MAN5_TXT += gitweb.conf.txt\n \n@@ -105,12 +109,8 @@ TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n-TECH_DOCS += technical/pack-protocol\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\n-TECH_DOCS += technical/protocol-capabilities\n-TECH_DOCS += technical/protocol-common\n-TECH_DOCS += technical/protocol-v2\n TECH_DOCS += technical/racy-git\n TECH_DOCS += technical/reftable\n TECH_DOCS += technical/send-pack-pipeline\ndiff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.txt\nindex adeda0f24d3..3d88fb0badb 100644\n--- a/Documentation/config/lsrefs.txt\n+++ b/Documentation/config/lsrefs.txt\n@@ -1,7 +1,7 @@\n lsrefs.unborn::\n \tMay be \"advertise\" (the default), \"allow\", or \"ignore\". If \"advertise\",\n \tthe server will respond to the client sending \"unborn\" (as described in\n-\tprotocol-v2.txt) and will advertise support for this feature during the\n+\tlinkgit:gitprotocol-v2[5]) and will advertise support for this feature during the\n \tprotocol v2 capability advertisement. \"allow\" is the same as\n \t\"advertise\" except that the server will not advertise support for this\n \tfeature; this is useful for load-balanced servers that cannot be\ndiff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt\nindex 756591d77b0..57603818514 100644\n--- a/Documentation/config/protocol.txt\n+++ b/Documentation/config/protocol.txt\n@@ -58,6 +58,6 @@ protocol.version::\n * `1` - the original wire protocol with the addition of a version string\n in the initial response from the server.\n \n-* `2` - link:technical/protocol-v2.html[wire protocol version 2].\n+* `2` - Wire protocol version 2, see linkgit:gitprotocol-v2[5].\n \n --\ndiff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt\nindex 8f87b23ea86..3409e0d36d1 100644\n--- a/Documentation/git-upload-pack.txt\n+++ b/Documentation/git-upload-pack.txt\n@@ -40,9 +40,8 @@ OPTIONS\n \tUsed by linkgit:git-http-backend[1] to serve up\n \t`$GIT_URL/info/refs?service=git-upload-pack` requests. See\n \t\"Smart Clients\" in link:technical/http-protocol.html[the HTTP\n-\ttransfer protocols] documentation and \"HTTP Transport\" in\n-\tlink:technical/protocol-v2.html[the Git Wire Protocol, Version\n-\t2] documentation. Also understood by\n+\ttransfer protocols] documentation and \"HTTP Transport\" in the\n+\tlinkgit:gitprotocol-v2[5] documentation. Also understood by\n \tlinkgit:git-receive-pack[1].\n \n ::\ndiff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.txt\nindex 6a9d9e5bf6f..00e0a20e657 100644\n--- a/Documentation/gitformat-bundle.txt\n+++ b/Documentation/gitformat-bundle.txt\n@@ -27,7 +27,7 @@ FORMAT\n ------\n \n We will use ABNF notation to define the Git bundle format. See\n-link:technical/protocol-common.html for the details.\n+linkgit:gitprotocol-common[5] for the details.\n \n A v2 bundle looks like this:\n \ndiff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/gitprotocol-capabilities.txt\nsimilarity index 96%\nrename from Documentation/technical/protocol-capabilities.txt\nrename to Documentation/gitprotocol-capabilities.txt\nindex 9dfade930da..c6dcc7d565d 100644\n--- a/Documentation/technical/protocol-capabilities.txt\n+++ b/Documentation/gitprotocol-capabilities.txt\n@@ -1,8 +1,20 @@\n-Git Protocol Capabilities\n-=========================\n+gitprotocol-capabilities(5)\n+===========================\n+\n+NAME\n+----\n+gitprotocol-capabilities - Protocol v0 and v1 capabilities\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n NOTE: this document describes capabilities for versions 0 and 1 of the pack\n-protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]\n+protocol. For version 2, please refer to the linkgit:gitprotocol-v2[5]\n doc.\n \n Servers SHOULD support all capabilities defined in this document.\n@@ -77,7 +89,7 @@ interleaved with S-R-Q.\n multi_ack_detailed\n ------------------\n This is an extension of multi_ack that permits client to better\n-understand the server's in-memory state. See pack-protocol.txt,\n+understand the server's in-memory state. See linkgit:gitprotocol-pack[5],\n section \"Packfile Negotiation\" for more information.\n \n no-done\n@@ -281,7 +293,7 @@ a packfile upload and reference update. If the pushing client requests\n this capability, after unpacking and updating references the server\n will respond with whether the packfile unpacked successfully and if\n each reference was updated successfully. If any of those were not\n-successful, it will send back an error message. See pack-protocol.txt\n+successful, it will send back an error message. See linkgit:gitprotocol-pack[5]\n for example messages.\n \n report-status-v2\n@@ -292,7 +304,7 @@ adding new \"option\" directives in order to support reference rewritten by\n the \"proc-receive\" hook. The \"proc-receive\" hook may handle a command\n for a pseudo-reference which may create or update a reference with\n different name, new-oid, and old-oid. While the capability\n-'report-status' cannot report for such case. See pack-protocol.txt\n+'report-status' cannot report for such case. See linkgit:gitprotocol-pack[5]\n for details.\n \n delete-refs\n@@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The\n current implementation uses trace2 session IDs (see\n link:api-trace2.html[api-trace2] for details), but this may change and users of\n the session ID should not rely on this fact.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-common.txt b/Documentation/gitprotocol-common.txt\nsimilarity index 89%\nrename from Documentation/technical/protocol-common.txt\nrename to Documentation/gitprotocol-common.txt\nindex ecedb34bba5..1486651bd10 100644\n--- a/Documentation/technical/protocol-common.txt\n+++ b/Documentation/gitprotocol-common.txt\n@@ -1,5 +1,20 @@\n-Documentation Common to Pack and Http Protocols\n-===============================================\n+gitprotocol-common(5)\n+=====================\n+\n+NAME\n+----\n+gitprotocol-common - Things common to various protocols\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n+\n+This document sets defines things common to various over-the-wire\n+protocols and file formats used in Git.\n \n ABNF Notation\n -------------\n@@ -97,3 +112,7 @@ Examples (as C-style strings):\n \"000bfoobar\\n\" \"foobar\\n\"\n \"0004\" \"\"\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitprotocol-pack.txt\nsimilarity index 98%\nrename from Documentation/technical/pack-protocol.txt\nrename to Documentation/gitprotocol-pack.txt\nindex e13a2c064d1..8a4de6decd0 100644\n--- a/Documentation/technical/pack-protocol.txt\n+++ b/Documentation/gitprotocol-pack.txt\n@@ -1,5 +1,17 @@\n-Packfile transfer protocols\n-===========================\n+gitprotocol-pack(5)\n+===================\n+\n+NAME\n+----\n+gitprotocol-pack - How packs are transferred over-the-wire\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n Git supports transferring data in packfiles over the ssh://, git://, http:// and\n file:// transports. There exist two sets of protocols, one for pushing\n@@ -18,7 +30,7 @@ pkt-line Format\n ---------------\n \n The descriptions below build on the pkt-line format described in\n-protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless\n+linkgit:gitprotocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless\n otherwise noted the usual pkt-line LF rules apply: the sender SHOULD\n include a LF, but the receiver MUST NOT complain if it is not present.\n \n@@ -60,7 +72,7 @@ Each Extra Parameter takes the form of `=` or ``.\n \n Servers that receive any such Extra Parameters MUST ignore all\n unrecognized keys. Currently, the only Extra Parameter recognized is\n-\"version\" with a value of '1' or '2'. See protocol-v2.txt for more\n+\"version\" with a value of '1' or '2'. See linkgit:gitprotocol-v2[5] for more\n information on protocol version 2.\n \n Git Transport\n@@ -707,3 +719,7 @@ An example client/server communication might look like this:\n S: 0018ok refs/heads/debug\\n\n S: 002ang refs/heads/master non-fast-forward\\n\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-v2.txt b/Documentation/gitprotocol-v2.txt\nsimilarity index 98%\nrename from Documentation/technical/protocol-v2.txt\nrename to Documentation/gitprotocol-v2.txt\nindex 8a877d27e23..d6105e07408 100644\n--- a/Documentation/technical/protocol-v2.txt\n+++ b/Documentation/gitprotocol-v2.txt\n@@ -1,5 +1,17 @@\n-Git Wire Protocol, Version 2\n-============================\n+gitprotocol-v2(5)\n+=================\n+\n+NAME\n+----\n+gitprotocol-v2 - Git Wire Protocol, Version 2\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n This document presents a specification for a version 2 of Git's wire\n protocol. Protocol v2 will improve upon v1 in the following ways:\n@@ -26,8 +38,7 @@ Packet-Line Framing\n -------------------\n \n All communication is done using packet-line framing, just as in v1. See\n-`Documentation/technical/pack-protocol.txt` and\n-`Documentation/technical/protocol-common.txt` for more information.\n+linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-common[5] for more information.\n \n In protocol v2 these special packets will have the following semantics:\n \n@@ -42,7 +53,7 @@ Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`. More information can be\n-found in `pack-protocol.txt` and `http-protocol.txt`, as well as the\n+found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the\n `GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n@@ -566,3 +577,7 @@ and associated requested information, each separated by a single space.\n \tattr = \"size\"\n \n \tobj-info = obj-id SP obj-size\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt\nindex d79ad323e67..d44ada98e7d 100644\n--- a/Documentation/technical/api-simple-ipc.txt\n+++ b/Documentation/technical/api-simple-ipc.txt\n@@ -78,7 +78,7 @@ client and an optional response message from the server. Both the\n client and server messages are unlimited in length and are terminated\n with a flush packet.\n \n-The pkt-line routines (Documentation/technical/protocol-common.txt)\n+The pkt-line routines (linkgit:gitprotocol-common[5])\n are used to simplify buffer management during message generation,\n transmission, and reception. A flush packet is used to mark the end\n of the message. This allows the sender to incrementally generate and\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt\nindex cc5126cfeda..8bd672d55bb 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/technical/http-protocol.txt\n@@ -222,7 +222,7 @@ smart server reply:\n S: 0000\n \n The client may send Extra Parameters (see\n-Documentation/technical/pack-protocol.txt) as a colon-separated string\n+linkgit:gitprotocol-pack[5]) as a colon-separated string\n in the Git-Protocol HTTP header.\n \n Uses the `--http-backend-info-refs` option to\n@@ -518,5 +518,5 @@ References\n \n http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n-link:technical/pack-protocol.html\n-link:technical/protocol-capabilities.html\n+linkgit:gitprotocol-pack[5]\n+linkgit:gitprotocol-capabilities[5]\ndiff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt\nindex aa0aa9af1c2..6f33654b428 100644\n--- a/Documentation/technical/long-running-process-protocol.txt\n+++ b/Documentation/technical/long-running-process-protocol.txt\n@@ -3,7 +3,7 @@ Long-running process protocol\n \n This protocol is used when Git needs to communicate with an external\n process throughout the entire life of a single Git command. All\n-communication is in pkt-line format (see technical/protocol-common.txt)\n+communication is in pkt-line format (see linkgit:gitprotocol-common[5])\n over standard input and standard output.\n \n Handshake\ndiff --git a/Documentation/technical/packfile-uri.txt b/Documentation/technical/packfile-uri.txt\nindex 1eb525fe760..9d453d47651 100644\n--- a/Documentation/technical/packfile-uri.txt\n+++ b/Documentation/technical/packfile-uri.txt\n@@ -18,7 +18,7 @@ a `packfile-uris` argument, the server MAY send a `packfile-uris` section\n directly before the `packfile` section (right after `wanted-refs` if it is\n sent) containing URIs of any of the given protocols. The URIs point to\n packfiles that use only features that the client has declared that it supports\n-(e.g. ofs-delta and thin-pack). See protocol-v2.txt for the documentation of\n+(e.g. ofs-delta and thin-pack). See linkgit:gitprotocol-v2[5] for the documentation of\n this section.\n \n Clients should then download and index all the given URIs (in addition to\ndiff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt\nindex 99f0eb30406..92fcee2bfff 100644\n--- a/Documentation/technical/partial-clone.txt\n+++ b/Documentation/technical/partial-clone.txt\n@@ -79,7 +79,7 @@ Design Details\n upload-pack negotiation.\n +\n This uses the existing capability discovery mechanism.\n-See \"filter\" in Documentation/technical/pack-protocol.txt.\n+See \"filter\" in linkgit:gitprotocol-pack[5].\n \n - Clients pass a \"filter-spec\" to clone and fetch which is passed to the\n server to request filtering during packfile construction.\ndiff --git a/command-list.txt b/command-list.txt\nindex 44e244a76f6..ed859fdd798 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -210,7 +210,6 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle developerinterfaces\n-gitformat-bundle developerinterfaces\n gitformat-commit-graph developerinterfaces\n gitglossary guide\n githooks userinterfaces\n@@ -219,6 +218,10 @@ gitk mainporcelain\n gitmailmap userinterfaces\n gitmodules userinterfaces\n gitnamespaces guide\n+gitprotocol-capabilities developerinterfaces\n+gitprotocol-common developerinterfaces\n+gitprotocol-pack developerinterfaces\n+gitprotocol-v2 developerinterfaces\n gitremote-helpers guide\n gitrepository-layout userinterfaces\n gitrevisions userinterfaces\ndiff --git a/refspec.h b/refspec.h\nindex 8b79891d321..8c0c4469933 100644\n--- a/refspec.h\n+++ b/refspec.h\n@@ -69,7 +69,7 @@ int valid_remote_name(const char *name);\n struct strvec;\n /*\n * Determine what values to pass to the peer in ref-prefix lines\n- * (see Documentation/technical/protocol-v2.txt).\n+ * (see linkgit:gitprotocol-v2[5]).\n */\n void refspec_ref_prefixes(const struct refspec *rs,\n \t\t\t struct strvec *ref_prefixes);\ndiff --git a/t/t5551-http-fetch-smart.sh b/t/t5551-http-fetch-smart.sh\nindex 245532df881..6a38294a476 100755\n--- a/t/t5551-http-fetch-smart.sh\n+++ b/t/t5551-http-fetch-smart.sh\n@@ -181,8 +181,8 @@ test_expect_success 'no-op half-auth fetch does not require a password' '\n \t# This is not possible with protocol v2, since both objects and refs\n \t# are obtained from the \"git-upload-pack\" path. A solution to this is\n \t# to teach the server and client to be able to inline ls-refs requests\n-\t# as an Extra Parameter (see pack-protocol.txt), so that \"info/refs\"\n-\t# can serve refs, just like it does in protocol v0.\n+\t# as an Extra Parameter (see \"git help gitformat-pack-protocol\"), so that\n+\t# \"info/refs\" can serve refs, just like it does in protocol v0.\n \tGIT_TEST_PROTOCOL_VERSION=0 git --git-dir=half-auth fetch &&\n \texpect_askpass none\n '\n-- \n2.37.1.1095.g64a1e8362fd\n\n"},{"id":"459650","messageId":"patch-v5-7.9-5b081e6637a-20220721T160721Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com","subject":"[PATCH v5 7/9] docs: move pack format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-21T16:13:56Z","receivedAt":"2022-07-21T16:15:46Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe various documentation pertaining to the *.pack format and related\nfiles, and updating things that refer to it to link to the new\nlocation.\n\nBy moving these we can properly link from the newly created\ngitformat-commit-graph do to a gitformat-chunk-format manpage we build\nby default.\n\nCreating a \"gitformat-pack-bitmap\" from\n\"Documentation/technical/bitmap-format\" might logically be part of\nthis change, but it's left out for now due to a conflict with the\nin-flight ac/bitmap-lookup-table series.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 9 ++---\n Documentation/config/pack.txt | 2 +-\n Documentation/git-bundle.txt | 3 +-\n Documentation/git-multi-pack-index.txt | 4 +--\n .../chunk-format.txt => gitformat-chunk.txt} | 25 +++++++++++---\n Documentation/gitformat-commit-graph.txt | 2 +-\n .../index-format.txt => gitformat-index.txt} | 22 ++++++++++--\n ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++++--\n .../pack-format.txt => gitformat-pack.txt} | 34 +++++++++++++++++--\n ...ure-format.txt => gitformat-signature.txt} | 21 ++++++++++--\n Documentation/gitprotocol-pack.txt | 2 +-\n .../howto/recover-corrupted-object-harder.txt | 2 +-\n .../technical/hash-function-transition.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n cache.h | 3 +-\n command-list.txt | 5 +++\n pack-revindex.h | 2 +-\n 17 files changed, 131 insertions(+), 31 deletions(-)\n rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (91%)\n rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)\n rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%)\n rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)\n rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex b53f3c12843..cd09ccd8c13 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -25,7 +25,12 @@ MAN1_TXT += gitweb.txt\n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n+MAN5_TXT += gitformat-chunk.txt\n MAN5_TXT += gitformat-commit-graph.txt\n+MAN5_TXT += gitformat-index.txt\n+MAN5_TXT += gitformat-pack-cruft.txt\n+MAN5_TXT += gitformat-pack.txt\n+MAN5_TXT += gitformat-signature.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -101,13 +106,10 @@ TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n-TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n-TECH_DOCS += technical/index-format\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n-TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\n@@ -115,7 +117,6 @@ TECH_DOCS += technical/racy-git\n TECH_DOCS += technical/reftable\n TECH_DOCS += technical/send-pack-pipeline\n TECH_DOCS += technical/shallow\n-TECH_DOCS += technical/signature-format\n TECH_DOCS += technical/trivial-merge\n SP_ARTICLES += $(TECH_DOCS)\n SP_ARTICLES += technical/api-index\ndiff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt\nindex ad7f73a1ead..3e581eab84a 100644\n--- a/Documentation/config/pack.txt\n+++ b/Documentation/config/pack.txt\n@@ -166,7 +166,7 @@ permuted into their appropriate location when writing a new bitmap.\n \n pack.writeReverseIndex::\n \tWhen true, git will write a corresponding .rev file (see:\n-\tlink:../technical/pack-format.html[Documentation/technical/pack-format.txt])\n+\tlinkgit:gitformat-pack[5])\n \tfor each new packfile that it writes in all places except for\n \tlinkgit:git-fast-import[1] and in the bulk checkin mechanism.\n \tDefaults to false.\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex f0b1282b918..6da61722431 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -57,8 +57,7 @@ size. That they're \"thin\" under the hood is merely noted here as a\n curiosity, and as a reference to other documentation.\n \n See linkgit:gitformat-bundle[5] for more details and the discussion of\n-\"thin pack\" in link:technical/pack-format.html[the pack format\n-documentation] for further details.\n+\"thin pack\" in linkgit:gitformat-pack[5] for further details.\n \n OPTIONS\n -------\ndiff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt\nindex c588fb91af1..a48c3d5ea63 100644\n--- a/Documentation/git-multi-pack-index.txt\n+++ b/Documentation/git-multi-pack-index.txt\n@@ -128,8 +128,8 @@ $ git multi-pack-index verify\n SEE ALSO\n --------\n See link:technical/multi-pack-index.html[The Multi-Pack-Index Design\n-Document] and link:technical/pack-format.html[The Multi-Pack-Index\n-Format] for more information on the multi-pack-index feature.\n+Document] and linkgit:gitformat-pack[5] for more information on the\n+multi-pack-index feature and its file format.\n \n \n GIT\ndiff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt\nsimilarity index 91%\nrename from Documentation/technical/chunk-format.txt\nrename to Documentation/gitformat-chunk.txt\nindex f36ce42f37c..57202ede273 100644\n--- a/Documentation/technical/chunk-format.txt\n+++ b/Documentation/gitformat-chunk.txt\n@@ -1,11 +1,24 @@\n-Chunk-based file formats\n-========================\n+gitformat-chunk(5)\n+==================\n+\n+NAME\n+----\n+gitformat-chunk - Chunk-based file formats\n+\n+SYNOPSIS\n+--------\n+\n+Used by linkgit:gitformat-commit-graph[5] and the \"MIDX\" format (see\n+the pack format documentation in linkgit:gitformat-pack[5]).\n+\n+DESCRIPTION\n+-----------\n \n Some file formats in Git use a common concept of \"chunks\" to describe\n sections of the file. This allows structured access to a large file by\n scanning a small \"table of contents\" for the remaining data. This common\n format is used by the `commit-graph` and `multi-pack-index` files. See\n-link:technical/pack-format.html[the `multi-pack-index` format] and\n+the `multi-pack-index` format in linkgit:gitformat-pack[5] and\n the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n how they use the chunks to describe structured data.\n \n@@ -113,4 +126,8 @@ for future formats:\n * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n in `midx.c` for how the chunk-format API is used to write and\n parse the multi-pack-index file format documented in\n- link:technical/pack-format.html[the multi-pack-index file format].\n+ the multi-pack-index file format section of linkgit:gitformat-pack[5].\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt\nindex 108dc2295c0..7324665716d 100644\n--- a/Documentation/gitformat-commit-graph.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -75,7 +75,7 @@ All multi-byte numbers are in network byte order.\n ID appears at most once.\n \n The CHUNK LOOKUP matches the table of contents from\n- link:technical/chunk-format.html[the chunk-based file format].\n+ the chunk-based file format, see linkgit:gitformat-chunk[5]\n \n The remaining data in the body is described one chunk at a time, and\n these chunks may be given in any order. Chunks are required unless\ndiff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt\nsimilarity index 98%\nrename from Documentation/technical/index-format.txt\nrename to Documentation/gitformat-index.txt\nindex 65da0daaa56..5f3ed10d2db 100644\n--- a/Documentation/technical/index-format.txt\n+++ b/Documentation/gitformat-index.txt\n@@ -1,5 +1,19 @@\n+gitformat-index(5)\n+==================\n+\n+NAME\n+----\n+gitformat-index - Git index format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/index\n+\n+DESCRIPTION\n+-----------\n+\n Git index format\n-================\n \n == The Git index file has the following format\n \n@@ -127,7 +141,7 @@ Git index format\n entry is encoded as if the path name for the previous entry is an\n empty string). At the beginning of an entry, an integer N in the\n variable width encoding (the same encoding as the offset is encoded\n- for OFS_DELTA pack entries; see pack-format.txt) is stored, followed\n+ for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed\n by a NUL-terminated string S. Removing N bytes from the end of the\n path name for the previous entry, and replacing it with the string S\n yields the path name for this entry.\n@@ -404,3 +418,7 @@ The remaining data of each directory block is grouped by type:\n with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,\n tools should avoid interacting with a sparse index unless they understand\n this extension.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/cruft-packs.txt b/Documentation/gitformat-pack-cruft.txt\nsimilarity index 96%\nrename from Documentation/technical/cruft-packs.txt\nrename to Documentation/gitformat-pack-cruft.txt\nindex d81f3a8982f..908f752bd84 100644\n--- a/Documentation/technical/cruft-packs.txt\n+++ b/Documentation/gitformat-pack-cruft.txt\n@@ -1,4 +1,17 @@\n-= Cruft packs\n+gitformat-pack-cruft(5)\n+=======================\n+\n+NAME\n+----\n+gitformat-pack-cruft - The cruft pack file format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/pack-*.mtimes\n+\n+DESCRIPTION\n+-----------\n \n The cruft packs feature offer an alternative to Git's traditional mechanism of\n removing unreachable objects. This document provides an overview of Git's\n@@ -10,10 +23,11 @@ same.\n To remove unreachable objects from your repository, Git offers `git repack -Ad`\n (see linkgit:git-repack[1]). Quoting from the documentation:\n \n-[quote]\n+----\n [...] unreachable objects in a previous pack become loose, unpacked objects,\n instead of being left in the old pack. [...] loose unreachable objects will be\n pruned according to normal expiry rules with the next 'git gc' invocation.\n+----\n \n Unreachable objects aren't removed immediately, since doing so could race with\n an incoming push which may reference an object which is about to be deleted.\n@@ -121,3 +135,7 @@ which aren't already stored in an earlier cruft pack) is significantly more\n complicated to construct, and so aren't pursued here. The obvious drawback to\n the current implementation is that the entire cruft pack must be re-written from\n scratch.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/pack-format.txt b/Documentation/gitformat-pack.txt\nsimilarity index 95%\nrename from Documentation/technical/pack-format.txt\nrename to Documentation/gitformat-pack.txt\nindex b520aa9c45b..546c99f8871 100644\n--- a/Documentation/technical/pack-format.txt\n+++ b/Documentation/gitformat-pack.txt\n@@ -1,5 +1,29 @@\n-Git pack format\n-===============\n+gitformat-pack(5)\n+=================\n+\n+NAME\n+----\n+gitformat-pack - Git pack format\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/pack-*.{pack,idx}\n+$GIT_DIR/objects/pack/pack-*.rev\n+$GIT_DIR/objects/pack/multi-pack-index\n+\n+DESCRIPTION\n+-----------\n+\n+The Git pack format is now Git stores most of its primary repository\n+data. Over the lietime af a repository loose objects (if any) and\n+smaller packs are consolidated into larger pack(s). See\n+linkgit:git-gc[1] and linkgit:git-pack-objects[1].\n+\n+The pack format is also used over-the-wire, see\n+e.g. linkgit:gitprotocol-v2[5], as well as being a part of\n+other container formats in the case of linkgit:gitformat-bundle[5].\n \n == Checksums and object IDs\n \n@@ -356,7 +380,7 @@ CHUNK LOOKUP:\n \t using the next chunk position if necessary.)\n \n \tThe CHUNK LOOKUP matches the table of contents from\n-\tlink:technical/chunk-format.html[the chunk-based file format].\n+\tthe chunk-based file format, see linkgit:gitformat-chunk[5].\n \n \tThe remaining data in the body is described one chunk at a time, and\n \tthese chunks may be given in any order. Chunks are required unless\n@@ -482,3 +506,7 @@ packs arranged in MIDX order (with the preferred pack coming first).\n \n The MIDX's reverse index is stored in the optional 'RIDX' chunk within\n the MIDX itself.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt\nsimilarity index 96%\nrename from Documentation/technical/signature-format.txt\nrename to Documentation/gitformat-signature.txt\nindex 166721be6f6..a249869fafa 100644\n--- a/Documentation/technical/signature-format.txt\n+++ b/Documentation/gitformat-signature.txt\n@@ -1,7 +1,18 @@\n-Git signature format\n-====================\n+gitformat-signature(5)\n+======================\n \n-== Overview\n+NAME\n+----\n+gitformat-signature - Git cryptographic signature formats\n+\n+SYNOPSIS\n+--------\n+[verse]\n+<[tag|commit] object header(s)>\n+\n+\n+DESCRIPTION\n+-----------\n \n Git uses cryptographic signatures in various places, currently objects (tags,\n commits, mergetags) and transactions (pushes). In every case, the command which\n@@ -200,3 +211,7 @@ Date: Wed Jun 15 09:13:29 2016 +0000\n # gpg: There is no indication that the signature belongs to the owner.\n # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.txt\nindex 8a4de6decd0..93b30b88450 100644\n--- a/Documentation/gitprotocol-pack.txt\n+++ b/Documentation/gitprotocol-pack.txt\n@@ -467,7 +467,7 @@ Now that the client and server have finished negotiation about what\n the minimal amount of data that needs to be sent to the client is, the server\n will construct and send the required data in packfile format.\n \n-See pack-format.txt for what the packfile itself actually looks like.\n+See linkgit:gitformat-pack[5] for what the packfile itself actually looks like.\n \n If 'side-band' or 'side-band-64k' capabilities have been specified by\n the client, the server will send the packfile data multiplexed.\ndiff --git a/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.txt\nindex 8994e2559ea..5efb4fe81ff 100644\n--- a/Documentation/howto/recover-corrupted-object-harder.txt\n+++ b/Documentation/howto/recover-corrupted-object-harder.txt\n@@ -68,7 +68,7 @@ Note that the \"object\" file isn't fit for feeding straight to zlib; it\n has the git packed object header, which is variable-length. We want to\n strip that off so we can start playing with the zlib data directly. You\n can either work your way through it manually (the format is described in\n-link:../technical/pack-format.html[Documentation/technical/pack-format.txt]),\n+linkgit:gitformat-pack[5]),\n or you can walk through it in a debugger. I did the latter, creating a\n valid pack like:\n \ndiff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt\nindex 260224b0331..e2ac36dd210 100644\n--- a/Documentation/technical/hash-function-transition.txt\n+++ b/Documentation/technical/hash-function-transition.txt\n@@ -205,7 +205,7 @@ SHA-1 content.\n Object storage\n ~~~~~~~~~~~~~~\n Loose objects use zlib compression and packed objects use the packed\n-format described in Documentation/technical/pack-format.txt, just like\n+format described in linkgit:gitformat-pack[5], just like\n today. The content that is compressed and stored uses SHA-256 content\n instead of SHA-1 content.\n \ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 865074bed4e..ca9decdd952 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -3133,7 +3133,7 @@ those \"loose\" objects.\n You can save space and make Git faster by moving these loose objects in\n to a \"pack file\", which stores a group of objects in an efficient\n compressed format; the details of how pack files are formatted can be\n-found in link:technical/pack-format.html[pack format].\n+found in link:gitformat-pack[5].\n \n To put the loose objects into a pack, just run git repack:\n \ndiff --git a/cache.h b/cache.h\nindex ac5ab4ef9d3..82755c7c0aa 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -475,8 +475,7 @@ extern struct index_state the_index;\n \n /*\n * Values in this enum (except those outside the 3 bit range) are part\n- * of pack file format. See Documentation/technical/pack-format.txt\n- * for more information.\n+ * of pack file format. See gitformat-pack(5) for more information.\n */\n enum object_type {\n \tOBJ_BAD = -1,\ndiff --git a/command-list.txt b/command-list.txt\nindex ed859fdd798..4f30a6c30c8 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -210,7 +210,12 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle developerinterfaces\n+gitformat-chunk developerinterfaces\n gitformat-commit-graph developerinterfaces\n+gitformat-index developerinterfaces\n+gitformat-pack developerinterfaces\n+gitformat-pack-cruft developerinterfaces\n+gitformat-signature developerinterfaces\n gitglossary guide\n githooks userinterfaces\n gitignore userinterfaces\ndiff --git a/pack-revindex.h b/pack-revindex.h\nindex 74f4eae668d..4974e75eb4d 100644\n--- a/pack-revindex.h\n+++ b/pack-revindex.h\n@@ -22,7 +22,7 @@\n *\n * - pack position refers to an object's position within a non-existent pack\n * described by the MIDX. The pack structure is described in\n- * Documentation/technical/pack-format.txt.\n+ * gitformat-pack(5).\n *\n * It is effectively a concatanation of all packs in the MIDX (ordered by\n * their numeric ID within the MIDX) in their original order within each\n-- \n2.37.1.1095.g64a1e8362fd\n\n"},{"id":"459651","messageId":"patch-v5-8.9-8f8214addfd-20220721T160721Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com","subject":"[PATCH v5 8/9] docs: move http-protocol docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-21T16:13:57Z","receivedAt":"2022-07-21T16:16:07Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe http-protocol.txt documentation over. I'm renaming it to\n\"protocol-http\" to be consistent with other things in the new\ngitformat-protocol-* namespace.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 2 +-\n Documentation/git-upload-pack.txt | 6 ++--\n ...http-protocol.txt => gitprotocol-http.txt} | 29 ++++++++++++++++---\n Documentation/gitprotocol-pack.txt | 2 +-\n Documentation/gitprotocol-v2.txt | 4 +--\n command-list.txt | 1 +\n 6 files changed, 33 insertions(+), 11 deletions(-)\n rename Documentation/{technical/http-protocol.txt => gitprotocol-http.txt} (98%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex cd09ccd8c13..6efac142e3e 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -37,6 +37,7 @@ MAN5_TXT += gitmailmap.txt\n MAN5_TXT += gitmodules.txt\n MAN5_TXT += gitprotocol-capabilities.txt\n MAN5_TXT += gitprotocol-common.txt\n+MAN5_TXT += gitprotocol-http.txt\n MAN5_TXT += gitprotocol-pack.txt\n MAN5_TXT += gitprotocol-v2.txt\n MAN5_TXT += gitrepository-layout.txt\n@@ -107,7 +108,6 @@ TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n TECH_DOCS += technical/hash-function-transition\n-TECH_DOCS += technical/http-protocol\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-heuristics\ndiff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt\nindex 3409e0d36d1..3f89d640772 100644\n--- a/Documentation/git-upload-pack.txt\n+++ b/Documentation/git-upload-pack.txt\n@@ -39,9 +39,9 @@ OPTIONS\n --http-backend-info-refs::\n \tUsed by linkgit:git-http-backend[1] to serve up\n \t`$GIT_URL/info/refs?service=git-upload-pack` requests. See\n-\t\"Smart Clients\" in link:technical/http-protocol.html[the HTTP\n-\ttransfer protocols] documentation and \"HTTP Transport\" in the\n-\tlinkgit:gitprotocol-v2[5] documentation. Also understood by\n+\t\"Smart Clients\" in linkgit:gitprotocol-http[5] and \"HTTP\n+\tTransport\" in in the linkgit:gitprotocol-v2[5]\n+\tdocumentation. Also understood by\n \tlinkgit:git-receive-pack[1].\n \n ::\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/gitprotocol-http.txt\nsimilarity index 98%\nrename from Documentation/technical/http-protocol.txt\nrename to Documentation/gitprotocol-http.txt\nindex 8bd672d55bb..ccc13f0a407 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/gitprotocol-http.txt\n@@ -1,5 +1,19 @@\n-HTTP transfer protocols\n-=======================\n+gitprotocol-http(5)\n+===================\n+\n+NAME\n+----\n+gitprotocol-http - Git HTTP-based protocols\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+\n+DESCRIPTION\n+-----------\n \n Git supports two HTTP based transfer protocols. A \"dumb\" protocol\n which requires only a standard HTTP server on the server end of the\n@@ -512,11 +526,18 @@ the id obtained through ref discovery as old_id.\n \n TODO: Document this further.\n \n-\n-References\n+REFERENCES\n ----------\n \n http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n+\n+SEE ALSO\n+--------\n+\n linkgit:gitprotocol-pack[5]\n linkgit:gitprotocol-capabilities[5]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.txt\nindex 93b30b88450..dd4108b7a3b 100644\n--- a/Documentation/gitprotocol-pack.txt\n+++ b/Documentation/gitprotocol-pack.txt\n@@ -17,7 +17,7 @@ Git supports transferring data in packfiles over the ssh://, git://, http:// and\n file:// transports. There exist two sets of protocols, one for pushing\n data from a client to a server and another for fetching data from a\n server to a client. The three transports (ssh, git, file) use the same\n-protocol to transfer data. http is documented in http-protocol.txt.\n+protocol to transfer data. http is documented in linkgit:gitprotocol-http[5].\n \n The processes invoked in the canonical Git implementation are 'upload-pack'\n on the server side and 'fetch-pack' on the client side for fetching data;\ndiff --git a/Documentation/gitprotocol-v2.txt b/Documentation/gitprotocol-v2.txt\nindex d6105e07408..c9c0f9160b2 100644\n--- a/Documentation/gitprotocol-v2.txt\n+++ b/Documentation/gitprotocol-v2.txt\n@@ -53,7 +53,7 @@ Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`. More information can be\n-found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the\n+found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the\n `GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n@@ -77,7 +77,7 @@ HTTP Transport\n ~~~~~~~~~~~~~~\n \n When using the http:// or https:// transport a client makes a \"smart\"\n-info/refs request as described in `http-protocol.txt` and requests that\n+info/refs request as described in linkgit:gitprotocol-http[5] and requests that\n v2 be used by supplying \"version=2\" in the `Git-Protocol` header.\n \n C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0\ndiff --git a/command-list.txt b/command-list.txt\nindex 4f30a6c30c8..e3a5d417792 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -225,6 +225,7 @@ gitmodules userinterfaces\n gitnamespaces guide\n gitprotocol-capabilities developerinterfaces\n gitprotocol-common developerinterfaces\n+gitprotocol-http developerinterfaces\n gitprotocol-pack developerinterfaces\n gitprotocol-v2 developerinterfaces\n gitremote-helpers guide\n-- \n2.37.1.1095.g64a1e8362fd\n\n"},{"id":"459652","messageId":"patch-v5-9.9-19601ac36a2-20220721T160721Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com","subject":"[PATCH v5 9/9] docs: move multi-pack-index docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-21T16:13:58Z","receivedAt":"2022-07-21T16:16:17Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe multi-pack-index documentation over.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 2 +-\n Documentation/git-multi-pack-index.txt | 4 ++--\n ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++++++++++++--\n Documentation/gitformat-pack.txt | 5 +++++\n command-list.txt | 1 +\n 5 files changed, 27 insertions(+), 5 deletions(-)\n rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 6efac142e3e..522d6011e7a 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -28,6 +28,7 @@ MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += gitformat-chunk.txt\n MAN5_TXT += gitformat-commit-graph.txt\n MAN5_TXT += gitformat-index.txt\n+MAN5_TXT += gitformat-multi-pack-index.txt\n MAN5_TXT += gitformat-pack-cruft.txt\n MAN5_TXT += gitformat-pack.txt\n MAN5_TXT += gitformat-signature.txt\n@@ -109,7 +110,6 @@ TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/long-running-process-protocol\n-TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-heuristics\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\ndiff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt\nindex a48c3d5ea63..0ffa8b852cd 100644\n--- a/Documentation/git-multi-pack-index.txt\n+++ b/Documentation/git-multi-pack-index.txt\n@@ -127,8 +127,8 @@ $ git multi-pack-index verify\n \n SEE ALSO\n --------\n-See link:technical/multi-pack-index.html[The Multi-Pack-Index Design\n-Document] and linkgit:gitformat-pack[5] for more information on the\n+See linkgit:git-multi-pack-index[1] and\n+linkgit:gitformat-multi-pack-index[5] for more information on the\n multi-pack-index feature and its file format.\n \n \ndiff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/gitformat-multi-pack-index.txt\nsimilarity index 94%\nrename from Documentation/technical/multi-pack-index.txt\nrename to Documentation/gitformat-multi-pack-index.txt\nindex f2221d2b441..3bca1e7b10d 100644\n--- a/Documentation/technical/multi-pack-index.txt\n+++ b/Documentation/gitformat-multi-pack-index.txt\n@@ -1,5 +1,17 @@\n-Multi-Pack-Index (MIDX) Design Notes\n-====================================\n+gitformat-multi-pack-index(5)\n+=============================\n+\n+NAME\n+----\n+gitformat-multi-pack-index - The multi-pack-index file format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/multi-pack-index\n+\n+DESCRIPTION\n+-----------\n \n The Git object directory contains a 'pack' directory containing\n packfiles (with suffix \".pack\") and pack-indexes (with suffix\n@@ -98,3 +110,7 @@ Related Links\n \n [2] https://lore.kernel.org/git/alpine.DEB.2.20.1803091557510.23109@alexmv-linux/\n Git Merge 2018 Contributor's summit notes (includes discussion of MIDX)\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt\nindex 546c99f8871..68328bada6b 100644\n--- a/Documentation/gitformat-pack.txt\n+++ b/Documentation/gitformat-pack.txt\n@@ -507,6 +507,11 @@ packs arranged in MIDX order (with the preferred pack coming first).\n The MIDX's reverse index is stored in the optional 'RIDX' chunk within\n the MIDX itself.\n \n+SEE ALSO\n+--------\n+\n+linkgit:gitformat-multi-pack-index[5]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/command-list.txt b/command-list.txt\nindex e3a5d417792..1215250c9ae 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -213,6 +213,7 @@ gitformat-bundle developerinterfaces\n gitformat-chunk developerinterfaces\n gitformat-commit-graph developerinterfaces\n gitformat-index developerinterfaces\n+gitformat-multi-pack-index developerinterfaces\n gitformat-pack developerinterfaces\n gitformat-pack-cruft developerinterfaces\n gitformat-signature developerinterfaces\n-- \n2.37.1.1095.g64a1e8362fd\n\n"},{"id":"459667","messageId":"CAPig+cQ99HD0d9wDS1=ESsDgucu_Dqk5YJGSYB9USUZ1odMP4Q@mail.gmail.com","threadId":"56715","inReplyTo":"patch-v5-4.9-a7310898866-20220721T160721Z-avarab@gmail.com","subject":"Re: [PATCH v5 4/9] git docs: add a category for file formats, protocols and interfaces","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2022-07-21T17:31:28Z","receivedAt":"2022-07-21T17:31:44Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"/On Thu, Jul 21, 2022 at 12:14 PM Ævar Arnfjörð Bjarmason\n wrote:\n> Create a new \"File formats, protocols and other developer interfaces\"\n> section in the main \"git help git\" manual page and start moving the\n> documentation that now lives in \"Documentation/technical/*.git\" over\n> to it. This compliments the newly added and adjacent \"Repository,\n> command and file interfaces\" section.\n\nnit: s/compliments/complements/\n\n> This makes the technical documentation more accessible and\n> discoverable. Before this we wouldn't install it by default, and had\n> no ability to build man page versions of them. The links to them from\n> our existing documentation link to the generated HTML version of these\n> docs.\n>\n> So let's start moving those over, starting with just the\n> \"bundle-format.txt\" documentation added in 7378ec90e1c (doc: describe\n> Git bundle format, 2020-02-07). We'll now have a new\n> gitformat-bundle(5) man page. Subsequent commits will move more git\n> internal format documentation over.\n>\n> Unfortunately the syntax of the current Documentation/technical/*.txt\n> is not the same (when it comes to section headings etc.) as our\n> Documentation/*.txt documentation, so change the relevant bits of\n> syntax as we're moving this over.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n"},{"id":"459678","messageId":"xmqqr12egwq0.fsf@gitster.g","threadId":"56715","inReplyTo":"cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com","subject":"Re: [PATCH v5 0/9] docs: create & use \"(user|developer) interfaces\" categories","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-21T18:13:43Z","receivedAt":"2022-07-21T18:13:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> See v3[1] for lofty goals. The changes since v4 are mainly to rename\n> the \"user formats\" and \"developer formats\" to \"user interfaces\" and\n> \"developer interfaces\".\n>\n> Now:\n>\n> \t$ ./git help --user-interfaces\n\nHopefully this is a much better choice of words. \"formats\" would\nhave had a very high chance of getting misunderstood and confusing\nreaders. The interaction with hooks (e.g. you stop the operation X\nthat asks the hook's decision by writing hooks/pre-X that exits with\nnon-zero status) would probably be much better understood if it is\ndescribed as \"interface\" than \"format\".\n\n> And for \"--developer-interfaces\" (I wondered about calling this --apis):\n\n\"api\" might be less misunderstanding-prone, but both should probably\nbe OK. Again, much better than calling it \"format\".\n\nThanks.\n\n\n"},{"id":"460116","messageId":"cover-v6-0.9-00000000000-20220728T164243Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com","subject":"[PATCH v6 0/9] docs: create & use \"(user|developer) interfaces\" categories","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-28T16:46:39Z","receivedAt":"2022-07-28T16:47:05Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"See the v5 for a general overview:\nhttps://lore.kernel.org/git/cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com/\n\nThis trivial v6 fixes a grammar error in a commit message pointed-out\nby Eric Sunshine, thanks Eric!\n\nÆvar Arnfjörð Bjarmason (9):\n help.c: BUG() out if \"help --guides\" can't remove \"git\" prefixes\n git help doc: use \"\" instead of \"\"\n git docs: add a category for user-facing file, repo and command UX\n git docs: add a category for file formats, protocols and interfaces\n docs: move commit-graph format docs to man section 5\n docs: move protocol-related docs to man section 5\n docs: move pack format docs to man section 5\n docs: move http-protocol docs to man section 5\n docs: move multi-pack-index docs to man section 5\n\n Documentation/Makefile | 26 +++++-----\n Documentation/config/lsrefs.txt | 2 +-\n Documentation/config/pack.txt | 2 +-\n Documentation/config/protocol.txt | 2 +-\n Documentation/git-bundle.txt | 13 +++--\n Documentation/git-commit-graph.txt | 5 ++\n Documentation/git-help.txt | 27 ++++++++--\n Documentation/git-multi-pack-index.txt | 6 +--\n Documentation/git-upload-pack.txt | 7 ++-\n Documentation/git.txt | 17 +++++++\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++---\n .../chunk-format.txt => gitformat-chunk.txt} | 29 ++++++++---\n ...-format.txt => gitformat-commit-graph.txt} | 49 +++++++++++++------\n .../index-format.txt => gitformat-index.txt} | 22 ++++++++-\n ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++-\n ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++-\n .../pack-format.txt => gitformat-pack.txt} | 39 +++++++++++++--\n ...ure-format.txt => gitformat-signature.txt} | 21 ++++++--\n ...ities.txt => gitprotocol-capabilities.txt} | 28 ++++++++---\n ...ocol-common.txt => gitprotocol-common.txt} | 23 ++++++++-\n ...http-protocol.txt => gitprotocol-http.txt} | 35 ++++++++++---\n ...pack-protocol.txt => gitprotocol-pack.txt} | 28 ++++++++---\n .../protocol-v2.txt => gitprotocol-v2.txt} | 27 +++++++---\n .../howto/recover-corrupted-object-harder.txt | 2 +-\n Documentation/lint-man-section-order.perl | 3 ++\n Documentation/technical/api-simple-ipc.txt | 2 +-\n .../technical/hash-function-transition.txt | 2 +-\n .../long-running-process-protocol.txt | 2 +-\n Documentation/technical/packfile-uri.txt | 2 +-\n Documentation/technical/partial-clone.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n Makefile | 1 +\n builtin/help.c | 20 +++++++-\n cache.h | 3 +-\n command-list.txt | 38 +++++++++++---\n help.c | 34 ++++++++++++-\n help.h | 2 +\n pack-revindex.h | 2 +-\n refspec.h | 2 +-\n t/t0012-help.sh | 14 +++++-\n t/t5551-http-fetch-smart.sh | 4 +-\n 41 files changed, 508 insertions(+), 123 deletions(-)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)\n rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (89%)\n rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (87%)\n rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)\n rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)\n rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%)\n rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)\n rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)\n rename Documentation/{technical/protocol-capabilities.txt => gitprotocol-capabilities.txt} (96%)\n rename Documentation/{technical/protocol-common.txt => gitprotocol-common.txt} (89%)\n rename Documentation/{technical/http-protocol.txt => gitprotocol-http.txt} (97%)\n rename Documentation/{technical/pack-protocol.txt => gitprotocol-pack.txt} (98%)\n rename Documentation/{technical/protocol-v2.txt => gitprotocol-v2.txt} (97%)\n\nRange-diff against v5:\n 1: b0bb29bb131 = 1: f3588319057 help.c: BUG() out if \"help --guides\" can't remove \"git\" prefixes\n 2: 2ec00f81552 = 2: 80322d44ea5 git help doc: use \"\" instead of \"\"\n 3: 31be7d01c50 = 3: 0d22eb645bd git docs: add a category for user-facing file, repo and command UX\n 4: a7310898866 ! 4: c25f8ec9bf5 git docs: add a category for file formats, protocols and interfaces\n @@ Commit message\n Create a new \"File formats, protocols and other developer interfaces\"\n section in the main \"git help git\" manual page and start moving the\n documentation that now lives in \"Documentation/technical/*.git\" over\n - to it. This compliments the newly added and adjacent \"Repository,\n + to it. This complements the newly added and adjacent \"Repository,\n command and file interfaces\" section.\n \n This makes the technical documentation more accessible and\n 5: 62f9020a72d = 5: 466dbd2a993 docs: move commit-graph format docs to man section 5\n 6: 019ec8cf73c = 6: 9a551b2d53a docs: move protocol-related docs to man section 5\n 7: 5b081e6637a = 7: 92be18b95d9 docs: move pack format docs to man section 5\n 8: 8f8214addfd = 8: a8a883ebf85 docs: move http-protocol docs to man section 5\n 9: 19601ac36a2 = 9: ecfda8c6770 docs: move multi-pack-index docs to man section 5\n-- \n2.37.1.1197.g7ed548b7807\n\n"},{"id":"460117","messageId":"patch-v6-1.9-f3588319057-20220728T164243Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v6-0.9-00000000000-20220728T164243Z-avarab@gmail.com","subject":"[PATCH v6 1/9] help.c: BUG() out if \"help --guides\" can't remove \"git\" prefixes","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-28T16:46:40Z","receivedAt":"2022-07-28T16:47:07Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Adjust code added in 929d9192828 (git docs: split \"User-facing file\nformats\" off from \"Guides\", 2021-06-04) to be more strict about the\nprefix trimming of the \"guides\" category.\n\nThere are no guides in the command-list.txt that don't start with\n\"git\", and we're unlikely to ever add any, if we do we can remove this\nBUG() invocation, but in the meantime this makes the intent more\nclear.\n\nWhile we're at it remove a stray newline that had been added after the\n\"return name;\" statement.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n help.c | 10 ++++++++--\n 1 file changed, 8 insertions(+), 2 deletions(-)\n\ndiff --git a/help.c b/help.c\nindex 41c41c2aa11..80d516abb0b 100644\n--- a/help.c\n+++ b/help.c\n@@ -44,13 +44,19 @@ static struct category_description main_categories[] = {\n static const char *drop_prefix(const char *name, uint32_t category)\n {\n \tconst char *new_name;\n+\tconst char *prefix;\n \n \tif (skip_prefix(name, \"git-\", &new_name))\n \t\treturn new_name;\n-\tif (category == CAT_guide && skip_prefix(name, \"git\", &new_name))\n+\tswitch (category) {\n+\tcase CAT_guide:\n+\t\tprefix = \"git\";\n+\t\tif (!skip_prefix(name, prefix, &new_name))\n+\t\t\tBUG(\"'%s' in category #%d should have '%s' prefix\",\n+\t\t\t name, category, prefix);\n \t\treturn new_name;\n+\t}\n \treturn name;\n-\n }\n \n static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask)\n-- \n2.37.1.1197.g7ed548b7807\n\n"},{"id":"460118","messageId":"patch-v6-2.9-80322d44ea5-20220728T164243Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v6-0.9-00000000000-20220728T164243Z-avarab@gmail.com","subject":"[PATCH v6 2/9] git help doc: use \"\" instead of \"\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-28T16:46:41Z","receivedAt":"2022-07-28T16:47:08Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Replace the use of \"\" originally introduced (as \"GUIDE\") in\na133737b809 (doc: include --guide option description for \"git help\",\n2013-04-02) with the more generic \"\". The \"\" placeholder is\nmore generic, and one we'll be able to use as we introduce new\ndocumentation categories.\n\nLet's also add \"\" to the \"git help -h\" output, when it was made\nto use parse_option() in in 41eb33bd0cb (help: use parseopt,\n2008-02-24).\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-help.txt | 8 ++++----\n builtin/help.c | 2 +-\n 2 files changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 239c68db457..bead763fd29 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -9,14 +9,14 @@ SYNOPSIS\n --------\n [verse]\n 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\n-'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n+'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n \n DESCRIPTION\n -----------\n \n-With no options and no '' or '' given, the synopsis of the 'git'\n+With no options and no '' or '' given, the synopsis of the 'git'\n command and a list of the most commonly used Git commands are printed\n on the standard output.\n \n@@ -26,8 +26,8 @@ printed on the standard output.\n If the option `--guides` or `-g` is given, a list of the\n Git concept guides is also printed on the standard output.\n \n-If a command, or a guide, is given, a manual page for that command or\n-guide is brought up. The 'man' program is used by default for this\n+If a command or other documentation is given, the relevant manual page\n+will be brought up. The 'man' program is used by default for this\n purpose, but this can be overridden by other options or configuration\n variables.\n \ndiff --git a/builtin/help.c b/builtin/help.c\nindex 222f994f863..dec82d1be27 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -81,7 +81,7 @@ static struct option builtin_help_options[] = {\n \n static const char * const builtin_help_usage[] = {\n \t\"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n-\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] []\"),\n+\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [|]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n \tNULL\n-- \n2.37.1.1197.g7ed548b7807\n\n"},{"id":"460119","messageId":"patch-v6-3.9-0d22eb645bd-20220728T164243Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v6-0.9-00000000000-20220728T164243Z-avarab@gmail.com","subject":"[PATCH v6 3/9] git docs: add a category for user-facing file, repo and command UX","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-28T16:46:42Z","receivedAt":"2022-07-28T16:47:11Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"Repository, command and file interfaces\" section in the\nmain \"git help git\" manual page. Move things that belong under this\nnew criteria from the generic \"Guides\" section.\n\nThe \"Guides\" section was added in f442f28a81b (git.txt: add list of\nguides, 2020-08-05). It makes sense to have e.g. \"giteveryday(7)\" and\n\"gitfaq(7)\" listed under \"Guides\".\n\nBut placing e.g. \"gitignore(5)\" in it is stretching the meaning of\nwhat a \"guide\" is, ideally that section should list things similar to\n\"giteveryday(7)\" and \"gitcore-tutorial(7)\".\n\nAn alternate name that was considered for this new section was \"User\nformats\", for consistency with the nomenclature used for man section 5\nin general. My man(1) lists it as \"File formats and conventions,\ne.g. /etc/passwd\".\n\nSo calling this \"git help --formats\" or \"git help --user-formats\"\nwould make sense for e.g. gitignore(5), but would be stretching it\nsomewhat for githooks(5), and would seem really suspect for the likes\nof gitcli(7).\n\nLet's instead pick a name that's closer to the generic term \"User\ninterface\", which is really what this documentation discusses: General\nuser-interface documentation that doesn't obviously belong elsewhere.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-help.txt | 14 ++++++++++++++\n Documentation/git.txt | 8 ++++++++\n Makefile | 1 +\n builtin/help.c | 9 +++++++++\n command-list.txt | 21 +++++++++++++--------\n help.c | 12 ++++++++++++\n help.h | 1 +\n t/t0012-help.sh | 12 +++++++++++-\n 9 files changed, 70 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 4f801f4e4c9..28eb940a9b8 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchingrepositories.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n+\tcmds-userinterfaces.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\n \ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex bead763fd29..4eb03bd6c38 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -12,6 +12,7 @@ SYNOPSIS\n 'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n+'git help' [--user-interfaces]\n \n DESCRIPTION\n -----------\n@@ -69,6 +70,19 @@ OPTIONS\n --guides::\n \tPrints a list of the Git concept guides on the standard output.\n \n+--user-interfaces::\n+\tPrints a list of the repository, command and file interfaces\n+\tdocumentation on the standard output.\n++\n+In-repository file interfaces such as `.git/info/exclude` are\n+documented here (see linkgit:gitrepository-layout[5]), as well as\n+in-tree configuration such as `.mailmap` (see linkgit:gitmailmap[5]).\n++\n+This section of the documentation also covers general or widespread\n+user-interface conventions (e.g. linkgit:gitcli[7]), and\n+pseudo-configuration such as the file-based `.git/hooks/*` interface\n+described in linkgit:githooks[5].\n+\n -i::\n --info::\n \tDisplay manual page for the command in the 'info' format. The\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 47a6095ff40..945a1ebd3b1 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -339,6 +339,14 @@ The following documentation pages are guides about Git concepts.\n \n include::cmds-guide.txt[]\n \n+Repository, command and file interfaces\n+---------------------------------------\n+\n+This documentation discusses repository and command interfaces which\n+users are expected to interact with directly. See `--user-formats` in\n+linkgit:git-help[1] for more details on the critera.\n+\n+include::cmds-userinterfaces.txt[]\n \n Configuration Mechanism\n -----------------------\ndiff --git a/Makefile b/Makefile\nindex 1624471badc..ea0ef7df734 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -3532,6 +3532,7 @@ check-docs::\n \t\tsed -e '1,/^### command list/d' \\\n \t\t -e '/^#/d' \\\n \t\t -e '/guide$$/d' \\\n+\t\t -e '/interfaces$$/d' \\\n \t\t -e 's/[ \t].*//' \\\n \t\t -e 's/^/listed /' command-list.txt; \\\n \t\t$(MAKE) -C Documentation print-man1 | \\\ndiff --git a/builtin/help.c b/builtin/help.c\nindex dec82d1be27..1ab1c8a0dd7 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -43,6 +43,7 @@ static enum help_action {\n \tHELP_ACTION_ALL = 1,\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n+\tHELP_ACTION_USER_INTERFACES,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -69,6 +70,9 @@ static struct option builtin_help_options[] = {\n \n \tOPT_CMDMODE('g', \"guides\", &cmd_mode, N_(\"print list of useful guides\"),\n \t\t HELP_ACTION_GUIDES),\n+\tOPT_CMDMODE(0, \"user-interfaces\", &cmd_mode,\n+\t\t N_(\"print list of user-facing repository, command and file interfaces\"),\n+\t\t HELP_ACTION_USER_INTERFACES),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -84,6 +88,7 @@ static const char * const builtin_help_usage[] = {\n \tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [|]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n+\t\"git help [--user-interfaces]\",\n \tNULL\n };\n \n@@ -654,6 +659,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\topt_mode_usage(argc, \"--config-for-completion\", help_format);\n \t\tlist_config_help(SHOW_CONFIG_VARS);\n \t\treturn 0;\n+\tcase HELP_ACTION_USER_INTERFACES:\n+\t\topt_mode_usage(argc, \"--user-interfaces\", help_format);\n+\t\tlist_user_interfaces_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n \t\t\t help_format);\ndiff --git a/command-list.txt b/command-list.txt\nindex 9bd6f3c48f4..1d45303e14c 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -43,6 +43,11 @@\n # specified here, which can only have \"guide\" attribute and nothing\n # else.\n #\n+# User-facing repository, command and file interfaces such as\n+# documentation for the .gitmodules, .mailmap etc. files lives in man\n+# sections 5 and 7. These entries can only have the \"userinterfaces\"\n+# attribute and nothing else.\n+#\n ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -192,8 +197,8 @@ git-verify-tag ancillaryinterrogators\n git-whatchanged ancillaryinterrogators complete\n git-worktree mainporcelain\n git-write-tree plumbingmanipulators\n-gitattributes guide\n-gitcli guide\n+gitattributes userinterfaces\n+gitcli userinterfaces\n gitcore-tutorial guide\n gitcredentials guide\n gitcvs-migration guide\n@@ -201,15 +206,15 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitglossary guide\n-githooks guide\n-gitignore guide\n+githooks userinterfaces\n+gitignore userinterfaces\n gitk mainporcelain\n-gitmailmap guide\n-gitmodules guide\n+gitmailmap userinterfaces\n+gitmodules userinterfaces\n gitnamespaces guide\n gitremote-helpers guide\n-gitrepository-layout guide\n-gitrevisions guide\n+gitrepository-layout userinterfaces\n+gitrevisions userinterfaces\n gitsubmodules guide\n gittutorial guide\n gittutorial-2 guide\ndiff --git a/help.c b/help.c\nindex 80d516abb0b..a2ceda1723d 100644\n--- a/help.c\n+++ b/help.c\n@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_plumbinginterrogators, N_(\"Low-level Commands / Interrogators\") },\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n+\t{ CAT_userinterfaces, N_(\"User-facing repository, command and file interfaces\") },\n \t{ 0, NULL }\n };\n \n@@ -50,6 +51,7 @@ static const char *drop_prefix(const char *name, uint32_t category)\n \t\treturn new_name;\n \tswitch (category) {\n \tcase CAT_guide:\n+\tcase CAT_userinterfaces:\n \t\tprefix = \"git\";\n \t\tif (!skip_prefix(name, prefix, &new_name))\n \t\t\tBUG(\"'%s' in category #%d should have '%s' prefix\",\n@@ -432,6 +434,16 @@ void list_guides_help(void)\n \tputchar('\\n');\n }\n \n+void list_user_interfaces_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_userinterfaces, N_(\"User-facing repository, command and file interfaces:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex 971a3ad855a..243104c27a7 100644\n--- a/help.h\n+++ b/help.h\n@@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num)\n void list_common_cmds_help(void);\n void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n+void list_user_interfaces_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex 6c33a436901..bee5ed12203 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -44,6 +44,8 @@ test_expect_success 'invalid usage' '\n \ttest_expect_code 129 git help -g add &&\n \ttest_expect_code 129 git help -a -g &&\n \n+\ttest_expect_code 129 git help --user-interfaces add &&\n+\n \ttest_expect_code 129 git help -g -c &&\n \ttest_expect_code 129 git help --config-for-completion add &&\n \ttest_expect_code 129 git help --config-sections-for-completion add\n@@ -104,9 +106,9 @@ test_expect_success 'git help' '\n \ttest_i18ngrep \"^ commit \" help.output &&\n \ttest_i18ngrep \"^ fetch \" help.output\n '\n+\n test_expect_success 'git help -g' '\n \tgit help -g >help.output &&\n-\ttest_i18ngrep \"^ attributes \" help.output &&\n \ttest_i18ngrep \"^ everyday \" help.output &&\n \ttest_i18ngrep \"^ tutorial \" help.output\n '\n@@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' '\n \ttest_cmp expect test-browser.log\n '\n \n+test_expect_success 'git help --user-interfaces' '\n+\tgit help --user-interfaces >help.output &&\n+\tgrep \"^ attributes \" help.output &&\n+\tgrep \"^ mailmap \" help.output\n+'\n+\n test_expect_success 'git help -c' '\n \tgit help -c >help.output &&\n \tcat >expect <<-\\EOF &&\n@@ -220,6 +228,8 @@ test_expect_success \"'git help -a' section spacing\" '\n \tLow-level Commands / Syncing Repositories\n \n \tLow-level Commands / Internal Helpers\n+\n+\tUser-facing repository, command and file interfaces\n \tEOF\n \ttest_cmp expect actual\n '\n-- \n2.37.1.1197.g7ed548b7807\n\n"},{"id":"460120","messageId":"patch-v6-4.9-c25f8ec9bf5-20220728T164243Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v6-0.9-00000000000-20220728T164243Z-avarab@gmail.com","subject":"[PATCH v6 4/9] git docs: add a category for file formats, protocols and interfaces","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-28T16:46:43Z","receivedAt":"2022-07-28T16:47:15Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"File formats, protocols and other developer interfaces\"\nsection in the main \"git help git\" manual page and start moving the\ndocumentation that now lives in \"Documentation/technical/*.git\" over\nto it. This complements the newly added and adjacent \"Repository,\ncommand and file interfaces\" section.\n\nThis makes the technical documentation more accessible and\ndiscoverable. Before this we wouldn't install it by default, and had\nno ability to build man page versions of them. The links to them from\nour existing documentation link to the generated HTML version of these\ndocs.\n\nSo let's start moving those over, starting with just the\n\"bundle-format.txt\" documentation added in 7378ec90e1c (doc: describe\nGit bundle format, 2020-02-07). We'll now have a new\ngitformat-bundle(5) man page. Subsequent commits will move more git\ninternal format documentation over.\n\nUnfortunately the syntax of the current Documentation/technical/*.txt\nis not the same (when it comes to section headings etc.) as our\nDocumentation/*.txt documentation, so change the relevant bits of\nsyntax as we're moving this over.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 3 +-\n Documentation/git-bundle.txt | 14 +++---\n Documentation/git-help.txt | 5 +++\n Documentation/git.txt | 9 ++++\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++---\n Documentation/lint-man-section-order.perl | 3 ++\n builtin/help.c | 9 ++++\n command-list.txt | 5 +++\n help.c | 12 +++++\n help.h | 1 +\n t/t0012-help.sh | 2 +\n 11 files changed, 94 insertions(+), 13 deletions(-)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 28eb940a9b8..1a4a545f44a 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -24,6 +24,7 @@ MAN1_TXT += gitweb.txt\n \n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n+MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -95,7 +96,6 @@ TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n-TECH_DOCS += technical/bundle-format\n TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchingrepositories.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n+\tcmds-developerinterfaces.txt \\\n \tcmds-userinterfaces.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 7685b570455..f0b1282b918 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -56,10 +56,9 @@ using \"thin packs\", bundles created using exclusions are smaller in\n size. That they're \"thin\" under the hood is merely noted here as a\n curiosity, and as a reference to other documentation.\n \n-See link:technical/bundle-format.html[the `bundle-format`\n-documentation] for more details and the discussion of \"thin pack\" in\n-link:technical/pack-format.html[the pack format documentation] for\n-further details.\n+See linkgit:gitformat-bundle[5] for more details and the discussion of\n+\"thin pack\" in link:technical/pack-format.html[the pack format\n+documentation] for further details.\n \n OPTIONS\n -------\n@@ -77,7 +76,7 @@ verify ::\n \tcommits exist and are fully linked in the current repository.\n \tThen, 'git bundle' prints a list of missing commits, if any.\n \tFinally, information about additional capabilities, such as \"object\n-\tfilter\", is printed. See \"Capabilities\" in link:technical/bundle-format.html\n+\tfilter\", is printed. See \"Capabilities\" in linkgit:gitformat-bundle[5]\n \tfor more information. The exit code is zero for success, but will\n \tbe nonzero if the bundle file is invalid.\n \n@@ -337,6 +336,11 @@ You can also see what references it offers:\n $ git ls-remote mybundle\n ----------------\n \n+FILE FORMAT\n+-----------\n+\n+See linkgit:gitformat-bundle[5].\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 4eb03bd6c38..2b0b5e390dc 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -13,6 +13,7 @@ SYNOPSIS\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n 'git help' [--user-interfaces]\n+'git help' [--developer-interfaces]\n \n DESCRIPTION\n -----------\n@@ -83,6 +84,10 @@ user-interface conventions (e.g. linkgit:gitcli[7]), and\n pseudo-configuration such as the file-based `.git/hooks/*` interface\n described in linkgit:githooks[5].\n \n+--developer-interfaces::\n+\tPrint list of file formats, protocols and other developer\n+\tinterfaces documentation on the standard output.\n+\n -i::\n --info::\n \tDisplay manual page for the command in the 'info' format. The\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 945a1ebd3b1..0ef7f5e4ece 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -348,6 +348,15 @@ linkgit:git-help[1] for more details on the critera.\n \n include::cmds-userinterfaces.txt[]\n \n+File formats, protocols and other developer interfaces\n+------------------------------------------------------\n+\n+This documentation discusses file formats, over-the-wire protocols and\n+other git developer interfaces. See `--developer-interfaces` in\n+linkgit:git-help[1].\n+\n+include::cmds-developerinterfaces.txt[]\n+\n Configuration Mechanism\n -----------------------\n \ndiff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt\nsimilarity index 79%\nrename from Documentation/technical/bundle-format.txt\nrename to Documentation/gitformat-bundle.txt\nindex b9be8644cf5..6a9d9e5bf6f 100644\n--- a/Documentation/technical/bundle-format.txt\n+++ b/Documentation/gitformat-bundle.txt\n@@ -1,11 +1,33 @@\n-= Git bundle v2 format\n+gitformat-bundle(5)\n+===================\n \n-The Git bundle format is a format that represents both refs and Git objects.\n+NAME\n+----\n+gitformat-bundle - The bundle file format\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+*.bundle\n+*.bdl\n+\n+DESCRIPTION\n+-----------\n+\n+The Git bundle format is a format that represents both refs and Git\n+objects. A bundle is a header in a format similar to\n+linkgit:git-show-ref[1] followed by a pack in *.pack format.\n \n-== Format\n+The format is created and read by the linkgit:git-bundle[1] command,\n+and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1].\n+\n+\n+FORMAT\n+------\n \n We will use ABNF notation to define the Git bundle format. See\n-protocol-common.txt for the details.\n+link:technical/protocol-common.html for the details.\n \n A v2 bundle looks like this:\n \n@@ -36,7 +58,9 @@ value = *(%01-09 / %0b-FF)\n pack = ... ; packfile\n ----\n \n-== Semantics\n+\n+SEMANTICS\n+---------\n \n A Git bundle consists of several parts.\n \n@@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id.\n This is a comment and it has no specific meaning. The writer of the bundle MAY\n put any string here. The reader of the bundle MUST ignore the comment.\n \n-=== Note on the shallow clone and a Git bundle\n+Note on the shallow clone and a Git bundle\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n Note that the prerequisites does not represent a shallow-clone boundary. The\n semantics of the prerequisites and the shallow-clone boundaries are different,\n and the Git bundle v2 format cannot represent a shallow clone repository.\n \n-== Capabilities\n+CAPABILITIES\n+------------\n \n Because there is no opportunity for negotiation, unknown capabilities cause 'git\n bundle' to abort.\n@@ -79,3 +105,7 @@ bundle' to abort.\n * `filter` specifies an object filter as in the `--filter` option in\n linkgit:git-rev-list[1]. The resulting pack-file must be marked as a\n `.promisor` pack-file after it is unbundled.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl\nindex 425377dfeb7..02408a0062f 100755\n--- a/Documentation/lint-man-section-order.perl\n+++ b/Documentation/lint-man-section-order.perl\n@@ -32,6 +32,9 @@\n \t\t'SEE ALSO' => {\n \t\t\torder => $order++,\n \t\t},\n+\t\t'FILE FORMAT' => {\n+\t\t\torder => $order++,\n+\t\t},\n \t\t'GIT' => {\n \t\t\trequired => 1,\n \t\t\torder => $order++,\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 1ab1c8a0dd7..09ac4289f13 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -44,6 +44,7 @@ static enum help_action {\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n \tHELP_ACTION_USER_INTERFACES,\n+\tHELP_ACTION_DEVELOPER_INTERFACES,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -73,6 +74,9 @@ static struct option builtin_help_options[] = {\n \tOPT_CMDMODE(0, \"user-interfaces\", &cmd_mode,\n \t\t N_(\"print list of user-facing repository, command and file interfaces\"),\n \t\t HELP_ACTION_USER_INTERFACES),\n+\tOPT_CMDMODE(0, \"developer-interfaces\", &cmd_mode,\n+\t\t N_(\"print list of file formats, protocols and other developer interfaces\"),\n+\t\t HELP_ACTION_DEVELOPER_INTERFACES),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -89,6 +93,7 @@ static const char * const builtin_help_usage[] = {\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n \t\"git help [--user-interfaces]\",\n+\t\"git help [--developer-interfaces]\",\n \tNULL\n };\n \n@@ -663,6 +668,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\topt_mode_usage(argc, \"--user-interfaces\", help_format);\n \t\tlist_user_interfaces_help();\n \t\treturn 0;\n+\tcase HELP_ACTION_DEVELOPER_INTERFACES:\n+\t\topt_mode_usage(argc, \"--developer-interfaces\", help_format);\n+\t\tlist_developer_interfaces_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n \t\t\t help_format);\ndiff --git a/command-list.txt b/command-list.txt\nindex 1d45303e14c..1950c4ccd9c 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -48,6 +48,10 @@\n # sections 5 and 7. These entries can only have the \"userinterfaces\"\n # attribute and nothing else.\n #\n+# Git's file formats and protocols, such as documentation for the\n+# *.bundle format lives in man section 5. These entries can only have\n+# the \"developerinterfaces\" attribute and nothing else.\n+#\n ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -205,6 +209,7 @@ gitcvs-migration guide\n gitdiffcore guide\n giteveryday guide\n gitfaq guide\n+gitformat-bundle developerinterfaces\n gitglossary guide\n githooks userinterfaces\n gitignore userinterfaces\ndiff --git a/help.c b/help.c\nindex a2ceda1723d..71f1c905d1c 100644\n--- a/help.c\n+++ b/help.c\n@@ -39,6 +39,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n \t{ CAT_userinterfaces, N_(\"User-facing repository, command and file interfaces\") },\n+\t{ CAT_developerinterfaces, N_(\"Developer-facing file file formats, protocols and interfaces\") },\n \t{ 0, NULL }\n };\n \n@@ -52,6 +53,7 @@ static const char *drop_prefix(const char *name, uint32_t category)\n \tswitch (category) {\n \tcase CAT_guide:\n \tcase CAT_userinterfaces:\n+\tcase CAT_developerinterfaces:\n \t\tprefix = \"git\";\n \t\tif (!skip_prefix(name, prefix, &new_name))\n \t\t\tBUG(\"'%s' in category #%d should have '%s' prefix\",\n@@ -444,6 +446,16 @@ void list_user_interfaces_help(void)\n \tputchar('\\n');\n }\n \n+void list_developer_interfaces_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_developerinterfaces, N_(\"File formats, protocols and other developer interfaces:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex 243104c27a7..af073a7a026 100644\n--- a/help.h\n+++ b/help.h\n@@ -23,6 +23,7 @@ void list_common_cmds_help(void);\n void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n void list_user_interfaces_help(void);\n+void list_developer_interfaces_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex bee5ed12203..4ed2f242eb2 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -230,6 +230,8 @@ test_expect_success \"'git help -a' section spacing\" '\n \tLow-level Commands / Internal Helpers\n \n \tUser-facing repository, command and file interfaces\n+\n+\tDeveloper-facing file file formats, protocols and interfaces\n \tEOF\n \ttest_cmp expect actual\n '\n-- \n2.37.1.1197.g7ed548b7807\n\n"},{"id":"460121","messageId":"patch-v6-5.9-466dbd2a993-20220728T164243Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v6-0.9-00000000000-20220728T164243Z-avarab@gmail.com","subject":"[PATCH v6 5/9] docs: move commit-graph format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-28T16:46:44Z","receivedAt":"2022-07-28T16:47:18Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space.\n\nBy moving the documentation for the commit-graph format into man\nsection 5 and the new \"developerinterfaces\" category. This change is\nsplit from subsequent commits due to the relatively large amount of\nASCIIDOC formatting changes that are required.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-commit-graph.txt | 5 ++\n ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------\n Documentation/technical/chunk-format.txt | 4 +-\n command-list.txt | 2 +\n 5 files changed, 42 insertions(+), 17 deletions(-)\n rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (88%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 1a4a545f44a..e7bd72bb84e 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -25,6 +25,7 @@ MAN1_TXT += gitweb.txt\n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n+MAN5_TXT += gitformat-commit-graph.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex e1f48c95b3c..047decdb65b 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append\n ------------------------------------------------\n \n \n+FILE FORMAT\n+-----------\n+\n+see linkgit:gitformat-commit-graph[5].\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt\nsimilarity index 88%\nrename from Documentation/technical/commit-graph-format.txt\nrename to Documentation/gitformat-commit-graph.txt\nindex 484b185ba98..108dc2295c0 100644\n--- a/Documentation/technical/commit-graph-format.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -1,5 +1,18 @@\n-Git commit graph format\n-=======================\n+gitformat-commit-graph(5)\n+=========================\n+\n+NAME\n+----\n+gitformat-commit-graph - Git commit graph format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/info/commit-graph\n+$GIT_DIR/objects/info/commit-graphs/*\n+\n+DESCRIPTION\n+-----------\n \n The Git commit graph stores a list of commit OIDs and some associated\n metadata, including:\n@@ -30,7 +43,7 @@ and hash type.\n \n All multi-byte numbers are in network byte order.\n \n-HEADER:\n+=== HEADER:\n \n 4-byte signature:\n The signature is: {'C', 'G', 'P', 'H'}\n@@ -52,7 +65,7 @@ HEADER:\n We infer the length (H*B) of the Base Graphs chunk\n from this value.\n \n-CHUNK LOOKUP:\n+=== CHUNK LOOKUP:\n \n (C + 1) * 12 bytes listing the table of contents for the chunks:\n First 4 bytes describe the chunk id. Value 0 is a terminating label.\n@@ -68,17 +81,17 @@ CHUNK LOOKUP:\n these chunks may be given in any order. Chunks are required unless\n otherwise specified.\n \n-CHUNK DATA:\n+=== CHUNK DATA:\n \n- OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n+==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n The ith entry, F[i], stores the number of OIDs with first\n byte at most i. Thus F[255] stores the total\n number of commits (N).\n \n- OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n+==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n The OIDs for all commits in the graph, sorted in ascending order.\n \n- Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n+==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n * The first H bytes are for the OID of the root tree.\n * The next 8 bytes are for the positions of the first two parents\n of the ith commit. Stores value 0x70000000 if no parent in that\n@@ -93,7 +106,7 @@ CHUNK DATA:\n 2 bits of the lowest byte, storing the 33rd and 34th bit of the\n commit time.\n \n- Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n+==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n * This list of 4-byte values store corrected commit date offsets for the\n commits, arranged in the same order as commit data chunk.\n * If the corrected commit date offset cannot be stored within 31 bits,\n@@ -104,7 +117,7 @@ CHUNK DATA:\n by compatible versions of Git and in case of split commit-graph chains,\n the topmost layer also has Generation Data chunk.\n \n- Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n+==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n * This list of 8-byte values stores the corrected commit date offsets\n for commits with corrected commit date offsets that cannot be\n stored within 31 bits.\n@@ -112,7 +125,7 @@ CHUNK DATA:\n chunk is present and atleast one corrected commit date offset cannot\n be stored within 31 bits.\n \n- Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n+==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n This list of 4-byte values store the second through nth parents for\n all octopus merges. The second parent value in the commit data stores\n an array position within this list along with the most-significant bit\n@@ -120,14 +133,14 @@ CHUNK DATA:\n positions for the parents until reaching a value with the most-significant\n bit on. The other bits correspond to the position of the last parent.\n \n- Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n+==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters\n from commit 0 to commit i (inclusive) in lexicographic order. The Bloom\n filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header\n length), where BIDX[-1] is 0.\n * The BIDX chunk is ignored if the BDAT chunk is not present.\n \n- Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n+==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n * It starts with header consisting of three unsigned 32-bit integers:\n - Version of the hash algorithm being used. We currently only support\n \tvalue 1 which corresponds to the 32-bit version of the murmur3 hash\n@@ -147,13 +160,13 @@ CHUNK DATA:\n of length one, with either all bits set to zero or one respectively.\n * The BDAT chunk is present if and only if BIDX is present.\n \n- Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n+==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n This list of H-byte hashes describe a set of B commit-graph files that\n form a commit-graph chain. The graph position for the ith commit in this\n file's OID Lookup chunk is equal to i plus the number of commits in all\n base graphs. If B is non-zero, this chunk must exist.\n \n-TRAILER:\n+=== TRAILER:\n \n \tH-byte HASH-checksum of all of the above.\n \n@@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote\n possibly erroneous data in these chunks with the IDs \"GDAT\" and \"GDOV\". By\n changing the IDs, newer versions of Git will silently ignore those older\n chunks and write the new information without trusting the incorrect data.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/chunk-format.txt b/Documentation/technical/chunk-format.txt\nindex 593614fceda..f36ce42f37c 100644\n--- a/Documentation/technical/chunk-format.txt\n+++ b/Documentation/technical/chunk-format.txt\n@@ -6,7 +6,7 @@ sections of the file. This allows structured access to a large file by\n scanning a small \"table of contents\" for the remaining data. This common\n format is used by the `commit-graph` and `multi-pack-index` files. See\n link:technical/pack-format.html[the `multi-pack-index` format] and\n-link:technical/commit-graph-format.html[the `commit-graph` format] for\n+the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n how they use the chunks to describe structured data.\n \n A chunk-based file format begins with some header information custom to\n@@ -108,7 +108,7 @@ for future formats:\n * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()`\n in `commit-graph.c` for how the chunk-format API is used to write and\n parse the commit-graph file format documented in\n- link:technical/commit-graph-format.html[the commit-graph file format].\n+ the commit-graph file format in linkgit:gitformat-commit-graph[5].\n \n * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n in `midx.c` for how the chunk-format API is used to write and\ndiff --git a/command-list.txt b/command-list.txt\nindex 1950c4ccd9c..44e244a76f6 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -210,6 +210,8 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle developerinterfaces\n+gitformat-bundle developerinterfaces\n+gitformat-commit-graph developerinterfaces\n gitglossary guide\n githooks userinterfaces\n gitignore userinterfaces\n-- \n2.37.1.1197.g7ed548b7807\n\n"},{"id":"460122","messageId":"patch-v6-6.9-9a551b2d53a-20220728T164243Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v6-0.9-00000000000-20220728T164243Z-avarab@gmail.com","subject":"[PATCH v6 6/9] docs: move protocol-related docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-28T16:46:45Z","receivedAt":"2022-07-28T16:47:20Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space. By moving\nthe things that discuss the protocol we can properly link from\ne.g. lsrefs.unborn and protocol.version documentation to a manpage we\nbuild by default.\n\nSo far we have been using the \"gitformat-\" prefix for the\ndocumentation we've been moving over from Documentation/technical/*,\nbut for protocol documentation let's use \"gitprotocol-*\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 8 +++---\n Documentation/config/lsrefs.txt | 2 +-\n Documentation/config/protocol.txt | 2 +-\n Documentation/git-upload-pack.txt | 5 ++--\n Documentation/gitformat-bundle.txt | 2 +-\n ...ities.txt => gitprotocol-capabilities.txt} | 28 +++++++++++++++----\n ...ocol-common.txt => gitprotocol-common.txt} | 23 +++++++++++++--\n ...pack-protocol.txt => gitprotocol-pack.txt} | 24 +++++++++++++---\n .../protocol-v2.txt => gitprotocol-v2.txt} | 25 +++++++++++++----\n Documentation/technical/api-simple-ipc.txt | 2 +-\n Documentation/technical/http-protocol.txt | 6 ++--\n .../long-running-process-protocol.txt | 2 +-\n Documentation/technical/packfile-uri.txt | 2 +-\n Documentation/technical/partial-clone.txt | 2 +-\n command-list.txt | 5 +++-\n refspec.h | 2 +-\n t/t5551-http-fetch-smart.sh | 4 +--\n 17 files changed, 106 insertions(+), 38 deletions(-)\n rename Documentation/{technical/protocol-capabilities.txt => gitprotocol-capabilities.txt} (96%)\n rename Documentation/{technical/protocol-common.txt => gitprotocol-common.txt} (89%)\n rename Documentation/{technical/pack-protocol.txt => gitprotocol-pack.txt} (98%)\n rename Documentation/{technical/protocol-v2.txt => gitprotocol-v2.txt} (98%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex e7bd72bb84e..b53f3c12843 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -30,6 +30,10 @@ MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n MAN5_TXT += gitmodules.txt\n+MAN5_TXT += gitprotocol-capabilities.txt\n+MAN5_TXT += gitprotocol-common.txt\n+MAN5_TXT += gitprotocol-pack.txt\n+MAN5_TXT += gitprotocol-v2.txt\n MAN5_TXT += gitrepository-layout.txt\n MAN5_TXT += gitweb.conf.txt\n \n@@ -105,12 +109,8 @@ TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n-TECH_DOCS += technical/pack-protocol\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\n-TECH_DOCS += technical/protocol-capabilities\n-TECH_DOCS += technical/protocol-common\n-TECH_DOCS += technical/protocol-v2\n TECH_DOCS += technical/racy-git\n TECH_DOCS += technical/reftable\n TECH_DOCS += technical/send-pack-pipeline\ndiff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.txt\nindex adeda0f24d3..3d88fb0badb 100644\n--- a/Documentation/config/lsrefs.txt\n+++ b/Documentation/config/lsrefs.txt\n@@ -1,7 +1,7 @@\n lsrefs.unborn::\n \tMay be \"advertise\" (the default), \"allow\", or \"ignore\". If \"advertise\",\n \tthe server will respond to the client sending \"unborn\" (as described in\n-\tprotocol-v2.txt) and will advertise support for this feature during the\n+\tlinkgit:gitprotocol-v2[5]) and will advertise support for this feature during the\n \tprotocol v2 capability advertisement. \"allow\" is the same as\n \t\"advertise\" except that the server will not advertise support for this\n \tfeature; this is useful for load-balanced servers that cannot be\ndiff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt\nindex 756591d77b0..57603818514 100644\n--- a/Documentation/config/protocol.txt\n+++ b/Documentation/config/protocol.txt\n@@ -58,6 +58,6 @@ protocol.version::\n * `1` - the original wire protocol with the addition of a version string\n in the initial response from the server.\n \n-* `2` - link:technical/protocol-v2.html[wire protocol version 2].\n+* `2` - Wire protocol version 2, see linkgit:gitprotocol-v2[5].\n \n --\ndiff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt\nindex 8f87b23ea86..3409e0d36d1 100644\n--- a/Documentation/git-upload-pack.txt\n+++ b/Documentation/git-upload-pack.txt\n@@ -40,9 +40,8 @@ OPTIONS\n \tUsed by linkgit:git-http-backend[1] to serve up\n \t`$GIT_URL/info/refs?service=git-upload-pack` requests. See\n \t\"Smart Clients\" in link:technical/http-protocol.html[the HTTP\n-\ttransfer protocols] documentation and \"HTTP Transport\" in\n-\tlink:technical/protocol-v2.html[the Git Wire Protocol, Version\n-\t2] documentation. Also understood by\n+\ttransfer protocols] documentation and \"HTTP Transport\" in the\n+\tlinkgit:gitprotocol-v2[5] documentation. Also understood by\n \tlinkgit:git-receive-pack[1].\n \n ::\ndiff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.txt\nindex 6a9d9e5bf6f..00e0a20e657 100644\n--- a/Documentation/gitformat-bundle.txt\n+++ b/Documentation/gitformat-bundle.txt\n@@ -27,7 +27,7 @@ FORMAT\n ------\n \n We will use ABNF notation to define the Git bundle format. See\n-link:technical/protocol-common.html for the details.\n+linkgit:gitprotocol-common[5] for the details.\n \n A v2 bundle looks like this:\n \ndiff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/gitprotocol-capabilities.txt\nsimilarity index 96%\nrename from Documentation/technical/protocol-capabilities.txt\nrename to Documentation/gitprotocol-capabilities.txt\nindex 9dfade930da..c6dcc7d565d 100644\n--- a/Documentation/technical/protocol-capabilities.txt\n+++ b/Documentation/gitprotocol-capabilities.txt\n@@ -1,8 +1,20 @@\n-Git Protocol Capabilities\n-=========================\n+gitprotocol-capabilities(5)\n+===========================\n+\n+NAME\n+----\n+gitprotocol-capabilities - Protocol v0 and v1 capabilities\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n NOTE: this document describes capabilities for versions 0 and 1 of the pack\n-protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]\n+protocol. For version 2, please refer to the linkgit:gitprotocol-v2[5]\n doc.\n \n Servers SHOULD support all capabilities defined in this document.\n@@ -77,7 +89,7 @@ interleaved with S-R-Q.\n multi_ack_detailed\n ------------------\n This is an extension of multi_ack that permits client to better\n-understand the server's in-memory state. See pack-protocol.txt,\n+understand the server's in-memory state. See linkgit:gitprotocol-pack[5],\n section \"Packfile Negotiation\" for more information.\n \n no-done\n@@ -281,7 +293,7 @@ a packfile upload and reference update. If the pushing client requests\n this capability, after unpacking and updating references the server\n will respond with whether the packfile unpacked successfully and if\n each reference was updated successfully. If any of those were not\n-successful, it will send back an error message. See pack-protocol.txt\n+successful, it will send back an error message. See linkgit:gitprotocol-pack[5]\n for example messages.\n \n report-status-v2\n@@ -292,7 +304,7 @@ adding new \"option\" directives in order to support reference rewritten by\n the \"proc-receive\" hook. The \"proc-receive\" hook may handle a command\n for a pseudo-reference which may create or update a reference with\n different name, new-oid, and old-oid. While the capability\n-'report-status' cannot report for such case. See pack-protocol.txt\n+'report-status' cannot report for such case. See linkgit:gitprotocol-pack[5]\n for details.\n \n delete-refs\n@@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The\n current implementation uses trace2 session IDs (see\n link:api-trace2.html[api-trace2] for details), but this may change and users of\n the session ID should not rely on this fact.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-common.txt b/Documentation/gitprotocol-common.txt\nsimilarity index 89%\nrename from Documentation/technical/protocol-common.txt\nrename to Documentation/gitprotocol-common.txt\nindex ecedb34bba5..1486651bd10 100644\n--- a/Documentation/technical/protocol-common.txt\n+++ b/Documentation/gitprotocol-common.txt\n@@ -1,5 +1,20 @@\n-Documentation Common to Pack and Http Protocols\n-===============================================\n+gitprotocol-common(5)\n+=====================\n+\n+NAME\n+----\n+gitprotocol-common - Things common to various protocols\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n+\n+This document sets defines things common to various over-the-wire\n+protocols and file formats used in Git.\n \n ABNF Notation\n -------------\n@@ -97,3 +112,7 @@ Examples (as C-style strings):\n \"000bfoobar\\n\" \"foobar\\n\"\n \"0004\" \"\"\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitprotocol-pack.txt\nsimilarity index 98%\nrename from Documentation/technical/pack-protocol.txt\nrename to Documentation/gitprotocol-pack.txt\nindex e13a2c064d1..8a4de6decd0 100644\n--- a/Documentation/technical/pack-protocol.txt\n+++ b/Documentation/gitprotocol-pack.txt\n@@ -1,5 +1,17 @@\n-Packfile transfer protocols\n-===========================\n+gitprotocol-pack(5)\n+===================\n+\n+NAME\n+----\n+gitprotocol-pack - How packs are transferred over-the-wire\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n Git supports transferring data in packfiles over the ssh://, git://, http:// and\n file:// transports. There exist two sets of protocols, one for pushing\n@@ -18,7 +30,7 @@ pkt-line Format\n ---------------\n \n The descriptions below build on the pkt-line format described in\n-protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless\n+linkgit:gitprotocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless\n otherwise noted the usual pkt-line LF rules apply: the sender SHOULD\n include a LF, but the receiver MUST NOT complain if it is not present.\n \n@@ -60,7 +72,7 @@ Each Extra Parameter takes the form of `=` or ``.\n \n Servers that receive any such Extra Parameters MUST ignore all\n unrecognized keys. Currently, the only Extra Parameter recognized is\n-\"version\" with a value of '1' or '2'. See protocol-v2.txt for more\n+\"version\" with a value of '1' or '2'. See linkgit:gitprotocol-v2[5] for more\n information on protocol version 2.\n \n Git Transport\n@@ -707,3 +719,7 @@ An example client/server communication might look like this:\n S: 0018ok refs/heads/debug\\n\n S: 002ang refs/heads/master non-fast-forward\\n\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-v2.txt b/Documentation/gitprotocol-v2.txt\nsimilarity index 98%\nrename from Documentation/technical/protocol-v2.txt\nrename to Documentation/gitprotocol-v2.txt\nindex 8a877d27e23..d6105e07408 100644\n--- a/Documentation/technical/protocol-v2.txt\n+++ b/Documentation/gitprotocol-v2.txt\n@@ -1,5 +1,17 @@\n-Git Wire Protocol, Version 2\n-============================\n+gitprotocol-v2(5)\n+=================\n+\n+NAME\n+----\n+gitprotocol-v2 - Git Wire Protocol, Version 2\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n This document presents a specification for a version 2 of Git's wire\n protocol. Protocol v2 will improve upon v1 in the following ways:\n@@ -26,8 +38,7 @@ Packet-Line Framing\n -------------------\n \n All communication is done using packet-line framing, just as in v1. See\n-`Documentation/technical/pack-protocol.txt` and\n-`Documentation/technical/protocol-common.txt` for more information.\n+linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-common[5] for more information.\n \n In protocol v2 these special packets will have the following semantics:\n \n@@ -42,7 +53,7 @@ Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`. More information can be\n-found in `pack-protocol.txt` and `http-protocol.txt`, as well as the\n+found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the\n `GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n@@ -566,3 +577,7 @@ and associated requested information, each separated by a single space.\n \tattr = \"size\"\n \n \tobj-info = obj-id SP obj-size\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt\nindex d79ad323e67..d44ada98e7d 100644\n--- a/Documentation/technical/api-simple-ipc.txt\n+++ b/Documentation/technical/api-simple-ipc.txt\n@@ -78,7 +78,7 @@ client and an optional response message from the server. Both the\n client and server messages are unlimited in length and are terminated\n with a flush packet.\n \n-The pkt-line routines (Documentation/technical/protocol-common.txt)\n+The pkt-line routines (linkgit:gitprotocol-common[5])\n are used to simplify buffer management during message generation,\n transmission, and reception. A flush packet is used to mark the end\n of the message. This allows the sender to incrementally generate and\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt\nindex cc5126cfeda..8bd672d55bb 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/technical/http-protocol.txt\n@@ -222,7 +222,7 @@ smart server reply:\n S: 0000\n \n The client may send Extra Parameters (see\n-Documentation/technical/pack-protocol.txt) as a colon-separated string\n+linkgit:gitprotocol-pack[5]) as a colon-separated string\n in the Git-Protocol HTTP header.\n \n Uses the `--http-backend-info-refs` option to\n@@ -518,5 +518,5 @@ References\n \n http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n-link:technical/pack-protocol.html\n-link:technical/protocol-capabilities.html\n+linkgit:gitprotocol-pack[5]\n+linkgit:gitprotocol-capabilities[5]\ndiff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt\nindex aa0aa9af1c2..6f33654b428 100644\n--- a/Documentation/technical/long-running-process-protocol.txt\n+++ b/Documentation/technical/long-running-process-protocol.txt\n@@ -3,7 +3,7 @@ Long-running process protocol\n \n This protocol is used when Git needs to communicate with an external\n process throughout the entire life of a single Git command. All\n-communication is in pkt-line format (see technical/protocol-common.txt)\n+communication is in pkt-line format (see linkgit:gitprotocol-common[5])\n over standard input and standard output.\n \n Handshake\ndiff --git a/Documentation/technical/packfile-uri.txt b/Documentation/technical/packfile-uri.txt\nindex 1eb525fe760..9d453d47651 100644\n--- a/Documentation/technical/packfile-uri.txt\n+++ b/Documentation/technical/packfile-uri.txt\n@@ -18,7 +18,7 @@ a `packfile-uris` argument, the server MAY send a `packfile-uris` section\n directly before the `packfile` section (right after `wanted-refs` if it is\n sent) containing URIs of any of the given protocols. The URIs point to\n packfiles that use only features that the client has declared that it supports\n-(e.g. ofs-delta and thin-pack). See protocol-v2.txt for the documentation of\n+(e.g. ofs-delta and thin-pack). See linkgit:gitprotocol-v2[5] for the documentation of\n this section.\n \n Clients should then download and index all the given URIs (in addition to\ndiff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt\nindex 99f0eb30406..92fcee2bfff 100644\n--- a/Documentation/technical/partial-clone.txt\n+++ b/Documentation/technical/partial-clone.txt\n@@ -79,7 +79,7 @@ Design Details\n upload-pack negotiation.\n +\n This uses the existing capability discovery mechanism.\n-See \"filter\" in Documentation/technical/pack-protocol.txt.\n+See \"filter\" in linkgit:gitprotocol-pack[5].\n \n - Clients pass a \"filter-spec\" to clone and fetch which is passed to the\n server to request filtering during packfile construction.\ndiff --git a/command-list.txt b/command-list.txt\nindex 44e244a76f6..ed859fdd798 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -210,7 +210,6 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle developerinterfaces\n-gitformat-bundle developerinterfaces\n gitformat-commit-graph developerinterfaces\n gitglossary guide\n githooks userinterfaces\n@@ -219,6 +218,10 @@ gitk mainporcelain\n gitmailmap userinterfaces\n gitmodules userinterfaces\n gitnamespaces guide\n+gitprotocol-capabilities developerinterfaces\n+gitprotocol-common developerinterfaces\n+gitprotocol-pack developerinterfaces\n+gitprotocol-v2 developerinterfaces\n gitremote-helpers guide\n gitrepository-layout userinterfaces\n gitrevisions userinterfaces\ndiff --git a/refspec.h b/refspec.h\nindex 8b79891d321..8c0c4469933 100644\n--- a/refspec.h\n+++ b/refspec.h\n@@ -69,7 +69,7 @@ int valid_remote_name(const char *name);\n struct strvec;\n /*\n * Determine what values to pass to the peer in ref-prefix lines\n- * (see Documentation/technical/protocol-v2.txt).\n+ * (see linkgit:gitprotocol-v2[5]).\n */\n void refspec_ref_prefixes(const struct refspec *rs,\n \t\t\t struct strvec *ref_prefixes);\ndiff --git a/t/t5551-http-fetch-smart.sh b/t/t5551-http-fetch-smart.sh\nindex 245532df881..6a38294a476 100755\n--- a/t/t5551-http-fetch-smart.sh\n+++ b/t/t5551-http-fetch-smart.sh\n@@ -181,8 +181,8 @@ test_expect_success 'no-op half-auth fetch does not require a password' '\n \t# This is not possible with protocol v2, since both objects and refs\n \t# are obtained from the \"git-upload-pack\" path. A solution to this is\n \t# to teach the server and client to be able to inline ls-refs requests\n-\t# as an Extra Parameter (see pack-protocol.txt), so that \"info/refs\"\n-\t# can serve refs, just like it does in protocol v0.\n+\t# as an Extra Parameter (see \"git help gitformat-pack-protocol\"), so that\n+\t# \"info/refs\" can serve refs, just like it does in protocol v0.\n \tGIT_TEST_PROTOCOL_VERSION=0 git --git-dir=half-auth fetch &&\n \texpect_askpass none\n '\n-- \n2.37.1.1197.g7ed548b7807\n\n"},{"id":"460123","messageId":"patch-v6-7.9-92be18b95d9-20220728T164243Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v6-0.9-00000000000-20220728T164243Z-avarab@gmail.com","subject":"[PATCH v6 7/9] docs: move pack format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-28T16:46:46Z","receivedAt":"2022-07-28T16:47:21Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe various documentation pertaining to the *.pack format and related\nfiles, and updating things that refer to it to link to the new\nlocation.\n\nBy moving these we can properly link from the newly created\ngitformat-commit-graph do to a gitformat-chunk-format manpage we build\nby default.\n\nCreating a \"gitformat-pack-bitmap\" from\n\"Documentation/technical/bitmap-format\" might logically be part of\nthis change, but it's left out for now due to a conflict with the\nin-flight ac/bitmap-lookup-table series.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 9 ++---\n Documentation/config/pack.txt | 2 +-\n Documentation/git-bundle.txt | 3 +-\n Documentation/git-multi-pack-index.txt | 4 +--\n .../chunk-format.txt => gitformat-chunk.txt} | 25 +++++++++++---\n Documentation/gitformat-commit-graph.txt | 2 +-\n .../index-format.txt => gitformat-index.txt} | 22 ++++++++++--\n ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++++--\n .../pack-format.txt => gitformat-pack.txt} | 34 +++++++++++++++++--\n ...ure-format.txt => gitformat-signature.txt} | 21 ++++++++++--\n Documentation/gitprotocol-pack.txt | 2 +-\n .../howto/recover-corrupted-object-harder.txt | 2 +-\n .../technical/hash-function-transition.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n cache.h | 3 +-\n command-list.txt | 5 +++\n pack-revindex.h | 2 +-\n 17 files changed, 131 insertions(+), 31 deletions(-)\n rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (91%)\n rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)\n rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%)\n rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)\n rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex b53f3c12843..cd09ccd8c13 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -25,7 +25,12 @@ MAN1_TXT += gitweb.txt\n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n+MAN5_TXT += gitformat-chunk.txt\n MAN5_TXT += gitformat-commit-graph.txt\n+MAN5_TXT += gitformat-index.txt\n+MAN5_TXT += gitformat-pack-cruft.txt\n+MAN5_TXT += gitformat-pack.txt\n+MAN5_TXT += gitformat-signature.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -101,13 +106,10 @@ TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n-TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n-TECH_DOCS += technical/index-format\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n-TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\n@@ -115,7 +117,6 @@ TECH_DOCS += technical/racy-git\n TECH_DOCS += technical/reftable\n TECH_DOCS += technical/send-pack-pipeline\n TECH_DOCS += technical/shallow\n-TECH_DOCS += technical/signature-format\n TECH_DOCS += technical/trivial-merge\n SP_ARTICLES += $(TECH_DOCS)\n SP_ARTICLES += technical/api-index\ndiff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt\nindex ad7f73a1ead..3e581eab84a 100644\n--- a/Documentation/config/pack.txt\n+++ b/Documentation/config/pack.txt\n@@ -166,7 +166,7 @@ permuted into their appropriate location when writing a new bitmap.\n \n pack.writeReverseIndex::\n \tWhen true, git will write a corresponding .rev file (see:\n-\tlink:../technical/pack-format.html[Documentation/technical/pack-format.txt])\n+\tlinkgit:gitformat-pack[5])\n \tfor each new packfile that it writes in all places except for\n \tlinkgit:git-fast-import[1] and in the bulk checkin mechanism.\n \tDefaults to false.\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex f0b1282b918..6da61722431 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -57,8 +57,7 @@ size. That they're \"thin\" under the hood is merely noted here as a\n curiosity, and as a reference to other documentation.\n \n See linkgit:gitformat-bundle[5] for more details and the discussion of\n-\"thin pack\" in link:technical/pack-format.html[the pack format\n-documentation] for further details.\n+\"thin pack\" in linkgit:gitformat-pack[5] for further details.\n \n OPTIONS\n -------\ndiff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt\nindex c588fb91af1..a48c3d5ea63 100644\n--- a/Documentation/git-multi-pack-index.txt\n+++ b/Documentation/git-multi-pack-index.txt\n@@ -128,8 +128,8 @@ $ git multi-pack-index verify\n SEE ALSO\n --------\n See link:technical/multi-pack-index.html[The Multi-Pack-Index Design\n-Document] and link:technical/pack-format.html[The Multi-Pack-Index\n-Format] for more information on the multi-pack-index feature.\n+Document] and linkgit:gitformat-pack[5] for more information on the\n+multi-pack-index feature and its file format.\n \n \n GIT\ndiff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt\nsimilarity index 91%\nrename from Documentation/technical/chunk-format.txt\nrename to Documentation/gitformat-chunk.txt\nindex f36ce42f37c..57202ede273 100644\n--- a/Documentation/technical/chunk-format.txt\n+++ b/Documentation/gitformat-chunk.txt\n@@ -1,11 +1,24 @@\n-Chunk-based file formats\n-========================\n+gitformat-chunk(5)\n+==================\n+\n+NAME\n+----\n+gitformat-chunk - Chunk-based file formats\n+\n+SYNOPSIS\n+--------\n+\n+Used by linkgit:gitformat-commit-graph[5] and the \"MIDX\" format (see\n+the pack format documentation in linkgit:gitformat-pack[5]).\n+\n+DESCRIPTION\n+-----------\n \n Some file formats in Git use a common concept of \"chunks\" to describe\n sections of the file. This allows structured access to a large file by\n scanning a small \"table of contents\" for the remaining data. This common\n format is used by the `commit-graph` and `multi-pack-index` files. See\n-link:technical/pack-format.html[the `multi-pack-index` format] and\n+the `multi-pack-index` format in linkgit:gitformat-pack[5] and\n the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n how they use the chunks to describe structured data.\n \n@@ -113,4 +126,8 @@ for future formats:\n * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n in `midx.c` for how the chunk-format API is used to write and\n parse the multi-pack-index file format documented in\n- link:technical/pack-format.html[the multi-pack-index file format].\n+ the multi-pack-index file format section of linkgit:gitformat-pack[5].\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt\nindex 108dc2295c0..7324665716d 100644\n--- a/Documentation/gitformat-commit-graph.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -75,7 +75,7 @@ All multi-byte numbers are in network byte order.\n ID appears at most once.\n \n The CHUNK LOOKUP matches the table of contents from\n- link:technical/chunk-format.html[the chunk-based file format].\n+ the chunk-based file format, see linkgit:gitformat-chunk[5]\n \n The remaining data in the body is described one chunk at a time, and\n these chunks may be given in any order. Chunks are required unless\ndiff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt\nsimilarity index 98%\nrename from Documentation/technical/index-format.txt\nrename to Documentation/gitformat-index.txt\nindex f691c20ab0a..015cb21bdc0 100644\n--- a/Documentation/technical/index-format.txt\n+++ b/Documentation/gitformat-index.txt\n@@ -1,5 +1,19 @@\n+gitformat-index(5)\n+==================\n+\n+NAME\n+----\n+gitformat-index - Git index format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/index\n+\n+DESCRIPTION\n+-----------\n+\n Git index format\n-================\n \n == The Git index file has the following format\n \n@@ -125,7 +139,7 @@ Git index format\n entry is encoded as if the path name for the previous entry is an\n empty string). At the beginning of an entry, an integer N in the\n variable width encoding (the same encoding as the offset is encoded\n- for OFS_DELTA pack entries; see pack-format.txt) is stored, followed\n+ for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed\n by a NUL-terminated string S. Removing N bytes from the end of the\n path name for the previous entry, and replacing it with the string S\n yields the path name for this entry.\n@@ -402,3 +416,7 @@ The remaining data of each directory block is grouped by type:\n with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,\n tools should avoid interacting with a sparse index unless they understand\n this extension.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/cruft-packs.txt b/Documentation/gitformat-pack-cruft.txt\nsimilarity index 96%\nrename from Documentation/technical/cruft-packs.txt\nrename to Documentation/gitformat-pack-cruft.txt\nindex d81f3a8982f..908f752bd84 100644\n--- a/Documentation/technical/cruft-packs.txt\n+++ b/Documentation/gitformat-pack-cruft.txt\n@@ -1,4 +1,17 @@\n-= Cruft packs\n+gitformat-pack-cruft(5)\n+=======================\n+\n+NAME\n+----\n+gitformat-pack-cruft - The cruft pack file format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/pack-*.mtimes\n+\n+DESCRIPTION\n+-----------\n \n The cruft packs feature offer an alternative to Git's traditional mechanism of\n removing unreachable objects. This document provides an overview of Git's\n@@ -10,10 +23,11 @@ same.\n To remove unreachable objects from your repository, Git offers `git repack -Ad`\n (see linkgit:git-repack[1]). Quoting from the documentation:\n \n-[quote]\n+----\n [...] unreachable objects in a previous pack become loose, unpacked objects,\n instead of being left in the old pack. [...] loose unreachable objects will be\n pruned according to normal expiry rules with the next 'git gc' invocation.\n+----\n \n Unreachable objects aren't removed immediately, since doing so could race with\n an incoming push which may reference an object which is about to be deleted.\n@@ -121,3 +135,7 @@ which aren't already stored in an earlier cruft pack) is significantly more\n complicated to construct, and so aren't pursued here. The obvious drawback to\n the current implementation is that the entire cruft pack must be re-written from\n scratch.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/pack-format.txt b/Documentation/gitformat-pack.txt\nsimilarity index 95%\nrename from Documentation/technical/pack-format.txt\nrename to Documentation/gitformat-pack.txt\nindex b520aa9c45b..546c99f8871 100644\n--- a/Documentation/technical/pack-format.txt\n+++ b/Documentation/gitformat-pack.txt\n@@ -1,5 +1,29 @@\n-Git pack format\n-===============\n+gitformat-pack(5)\n+=================\n+\n+NAME\n+----\n+gitformat-pack - Git pack format\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/pack-*.{pack,idx}\n+$GIT_DIR/objects/pack/pack-*.rev\n+$GIT_DIR/objects/pack/multi-pack-index\n+\n+DESCRIPTION\n+-----------\n+\n+The Git pack format is now Git stores most of its primary repository\n+data. Over the lietime af a repository loose objects (if any) and\n+smaller packs are consolidated into larger pack(s). See\n+linkgit:git-gc[1] and linkgit:git-pack-objects[1].\n+\n+The pack format is also used over-the-wire, see\n+e.g. linkgit:gitprotocol-v2[5], as well as being a part of\n+other container formats in the case of linkgit:gitformat-bundle[5].\n \n == Checksums and object IDs\n \n@@ -356,7 +380,7 @@ CHUNK LOOKUP:\n \t using the next chunk position if necessary.)\n \n \tThe CHUNK LOOKUP matches the table of contents from\n-\tlink:technical/chunk-format.html[the chunk-based file format].\n+\tthe chunk-based file format, see linkgit:gitformat-chunk[5].\n \n \tThe remaining data in the body is described one chunk at a time, and\n \tthese chunks may be given in any order. Chunks are required unless\n@@ -482,3 +506,7 @@ packs arranged in MIDX order (with the preferred pack coming first).\n \n The MIDX's reverse index is stored in the optional 'RIDX' chunk within\n the MIDX itself.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt\nsimilarity index 96%\nrename from Documentation/technical/signature-format.txt\nrename to Documentation/gitformat-signature.txt\nindex 166721be6f6..a249869fafa 100644\n--- a/Documentation/technical/signature-format.txt\n+++ b/Documentation/gitformat-signature.txt\n@@ -1,7 +1,18 @@\n-Git signature format\n-====================\n+gitformat-signature(5)\n+======================\n \n-== Overview\n+NAME\n+----\n+gitformat-signature - Git cryptographic signature formats\n+\n+SYNOPSIS\n+--------\n+[verse]\n+<[tag|commit] object header(s)>\n+\n+\n+DESCRIPTION\n+-----------\n \n Git uses cryptographic signatures in various places, currently objects (tags,\n commits, mergetags) and transactions (pushes). In every case, the command which\n@@ -200,3 +211,7 @@ Date: Wed Jun 15 09:13:29 2016 +0000\n # gpg: There is no indication that the signature belongs to the owner.\n # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.txt\nindex 8a4de6decd0..93b30b88450 100644\n--- a/Documentation/gitprotocol-pack.txt\n+++ b/Documentation/gitprotocol-pack.txt\n@@ -467,7 +467,7 @@ Now that the client and server have finished negotiation about what\n the minimal amount of data that needs to be sent to the client is, the server\n will construct and send the required data in packfile format.\n \n-See pack-format.txt for what the packfile itself actually looks like.\n+See linkgit:gitformat-pack[5] for what the packfile itself actually looks like.\n \n If 'side-band' or 'side-band-64k' capabilities have been specified by\n the client, the server will send the packfile data multiplexed.\ndiff --git a/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.txt\nindex 8994e2559ea..5efb4fe81ff 100644\n--- a/Documentation/howto/recover-corrupted-object-harder.txt\n+++ b/Documentation/howto/recover-corrupted-object-harder.txt\n@@ -68,7 +68,7 @@ Note that the \"object\" file isn't fit for feeding straight to zlib; it\n has the git packed object header, which is variable-length. We want to\n strip that off so we can start playing with the zlib data directly. You\n can either work your way through it manually (the format is described in\n-link:../technical/pack-format.html[Documentation/technical/pack-format.txt]),\n+linkgit:gitformat-pack[5]),\n or you can walk through it in a debugger. I did the latter, creating a\n valid pack like:\n \ndiff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt\nindex 260224b0331..e2ac36dd210 100644\n--- a/Documentation/technical/hash-function-transition.txt\n+++ b/Documentation/technical/hash-function-transition.txt\n@@ -205,7 +205,7 @@ SHA-1 content.\n Object storage\n ~~~~~~~~~~~~~~\n Loose objects use zlib compression and packed objects use the packed\n-format described in Documentation/technical/pack-format.txt, just like\n+format described in linkgit:gitformat-pack[5], just like\n today. The content that is compressed and stored uses SHA-256 content\n instead of SHA-1 content.\n \ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 865074bed4e..ca9decdd952 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -3133,7 +3133,7 @@ those \"loose\" objects.\n You can save space and make Git faster by moving these loose objects in\n to a \"pack file\", which stores a group of objects in an efficient\n compressed format; the details of how pack files are formatted can be\n-found in link:technical/pack-format.html[pack format].\n+found in link:gitformat-pack[5].\n \n To put the loose objects into a pack, just run git repack:\n \ndiff --git a/cache.h b/cache.h\nindex ac5ab4ef9d3..82755c7c0aa 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -475,8 +475,7 @@ extern struct index_state the_index;\n \n /*\n * Values in this enum (except those outside the 3 bit range) are part\n- * of pack file format. See Documentation/technical/pack-format.txt\n- * for more information.\n+ * of pack file format. See gitformat-pack(5) for more information.\n */\n enum object_type {\n \tOBJ_BAD = -1,\ndiff --git a/command-list.txt b/command-list.txt\nindex ed859fdd798..4f30a6c30c8 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -210,7 +210,12 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle developerinterfaces\n+gitformat-chunk developerinterfaces\n gitformat-commit-graph developerinterfaces\n+gitformat-index developerinterfaces\n+gitformat-pack developerinterfaces\n+gitformat-pack-cruft developerinterfaces\n+gitformat-signature developerinterfaces\n gitglossary guide\n githooks userinterfaces\n gitignore userinterfaces\ndiff --git a/pack-revindex.h b/pack-revindex.h\nindex 74f4eae668d..4974e75eb4d 100644\n--- a/pack-revindex.h\n+++ b/pack-revindex.h\n@@ -22,7 +22,7 @@\n *\n * - pack position refers to an object's position within a non-existent pack\n * described by the MIDX. The pack structure is described in\n- * Documentation/technical/pack-format.txt.\n+ * gitformat-pack(5).\n *\n * It is effectively a concatanation of all packs in the MIDX (ordered by\n * their numeric ID within the MIDX) in their original order within each\n-- \n2.37.1.1197.g7ed548b7807\n\n"},{"id":"460124","messageId":"patch-v6-8.9-a8a883ebf85-20220728T164243Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v6-0.9-00000000000-20220728T164243Z-avarab@gmail.com","subject":"[PATCH v6 8/9] docs: move http-protocol docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-28T16:46:47Z","receivedAt":"2022-07-28T16:47:57Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe http-protocol.txt documentation over. I'm renaming it to\n\"protocol-http\" to be consistent with other things in the new\ngitformat-protocol-* namespace.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 2 +-\n Documentation/git-upload-pack.txt | 6 ++--\n ...http-protocol.txt => gitprotocol-http.txt} | 29 ++++++++++++++++---\n Documentation/gitprotocol-pack.txt | 2 +-\n Documentation/gitprotocol-v2.txt | 4 +--\n command-list.txt | 1 +\n 6 files changed, 33 insertions(+), 11 deletions(-)\n rename Documentation/{technical/http-protocol.txt => gitprotocol-http.txt} (98%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex cd09ccd8c13..6efac142e3e 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -37,6 +37,7 @@ MAN5_TXT += gitmailmap.txt\n MAN5_TXT += gitmodules.txt\n MAN5_TXT += gitprotocol-capabilities.txt\n MAN5_TXT += gitprotocol-common.txt\n+MAN5_TXT += gitprotocol-http.txt\n MAN5_TXT += gitprotocol-pack.txt\n MAN5_TXT += gitprotocol-v2.txt\n MAN5_TXT += gitrepository-layout.txt\n@@ -107,7 +108,6 @@ TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n TECH_DOCS += technical/hash-function-transition\n-TECH_DOCS += technical/http-protocol\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-heuristics\ndiff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt\nindex 3409e0d36d1..3f89d640772 100644\n--- a/Documentation/git-upload-pack.txt\n+++ b/Documentation/git-upload-pack.txt\n@@ -39,9 +39,9 @@ OPTIONS\n --http-backend-info-refs::\n \tUsed by linkgit:git-http-backend[1] to serve up\n \t`$GIT_URL/info/refs?service=git-upload-pack` requests. See\n-\t\"Smart Clients\" in link:technical/http-protocol.html[the HTTP\n-\ttransfer protocols] documentation and \"HTTP Transport\" in the\n-\tlinkgit:gitprotocol-v2[5] documentation. Also understood by\n+\t\"Smart Clients\" in linkgit:gitprotocol-http[5] and \"HTTP\n+\tTransport\" in in the linkgit:gitprotocol-v2[5]\n+\tdocumentation. Also understood by\n \tlinkgit:git-receive-pack[1].\n \n ::\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/gitprotocol-http.txt\nsimilarity index 98%\nrename from Documentation/technical/http-protocol.txt\nrename to Documentation/gitprotocol-http.txt\nindex 8bd672d55bb..ccc13f0a407 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/gitprotocol-http.txt\n@@ -1,5 +1,19 @@\n-HTTP transfer protocols\n-=======================\n+gitprotocol-http(5)\n+===================\n+\n+NAME\n+----\n+gitprotocol-http - Git HTTP-based protocols\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+\n+DESCRIPTION\n+-----------\n \n Git supports two HTTP based transfer protocols. A \"dumb\" protocol\n which requires only a standard HTTP server on the server end of the\n@@ -512,11 +526,18 @@ the id obtained through ref discovery as old_id.\n \n TODO: Document this further.\n \n-\n-References\n+REFERENCES\n ----------\n \n http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n+\n+SEE ALSO\n+--------\n+\n linkgit:gitprotocol-pack[5]\n linkgit:gitprotocol-capabilities[5]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.txt\nindex 93b30b88450..dd4108b7a3b 100644\n--- a/Documentation/gitprotocol-pack.txt\n+++ b/Documentation/gitprotocol-pack.txt\n@@ -17,7 +17,7 @@ Git supports transferring data in packfiles over the ssh://, git://, http:// and\n file:// transports. There exist two sets of protocols, one for pushing\n data from a client to a server and another for fetching data from a\n server to a client. The three transports (ssh, git, file) use the same\n-protocol to transfer data. http is documented in http-protocol.txt.\n+protocol to transfer data. http is documented in linkgit:gitprotocol-http[5].\n \n The processes invoked in the canonical Git implementation are 'upload-pack'\n on the server side and 'fetch-pack' on the client side for fetching data;\ndiff --git a/Documentation/gitprotocol-v2.txt b/Documentation/gitprotocol-v2.txt\nindex d6105e07408..c9c0f9160b2 100644\n--- a/Documentation/gitprotocol-v2.txt\n+++ b/Documentation/gitprotocol-v2.txt\n@@ -53,7 +53,7 @@ Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`. More information can be\n-found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the\n+found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the\n `GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n@@ -77,7 +77,7 @@ HTTP Transport\n ~~~~~~~~~~~~~~\n \n When using the http:// or https:// transport a client makes a \"smart\"\n-info/refs request as described in `http-protocol.txt` and requests that\n+info/refs request as described in linkgit:gitprotocol-http[5] and requests that\n v2 be used by supplying \"version=2\" in the `Git-Protocol` header.\n \n C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0\ndiff --git a/command-list.txt b/command-list.txt\nindex 4f30a6c30c8..e3a5d417792 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -225,6 +225,7 @@ gitmodules userinterfaces\n gitnamespaces guide\n gitprotocol-capabilities developerinterfaces\n gitprotocol-common developerinterfaces\n+gitprotocol-http developerinterfaces\n gitprotocol-pack developerinterfaces\n gitprotocol-v2 developerinterfaces\n gitremote-helpers guide\n-- \n2.37.1.1197.g7ed548b7807\n\n"},{"id":"460125","messageId":"patch-v6-9.9-ecfda8c6770-20220728T164243Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v6-0.9-00000000000-20220728T164243Z-avarab@gmail.com","subject":"[PATCH v6 9/9] docs: move multi-pack-index docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-28T16:46:48Z","receivedAt":"2022-07-28T16:48:02Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe multi-pack-index documentation over.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 2 +-\n Documentation/git-multi-pack-index.txt | 4 ++--\n ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++++++++++++--\n Documentation/gitformat-pack.txt | 5 +++++\n command-list.txt | 1 +\n 5 files changed, 27 insertions(+), 5 deletions(-)\n rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 6efac142e3e..522d6011e7a 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -28,6 +28,7 @@ MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += gitformat-chunk.txt\n MAN5_TXT += gitformat-commit-graph.txt\n MAN5_TXT += gitformat-index.txt\n+MAN5_TXT += gitformat-multi-pack-index.txt\n MAN5_TXT += gitformat-pack-cruft.txt\n MAN5_TXT += gitformat-pack.txt\n MAN5_TXT += gitformat-signature.txt\n@@ -109,7 +110,6 @@ TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/long-running-process-protocol\n-TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-heuristics\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\ndiff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt\nindex a48c3d5ea63..0ffa8b852cd 100644\n--- a/Documentation/git-multi-pack-index.txt\n+++ b/Documentation/git-multi-pack-index.txt\n@@ -127,8 +127,8 @@ $ git multi-pack-index verify\n \n SEE ALSO\n --------\n-See link:technical/multi-pack-index.html[The Multi-Pack-Index Design\n-Document] and linkgit:gitformat-pack[5] for more information on the\n+See linkgit:git-multi-pack-index[1] and\n+linkgit:gitformat-multi-pack-index[5] for more information on the\n multi-pack-index feature and its file format.\n \n \ndiff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/gitformat-multi-pack-index.txt\nsimilarity index 94%\nrename from Documentation/technical/multi-pack-index.txt\nrename to Documentation/gitformat-multi-pack-index.txt\nindex f2221d2b441..3bca1e7b10d 100644\n--- a/Documentation/technical/multi-pack-index.txt\n+++ b/Documentation/gitformat-multi-pack-index.txt\n@@ -1,5 +1,17 @@\n-Multi-Pack-Index (MIDX) Design Notes\n-====================================\n+gitformat-multi-pack-index(5)\n+=============================\n+\n+NAME\n+----\n+gitformat-multi-pack-index - The multi-pack-index file format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/multi-pack-index\n+\n+DESCRIPTION\n+-----------\n \n The Git object directory contains a 'pack' directory containing\n packfiles (with suffix \".pack\") and pack-indexes (with suffix\n@@ -98,3 +110,7 @@ Related Links\n \n [2] https://lore.kernel.org/git/alpine.DEB.2.20.1803091557510.23109@alexmv-linux/\n Git Merge 2018 Contributor's summit notes (includes discussion of MIDX)\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt\nindex 546c99f8871..68328bada6b 100644\n--- a/Documentation/gitformat-pack.txt\n+++ b/Documentation/gitformat-pack.txt\n@@ -507,6 +507,11 @@ packs arranged in MIDX order (with the preferred pack coming first).\n The MIDX's reverse index is stored in the optional 'RIDX' chunk within\n the MIDX itself.\n \n+SEE ALSO\n+--------\n+\n+linkgit:gitformat-multi-pack-index[5]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/command-list.txt b/command-list.txt\nindex e3a5d417792..1215250c9ae 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -213,6 +213,7 @@ gitformat-bundle developerinterfaces\n gitformat-chunk developerinterfaces\n gitformat-commit-graph developerinterfaces\n gitformat-index developerinterfaces\n+gitformat-multi-pack-index developerinterfaces\n gitformat-pack developerinterfaces\n gitformat-pack-cruft developerinterfaces\n gitformat-signature developerinterfaces\n-- \n2.37.1.1197.g7ed548b7807\n\n"},{"id":"460147","messageId":"xmqqzggt9dja.fsf@gitster.g","threadId":"56715","inReplyTo":"cover-v6-0.9-00000000000-20220728T164243Z-avarab@gmail.com","subject":"Re: [PATCH v6 0/9] docs: create & use \"(user|developer) interfaces\" categories","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-28T20:40:25Z","receivedAt":"2022-07-28T20:40:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> See the v5 for a general overview:\n> https://lore.kernel.org/git/cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com/\n>\n> This trivial v6 fixes a grammar error in a commit message pointed-out\n> by Eric Sunshine, thanks Eric!\n\nThis seems to be identical to what we already have in my tree, which\nis OK.\n\nWill not queue but instead keep the old one that has the fix applied\nwhen it was queued, to keep the author & committer dates.\n\nThanks.\n"},{"id":"460292","messageId":"xmqq35ej313l.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-v6-1.9-f3588319057-20220728T164243Z-avarab@gmail.com","subject":"Re: [PATCH v6 1/9] help.c: BUG() out if \"help --guides\" can't remove \"git\" prefixes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-30T00:17:50Z","receivedAt":"2022-07-30T00:18:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Adjust code added in 929d9192828 (git docs: split \"User-facing file\n> formats\" off from \"Guides\", 2021-06-04) to be more strict about the\n> prefix trimming of the \"guides\" category.\n>\n> There are no guides in the command-list.txt that don't start with\n> \"git\", and we're unlikely to ever add any, if we do we can remove this\n> BUG() invocation, but in the meantime this makes the intent more\n> clear.\n\nI am not sure what this buys us. After dealing with pages that\nbegin with \"git-\", if the set of documentation we have happen to all\nshare \"git\" as their prefix, then this new BUG() does not do\nanything to them, and when we ever add say \"scalar-guide.txt\", the\nnew BUG() would only force people to rewrite this part of the code.\n\nInstead we could be more forward looking and do something like\n\"Yield a name without 'git' prefix if it begins with it, or the\noriginal name\", and then new guides that are outside \"git\" namespace\ncan be added without touching this part of the code again.\n\nIOW, it is not entirely clear to me what we are adding this extra\nroadblock for.\n\n\n> While we're at it remove a stray newline that had been added after the\n> \"return name;\" statement.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> help.c | 10 ++++++++--\n> 1 file changed, 8 insertions(+), 2 deletions(-)\n>\n> diff --git a/help.c b/help.c\n> index 41c41c2aa11..80d516abb0b 100644\n> --- a/help.c\n> +++ b/help.c\n> @@ -44,13 +44,19 @@ static struct category_description main_categories[] = {\n> static const char *drop_prefix(const char *name, uint32_t category)\n> {\n> \tconst char *new_name;\n> +\tconst char *prefix;\n> \n> \tif (skip_prefix(name, \"git-\", &new_name))\n> \t\treturn new_name;\n> -\tif (category == CAT_guide && skip_prefix(name, \"git\", &new_name))\n> +\tswitch (category) {\n> +\tcase CAT_guide:\n> +\t\tprefix = \"git\";\n> +\t\tif (!skip_prefix(name, prefix, &new_name))\n> +\t\t\tBUG(\"'%s' in category #%d should have '%s' prefix\",\n> +\t\t\t name, category, prefix);\n> \t\treturn new_name;\n> +\t}\n> \treturn name;\n> -\n> }\n> \n> static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask)\n"},{"id":"460343","messageId":"220801.86czdki3ad.gmgdl@evledraar.gmail.com","threadId":"56715","inReplyTo":"xmqq35ej313l.fsf@gitster.g","subject":"Re: [PATCH v6 1/9] help.c: BUG() out if \"help --guides\" can't remove \"git\" prefixes","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-01T11:55:11Z","receivedAt":"2022-08-01T12:16:21Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Fri, Jul 29 2022, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason writes:\n>\n>> Adjust code added in 929d9192828 (git docs: split \"User-facing file\n>> formats\" off from \"Guides\", 2021-06-04) to be more strict about the\n>> prefix trimming of the \"guides\" category.\n>>\n>> There are no guides in the command-list.txt that don't start with\n>> \"git\", and we're unlikely to ever add any, if we do we can remove this\n>> BUG() invocation, but in the meantime this makes the intent more\n>> clear.\n>\n> I am not sure what this buys us. After dealing with pages that\n> begin with \"git-\", if the set of documentation we have happen to all\n> share \"git\" as their prefix, then this new BUG() does not do\n> anything to them, and when we ever add say \"scalar-guide.txt\", the\n> new BUG() would only force people to rewrite this part of the code.\n>\n> Instead we could be more forward looking and do something like\n> \"Yield a name without 'git' prefix if it begins with it, or the\n> original name\", and then new guides that are outside \"git\" namespace\n> can be added without touching this part of the code again.\n>\n> IOW, it is not entirely clear to me what we are adding this extra\n> roadblock for.\n\nI think if we ever have non-git documentation such as scalar's being\nshipped as part of our build it would be good to run into this BUG(),\nsince presumably a \"git help -g\" should not list them, but e.g. \"scalar\nhelp -g\" or whatever.\n\nOr if \"git help -g\" should list them we should extend it somehow so that\nit's not listed under the main \"The Git concept guides are\" heading.\n\nBut per that rationale I should give \"git-\" the same BUG() treatment,\nwhich I didn't because I wanted to focus just on \"git\" here, to make\nthis easier to explain (but perhaps it wasn't).\n\nSo I can remove this stricture entirely, or make the BUG() stricter and\nremove the \"git\" (or \"git-\" requirenment. Whatever you prefer after\nreading the above..\n"},{"id":"460358","messageId":"xmqqbkt3zzeb.fsf@gitster.g","threadId":"56715","inReplyTo":"220801.86czdki3ad.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH v6 1/9] help.c: BUG() out if \"help --guides\" can't remove \"git\" prefixes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-01T16:45:00Z","receivedAt":"2022-08-01T16:45:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> So I can remove this stricture entirely, or make the BUG() stricter and\n> remove the \"git\" (or \"git-\" requirenment. Whatever you prefer after\n> reading the above..\n\nMy preference is that you do not have this patch at all.\n\nWe do not need it now, and we do not know, and more imoprtantly, we\ndo not have to decide, what we want to do when we add a guide whose\nname does not want to begin with \"git\". It would only locally be\none patch we do not have to discuss out of 9, but things add up.\n\nIf you switch to the attitude of not churning what you do not have\nto touch right at the moment, hopefully it would save reviewers'\ntime. It unfortunately probably make you spend more time thinking\nabout everything you do if that is essential or unnecessary churn\nafter writing but before sending them out.\n\nBut hopefully the original author spending more time and effort on\nthe quality of the primary part of the changes, without getting\ndistracted and without distracting reviewers by what is not\nnecessary yet, would contribute positively to the quality of the end\nproduct?\n\nTHanks.\n\n\n\n"},{"id":"460419","messageId":"cover-v7-00.10-00000000000-20220802T125258Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v6-0.9-00000000000-20220728T164243Z-avarab@gmail.com","subject":"[PATCH v7 00/10] docs: create & use \"(user|developer) interfaces\" categories","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-02T12:56:49Z","receivedAt":"2022-08-02T12:58:14Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"See the v5 for a general overview:\nhttps://lore.kernel.org/git/cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com/\n\nThis v7:\n\n * Gets rid of the BUG() addition in an earlier commit when handle the\n command-list.txt data.\n\n * We still need to change that drop_prefix() function to handle our\n new categories.\n\n That's now done in a couple of commits. One to\n change it to a \"switch\" statement without any functional changes,\n another to strip either \"git\" or \"git-\" prefixes, not both.\n\n * There was an indentation error in a command-list.txt addition, fix\n it.\n\nÆvar Arnfjörð Bjarmason (10):\n help.c: refactor drop_prefix() to use a \"switch\" statement\"\n help.c: remove common category behavior from drop_prefix() behavior\n git help doc: use \"\" instead of \"\"\n git docs: add a category for user-facing file, repo and command UX\n git docs: add a category for file formats, protocols and interfaces\n docs: move commit-graph format docs to man section 5\n docs: move protocol-related docs to man section 5\n docs: move pack format docs to man section 5\n docs: move http-protocol docs to man section 5\n docs: move multi-pack-index docs to man section 5\n\n Documentation/Makefile | 26 +++++-----\n Documentation/config/lsrefs.txt | 2 +-\n Documentation/config/pack.txt | 2 +-\n Documentation/config/protocol.txt | 2 +-\n Documentation/git-bundle.txt | 13 +++--\n Documentation/git-commit-graph.txt | 5 ++\n Documentation/git-help.txt | 27 ++++++++--\n Documentation/git-multi-pack-index.txt | 6 +--\n Documentation/git-upload-pack.txt | 7 ++-\n Documentation/git.txt | 17 +++++++\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++---\n .../chunk-format.txt => gitformat-chunk.txt} | 29 ++++++++---\n ...-format.txt => gitformat-commit-graph.txt} | 49 +++++++++++++------\n .../index-format.txt => gitformat-index.txt} | 22 ++++++++-\n ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++-\n ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++-\n .../pack-format.txt => gitformat-pack.txt} | 39 +++++++++++++--\n ...ure-format.txt => gitformat-signature.txt} | 21 ++++++--\n ...ities.txt => gitprotocol-capabilities.txt} | 28 ++++++++---\n ...ocol-common.txt => gitprotocol-common.txt} | 23 ++++++++-\n ...http-protocol.txt => gitprotocol-http.txt} | 35 ++++++++++---\n ...pack-protocol.txt => gitprotocol-pack.txt} | 28 ++++++++---\n .../protocol-v2.txt => gitprotocol-v2.txt} | 27 +++++++---\n .../howto/recover-corrupted-object-harder.txt | 2 +-\n Documentation/lint-man-section-order.perl | 3 ++\n Documentation/technical/api-simple-ipc.txt | 2 +-\n .../technical/hash-function-transition.txt | 2 +-\n .../long-running-process-protocol.txt | 2 +-\n Documentation/technical/packfile-uri.txt | 2 +-\n Documentation/technical/partial-clone.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n Makefile | 1 +\n builtin/help.c | 20 +++++++-\n cache.h | 3 +-\n command-list.txt | 38 +++++++++++---\n help.c | 41 ++++++++++++++--\n help.h | 2 +\n pack-revindex.h | 2 +-\n refspec.h | 2 +-\n t/t0012-help.sh | 14 +++++-\n t/t5551-http-fetch-smart.sh | 4 +-\n 41 files changed, 512 insertions(+), 126 deletions(-)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)\n rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (89%)\n rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (87%)\n rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)\n rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)\n rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%)\n rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)\n rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)\n rename Documentation/{technical/protocol-capabilities.txt => gitprotocol-capabilities.txt} (96%)\n rename Documentation/{technical/protocol-common.txt => gitprotocol-common.txt} (89%)\n rename Documentation/{technical/http-protocol.txt => gitprotocol-http.txt} (97%)\n rename Documentation/{technical/pack-protocol.txt => gitprotocol-pack.txt} (98%)\n rename Documentation/{technical/protocol-v2.txt => gitprotocol-v2.txt} (97%)\n\nRange-diff against v6:\n 1: f3588319057 ! 1: 2665148f45b help.c: BUG() out if \"help --guides\" can't remove \"git\" prefixes\n @@ Metadata\n Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - help.c: BUG() out if \"help --guides\" can't remove \"git\" prefixes\n + help.c: refactor drop_prefix() to use a \"switch\" statement\"\n \n - Adjust code added in 929d9192828 (git docs: split \"User-facing file\n - formats\" off from \"Guides\", 2021-06-04) to be more strict about the\n - prefix trimming of the \"guides\" category.\n + Refactor the drop_prefix() function in in help.c to make it easier to\n + strip prefixes from categories that aren't \"CAT_guide\". There are no\n + functional changes here, by doing this we make a subsequent functional\n + change's diff smaller.\n \n - There are no guides in the command-list.txt that don't start with\n - \"git\", and we're unlikely to ever add any, if we do we can remove this\n - BUG() invocation, but in the meantime this makes the intent more\n - clear.\n + As before we first try to strip \"git-\" unconditionally, if that works\n + we'll return the stripped string. Then we'll strip \"git\" if the\n + command is in \"CAT_guide\".\n +\n + This means that we'd in principle strip \"git-gitfoo\" down to \"foo\" if\n + it's in CAT_guide. That doesn't make much sense, and we don't have\n + such an entry in command-list.txt, but let's preserve that behavior\n + for now.\n \n While we're at it remove a stray newline that had been added after the\n \"return name;\" statement.\n @@ help.c: static struct category_description main_categories[] = {\n static const char *drop_prefix(const char *name, uint32_t category)\n {\n \tconst char *new_name;\n -+\tconst char *prefix;\n ++\tconst char *prefix = NULL;\n \n \tif (skip_prefix(name, \"git-\", &new_name))\n \t\treturn new_name;\n @@ help.c: static struct category_description main_categories[] = {\n +\tswitch (category) {\n +\tcase CAT_guide:\n +\t\tprefix = \"git\";\n -+\t\tif (!skip_prefix(name, prefix, &new_name))\n -+\t\t\tBUG(\"'%s' in category #%d should have '%s' prefix\",\n -+\t\t\t name, category, prefix);\n - \t\treturn new_name;\n ++\t\tbreak;\n +\t}\n - \treturn name;\n --\n ++\tif (prefix && skip_prefix(name, prefix, &new_name))\n + \t\treturn new_name;\n +-\treturn name;\n + \n ++\treturn name;\n }\n \n static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask)\n -: ----------- > 2: 56429194634 help.c: remove common category behavior from drop_prefix() behavior\n 2: 80322d44ea5 = 3: 2d6c00a51fa git help doc: use \"\" instead of \"\"\n 3: 0d22eb645bd ! 4: 8e9384a92f2 git docs: add a category for user-facing file, repo and command UX\n @@ help.c: static struct category_description main_categories[] = {\n };\n \n @@ help.c: static const char *drop_prefix(const char *name, uint32_t category)\n - \t\treturn new_name;\n + \n \tswitch (category) {\n \tcase CAT_guide:\n +\tcase CAT_userinterfaces:\n \t\tprefix = \"git\";\n - \t\tif (!skip_prefix(name, prefix, &new_name))\n - \t\t\tBUG(\"'%s' in category #%d should have '%s' prefix\",\n + \t\tbreak;\n + \tdefault:\n @@ help.c: void list_guides_help(void)\n \tputchar('\\n');\n }\n 4: c25f8ec9bf5 ! 5: 4367c1e7f50 git docs: add a category for file formats, protocols and interfaces\n @@ help.c: static const char *drop_prefix(const char *name, uint32_t category)\n \tcase CAT_userinterfaces:\n +\tcase CAT_developerinterfaces:\n \t\tprefix = \"git\";\n - \t\tif (!skip_prefix(name, prefix, &new_name))\n - \t\t\tBUG(\"'%s' in category #%d should have '%s' prefix\",\n + \t\tbreak;\n + \tdefault:\n @@ help.c: void list_user_interfaces_help(void)\n \tputchar('\\n');\n }\n 5: 466dbd2a993 = 6: 5adabbb3a26 docs: move commit-graph format docs to man section 5\n 6: 9a551b2d53a = 7: cfd1b0afb53 docs: move protocol-related docs to man section 5\n 7: 92be18b95d9 = 8: 3505fa86039 docs: move pack format docs to man section 5\n 8: a8a883ebf85 ! 9: c4a7fe9d439 docs: move http-protocol docs to man section 5\n @@ command-list.txt: gitmodules userinterfaces\n gitnamespaces guide\n gitprotocol-capabilities developerinterfaces\n gitprotocol-common developerinterfaces\n -+gitprotocol-http developerinterfaces\n ++gitprotocol-http developerinterfaces\n gitprotocol-pack developerinterfaces\n gitprotocol-v2 developerinterfaces\n gitremote-helpers guide\n 9: ecfda8c6770 = 10: 8baf1db4d30 docs: move multi-pack-index docs to man section 5\n-- \n2.37.1.1232.gc0cde427aa7\n\n"},{"id":"460420","messageId":"patch-v7-01.10-2665148f45b-20220802T125258Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v7-00.10-00000000000-20220802T125258Z-avarab@gmail.com","subject":"[PATCH v7 01/10] help.c: refactor drop_prefix() to use a \"switch\" statement\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-02T12:56:50Z","receivedAt":"2022-08-02T12:58:15Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Refactor the drop_prefix() function in in help.c to make it easier to\nstrip prefixes from categories that aren't \"CAT_guide\". There are no\nfunctional changes here, by doing this we make a subsequent functional\nchange's diff smaller.\n\nAs before we first try to strip \"git-\" unconditionally, if that works\nwe'll return the stripped string. Then we'll strip \"git\" if the\ncommand is in \"CAT_guide\".\n\nThis means that we'd in principle strip \"git-gitfoo\" down to \"foo\" if\nit's in CAT_guide. That doesn't make much sense, and we don't have\nsuch an entry in command-list.txt, but let's preserve that behavior\nfor now.\n\nWhile we're at it remove a stray newline that had been added after the\n\"return name;\" statement.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n help.c | 10 ++++++++--\n 1 file changed, 8 insertions(+), 2 deletions(-)\n\ndiff --git a/help.c b/help.c\nindex 41c41c2aa11..7e594d291b0 100644\n--- a/help.c\n+++ b/help.c\n@@ -44,13 +44,19 @@ static struct category_description main_categories[] = {\n static const char *drop_prefix(const char *name, uint32_t category)\n {\n \tconst char *new_name;\n+\tconst char *prefix = NULL;\n \n \tif (skip_prefix(name, \"git-\", &new_name))\n \t\treturn new_name;\n-\tif (category == CAT_guide && skip_prefix(name, \"git\", &new_name))\n+\tswitch (category) {\n+\tcase CAT_guide:\n+\t\tprefix = \"git\";\n+\t\tbreak;\n+\t}\n+\tif (prefix && skip_prefix(name, prefix, &new_name))\n \t\treturn new_name;\n-\treturn name;\n \n+\treturn name;\n }\n \n static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask)\n-- \n2.37.1.1232.gc0cde427aa7\n\n"},{"id":"460421","messageId":"patch-v7-02.10-56429194634-20220802T125258Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v7-00.10-00000000000-20220802T125258Z-avarab@gmail.com","subject":"[PATCH v7 02/10] help.c: remove common category behavior from drop_prefix() behavior","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-02T12:56:51Z","receivedAt":"2022-08-02T12:58:20Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the behavior of the \"git\" prefix stripping for CAT_guide so\nthat we don't try to strip the \"git-\" prefix in that case. We should\nbe stripping either \"git\" or \"git-\" depending on the category. This\nchange makes it easier to add extra \"category\" conditions in\nsubsequent commits.\n\nBefore this we'd in principle strip a \"git-\" prefix from a \"guide\" in\ncommand-list.txt, in practice we have no such entry there. As we don't\nhave any entry that looks like \"git-gitfoo\" in command-list.txt this\nchanges nothing in practice, but it makes the intent of the code\nclearer.\n\nWhen this code was added in cfb22a02ab5 (help: use command-list.h for\ncommon command list, 2018-05-10) the only entries in command-list.txt\nthat didn't begin with \"git-\" were \"gitweb\" and \"gitk\".\n\nThen when the \"guides\" special-case was added in 1b81d8cb19d (help:\nuse command-list.txt for the source of guides, 2018-05-20) we had the\nvarious \"git\" (not \"git-\") prefixed \"guide\" entries, which the\n\"CAT_guide\" case handles.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n help.c | 9 +++++----\n 1 file changed, 5 insertions(+), 4 deletions(-)\n\ndiff --git a/help.c b/help.c\nindex 7e594d291b0..8a09f18a3d9 100644\n--- a/help.c\n+++ b/help.c\n@@ -44,16 +44,17 @@ static struct category_description main_categories[] = {\n static const char *drop_prefix(const char *name, uint32_t category)\n {\n \tconst char *new_name;\n-\tconst char *prefix = NULL;\n+\tconst char *prefix;\n \n-\tif (skip_prefix(name, \"git-\", &new_name))\n-\t\treturn new_name;\n \tswitch (category) {\n \tcase CAT_guide:\n \t\tprefix = \"git\";\n \t\tbreak;\n+\tdefault:\n+\t\tprefix = \"git-\";\n+\t\tbreak;\n \t}\n-\tif (prefix && skip_prefix(name, prefix, &new_name))\n+\tif (skip_prefix(name, prefix, &new_name))\n \t\treturn new_name;\n \n \treturn name;\n-- \n2.37.1.1232.gc0cde427aa7\n\n"},{"id":"460422","messageId":"patch-v7-03.10-2d6c00a51fa-20220802T125258Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v7-00.10-00000000000-20220802T125258Z-avarab@gmail.com","subject":"[PATCH v7 03/10] git help doc: use \"\" instead of \"\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-02T12:56:52Z","receivedAt":"2022-08-02T12:58:24Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Replace the use of \"\" originally introduced (as \"GUIDE\") in\na133737b809 (doc: include --guide option description for \"git help\",\n2013-04-02) with the more generic \"\". The \"\" placeholder is\nmore generic, and one we'll be able to use as we introduce new\ndocumentation categories.\n\nLet's also add \"\" to the \"git help -h\" output, when it was made\nto use parse_option() in in 41eb33bd0cb (help: use parseopt,\n2008-02-24).\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-help.txt | 8 ++++----\n builtin/help.c | 2 +-\n 2 files changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 239c68db457..bead763fd29 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -9,14 +9,14 @@ SYNOPSIS\n --------\n [verse]\n 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\n-'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n+'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n \n DESCRIPTION\n -----------\n \n-With no options and no '' or '' given, the synopsis of the 'git'\n+With no options and no '' or '' given, the synopsis of the 'git'\n command and a list of the most commonly used Git commands are printed\n on the standard output.\n \n@@ -26,8 +26,8 @@ printed on the standard output.\n If the option `--guides` or `-g` is given, a list of the\n Git concept guides is also printed on the standard output.\n \n-If a command, or a guide, is given, a manual page for that command or\n-guide is brought up. The 'man' program is used by default for this\n+If a command or other documentation is given, the relevant manual page\n+will be brought up. The 'man' program is used by default for this\n purpose, but this can be overridden by other options or configuration\n variables.\n \ndiff --git a/builtin/help.c b/builtin/help.c\nindex 222f994f863..dec82d1be27 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -81,7 +81,7 @@ static struct option builtin_help_options[] = {\n \n static const char * const builtin_help_usage[] = {\n \t\"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n-\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] []\"),\n+\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [|]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n \tNULL\n-- \n2.37.1.1232.gc0cde427aa7\n\n"},{"id":"460423","messageId":"patch-v7-04.10-8e9384a92f2-20220802T125258Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v7-00.10-00000000000-20220802T125258Z-avarab@gmail.com","subject":"[PATCH v7 04/10] git docs: add a category for user-facing file, repo and command UX","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-02T12:56:53Z","receivedAt":"2022-08-02T12:58:27Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"Repository, command and file interfaces\" section in the\nmain \"git help git\" manual page. Move things that belong under this\nnew criteria from the generic \"Guides\" section.\n\nThe \"Guides\" section was added in f442f28a81b (git.txt: add list of\nguides, 2020-08-05). It makes sense to have e.g. \"giteveryday(7)\" and\n\"gitfaq(7)\" listed under \"Guides\".\n\nBut placing e.g. \"gitignore(5)\" in it is stretching the meaning of\nwhat a \"guide\" is, ideally that section should list things similar to\n\"giteveryday(7)\" and \"gitcore-tutorial(7)\".\n\nAn alternate name that was considered for this new section was \"User\nformats\", for consistency with the nomenclature used for man section 5\nin general. My man(1) lists it as \"File formats and conventions,\ne.g. /etc/passwd\".\n\nSo calling this \"git help --formats\" or \"git help --user-formats\"\nwould make sense for e.g. gitignore(5), but would be stretching it\nsomewhat for githooks(5), and would seem really suspect for the likes\nof gitcli(7).\n\nLet's instead pick a name that's closer to the generic term \"User\ninterface\", which is really what this documentation discusses: General\nuser-interface documentation that doesn't obviously belong elsewhere.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-help.txt | 14 ++++++++++++++\n Documentation/git.txt | 8 ++++++++\n Makefile | 1 +\n builtin/help.c | 9 +++++++++\n command-list.txt | 21 +++++++++++++--------\n help.c | 12 ++++++++++++\n help.h | 1 +\n t/t0012-help.sh | 12 +++++++++++-\n 9 files changed, 70 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 4f801f4e4c9..28eb940a9b8 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchingrepositories.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n+\tcmds-userinterfaces.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\n \ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex bead763fd29..4eb03bd6c38 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -12,6 +12,7 @@ SYNOPSIS\n 'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n+'git help' [--user-interfaces]\n \n DESCRIPTION\n -----------\n@@ -69,6 +70,19 @@ OPTIONS\n --guides::\n \tPrints a list of the Git concept guides on the standard output.\n \n+--user-interfaces::\n+\tPrints a list of the repository, command and file interfaces\n+\tdocumentation on the standard output.\n++\n+In-repository file interfaces such as `.git/info/exclude` are\n+documented here (see linkgit:gitrepository-layout[5]), as well as\n+in-tree configuration such as `.mailmap` (see linkgit:gitmailmap[5]).\n++\n+This section of the documentation also covers general or widespread\n+user-interface conventions (e.g. linkgit:gitcli[7]), and\n+pseudo-configuration such as the file-based `.git/hooks/*` interface\n+described in linkgit:githooks[5].\n+\n -i::\n --info::\n \tDisplay manual page for the command in the 'info' format. The\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 47a6095ff40..945a1ebd3b1 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -339,6 +339,14 @@ The following documentation pages are guides about Git concepts.\n \n include::cmds-guide.txt[]\n \n+Repository, command and file interfaces\n+---------------------------------------\n+\n+This documentation discusses repository and command interfaces which\n+users are expected to interact with directly. See `--user-formats` in\n+linkgit:git-help[1] for more details on the critera.\n+\n+include::cmds-userinterfaces.txt[]\n \n Configuration Mechanism\n -----------------------\ndiff --git a/Makefile b/Makefile\nindex 1624471badc..ea0ef7df734 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -3532,6 +3532,7 @@ check-docs::\n \t\tsed -e '1,/^### command list/d' \\\n \t\t -e '/^#/d' \\\n \t\t -e '/guide$$/d' \\\n+\t\t -e '/interfaces$$/d' \\\n \t\t -e 's/[ \t].*//' \\\n \t\t -e 's/^/listed /' command-list.txt; \\\n \t\t$(MAKE) -C Documentation print-man1 | \\\ndiff --git a/builtin/help.c b/builtin/help.c\nindex dec82d1be27..1ab1c8a0dd7 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -43,6 +43,7 @@ static enum help_action {\n \tHELP_ACTION_ALL = 1,\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n+\tHELP_ACTION_USER_INTERFACES,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -69,6 +70,9 @@ static struct option builtin_help_options[] = {\n \n \tOPT_CMDMODE('g', \"guides\", &cmd_mode, N_(\"print list of useful guides\"),\n \t\t HELP_ACTION_GUIDES),\n+\tOPT_CMDMODE(0, \"user-interfaces\", &cmd_mode,\n+\t\t N_(\"print list of user-facing repository, command and file interfaces\"),\n+\t\t HELP_ACTION_USER_INTERFACES),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -84,6 +88,7 @@ static const char * const builtin_help_usage[] = {\n \tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [|]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n+\t\"git help [--user-interfaces]\",\n \tNULL\n };\n \n@@ -654,6 +659,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\topt_mode_usage(argc, \"--config-for-completion\", help_format);\n \t\tlist_config_help(SHOW_CONFIG_VARS);\n \t\treturn 0;\n+\tcase HELP_ACTION_USER_INTERFACES:\n+\t\topt_mode_usage(argc, \"--user-interfaces\", help_format);\n+\t\tlist_user_interfaces_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n \t\t\t help_format);\ndiff --git a/command-list.txt b/command-list.txt\nindex 9bd6f3c48f4..1d45303e14c 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -43,6 +43,11 @@\n # specified here, which can only have \"guide\" attribute and nothing\n # else.\n #\n+# User-facing repository, command and file interfaces such as\n+# documentation for the .gitmodules, .mailmap etc. files lives in man\n+# sections 5 and 7. These entries can only have the \"userinterfaces\"\n+# attribute and nothing else.\n+#\n ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -192,8 +197,8 @@ git-verify-tag ancillaryinterrogators\n git-whatchanged ancillaryinterrogators complete\n git-worktree mainporcelain\n git-write-tree plumbingmanipulators\n-gitattributes guide\n-gitcli guide\n+gitattributes userinterfaces\n+gitcli userinterfaces\n gitcore-tutorial guide\n gitcredentials guide\n gitcvs-migration guide\n@@ -201,15 +206,15 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitglossary guide\n-githooks guide\n-gitignore guide\n+githooks userinterfaces\n+gitignore userinterfaces\n gitk mainporcelain\n-gitmailmap guide\n-gitmodules guide\n+gitmailmap userinterfaces\n+gitmodules userinterfaces\n gitnamespaces guide\n gitremote-helpers guide\n-gitrepository-layout guide\n-gitrevisions guide\n+gitrepository-layout userinterfaces\n+gitrevisions userinterfaces\n gitsubmodules guide\n gittutorial guide\n gittutorial-2 guide\ndiff --git a/help.c b/help.c\nindex 8a09f18a3d9..3e2a78863b7 100644\n--- a/help.c\n+++ b/help.c\n@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_plumbinginterrogators, N_(\"Low-level Commands / Interrogators\") },\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n+\t{ CAT_userinterfaces, N_(\"User-facing repository, command and file interfaces\") },\n \t{ 0, NULL }\n };\n \n@@ -48,6 +49,7 @@ static const char *drop_prefix(const char *name, uint32_t category)\n \n \tswitch (category) {\n \tcase CAT_guide:\n+\tcase CAT_userinterfaces:\n \t\tprefix = \"git\";\n \t\tbreak;\n \tdefault:\n@@ -433,6 +435,16 @@ void list_guides_help(void)\n \tputchar('\\n');\n }\n \n+void list_user_interfaces_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_userinterfaces, N_(\"User-facing repository, command and file interfaces:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex 971a3ad855a..243104c27a7 100644\n--- a/help.h\n+++ b/help.h\n@@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num)\n void list_common_cmds_help(void);\n void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n+void list_user_interfaces_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex 6c33a436901..bee5ed12203 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -44,6 +44,8 @@ test_expect_success 'invalid usage' '\n \ttest_expect_code 129 git help -g add &&\n \ttest_expect_code 129 git help -a -g &&\n \n+\ttest_expect_code 129 git help --user-interfaces add &&\n+\n \ttest_expect_code 129 git help -g -c &&\n \ttest_expect_code 129 git help --config-for-completion add &&\n \ttest_expect_code 129 git help --config-sections-for-completion add\n@@ -104,9 +106,9 @@ test_expect_success 'git help' '\n \ttest_i18ngrep \"^ commit \" help.output &&\n \ttest_i18ngrep \"^ fetch \" help.output\n '\n+\n test_expect_success 'git help -g' '\n \tgit help -g >help.output &&\n-\ttest_i18ngrep \"^ attributes \" help.output &&\n \ttest_i18ngrep \"^ everyday \" help.output &&\n \ttest_i18ngrep \"^ tutorial \" help.output\n '\n@@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' '\n \ttest_cmp expect test-browser.log\n '\n \n+test_expect_success 'git help --user-interfaces' '\n+\tgit help --user-interfaces >help.output &&\n+\tgrep \"^ attributes \" help.output &&\n+\tgrep \"^ mailmap \" help.output\n+'\n+\n test_expect_success 'git help -c' '\n \tgit help -c >help.output &&\n \tcat >expect <<-\\EOF &&\n@@ -220,6 +228,8 @@ test_expect_success \"'git help -a' section spacing\" '\n \tLow-level Commands / Syncing Repositories\n \n \tLow-level Commands / Internal Helpers\n+\n+\tUser-facing repository, command and file interfaces\n \tEOF\n \ttest_cmp expect actual\n '\n-- \n2.37.1.1232.gc0cde427aa7\n\n"},{"id":"460424","messageId":"patch-v7-05.10-4367c1e7f50-20220802T125258Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v7-00.10-00000000000-20220802T125258Z-avarab@gmail.com","subject":"[PATCH v7 05/10] git docs: add a category for file formats, protocols and interfaces","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-02T12:56:54Z","receivedAt":"2022-08-02T12:58:29Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"File formats, protocols and other developer interfaces\"\nsection in the main \"git help git\" manual page and start moving the\ndocumentation that now lives in \"Documentation/technical/*.git\" over\nto it. This complements the newly added and adjacent \"Repository,\ncommand and file interfaces\" section.\n\nThis makes the technical documentation more accessible and\ndiscoverable. Before this we wouldn't install it by default, and had\nno ability to build man page versions of them. The links to them from\nour existing documentation link to the generated HTML version of these\ndocs.\n\nSo let's start moving those over, starting with just the\n\"bundle-format.txt\" documentation added in 7378ec90e1c (doc: describe\nGit bundle format, 2020-02-07). We'll now have a new\ngitformat-bundle(5) man page. Subsequent commits will move more git\ninternal format documentation over.\n\nUnfortunately the syntax of the current Documentation/technical/*.txt\nis not the same (when it comes to section headings etc.) as our\nDocumentation/*.txt documentation, so change the relevant bits of\nsyntax as we're moving this over.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 3 +-\n Documentation/git-bundle.txt | 14 +++---\n Documentation/git-help.txt | 5 +++\n Documentation/git.txt | 9 ++++\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++---\n Documentation/lint-man-section-order.perl | 3 ++\n builtin/help.c | 9 ++++\n command-list.txt | 5 +++\n help.c | 12 +++++\n help.h | 1 +\n t/t0012-help.sh | 2 +\n 11 files changed, 94 insertions(+), 13 deletions(-)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 28eb940a9b8..1a4a545f44a 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -24,6 +24,7 @@ MAN1_TXT += gitweb.txt\n \n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n+MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -95,7 +96,6 @@ TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n-TECH_DOCS += technical/bundle-format\n TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchingrepositories.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n+\tcmds-developerinterfaces.txt \\\n \tcmds-userinterfaces.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 7685b570455..f0b1282b918 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -56,10 +56,9 @@ using \"thin packs\", bundles created using exclusions are smaller in\n size. That they're \"thin\" under the hood is merely noted here as a\n curiosity, and as a reference to other documentation.\n \n-See link:technical/bundle-format.html[the `bundle-format`\n-documentation] for more details and the discussion of \"thin pack\" in\n-link:technical/pack-format.html[the pack format documentation] for\n-further details.\n+See linkgit:gitformat-bundle[5] for more details and the discussion of\n+\"thin pack\" in link:technical/pack-format.html[the pack format\n+documentation] for further details.\n \n OPTIONS\n -------\n@@ -77,7 +76,7 @@ verify ::\n \tcommits exist and are fully linked in the current repository.\n \tThen, 'git bundle' prints a list of missing commits, if any.\n \tFinally, information about additional capabilities, such as \"object\n-\tfilter\", is printed. See \"Capabilities\" in link:technical/bundle-format.html\n+\tfilter\", is printed. See \"Capabilities\" in linkgit:gitformat-bundle[5]\n \tfor more information. The exit code is zero for success, but will\n \tbe nonzero if the bundle file is invalid.\n \n@@ -337,6 +336,11 @@ You can also see what references it offers:\n $ git ls-remote mybundle\n ----------------\n \n+FILE FORMAT\n+-----------\n+\n+See linkgit:gitformat-bundle[5].\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 4eb03bd6c38..2b0b5e390dc 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -13,6 +13,7 @@ SYNOPSIS\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n 'git help' [--user-interfaces]\n+'git help' [--developer-interfaces]\n \n DESCRIPTION\n -----------\n@@ -83,6 +84,10 @@ user-interface conventions (e.g. linkgit:gitcli[7]), and\n pseudo-configuration such as the file-based `.git/hooks/*` interface\n described in linkgit:githooks[5].\n \n+--developer-interfaces::\n+\tPrint list of file formats, protocols and other developer\n+\tinterfaces documentation on the standard output.\n+\n -i::\n --info::\n \tDisplay manual page for the command in the 'info' format. The\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 945a1ebd3b1..0ef7f5e4ece 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -348,6 +348,15 @@ linkgit:git-help[1] for more details on the critera.\n \n include::cmds-userinterfaces.txt[]\n \n+File formats, protocols and other developer interfaces\n+------------------------------------------------------\n+\n+This documentation discusses file formats, over-the-wire protocols and\n+other git developer interfaces. See `--developer-interfaces` in\n+linkgit:git-help[1].\n+\n+include::cmds-developerinterfaces.txt[]\n+\n Configuration Mechanism\n -----------------------\n \ndiff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt\nsimilarity index 79%\nrename from Documentation/technical/bundle-format.txt\nrename to Documentation/gitformat-bundle.txt\nindex b9be8644cf5..6a9d9e5bf6f 100644\n--- a/Documentation/technical/bundle-format.txt\n+++ b/Documentation/gitformat-bundle.txt\n@@ -1,11 +1,33 @@\n-= Git bundle v2 format\n+gitformat-bundle(5)\n+===================\n \n-The Git bundle format is a format that represents both refs and Git objects.\n+NAME\n+----\n+gitformat-bundle - The bundle file format\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+*.bundle\n+*.bdl\n+\n+DESCRIPTION\n+-----------\n+\n+The Git bundle format is a format that represents both refs and Git\n+objects. A bundle is a header in a format similar to\n+linkgit:git-show-ref[1] followed by a pack in *.pack format.\n \n-== Format\n+The format is created and read by the linkgit:git-bundle[1] command,\n+and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1].\n+\n+\n+FORMAT\n+------\n \n We will use ABNF notation to define the Git bundle format. See\n-protocol-common.txt for the details.\n+link:technical/protocol-common.html for the details.\n \n A v2 bundle looks like this:\n \n@@ -36,7 +58,9 @@ value = *(%01-09 / %0b-FF)\n pack = ... ; packfile\n ----\n \n-== Semantics\n+\n+SEMANTICS\n+---------\n \n A Git bundle consists of several parts.\n \n@@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id.\n This is a comment and it has no specific meaning. The writer of the bundle MAY\n put any string here. The reader of the bundle MUST ignore the comment.\n \n-=== Note on the shallow clone and a Git bundle\n+Note on the shallow clone and a Git bundle\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n Note that the prerequisites does not represent a shallow-clone boundary. The\n semantics of the prerequisites and the shallow-clone boundaries are different,\n and the Git bundle v2 format cannot represent a shallow clone repository.\n \n-== Capabilities\n+CAPABILITIES\n+------------\n \n Because there is no opportunity for negotiation, unknown capabilities cause 'git\n bundle' to abort.\n@@ -79,3 +105,7 @@ bundle' to abort.\n * `filter` specifies an object filter as in the `--filter` option in\n linkgit:git-rev-list[1]. The resulting pack-file must be marked as a\n `.promisor` pack-file after it is unbundled.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl\nindex 425377dfeb7..02408a0062f 100755\n--- a/Documentation/lint-man-section-order.perl\n+++ b/Documentation/lint-man-section-order.perl\n@@ -32,6 +32,9 @@\n \t\t'SEE ALSO' => {\n \t\t\torder => $order++,\n \t\t},\n+\t\t'FILE FORMAT' => {\n+\t\t\torder => $order++,\n+\t\t},\n \t\t'GIT' => {\n \t\t\trequired => 1,\n \t\t\torder => $order++,\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 1ab1c8a0dd7..09ac4289f13 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -44,6 +44,7 @@ static enum help_action {\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n \tHELP_ACTION_USER_INTERFACES,\n+\tHELP_ACTION_DEVELOPER_INTERFACES,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -73,6 +74,9 @@ static struct option builtin_help_options[] = {\n \tOPT_CMDMODE(0, \"user-interfaces\", &cmd_mode,\n \t\t N_(\"print list of user-facing repository, command and file interfaces\"),\n \t\t HELP_ACTION_USER_INTERFACES),\n+\tOPT_CMDMODE(0, \"developer-interfaces\", &cmd_mode,\n+\t\t N_(\"print list of file formats, protocols and other developer interfaces\"),\n+\t\t HELP_ACTION_DEVELOPER_INTERFACES),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -89,6 +93,7 @@ static const char * const builtin_help_usage[] = {\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n \t\"git help [--user-interfaces]\",\n+\t\"git help [--developer-interfaces]\",\n \tNULL\n };\n \n@@ -663,6 +668,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\topt_mode_usage(argc, \"--user-interfaces\", help_format);\n \t\tlist_user_interfaces_help();\n \t\treturn 0;\n+\tcase HELP_ACTION_DEVELOPER_INTERFACES:\n+\t\topt_mode_usage(argc, \"--developer-interfaces\", help_format);\n+\t\tlist_developer_interfaces_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n \t\t\t help_format);\ndiff --git a/command-list.txt b/command-list.txt\nindex 1d45303e14c..1950c4ccd9c 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -48,6 +48,10 @@\n # sections 5 and 7. These entries can only have the \"userinterfaces\"\n # attribute and nothing else.\n #\n+# Git's file formats and protocols, such as documentation for the\n+# *.bundle format lives in man section 5. These entries can only have\n+# the \"developerinterfaces\" attribute and nothing else.\n+#\n ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -205,6 +209,7 @@ gitcvs-migration guide\n gitdiffcore guide\n giteveryday guide\n gitfaq guide\n+gitformat-bundle developerinterfaces\n gitglossary guide\n githooks userinterfaces\n gitignore userinterfaces\ndiff --git a/help.c b/help.c\nindex 3e2a78863b7..991e33f8a6e 100644\n--- a/help.c\n+++ b/help.c\n@@ -39,6 +39,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n \t{ CAT_userinterfaces, N_(\"User-facing repository, command and file interfaces\") },\n+\t{ CAT_developerinterfaces, N_(\"Developer-facing file file formats, protocols and interfaces\") },\n \t{ 0, NULL }\n };\n \n@@ -50,6 +51,7 @@ static const char *drop_prefix(const char *name, uint32_t category)\n \tswitch (category) {\n \tcase CAT_guide:\n \tcase CAT_userinterfaces:\n+\tcase CAT_developerinterfaces:\n \t\tprefix = \"git\";\n \t\tbreak;\n \tdefault:\n@@ -445,6 +447,16 @@ void list_user_interfaces_help(void)\n \tputchar('\\n');\n }\n \n+void list_developer_interfaces_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_developerinterfaces, N_(\"File formats, protocols and other developer interfaces:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex 243104c27a7..af073a7a026 100644\n--- a/help.h\n+++ b/help.h\n@@ -23,6 +23,7 @@ void list_common_cmds_help(void);\n void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n void list_user_interfaces_help(void);\n+void list_developer_interfaces_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex bee5ed12203..4ed2f242eb2 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -230,6 +230,8 @@ test_expect_success \"'git help -a' section spacing\" '\n \tLow-level Commands / Internal Helpers\n \n \tUser-facing repository, command and file interfaces\n+\n+\tDeveloper-facing file file formats, protocols and interfaces\n \tEOF\n \ttest_cmp expect actual\n '\n-- \n2.37.1.1232.gc0cde427aa7\n\n"},{"id":"460425","messageId":"patch-v7-06.10-5adabbb3a26-20220802T125258Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v7-00.10-00000000000-20220802T125258Z-avarab@gmail.com","subject":"[PATCH v7 06/10] docs: move commit-graph format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-02T12:56:55Z","receivedAt":"2022-08-02T12:58:32Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space.\n\nBy moving the documentation for the commit-graph format into man\nsection 5 and the new \"developerinterfaces\" category. This change is\nsplit from subsequent commits due to the relatively large amount of\nASCIIDOC formatting changes that are required.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-commit-graph.txt | 5 ++\n ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------\n Documentation/technical/chunk-format.txt | 4 +-\n command-list.txt | 2 +\n 5 files changed, 42 insertions(+), 17 deletions(-)\n rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (88%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 1a4a545f44a..e7bd72bb84e 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -25,6 +25,7 @@ MAN1_TXT += gitweb.txt\n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n+MAN5_TXT += gitformat-commit-graph.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex e1f48c95b3c..047decdb65b 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append\n ------------------------------------------------\n \n \n+FILE FORMAT\n+-----------\n+\n+see linkgit:gitformat-commit-graph[5].\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt\nsimilarity index 88%\nrename from Documentation/technical/commit-graph-format.txt\nrename to Documentation/gitformat-commit-graph.txt\nindex 484b185ba98..108dc2295c0 100644\n--- a/Documentation/technical/commit-graph-format.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -1,5 +1,18 @@\n-Git commit graph format\n-=======================\n+gitformat-commit-graph(5)\n+=========================\n+\n+NAME\n+----\n+gitformat-commit-graph - Git commit graph format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/info/commit-graph\n+$GIT_DIR/objects/info/commit-graphs/*\n+\n+DESCRIPTION\n+-----------\n \n The Git commit graph stores a list of commit OIDs and some associated\n metadata, including:\n@@ -30,7 +43,7 @@ and hash type.\n \n All multi-byte numbers are in network byte order.\n \n-HEADER:\n+=== HEADER:\n \n 4-byte signature:\n The signature is: {'C', 'G', 'P', 'H'}\n@@ -52,7 +65,7 @@ HEADER:\n We infer the length (H*B) of the Base Graphs chunk\n from this value.\n \n-CHUNK LOOKUP:\n+=== CHUNK LOOKUP:\n \n (C + 1) * 12 bytes listing the table of contents for the chunks:\n First 4 bytes describe the chunk id. Value 0 is a terminating label.\n@@ -68,17 +81,17 @@ CHUNK LOOKUP:\n these chunks may be given in any order. Chunks are required unless\n otherwise specified.\n \n-CHUNK DATA:\n+=== CHUNK DATA:\n \n- OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n+==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n The ith entry, F[i], stores the number of OIDs with first\n byte at most i. Thus F[255] stores the total\n number of commits (N).\n \n- OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n+==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n The OIDs for all commits in the graph, sorted in ascending order.\n \n- Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n+==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n * The first H bytes are for the OID of the root tree.\n * The next 8 bytes are for the positions of the first two parents\n of the ith commit. Stores value 0x70000000 if no parent in that\n@@ -93,7 +106,7 @@ CHUNK DATA:\n 2 bits of the lowest byte, storing the 33rd and 34th bit of the\n commit time.\n \n- Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n+==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n * This list of 4-byte values store corrected commit date offsets for the\n commits, arranged in the same order as commit data chunk.\n * If the corrected commit date offset cannot be stored within 31 bits,\n@@ -104,7 +117,7 @@ CHUNK DATA:\n by compatible versions of Git and in case of split commit-graph chains,\n the topmost layer also has Generation Data chunk.\n \n- Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n+==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n * This list of 8-byte values stores the corrected commit date offsets\n for commits with corrected commit date offsets that cannot be\n stored within 31 bits.\n@@ -112,7 +125,7 @@ CHUNK DATA:\n chunk is present and atleast one corrected commit date offset cannot\n be stored within 31 bits.\n \n- Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n+==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n This list of 4-byte values store the second through nth parents for\n all octopus merges. The second parent value in the commit data stores\n an array position within this list along with the most-significant bit\n@@ -120,14 +133,14 @@ CHUNK DATA:\n positions for the parents until reaching a value with the most-significant\n bit on. The other bits correspond to the position of the last parent.\n \n- Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n+==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters\n from commit 0 to commit i (inclusive) in lexicographic order. The Bloom\n filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header\n length), where BIDX[-1] is 0.\n * The BIDX chunk is ignored if the BDAT chunk is not present.\n \n- Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n+==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n * It starts with header consisting of three unsigned 32-bit integers:\n - Version of the hash algorithm being used. We currently only support\n \tvalue 1 which corresponds to the 32-bit version of the murmur3 hash\n@@ -147,13 +160,13 @@ CHUNK DATA:\n of length one, with either all bits set to zero or one respectively.\n * The BDAT chunk is present if and only if BIDX is present.\n \n- Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n+==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n This list of H-byte hashes describe a set of B commit-graph files that\n form a commit-graph chain. The graph position for the ith commit in this\n file's OID Lookup chunk is equal to i plus the number of commits in all\n base graphs. If B is non-zero, this chunk must exist.\n \n-TRAILER:\n+=== TRAILER:\n \n \tH-byte HASH-checksum of all of the above.\n \n@@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote\n possibly erroneous data in these chunks with the IDs \"GDAT\" and \"GDOV\". By\n changing the IDs, newer versions of Git will silently ignore those older\n chunks and write the new information without trusting the incorrect data.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/chunk-format.txt b/Documentation/technical/chunk-format.txt\nindex 593614fceda..f36ce42f37c 100644\n--- a/Documentation/technical/chunk-format.txt\n+++ b/Documentation/technical/chunk-format.txt\n@@ -6,7 +6,7 @@ sections of the file. This allows structured access to a large file by\n scanning a small \"table of contents\" for the remaining data. This common\n format is used by the `commit-graph` and `multi-pack-index` files. See\n link:technical/pack-format.html[the `multi-pack-index` format] and\n-link:technical/commit-graph-format.html[the `commit-graph` format] for\n+the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n how they use the chunks to describe structured data.\n \n A chunk-based file format begins with some header information custom to\n@@ -108,7 +108,7 @@ for future formats:\n * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()`\n in `commit-graph.c` for how the chunk-format API is used to write and\n parse the commit-graph file format documented in\n- link:technical/commit-graph-format.html[the commit-graph file format].\n+ the commit-graph file format in linkgit:gitformat-commit-graph[5].\n \n * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n in `midx.c` for how the chunk-format API is used to write and\ndiff --git a/command-list.txt b/command-list.txt\nindex 1950c4ccd9c..44e244a76f6 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -210,6 +210,8 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle developerinterfaces\n+gitformat-bundle developerinterfaces\n+gitformat-commit-graph developerinterfaces\n gitglossary guide\n githooks userinterfaces\n gitignore userinterfaces\n-- \n2.37.1.1232.gc0cde427aa7\n\n"},{"id":"460426","messageId":"patch-v7-07.10-cfd1b0afb53-20220802T125258Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v7-00.10-00000000000-20220802T125258Z-avarab@gmail.com","subject":"[PATCH v7 07/10] docs: move protocol-related docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-02T12:56:56Z","receivedAt":"2022-08-02T12:58:33Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space. By moving\nthe things that discuss the protocol we can properly link from\ne.g. lsrefs.unborn and protocol.version documentation to a manpage we\nbuild by default.\n\nSo far we have been using the \"gitformat-\" prefix for the\ndocumentation we've been moving over from Documentation/technical/*,\nbut for protocol documentation let's use \"gitprotocol-*\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 8 +++---\n Documentation/config/lsrefs.txt | 2 +-\n Documentation/config/protocol.txt | 2 +-\n Documentation/git-upload-pack.txt | 5 ++--\n Documentation/gitformat-bundle.txt | 2 +-\n ...ities.txt => gitprotocol-capabilities.txt} | 28 +++++++++++++++----\n ...ocol-common.txt => gitprotocol-common.txt} | 23 +++++++++++++--\n ...pack-protocol.txt => gitprotocol-pack.txt} | 24 +++++++++++++---\n .../protocol-v2.txt => gitprotocol-v2.txt} | 25 +++++++++++++----\n Documentation/technical/api-simple-ipc.txt | 2 +-\n Documentation/technical/http-protocol.txt | 6 ++--\n .../long-running-process-protocol.txt | 2 +-\n Documentation/technical/packfile-uri.txt | 2 +-\n Documentation/technical/partial-clone.txt | 2 +-\n command-list.txt | 5 +++-\n refspec.h | 2 +-\n t/t5551-http-fetch-smart.sh | 4 +--\n 17 files changed, 106 insertions(+), 38 deletions(-)\n rename Documentation/{technical/protocol-capabilities.txt => gitprotocol-capabilities.txt} (96%)\n rename Documentation/{technical/protocol-common.txt => gitprotocol-common.txt} (89%)\n rename Documentation/{technical/pack-protocol.txt => gitprotocol-pack.txt} (98%)\n rename Documentation/{technical/protocol-v2.txt => gitprotocol-v2.txt} (98%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex e7bd72bb84e..b53f3c12843 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -30,6 +30,10 @@ MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n MAN5_TXT += gitmodules.txt\n+MAN5_TXT += gitprotocol-capabilities.txt\n+MAN5_TXT += gitprotocol-common.txt\n+MAN5_TXT += gitprotocol-pack.txt\n+MAN5_TXT += gitprotocol-v2.txt\n MAN5_TXT += gitrepository-layout.txt\n MAN5_TXT += gitweb.conf.txt\n \n@@ -105,12 +109,8 @@ TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n-TECH_DOCS += technical/pack-protocol\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\n-TECH_DOCS += technical/protocol-capabilities\n-TECH_DOCS += technical/protocol-common\n-TECH_DOCS += technical/protocol-v2\n TECH_DOCS += technical/racy-git\n TECH_DOCS += technical/reftable\n TECH_DOCS += technical/send-pack-pipeline\ndiff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.txt\nindex adeda0f24d3..3d88fb0badb 100644\n--- a/Documentation/config/lsrefs.txt\n+++ b/Documentation/config/lsrefs.txt\n@@ -1,7 +1,7 @@\n lsrefs.unborn::\n \tMay be \"advertise\" (the default), \"allow\", or \"ignore\". If \"advertise\",\n \tthe server will respond to the client sending \"unborn\" (as described in\n-\tprotocol-v2.txt) and will advertise support for this feature during the\n+\tlinkgit:gitprotocol-v2[5]) and will advertise support for this feature during the\n \tprotocol v2 capability advertisement. \"allow\" is the same as\n \t\"advertise\" except that the server will not advertise support for this\n \tfeature; this is useful for load-balanced servers that cannot be\ndiff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt\nindex 756591d77b0..57603818514 100644\n--- a/Documentation/config/protocol.txt\n+++ b/Documentation/config/protocol.txt\n@@ -58,6 +58,6 @@ protocol.version::\n * `1` - the original wire protocol with the addition of a version string\n in the initial response from the server.\n \n-* `2` - link:technical/protocol-v2.html[wire protocol version 2].\n+* `2` - Wire protocol version 2, see linkgit:gitprotocol-v2[5].\n \n --\ndiff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt\nindex 8f87b23ea86..3409e0d36d1 100644\n--- a/Documentation/git-upload-pack.txt\n+++ b/Documentation/git-upload-pack.txt\n@@ -40,9 +40,8 @@ OPTIONS\n \tUsed by linkgit:git-http-backend[1] to serve up\n \t`$GIT_URL/info/refs?service=git-upload-pack` requests. See\n \t\"Smart Clients\" in link:technical/http-protocol.html[the HTTP\n-\ttransfer protocols] documentation and \"HTTP Transport\" in\n-\tlink:technical/protocol-v2.html[the Git Wire Protocol, Version\n-\t2] documentation. Also understood by\n+\ttransfer protocols] documentation and \"HTTP Transport\" in the\n+\tlinkgit:gitprotocol-v2[5] documentation. Also understood by\n \tlinkgit:git-receive-pack[1].\n \n ::\ndiff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.txt\nindex 6a9d9e5bf6f..00e0a20e657 100644\n--- a/Documentation/gitformat-bundle.txt\n+++ b/Documentation/gitformat-bundle.txt\n@@ -27,7 +27,7 @@ FORMAT\n ------\n \n We will use ABNF notation to define the Git bundle format. See\n-link:technical/protocol-common.html for the details.\n+linkgit:gitprotocol-common[5] for the details.\n \n A v2 bundle looks like this:\n \ndiff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/gitprotocol-capabilities.txt\nsimilarity index 96%\nrename from Documentation/technical/protocol-capabilities.txt\nrename to Documentation/gitprotocol-capabilities.txt\nindex 9dfade930da..c6dcc7d565d 100644\n--- a/Documentation/technical/protocol-capabilities.txt\n+++ b/Documentation/gitprotocol-capabilities.txt\n@@ -1,8 +1,20 @@\n-Git Protocol Capabilities\n-=========================\n+gitprotocol-capabilities(5)\n+===========================\n+\n+NAME\n+----\n+gitprotocol-capabilities - Protocol v0 and v1 capabilities\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n NOTE: this document describes capabilities for versions 0 and 1 of the pack\n-protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]\n+protocol. For version 2, please refer to the linkgit:gitprotocol-v2[5]\n doc.\n \n Servers SHOULD support all capabilities defined in this document.\n@@ -77,7 +89,7 @@ interleaved with S-R-Q.\n multi_ack_detailed\n ------------------\n This is an extension of multi_ack that permits client to better\n-understand the server's in-memory state. See pack-protocol.txt,\n+understand the server's in-memory state. See linkgit:gitprotocol-pack[5],\n section \"Packfile Negotiation\" for more information.\n \n no-done\n@@ -281,7 +293,7 @@ a packfile upload and reference update. If the pushing client requests\n this capability, after unpacking and updating references the server\n will respond with whether the packfile unpacked successfully and if\n each reference was updated successfully. If any of those were not\n-successful, it will send back an error message. See pack-protocol.txt\n+successful, it will send back an error message. See linkgit:gitprotocol-pack[5]\n for example messages.\n \n report-status-v2\n@@ -292,7 +304,7 @@ adding new \"option\" directives in order to support reference rewritten by\n the \"proc-receive\" hook. The \"proc-receive\" hook may handle a command\n for a pseudo-reference which may create or update a reference with\n different name, new-oid, and old-oid. While the capability\n-'report-status' cannot report for such case. See pack-protocol.txt\n+'report-status' cannot report for such case. See linkgit:gitprotocol-pack[5]\n for details.\n \n delete-refs\n@@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The\n current implementation uses trace2 session IDs (see\n link:api-trace2.html[api-trace2] for details), but this may change and users of\n the session ID should not rely on this fact.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-common.txt b/Documentation/gitprotocol-common.txt\nsimilarity index 89%\nrename from Documentation/technical/protocol-common.txt\nrename to Documentation/gitprotocol-common.txt\nindex ecedb34bba5..1486651bd10 100644\n--- a/Documentation/technical/protocol-common.txt\n+++ b/Documentation/gitprotocol-common.txt\n@@ -1,5 +1,20 @@\n-Documentation Common to Pack and Http Protocols\n-===============================================\n+gitprotocol-common(5)\n+=====================\n+\n+NAME\n+----\n+gitprotocol-common - Things common to various protocols\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n+\n+This document sets defines things common to various over-the-wire\n+protocols and file formats used in Git.\n \n ABNF Notation\n -------------\n@@ -97,3 +112,7 @@ Examples (as C-style strings):\n \"000bfoobar\\n\" \"foobar\\n\"\n \"0004\" \"\"\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitprotocol-pack.txt\nsimilarity index 98%\nrename from Documentation/technical/pack-protocol.txt\nrename to Documentation/gitprotocol-pack.txt\nindex e13a2c064d1..8a4de6decd0 100644\n--- a/Documentation/technical/pack-protocol.txt\n+++ b/Documentation/gitprotocol-pack.txt\n@@ -1,5 +1,17 @@\n-Packfile transfer protocols\n-===========================\n+gitprotocol-pack(5)\n+===================\n+\n+NAME\n+----\n+gitprotocol-pack - How packs are transferred over-the-wire\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n Git supports transferring data in packfiles over the ssh://, git://, http:// and\n file:// transports. There exist two sets of protocols, one for pushing\n@@ -18,7 +30,7 @@ pkt-line Format\n ---------------\n \n The descriptions below build on the pkt-line format described in\n-protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless\n+linkgit:gitprotocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless\n otherwise noted the usual pkt-line LF rules apply: the sender SHOULD\n include a LF, but the receiver MUST NOT complain if it is not present.\n \n@@ -60,7 +72,7 @@ Each Extra Parameter takes the form of `=` or ``.\n \n Servers that receive any such Extra Parameters MUST ignore all\n unrecognized keys. Currently, the only Extra Parameter recognized is\n-\"version\" with a value of '1' or '2'. See protocol-v2.txt for more\n+\"version\" with a value of '1' or '2'. See linkgit:gitprotocol-v2[5] for more\n information on protocol version 2.\n \n Git Transport\n@@ -707,3 +719,7 @@ An example client/server communication might look like this:\n S: 0018ok refs/heads/debug\\n\n S: 002ang refs/heads/master non-fast-forward\\n\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-v2.txt b/Documentation/gitprotocol-v2.txt\nsimilarity index 98%\nrename from Documentation/technical/protocol-v2.txt\nrename to Documentation/gitprotocol-v2.txt\nindex 8a877d27e23..d6105e07408 100644\n--- a/Documentation/technical/protocol-v2.txt\n+++ b/Documentation/gitprotocol-v2.txt\n@@ -1,5 +1,17 @@\n-Git Wire Protocol, Version 2\n-============================\n+gitprotocol-v2(5)\n+=================\n+\n+NAME\n+----\n+gitprotocol-v2 - Git Wire Protocol, Version 2\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n This document presents a specification for a version 2 of Git's wire\n protocol. Protocol v2 will improve upon v1 in the following ways:\n@@ -26,8 +38,7 @@ Packet-Line Framing\n -------------------\n \n All communication is done using packet-line framing, just as in v1. See\n-`Documentation/technical/pack-protocol.txt` and\n-`Documentation/technical/protocol-common.txt` for more information.\n+linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-common[5] for more information.\n \n In protocol v2 these special packets will have the following semantics:\n \n@@ -42,7 +53,7 @@ Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`. More information can be\n-found in `pack-protocol.txt` and `http-protocol.txt`, as well as the\n+found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the\n `GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n@@ -566,3 +577,7 @@ and associated requested information, each separated by a single space.\n \tattr = \"size\"\n \n \tobj-info = obj-id SP obj-size\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt\nindex d79ad323e67..d44ada98e7d 100644\n--- a/Documentation/technical/api-simple-ipc.txt\n+++ b/Documentation/technical/api-simple-ipc.txt\n@@ -78,7 +78,7 @@ client and an optional response message from the server. Both the\n client and server messages are unlimited in length and are terminated\n with a flush packet.\n \n-The pkt-line routines (Documentation/technical/protocol-common.txt)\n+The pkt-line routines (linkgit:gitprotocol-common[5])\n are used to simplify buffer management during message generation,\n transmission, and reception. A flush packet is used to mark the end\n of the message. This allows the sender to incrementally generate and\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt\nindex cc5126cfeda..8bd672d55bb 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/technical/http-protocol.txt\n@@ -222,7 +222,7 @@ smart server reply:\n S: 0000\n \n The client may send Extra Parameters (see\n-Documentation/technical/pack-protocol.txt) as a colon-separated string\n+linkgit:gitprotocol-pack[5]) as a colon-separated string\n in the Git-Protocol HTTP header.\n \n Uses the `--http-backend-info-refs` option to\n@@ -518,5 +518,5 @@ References\n \n http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n-link:technical/pack-protocol.html\n-link:technical/protocol-capabilities.html\n+linkgit:gitprotocol-pack[5]\n+linkgit:gitprotocol-capabilities[5]\ndiff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt\nindex aa0aa9af1c2..6f33654b428 100644\n--- a/Documentation/technical/long-running-process-protocol.txt\n+++ b/Documentation/technical/long-running-process-protocol.txt\n@@ -3,7 +3,7 @@ Long-running process protocol\n \n This protocol is used when Git needs to communicate with an external\n process throughout the entire life of a single Git command. All\n-communication is in pkt-line format (see technical/protocol-common.txt)\n+communication is in pkt-line format (see linkgit:gitprotocol-common[5])\n over standard input and standard output.\n \n Handshake\ndiff --git a/Documentation/technical/packfile-uri.txt b/Documentation/technical/packfile-uri.txt\nindex 1eb525fe760..9d453d47651 100644\n--- a/Documentation/technical/packfile-uri.txt\n+++ b/Documentation/technical/packfile-uri.txt\n@@ -18,7 +18,7 @@ a `packfile-uris` argument, the server MAY send a `packfile-uris` section\n directly before the `packfile` section (right after `wanted-refs` if it is\n sent) containing URIs of any of the given protocols. The URIs point to\n packfiles that use only features that the client has declared that it supports\n-(e.g. ofs-delta and thin-pack). See protocol-v2.txt for the documentation of\n+(e.g. ofs-delta and thin-pack). See linkgit:gitprotocol-v2[5] for the documentation of\n this section.\n \n Clients should then download and index all the given URIs (in addition to\ndiff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt\nindex 99f0eb30406..92fcee2bfff 100644\n--- a/Documentation/technical/partial-clone.txt\n+++ b/Documentation/technical/partial-clone.txt\n@@ -79,7 +79,7 @@ Design Details\n upload-pack negotiation.\n +\n This uses the existing capability discovery mechanism.\n-See \"filter\" in Documentation/technical/pack-protocol.txt.\n+See \"filter\" in linkgit:gitprotocol-pack[5].\n \n - Clients pass a \"filter-spec\" to clone and fetch which is passed to the\n server to request filtering during packfile construction.\ndiff --git a/command-list.txt b/command-list.txt\nindex 44e244a76f6..ed859fdd798 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -210,7 +210,6 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle developerinterfaces\n-gitformat-bundle developerinterfaces\n gitformat-commit-graph developerinterfaces\n gitglossary guide\n githooks userinterfaces\n@@ -219,6 +218,10 @@ gitk mainporcelain\n gitmailmap userinterfaces\n gitmodules userinterfaces\n gitnamespaces guide\n+gitprotocol-capabilities developerinterfaces\n+gitprotocol-common developerinterfaces\n+gitprotocol-pack developerinterfaces\n+gitprotocol-v2 developerinterfaces\n gitremote-helpers guide\n gitrepository-layout userinterfaces\n gitrevisions userinterfaces\ndiff --git a/refspec.h b/refspec.h\nindex 8b79891d321..8c0c4469933 100644\n--- a/refspec.h\n+++ b/refspec.h\n@@ -69,7 +69,7 @@ int valid_remote_name(const char *name);\n struct strvec;\n /*\n * Determine what values to pass to the peer in ref-prefix lines\n- * (see Documentation/technical/protocol-v2.txt).\n+ * (see linkgit:gitprotocol-v2[5]).\n */\n void refspec_ref_prefixes(const struct refspec *rs,\n \t\t\t struct strvec *ref_prefixes);\ndiff --git a/t/t5551-http-fetch-smart.sh b/t/t5551-http-fetch-smart.sh\nindex 245532df881..6a38294a476 100755\n--- a/t/t5551-http-fetch-smart.sh\n+++ b/t/t5551-http-fetch-smart.sh\n@@ -181,8 +181,8 @@ test_expect_success 'no-op half-auth fetch does not require a password' '\n \t# This is not possible with protocol v2, since both objects and refs\n \t# are obtained from the \"git-upload-pack\" path. A solution to this is\n \t# to teach the server and client to be able to inline ls-refs requests\n-\t# as an Extra Parameter (see pack-protocol.txt), so that \"info/refs\"\n-\t# can serve refs, just like it does in protocol v0.\n+\t# as an Extra Parameter (see \"git help gitformat-pack-protocol\"), so that\n+\t# \"info/refs\" can serve refs, just like it does in protocol v0.\n \tGIT_TEST_PROTOCOL_VERSION=0 git --git-dir=half-auth fetch &&\n \texpect_askpass none\n '\n-- \n2.37.1.1232.gc0cde427aa7\n\n"},{"id":"460427","messageId":"patch-v7-09.10-c4a7fe9d439-20220802T125258Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v7-00.10-00000000000-20220802T125258Z-avarab@gmail.com","subject":"[PATCH v7 09/10] docs: move http-protocol docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-02T12:56:58Z","receivedAt":"2022-08-02T12:58:36Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe http-protocol.txt documentation over. I'm renaming it to\n\"protocol-http\" to be consistent with other things in the new\ngitformat-protocol-* namespace.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 2 +-\n Documentation/git-upload-pack.txt | 6 ++--\n ...http-protocol.txt => gitprotocol-http.txt} | 29 ++++++++++++++++---\n Documentation/gitprotocol-pack.txt | 2 +-\n Documentation/gitprotocol-v2.txt | 4 +--\n command-list.txt | 1 +\n 6 files changed, 33 insertions(+), 11 deletions(-)\n rename Documentation/{technical/http-protocol.txt => gitprotocol-http.txt} (98%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex cd09ccd8c13..6efac142e3e 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -37,6 +37,7 @@ MAN5_TXT += gitmailmap.txt\n MAN5_TXT += gitmodules.txt\n MAN5_TXT += gitprotocol-capabilities.txt\n MAN5_TXT += gitprotocol-common.txt\n+MAN5_TXT += gitprotocol-http.txt\n MAN5_TXT += gitprotocol-pack.txt\n MAN5_TXT += gitprotocol-v2.txt\n MAN5_TXT += gitrepository-layout.txt\n@@ -107,7 +108,6 @@ TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n TECH_DOCS += technical/hash-function-transition\n-TECH_DOCS += technical/http-protocol\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-heuristics\ndiff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt\nindex 3409e0d36d1..3f89d640772 100644\n--- a/Documentation/git-upload-pack.txt\n+++ b/Documentation/git-upload-pack.txt\n@@ -39,9 +39,9 @@ OPTIONS\n --http-backend-info-refs::\n \tUsed by linkgit:git-http-backend[1] to serve up\n \t`$GIT_URL/info/refs?service=git-upload-pack` requests. See\n-\t\"Smart Clients\" in link:technical/http-protocol.html[the HTTP\n-\ttransfer protocols] documentation and \"HTTP Transport\" in the\n-\tlinkgit:gitprotocol-v2[5] documentation. Also understood by\n+\t\"Smart Clients\" in linkgit:gitprotocol-http[5] and \"HTTP\n+\tTransport\" in in the linkgit:gitprotocol-v2[5]\n+\tdocumentation. Also understood by\n \tlinkgit:git-receive-pack[1].\n \n ::\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/gitprotocol-http.txt\nsimilarity index 98%\nrename from Documentation/technical/http-protocol.txt\nrename to Documentation/gitprotocol-http.txt\nindex 8bd672d55bb..ccc13f0a407 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/gitprotocol-http.txt\n@@ -1,5 +1,19 @@\n-HTTP transfer protocols\n-=======================\n+gitprotocol-http(5)\n+===================\n+\n+NAME\n+----\n+gitprotocol-http - Git HTTP-based protocols\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+\n+DESCRIPTION\n+-----------\n \n Git supports two HTTP based transfer protocols. A \"dumb\" protocol\n which requires only a standard HTTP server on the server end of the\n@@ -512,11 +526,18 @@ the id obtained through ref discovery as old_id.\n \n TODO: Document this further.\n \n-\n-References\n+REFERENCES\n ----------\n \n http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n+\n+SEE ALSO\n+--------\n+\n linkgit:gitprotocol-pack[5]\n linkgit:gitprotocol-capabilities[5]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.txt\nindex 93b30b88450..dd4108b7a3b 100644\n--- a/Documentation/gitprotocol-pack.txt\n+++ b/Documentation/gitprotocol-pack.txt\n@@ -17,7 +17,7 @@ Git supports transferring data in packfiles over the ssh://, git://, http:// and\n file:// transports. There exist two sets of protocols, one for pushing\n data from a client to a server and another for fetching data from a\n server to a client. The three transports (ssh, git, file) use the same\n-protocol to transfer data. http is documented in http-protocol.txt.\n+protocol to transfer data. http is documented in linkgit:gitprotocol-http[5].\n \n The processes invoked in the canonical Git implementation are 'upload-pack'\n on the server side and 'fetch-pack' on the client side for fetching data;\ndiff --git a/Documentation/gitprotocol-v2.txt b/Documentation/gitprotocol-v2.txt\nindex d6105e07408..c9c0f9160b2 100644\n--- a/Documentation/gitprotocol-v2.txt\n+++ b/Documentation/gitprotocol-v2.txt\n@@ -53,7 +53,7 @@ Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`. More information can be\n-found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the\n+found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the\n `GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n@@ -77,7 +77,7 @@ HTTP Transport\n ~~~~~~~~~~~~~~\n \n When using the http:// or https:// transport a client makes a \"smart\"\n-info/refs request as described in `http-protocol.txt` and requests that\n+info/refs request as described in linkgit:gitprotocol-http[5] and requests that\n v2 be used by supplying \"version=2\" in the `Git-Protocol` header.\n \n C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0\ndiff --git a/command-list.txt b/command-list.txt\nindex 4f30a6c30c8..2d5d6d17fb1 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -225,6 +225,7 @@ gitmodules userinterfaces\n gitnamespaces guide\n gitprotocol-capabilities developerinterfaces\n gitprotocol-common developerinterfaces\n+gitprotocol-http developerinterfaces\n gitprotocol-pack developerinterfaces\n gitprotocol-v2 developerinterfaces\n gitremote-helpers guide\n-- \n2.37.1.1232.gc0cde427aa7\n\n"},{"id":"460428","messageId":"patch-v7-08.10-3505fa86039-20220802T125258Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v7-00.10-00000000000-20220802T125258Z-avarab@gmail.com","subject":"[PATCH v7 08/10] docs: move pack format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-02T12:56:57Z","receivedAt":"2022-08-02T12:58:38Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe various documentation pertaining to the *.pack format and related\nfiles, and updating things that refer to it to link to the new\nlocation.\n\nBy moving these we can properly link from the newly created\ngitformat-commit-graph do to a gitformat-chunk-format manpage we build\nby default.\n\nCreating a \"gitformat-pack-bitmap\" from\n\"Documentation/technical/bitmap-format\" might logically be part of\nthis change, but it's left out for now due to a conflict with the\nin-flight ac/bitmap-lookup-table series.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 9 ++---\n Documentation/config/pack.txt | 2 +-\n Documentation/git-bundle.txt | 3 +-\n Documentation/git-multi-pack-index.txt | 4 +--\n .../chunk-format.txt => gitformat-chunk.txt} | 25 +++++++++++---\n Documentation/gitformat-commit-graph.txt | 2 +-\n .../index-format.txt => gitformat-index.txt} | 22 ++++++++++--\n ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++++--\n .../pack-format.txt => gitformat-pack.txt} | 34 +++++++++++++++++--\n ...ure-format.txt => gitformat-signature.txt} | 21 ++++++++++--\n Documentation/gitprotocol-pack.txt | 2 +-\n .../howto/recover-corrupted-object-harder.txt | 2 +-\n .../technical/hash-function-transition.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n cache.h | 3 +-\n command-list.txt | 5 +++\n pack-revindex.h | 2 +-\n 17 files changed, 131 insertions(+), 31 deletions(-)\n rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (91%)\n rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)\n rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%)\n rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)\n rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex b53f3c12843..cd09ccd8c13 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -25,7 +25,12 @@ MAN1_TXT += gitweb.txt\n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n+MAN5_TXT += gitformat-chunk.txt\n MAN5_TXT += gitformat-commit-graph.txt\n+MAN5_TXT += gitformat-index.txt\n+MAN5_TXT += gitformat-pack-cruft.txt\n+MAN5_TXT += gitformat-pack.txt\n+MAN5_TXT += gitformat-signature.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -101,13 +106,10 @@ TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n-TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n-TECH_DOCS += technical/index-format\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n-TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\n@@ -115,7 +117,6 @@ TECH_DOCS += technical/racy-git\n TECH_DOCS += technical/reftable\n TECH_DOCS += technical/send-pack-pipeline\n TECH_DOCS += technical/shallow\n-TECH_DOCS += technical/signature-format\n TECH_DOCS += technical/trivial-merge\n SP_ARTICLES += $(TECH_DOCS)\n SP_ARTICLES += technical/api-index\ndiff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt\nindex ad7f73a1ead..3e581eab84a 100644\n--- a/Documentation/config/pack.txt\n+++ b/Documentation/config/pack.txt\n@@ -166,7 +166,7 @@ permuted into their appropriate location when writing a new bitmap.\n \n pack.writeReverseIndex::\n \tWhen true, git will write a corresponding .rev file (see:\n-\tlink:../technical/pack-format.html[Documentation/technical/pack-format.txt])\n+\tlinkgit:gitformat-pack[5])\n \tfor each new packfile that it writes in all places except for\n \tlinkgit:git-fast-import[1] and in the bulk checkin mechanism.\n \tDefaults to false.\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex f0b1282b918..6da61722431 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -57,8 +57,7 @@ size. That they're \"thin\" under the hood is merely noted here as a\n curiosity, and as a reference to other documentation.\n \n See linkgit:gitformat-bundle[5] for more details and the discussion of\n-\"thin pack\" in link:technical/pack-format.html[the pack format\n-documentation] for further details.\n+\"thin pack\" in linkgit:gitformat-pack[5] for further details.\n \n OPTIONS\n -------\ndiff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt\nindex c588fb91af1..a48c3d5ea63 100644\n--- a/Documentation/git-multi-pack-index.txt\n+++ b/Documentation/git-multi-pack-index.txt\n@@ -128,8 +128,8 @@ $ git multi-pack-index verify\n SEE ALSO\n --------\n See link:technical/multi-pack-index.html[The Multi-Pack-Index Design\n-Document] and link:technical/pack-format.html[The Multi-Pack-Index\n-Format] for more information on the multi-pack-index feature.\n+Document] and linkgit:gitformat-pack[5] for more information on the\n+multi-pack-index feature and its file format.\n \n \n GIT\ndiff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt\nsimilarity index 91%\nrename from Documentation/technical/chunk-format.txt\nrename to Documentation/gitformat-chunk.txt\nindex f36ce42f37c..57202ede273 100644\n--- a/Documentation/technical/chunk-format.txt\n+++ b/Documentation/gitformat-chunk.txt\n@@ -1,11 +1,24 @@\n-Chunk-based file formats\n-========================\n+gitformat-chunk(5)\n+==================\n+\n+NAME\n+----\n+gitformat-chunk - Chunk-based file formats\n+\n+SYNOPSIS\n+--------\n+\n+Used by linkgit:gitformat-commit-graph[5] and the \"MIDX\" format (see\n+the pack format documentation in linkgit:gitformat-pack[5]).\n+\n+DESCRIPTION\n+-----------\n \n Some file formats in Git use a common concept of \"chunks\" to describe\n sections of the file. This allows structured access to a large file by\n scanning a small \"table of contents\" for the remaining data. This common\n format is used by the `commit-graph` and `multi-pack-index` files. See\n-link:technical/pack-format.html[the `multi-pack-index` format] and\n+the `multi-pack-index` format in linkgit:gitformat-pack[5] and\n the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n how they use the chunks to describe structured data.\n \n@@ -113,4 +126,8 @@ for future formats:\n * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n in `midx.c` for how the chunk-format API is used to write and\n parse the multi-pack-index file format documented in\n- link:technical/pack-format.html[the multi-pack-index file format].\n+ the multi-pack-index file format section of linkgit:gitformat-pack[5].\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt\nindex 108dc2295c0..7324665716d 100644\n--- a/Documentation/gitformat-commit-graph.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -75,7 +75,7 @@ All multi-byte numbers are in network byte order.\n ID appears at most once.\n \n The CHUNK LOOKUP matches the table of contents from\n- link:technical/chunk-format.html[the chunk-based file format].\n+ the chunk-based file format, see linkgit:gitformat-chunk[5]\n \n The remaining data in the body is described one chunk at a time, and\n these chunks may be given in any order. Chunks are required unless\ndiff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt\nsimilarity index 98%\nrename from Documentation/technical/index-format.txt\nrename to Documentation/gitformat-index.txt\nindex f691c20ab0a..015cb21bdc0 100644\n--- a/Documentation/technical/index-format.txt\n+++ b/Documentation/gitformat-index.txt\n@@ -1,5 +1,19 @@\n+gitformat-index(5)\n+==================\n+\n+NAME\n+----\n+gitformat-index - Git index format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/index\n+\n+DESCRIPTION\n+-----------\n+\n Git index format\n-================\n \n == The Git index file has the following format\n \n@@ -125,7 +139,7 @@ Git index format\n entry is encoded as if the path name for the previous entry is an\n empty string). At the beginning of an entry, an integer N in the\n variable width encoding (the same encoding as the offset is encoded\n- for OFS_DELTA pack entries; see pack-format.txt) is stored, followed\n+ for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed\n by a NUL-terminated string S. Removing N bytes from the end of the\n path name for the previous entry, and replacing it with the string S\n yields the path name for this entry.\n@@ -402,3 +416,7 @@ The remaining data of each directory block is grouped by type:\n with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,\n tools should avoid interacting with a sparse index unless they understand\n this extension.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/cruft-packs.txt b/Documentation/gitformat-pack-cruft.txt\nsimilarity index 96%\nrename from Documentation/technical/cruft-packs.txt\nrename to Documentation/gitformat-pack-cruft.txt\nindex d81f3a8982f..908f752bd84 100644\n--- a/Documentation/technical/cruft-packs.txt\n+++ b/Documentation/gitformat-pack-cruft.txt\n@@ -1,4 +1,17 @@\n-= Cruft packs\n+gitformat-pack-cruft(5)\n+=======================\n+\n+NAME\n+----\n+gitformat-pack-cruft - The cruft pack file format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/pack-*.mtimes\n+\n+DESCRIPTION\n+-----------\n \n The cruft packs feature offer an alternative to Git's traditional mechanism of\n removing unreachable objects. This document provides an overview of Git's\n@@ -10,10 +23,11 @@ same.\n To remove unreachable objects from your repository, Git offers `git repack -Ad`\n (see linkgit:git-repack[1]). Quoting from the documentation:\n \n-[quote]\n+----\n [...] unreachable objects in a previous pack become loose, unpacked objects,\n instead of being left in the old pack. [...] loose unreachable objects will be\n pruned according to normal expiry rules with the next 'git gc' invocation.\n+----\n \n Unreachable objects aren't removed immediately, since doing so could race with\n an incoming push which may reference an object which is about to be deleted.\n@@ -121,3 +135,7 @@ which aren't already stored in an earlier cruft pack) is significantly more\n complicated to construct, and so aren't pursued here. The obvious drawback to\n the current implementation is that the entire cruft pack must be re-written from\n scratch.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/pack-format.txt b/Documentation/gitformat-pack.txt\nsimilarity index 95%\nrename from Documentation/technical/pack-format.txt\nrename to Documentation/gitformat-pack.txt\nindex b520aa9c45b..546c99f8871 100644\n--- a/Documentation/technical/pack-format.txt\n+++ b/Documentation/gitformat-pack.txt\n@@ -1,5 +1,29 @@\n-Git pack format\n-===============\n+gitformat-pack(5)\n+=================\n+\n+NAME\n+----\n+gitformat-pack - Git pack format\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/pack-*.{pack,idx}\n+$GIT_DIR/objects/pack/pack-*.rev\n+$GIT_DIR/objects/pack/multi-pack-index\n+\n+DESCRIPTION\n+-----------\n+\n+The Git pack format is now Git stores most of its primary repository\n+data. Over the lietime af a repository loose objects (if any) and\n+smaller packs are consolidated into larger pack(s). See\n+linkgit:git-gc[1] and linkgit:git-pack-objects[1].\n+\n+The pack format is also used over-the-wire, see\n+e.g. linkgit:gitprotocol-v2[5], as well as being a part of\n+other container formats in the case of linkgit:gitformat-bundle[5].\n \n == Checksums and object IDs\n \n@@ -356,7 +380,7 @@ CHUNK LOOKUP:\n \t using the next chunk position if necessary.)\n \n \tThe CHUNK LOOKUP matches the table of contents from\n-\tlink:technical/chunk-format.html[the chunk-based file format].\n+\tthe chunk-based file format, see linkgit:gitformat-chunk[5].\n \n \tThe remaining data in the body is described one chunk at a time, and\n \tthese chunks may be given in any order. Chunks are required unless\n@@ -482,3 +506,7 @@ packs arranged in MIDX order (with the preferred pack coming first).\n \n The MIDX's reverse index is stored in the optional 'RIDX' chunk within\n the MIDX itself.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt\nsimilarity index 96%\nrename from Documentation/technical/signature-format.txt\nrename to Documentation/gitformat-signature.txt\nindex 166721be6f6..a249869fafa 100644\n--- a/Documentation/technical/signature-format.txt\n+++ b/Documentation/gitformat-signature.txt\n@@ -1,7 +1,18 @@\n-Git signature format\n-====================\n+gitformat-signature(5)\n+======================\n \n-== Overview\n+NAME\n+----\n+gitformat-signature - Git cryptographic signature formats\n+\n+SYNOPSIS\n+--------\n+[verse]\n+<[tag|commit] object header(s)>\n+\n+\n+DESCRIPTION\n+-----------\n \n Git uses cryptographic signatures in various places, currently objects (tags,\n commits, mergetags) and transactions (pushes). In every case, the command which\n@@ -200,3 +211,7 @@ Date: Wed Jun 15 09:13:29 2016 +0000\n # gpg: There is no indication that the signature belongs to the owner.\n # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.txt\nindex 8a4de6decd0..93b30b88450 100644\n--- a/Documentation/gitprotocol-pack.txt\n+++ b/Documentation/gitprotocol-pack.txt\n@@ -467,7 +467,7 @@ Now that the client and server have finished negotiation about what\n the minimal amount of data that needs to be sent to the client is, the server\n will construct and send the required data in packfile format.\n \n-See pack-format.txt for what the packfile itself actually looks like.\n+See linkgit:gitformat-pack[5] for what the packfile itself actually looks like.\n \n If 'side-band' or 'side-band-64k' capabilities have been specified by\n the client, the server will send the packfile data multiplexed.\ndiff --git a/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.txt\nindex 8994e2559ea..5efb4fe81ff 100644\n--- a/Documentation/howto/recover-corrupted-object-harder.txt\n+++ b/Documentation/howto/recover-corrupted-object-harder.txt\n@@ -68,7 +68,7 @@ Note that the \"object\" file isn't fit for feeding straight to zlib; it\n has the git packed object header, which is variable-length. We want to\n strip that off so we can start playing with the zlib data directly. You\n can either work your way through it manually (the format is described in\n-link:../technical/pack-format.html[Documentation/technical/pack-format.txt]),\n+linkgit:gitformat-pack[5]),\n or you can walk through it in a debugger. I did the latter, creating a\n valid pack like:\n \ndiff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt\nindex 260224b0331..e2ac36dd210 100644\n--- a/Documentation/technical/hash-function-transition.txt\n+++ b/Documentation/technical/hash-function-transition.txt\n@@ -205,7 +205,7 @@ SHA-1 content.\n Object storage\n ~~~~~~~~~~~~~~\n Loose objects use zlib compression and packed objects use the packed\n-format described in Documentation/technical/pack-format.txt, just like\n+format described in linkgit:gitformat-pack[5], just like\n today. The content that is compressed and stored uses SHA-256 content\n instead of SHA-1 content.\n \ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 865074bed4e..ca9decdd952 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -3133,7 +3133,7 @@ those \"loose\" objects.\n You can save space and make Git faster by moving these loose objects in\n to a \"pack file\", which stores a group of objects in an efficient\n compressed format; the details of how pack files are formatted can be\n-found in link:technical/pack-format.html[pack format].\n+found in link:gitformat-pack[5].\n \n To put the loose objects into a pack, just run git repack:\n \ndiff --git a/cache.h b/cache.h\nindex ac5ab4ef9d3..82755c7c0aa 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -475,8 +475,7 @@ extern struct index_state the_index;\n \n /*\n * Values in this enum (except those outside the 3 bit range) are part\n- * of pack file format. See Documentation/technical/pack-format.txt\n- * for more information.\n+ * of pack file format. See gitformat-pack(5) for more information.\n */\n enum object_type {\n \tOBJ_BAD = -1,\ndiff --git a/command-list.txt b/command-list.txt\nindex ed859fdd798..4f30a6c30c8 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -210,7 +210,12 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle developerinterfaces\n+gitformat-chunk developerinterfaces\n gitformat-commit-graph developerinterfaces\n+gitformat-index developerinterfaces\n+gitformat-pack developerinterfaces\n+gitformat-pack-cruft developerinterfaces\n+gitformat-signature developerinterfaces\n gitglossary guide\n githooks userinterfaces\n gitignore userinterfaces\ndiff --git a/pack-revindex.h b/pack-revindex.h\nindex 74f4eae668d..4974e75eb4d 100644\n--- a/pack-revindex.h\n+++ b/pack-revindex.h\n@@ -22,7 +22,7 @@\n *\n * - pack position refers to an object's position within a non-existent pack\n * described by the MIDX. The pack structure is described in\n- * Documentation/technical/pack-format.txt.\n+ * gitformat-pack(5).\n *\n * It is effectively a concatanation of all packs in the MIDX (ordered by\n * their numeric ID within the MIDX) in their original order within each\n-- \n2.37.1.1232.gc0cde427aa7\n\n"},{"id":"460429","messageId":"patch-v7-10.10-8baf1db4d30-20220802T125258Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v7-00.10-00000000000-20220802T125258Z-avarab@gmail.com","subject":"[PATCH v7 10/10] docs: move multi-pack-index docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-02T12:56:59Z","receivedAt":"2022-08-02T12:58:40Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe multi-pack-index documentation over.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 2 +-\n Documentation/git-multi-pack-index.txt | 4 ++--\n ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++++++++++++--\n Documentation/gitformat-pack.txt | 5 +++++\n command-list.txt | 1 +\n 5 files changed, 27 insertions(+), 5 deletions(-)\n rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 6efac142e3e..522d6011e7a 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -28,6 +28,7 @@ MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += gitformat-chunk.txt\n MAN5_TXT += gitformat-commit-graph.txt\n MAN5_TXT += gitformat-index.txt\n+MAN5_TXT += gitformat-multi-pack-index.txt\n MAN5_TXT += gitformat-pack-cruft.txt\n MAN5_TXT += gitformat-pack.txt\n MAN5_TXT += gitformat-signature.txt\n@@ -109,7 +110,6 @@ TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/long-running-process-protocol\n-TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-heuristics\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\ndiff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt\nindex a48c3d5ea63..0ffa8b852cd 100644\n--- a/Documentation/git-multi-pack-index.txt\n+++ b/Documentation/git-multi-pack-index.txt\n@@ -127,8 +127,8 @@ $ git multi-pack-index verify\n \n SEE ALSO\n --------\n-See link:technical/multi-pack-index.html[The Multi-Pack-Index Design\n-Document] and linkgit:gitformat-pack[5] for more information on the\n+See linkgit:git-multi-pack-index[1] and\n+linkgit:gitformat-multi-pack-index[5] for more information on the\n multi-pack-index feature and its file format.\n \n \ndiff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/gitformat-multi-pack-index.txt\nsimilarity index 94%\nrename from Documentation/technical/multi-pack-index.txt\nrename to Documentation/gitformat-multi-pack-index.txt\nindex f2221d2b441..3bca1e7b10d 100644\n--- a/Documentation/technical/multi-pack-index.txt\n+++ b/Documentation/gitformat-multi-pack-index.txt\n@@ -1,5 +1,17 @@\n-Multi-Pack-Index (MIDX) Design Notes\n-====================================\n+gitformat-multi-pack-index(5)\n+=============================\n+\n+NAME\n+----\n+gitformat-multi-pack-index - The multi-pack-index file format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/multi-pack-index\n+\n+DESCRIPTION\n+-----------\n \n The Git object directory contains a 'pack' directory containing\n packfiles (with suffix \".pack\") and pack-indexes (with suffix\n@@ -98,3 +110,7 @@ Related Links\n \n [2] https://lore.kernel.org/git/alpine.DEB.2.20.1803091557510.23109@alexmv-linux/\n Git Merge 2018 Contributor's summit notes (includes discussion of MIDX)\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt\nindex 546c99f8871..68328bada6b 100644\n--- a/Documentation/gitformat-pack.txt\n+++ b/Documentation/gitformat-pack.txt\n@@ -507,6 +507,11 @@ packs arranged in MIDX order (with the preferred pack coming first).\n The MIDX's reverse index is stored in the optional 'RIDX' chunk within\n the MIDX itself.\n \n+SEE ALSO\n+--------\n+\n+linkgit:gitformat-multi-pack-index[5]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/command-list.txt b/command-list.txt\nindex 2d5d6d17fb1..65b3e739be4 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -213,6 +213,7 @@ gitformat-bundle developerinterfaces\n gitformat-chunk developerinterfaces\n gitformat-commit-graph developerinterfaces\n gitformat-index developerinterfaces\n+gitformat-multi-pack-index developerinterfaces\n gitformat-pack developerinterfaces\n gitformat-pack-cruft developerinterfaces\n gitformat-signature developerinterfaces\n-- \n2.37.1.1232.gc0cde427aa7\n\n"},{"id":"460520","messageId":"xmqqo7x2dzbt.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-v7-01.10-2665148f45b-20220802T125258Z-avarab@gmail.com","subject":"Re: [PATCH v7 01/10] help.c: refactor drop_prefix() to use a \"switch\" statement\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-02T23:01:58Z","receivedAt":"2022-08-02T23:02:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Refactor the drop_prefix() function in in help.c to make it easier to\n> strip prefixes from categories that aren't \"CAT_guide\". There are no\n> functional changes here, by doing this we make a subsequent functional\n> change's diff smaller.\n>\n> As before we first try to strip \"git-\" unconditionally, if that works\n> we'll return the stripped string. Then we'll strip \"git\" if the\n> command is in \"CAT_guide\".\n\nOK. From the code structure's point of view, it somehow not exactly\nsatisfactory that we still need two \"skip and then if skipped yield\nthe remainder\" in this function. Especially because we only strip\nonce.\n\n> This means that we'd in principle strip \"git-gitfoo\" down to \"foo\" if\n> it's in CAT_guide. That doesn't make much sense, and we don't have\n> such an entry in command-list.txt, but let's preserve that behavior\n> for now.\n\nI am not sure if that is what the code means.\n\n\"git-gitfoo\" will become \"gitfoo\" regardless of what category we are\ncalling drop_prefix() for, because we will return the resulting name\nwithout falling through to the new switch statement, if the first\n\"strip 'git-'\" succeeds, no?\n\n> While we're at it remove a stray newline that had been added after the\n> \"return name;\" statement.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> help.c | 10 ++++++++--\n> 1 file changed, 8 insertions(+), 2 deletions(-)\n>\n> diff --git a/help.c b/help.c\n> index 41c41c2aa11..7e594d291b0 100644\n> --- a/help.c\n> +++ b/help.c\n> @@ -44,13 +44,19 @@ static struct category_description main_categories[] = {\n> static const char *drop_prefix(const char *name, uint32_t category)\n> {\n> \tconst char *new_name;\n> +\tconst char *prefix = NULL;\n> \n> \tif (skip_prefix(name, \"git-\", &new_name))\n> \t\treturn new_name;\n> -\tif (category == CAT_guide && skip_prefix(name, \"git\", &new_name))\n> +\tswitch (category) {\n> +\tcase CAT_guide:\n> +\t\tprefix = \"git\";\n> +\t\tbreak;\n> +\t}\n> +\tif (prefix && skip_prefix(name, prefix, &new_name))\n> \t\treturn new_name;\n> -\treturn name;\n> \n> +\treturn name;\n> }\n\nThe diff algorighm made an interesting choice as to which line to\nconsider common here. I would have expected to see\n\n\t\treturn new_name;\n+\n\treturn name;\n-\n }\n\nespecially after reading the last paragraph of the proposed log\nmessage.\n"},{"id":"460521","messageId":"xmqqk07qdz1n.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-v7-05.10-4367c1e7f50-20220802T125258Z-avarab@gmail.com","subject":"Re: [PATCH v7 05/10] git docs: add a category for file formats, protocols and interfaces","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-02T23:08:04Z","receivedAt":"2022-08-02T23:08:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> So let's start moving those over, starting with just the\n> \"bundle-format.txt\" documentation added in 7378ec90e1c (doc: describe\n> Git bundle format, 2020-02-07). We'll now have a new\n> gitformat-bundle(5) man page. Subsequent commits will move more git\n> internal format documentation over.\n\nUp to this point I think I didn't see anything objectionable (one\nparagraph in the proposed log message of an early step was suspect,\nthough). I'll leave the rest to another sitting, as my\nconcentration is running out.\n\nThanks.\n\n"},{"id":"460551","messageId":"xmqqfsidcoqs.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-v7-06.10-5adabbb3a26-20220802T125258Z-avarab@gmail.com","subject":"Re: [PATCH v7 06/10] docs: move commit-graph format docs to man section 5","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-03T15:48:11Z","receivedAt":"2022-08-03T15:48:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Continue the move of existing Documentation/technical/* protocol and\n> file-format documentation into our main documentation space.\n>\n> By moving the documentation for the commit-graph format into man\n> section 5 and the new \"developerinterfaces\" category. This change is\n> split from subsequent commits due to the relatively large amount of\n> ASCIIDOC formatting changes that are required.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/Makefile | 1 +\n> Documentation/git-commit-graph.txt | 5 ++\n> ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------\n> Documentation/technical/chunk-format.txt | 4 +-\n> command-list.txt | 2 +\n> 5 files changed, 42 insertions(+), 17 deletions(-)\n\nOK. Rename of a single document with a bit of mark-up updates, plus\nadjusting the links that refer to the original location to its new\nlocation. Nothing unexpected, other than a single curious bit.\n\n> diff --git a/command-list.txt b/command-list.txt\n> index 1950c4ccd9c..44e244a76f6 100644\n> --- a/command-list.txt\n> +++ b/command-list.txt\n> @@ -210,6 +210,8 @@ gitdiffcore guide\n> giteveryday guide\n> gitfaq guide\n> gitformat-bundle developerinterfaces\n> +gitformat-bundle developerinterfaces\n> +gitformat-commit-graph developerinterfaces\n> gitglossary guide\n> githooks userinterfaces\n> gitignore userinterfaces\n\nI do not think we want or need duplicate entries for \"bundle\",\nand it has nothing to do with the \"commit-graph\" doc.\n\n\n\n"},{"id":"460552","messageId":"xmqqbkt1cohu.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-v7-07.10-cfd1b0afb53-20220802T125258Z-avarab@gmail.com","subject":"Re: [PATCH v7 07/10] docs: move protocol-related docs to man section 5","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-03T15:53:33Z","receivedAt":"2022-08-03T15:55:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Continue the move of existing Documentation/technical/* protocol and\n> file-format documentation into our main documentation space. By moving\n> the things that discuss the protocol we can properly link from\n> e.g. lsrefs.unborn and protocol.version documentation to a manpage we\n> build by default.\n>\n> So far we have been using the \"gitformat-\" prefix for the\n> documentation we've been moving over from Documentation/technical/*,\n> but for protocol documentation let's use \"gitprotocol-*\".\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/Makefile | 8 +++---\n> Documentation/config/lsrefs.txt | 2 +-\n> Documentation/config/protocol.txt | 2 +-\n> Documentation/git-upload-pack.txt | 5 ++--\n> Documentation/gitformat-bundle.txt | 2 +-\n> ...ities.txt => gitprotocol-capabilities.txt} | 28 +++++++++++++++----\n> ...ocol-common.txt => gitprotocol-common.txt} | 23 +++++++++++++--\n> ...pack-protocol.txt => gitprotocol-pack.txt} | 24 +++++++++++++---\n> .../protocol-v2.txt => gitprotocol-v2.txt} | 25 +++++++++++++----\n> Documentation/technical/api-simple-ipc.txt | 2 +-\n> Documentation/technical/http-protocol.txt | 6 ++--\n> .../long-running-process-protocol.txt | 2 +-\n> Documentation/technical/packfile-uri.txt | 2 +-\n> Documentation/technical/partial-clone.txt | 2 +-\n> command-list.txt | 5 +++-\n> refspec.h | 2 +-\n> t/t5551-http-fetch-smart.sh | 4 +--\n> 17 files changed, 106 insertions(+), 38 deletions(-)\n\nOK, I see nothing unexpected.\n\nThere is a silent \"oops that is a screw-up in the previous step that\ncan be buried in this patch that renames 4 files and hopefully nobody\nwould notice\" included, which should be removed by fixing the original\nscrew-up in the previous step, though.\n"},{"id":"460557","messageId":"xmqqv8r9b8gm.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-v7-08.10-3505fa86039-20220802T125258Z-avarab@gmail.com","subject":"Re: [PATCH v7 08/10] docs: move pack format docs to man section 5","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-03T16:25:13Z","receivedAt":"2022-08-03T16:25:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> @@ -125,7 +139,7 @@ Git index format\n> entry is encoded as if the path name for the previous entry is an\n> empty string). At the beginning of an entry, an integer N in the\n> variable width encoding (the same encoding as the offset is encoded\n> - for OFS_DELTA pack entries; see pack-format.txt) is stored, followed\n> + for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed\n\nPossible #leftoverbits for cleaning up around here are:\n\n * Update the above description to use the term \"offset encoding\"\n from gitformat-patck[5] to give readers the term to look for;\n\n * Update and mention that the encode/decode pair\n declared there are to handle variable-length integers in the\n \"offset encoding\".\n\n * We might want to add an entry to the glossary, but the varint\n representation is not end-user facing, so it may not be necessary\n and the mention in would be enough.\n\n> diff --git a/Documentation/technical/cruft-packs.txt b/Documentation/gitformat-pack-cruft.txt\n> similarity index 96%\n> rename from Documentation/technical/cruft-packs.txt\n> rename to Documentation/gitformat-pack-cruft.txt\n> index d81f3a8982f..908f752bd84 100644\n> --- a/Documentation/technical/cruft-packs.txt\n> +++ b/Documentation/gitformat-pack-cruft.txt\n> @@ -1,4 +1,17 @@\n> -= Cruft packs\n> +gitformat-pack-cruft(5)\n> +=======================\n> +\n> +NAME\n> +----\n> +gitformat-pack-cruft - The cruft pack file format\n> +\n> +SYNOPSIS\n> +--------\n> +[verse]\n> +$GIT_DIR/objects/pack/pack-*.mtimes\n\nI do not think this is quite right.\n\nA reader who wants to learn about cruft packs, they need to know:\n\n * what a packfile is and what is in .pack/.idx pair, as a\n prerequisite information, that is described elsewhere\n\n * what it is, what it is used for, and how it is meant to be used,\n why the mtimes from the original loose objects need to be kept,\n all of which is not file-format per-se, but is part of the\n design, described in the original technical/cruft-packs.txt\n\n * how .mtimes file records the _additional_ pieces of per-object\n information only maintained for the \"cruft pack\" objects.\n\nThe original technical/cruft-packs.txt document was the design\ndocument for the cruft packs feature as a whole, and it made sense\nto write about both design and the implementation detail of the\nmtimes format.\n\nBut that is not \"cruft pack file format\". I think this can be fixed\neither by having at least two documents (one for \"cruft packs\"\noverall design, plus another one for \"mtimes file format\"), or by\nhaving one document that is clearly more than \"file format\". The\nposted patch gives us a mixture of the two, that results in neither\nof the two.\n\nStepping back a bit, unless we have separate .pack(5) and .idx(5)\nmanual pages, I suspect that having the format of .pack, .idx, .midx,\nand .mtimes described in the same \"file formats for packfiles\" document\nmight make more sense. After all, those who come to the packfile format\ndocument from \"pack protocol\" document do not mind that the former talks\nabout .idx file, which they would find no use for.\n\nI hope Taylor can help us with his input when he comes back from his\nhoneymoon.\n\n> diff --git a/Documentation/technical/pack-format.txt b/Documentation/gitformat-pack.txt\n> similarity index 95%\n> rename from Documentation/technical/pack-format.txt\n> rename to Documentation/gitformat-pack.txt\n> index b520aa9c45b..546c99f8871 100644\n> --- a/Documentation/technical/pack-format.txt\n> +++ b/Documentation/gitformat-pack.txt\n> @@ -1,5 +1,29 @@\n> -Git pack format\n> -===============\n> +gitformat-pack(5)\n> +=================\n> +\n> +NAME\n> +----\n> +gitformat-pack - Git pack format\n\nOK.\n\n> diff --git a/command-list.txt b/command-list.txt\n> index ed859fdd798..4f30a6c30c8 100644\n> --- a/command-list.txt\n> +++ b/command-list.txt\n> @@ -210,7 +210,12 @@ gitdiffcore guide\n> giteveryday guide\n> gitfaq guide\n> gitformat-bundle developerinterfaces\n> +gitformat-chunk developerinterfaces\n> gitformat-commit-graph developerinterfaces\n> +gitformat-index developerinterfaces\n> +gitformat-pack developerinterfaces\n> +gitformat-pack-cruft developerinterfaces\n> +gitformat-signature developerinterfaces\n> gitglossary guide\n> githooks userinterfaces\n> gitignore userinterfaces\n\nOK.\n"},{"id":"460558","messageId":"xmqqr11xb869.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-v7-09.10-c4a7fe9d439-20220802T125258Z-avarab@gmail.com","subject":"Re: [PATCH v7 09/10] docs: move http-protocol docs to man section 5","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-03T16:31:26Z","receivedAt":"2022-08-03T16:32:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Continue the move of existing Documentation/technical/* protocol and\n> file-format documentation into our main documentation space by moving\n> the http-protocol.txt documentation over. I'm renaming it to\n> \"protocol-http\" to be consistent with other things in the new\n> gitformat-protocol-* namespace.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/Makefile | 2 +-\n> Documentation/git-upload-pack.txt | 6 ++--\n> ...http-protocol.txt => gitprotocol-http.txt} | 29 ++++++++++++++++---\n> Documentation/gitprotocol-pack.txt | 2 +-\n> Documentation/gitprotocol-v2.txt | 4 +--\n> command-list.txt | 1 +\n> 6 files changed, 33 insertions(+), 11 deletions(-)\n> rename Documentation/{technical/http-protocol.txt => gitprotocol-http.txt} (98%)\n\nOK.\n"},{"id":"460559","messageId":"xmqqiln9b7wt.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-v7-10.10-8baf1db4d30-20220802T125258Z-avarab@gmail.com","subject":"Re: [PATCH v7 10/10] docs: move multi-pack-index docs to man section 5","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-03T16:37:06Z","receivedAt":"2022-08-03T16:37:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> diff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt\n> index 546c99f8871..68328bada6b 100644\n> --- a/Documentation/gitformat-pack.txt\n> +++ b/Documentation/gitformat-pack.txt\n> @@ -507,6 +507,11 @@ packs arranged in MIDX order (with the preferred pack coming first).\n> The MIDX's reverse index is stored in the optional 'RIDX' chunk within\n> the MIDX itself.\n> \n> +SEE ALSO\n> +--------\n> +\n> +linkgit:gitformat-multi-pack-index[5]\n\nI already sais that midx and mtimes may want to be all described in\nthe main packfile format documentation, but I am OK to have separate\npages for these auxiliary files that supplement the .pack/.idx pairs\nof files. If we were to go that route, we should have a link to\ncruft .mtimes page here, next to the link to midx page added here.\n\nI find the direction of the overall goal of the series agreeable.\nThanks for working on the patches.\n"},{"id":"460631","messageId":"patch-v8-01.12-8ae30ce2e80-20220804T162138Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v8-00.12-00000000000-20220804T162138Z-avarab@gmail.com","subject":"[PATCH v8 01/12] help.c: refactor drop_prefix() to use a \"switch\" statement\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-04T16:28:30Z","receivedAt":"2022-08-04T16:28:57Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Refactor the drop_prefix() function in in help.c to make it easier to\nstrip prefixes from categories that aren't \"CAT_guide\". There are no\nfunctional changes here, by doing this we make a subsequent functional\nchange's diff smaller.\n\nAs before we first try to strip \"git-\" unconditionally, if that works\nwe'll return the stripped string. Then we'll strip \"git\" if the\ncommand is in \"CAT_guide\".\n\nThis means that we'd in principle strip \"git-foo\" down to \"foo\" if\nit's in CAT_guide. That doesn't make much sense, and we don't have\nsuch an entry in command-list.txt, but let's preserve that behavior\nfor now.\n\nWhile we're at it remove a stray newline that had been added after the\n\"return name;\" statement.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n help.c | 10 ++++++++--\n 1 file changed, 8 insertions(+), 2 deletions(-)\n\ndiff --git a/help.c b/help.c\nindex 41c41c2aa11..7e594d291b0 100644\n--- a/help.c\n+++ b/help.c\n@@ -44,13 +44,19 @@ static struct category_description main_categories[] = {\n static const char *drop_prefix(const char *name, uint32_t category)\n {\n \tconst char *new_name;\n+\tconst char *prefix = NULL;\n \n \tif (skip_prefix(name, \"git-\", &new_name))\n \t\treturn new_name;\n-\tif (category == CAT_guide && skip_prefix(name, \"git\", &new_name))\n+\tswitch (category) {\n+\tcase CAT_guide:\n+\t\tprefix = \"git\";\n+\t\tbreak;\n+\t}\n+\tif (prefix && skip_prefix(name, prefix, &new_name))\n \t\treturn new_name;\n-\treturn name;\n \n+\treturn name;\n }\n \n static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask)\n-- \n2.37.1.1233.g61622908797\n\n"},{"id":"460632","messageId":"cover-v8-00.12-00000000000-20220804T162138Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v7-00.10-00000000000-20220802T125258Z-avarab@gmail.com","subject":"[PATCH v8 00/12] docs: create & use \"(user|developer) interfaces\" categories","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-04T16:28:29Z","receivedAt":"2022-08-04T16:28:59Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"See the v5 for a general overview:\nhttps://lore.kernel.org/git/cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com/\n\nChanges since v7:\n\n * Corrects the discussion of existing behavior in 1-2/12 (git-gitfoo\n v.s. git-foo).\n\n * Fixes a stray error in previous v7 rebasing in 6/12.\n\n * Splits out the \"signature\" and \"index\" format doc conversions into\n their own commits (previously part of the \"pack\" conversion).\n\n * The \"gitformat-pack\" now contains what was previously in\n \"gitformat-cruft-pack\", i.e. we discuss all of the pack files\n (*.pack, *.idx etc.) in the one file.\n\n (The *.bitmap bit is left out for now as before, due to in-flight\n conflicts)\n\n * Ejected the conversion of\n Documentation/technical/multi-pack-index.txt, we discuss the midx\n in the gitformat-pack already, that documentation is more in the\n \"design notes\" category.\n\n Perhaps we should have a gitdesign-* namespace for such things, but\n let's leave it aside for now.\n\nÆvar Arnfjörð Bjarmason (12):\n help.c: refactor drop_prefix() to use a \"switch\" statement\"\n help.c: remove common category behavior from drop_prefix() behavior\n git help doc: use \"\" instead of \"\"\n git docs: add a category for user-facing file, repo and command UX\n git docs: add a category for file formats, protocols and interfaces\n docs: move commit-graph format docs to man section 5\n docs: move protocol-related docs to man section 5\n docs: move index format docs to man section 5\n docs: move signature docs to man section 5\n docs: move pack format docs to man section 5\n docs: move cruft pack docs to gitformat-pack\n docs: move http-protocol docs to man section 5\n\n Documentation/Makefile | 23 +--\n Documentation/config/lsrefs.txt | 2 +-\n Documentation/config/pack.txt | 2 +-\n Documentation/config/protocol.txt | 2 +-\n Documentation/git-bundle.txt | 13 +-\n Documentation/git-commit-graph.txt | 5 +\n Documentation/git-help.txt | 27 ++-\n Documentation/git-multi-pack-index.txt | 4 +-\n Documentation/git-upload-pack.txt | 7 +-\n Documentation/git.txt | 17 ++\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++-\n .../chunk-format.txt => gitformat-chunk.txt} | 29 +++-\n ...-format.txt => gitformat-commit-graph.txt} | 49 ++++--\n .../index-format.txt => gitformat-index.txt} | 22 ++-\n .../pack-format.txt => gitformat-pack.txt} | 160 +++++++++++++++++-\n ...ure-format.txt => gitformat-signature.txt} | 21 ++-\n ...ities.txt => gitprotocol-capabilities.txt} | 28 ++-\n ...ocol-common.txt => gitprotocol-common.txt} | 23 ++-\n ...http-protocol.txt => gitprotocol-http.txt} | 35 +++-\n ...pack-protocol.txt => gitprotocol-pack.txt} | 28 ++-\n .../protocol-v2.txt => gitprotocol-v2.txt} | 27 ++-\n .../howto/recover-corrupted-object-harder.txt | 2 +-\n Documentation/lint-man-section-order.perl | 3 +\n Documentation/technical/api-simple-ipc.txt | 2 +-\n Documentation/technical/cruft-packs.txt | 123 --------------\n .../technical/hash-function-transition.txt | 2 +-\n .../long-running-process-protocol.txt | 2 +-\n Documentation/technical/packfile-uri.txt | 2 +-\n Documentation/technical/partial-clone.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n Makefile | 1 +\n builtin/help.c | 20 ++-\n cache.h | 3 +-\n command-list.txt | 36 +++-\n help.c | 41 ++++-\n help.h | 2 +\n pack-revindex.h | 2 +-\n refspec.h | 2 +-\n t/t0012-help.sh | 14 +-\n t/t5551-http-fetch-smart.sh | 4 +-\n 40 files changed, 590 insertions(+), 243 deletions(-)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)\n rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (89%)\n rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (87%)\n rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)\n rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (72%)\n rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)\n rename Documentation/{technical/protocol-capabilities.txt => gitprotocol-capabilities.txt} (96%)\n rename Documentation/{technical/protocol-common.txt => gitprotocol-common.txt} (89%)\n rename Documentation/{technical/http-protocol.txt => gitprotocol-http.txt} (97%)\n rename Documentation/{technical/pack-protocol.txt => gitprotocol-pack.txt} (98%)\n rename Documentation/{technical/protocol-v2.txt => gitprotocol-v2.txt} (97%)\n delete mode 100644 Documentation/technical/cruft-packs.txt\n\nRange-diff against v7:\n 1: 2665148f45b ! 1: 8ae30ce2e80 help.c: refactor drop_prefix() to use a \"switch\" statement\"\n @@ Commit message\n we'll return the stripped string. Then we'll strip \"git\" if the\n command is in \"CAT_guide\".\n \n - This means that we'd in principle strip \"git-gitfoo\" down to \"foo\" if\n + This means that we'd in principle strip \"git-foo\" down to \"foo\" if\n it's in CAT_guide. That doesn't make much sense, and we don't have\n such an entry in command-list.txt, but let's preserve that behavior\n for now.\n 2: 56429194634 ! 2: aebb56da6e9 help.c: remove common category behavior from drop_prefix() behavior\n @@ Commit message\n \n Before this we'd in principle strip a \"git-\" prefix from a \"guide\" in\n command-list.txt, in practice we have no such entry there. As we don't\n - have any entry that looks like \"git-gitfoo\" in command-list.txt this\n + have any entry that looks like \"git-foo\" in command-list.txt this\n changes nothing in practice, but it makes the intent of the code\n - clearer.\n + clearer. In that hypothetical case we'd now strip it down to \"-foo\",\n + not \"foo\".\n \n When this code was added in cfb22a02ab5 (help: use command-list.h for\n common command list, 2018-05-10) the only entries in command-list.txt\n 3: 2d6c00a51fa = 3: 6c3c072de6f git help doc: use \"\" instead of \"\"\n 4: 8e9384a92f2 = 4: d12db4a9540 git docs: add a category for user-facing file, repo and command UX\n 5: 4367c1e7f50 = 5: f76e775bfdd git docs: add a category for file formats, protocols and interfaces\n 6: 5adabbb3a26 ! 6: df3ef265d45 docs: move commit-graph format docs to man section 5\n @@ command-list.txt: gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle developerinterfaces\n -+gitformat-bundle developerinterfaces\n +gitformat-commit-graph developerinterfaces\n gitglossary guide\n githooks userinterfaces\n 7: cfd1b0afb53 ! 7: daafbf9ae90 docs: move protocol-related docs to man section 5\n @@ Documentation/technical/partial-clone.txt: Design Details\n server to request filtering during packfile construction.\n \n ## command-list.txt ##\n -@@ command-list.txt: gitdiffcore guide\n - giteveryday guide\n - gitfaq guide\n - gitformat-bundle developerinterfaces\n --gitformat-bundle developerinterfaces\n - gitformat-commit-graph developerinterfaces\n - gitglossary guide\n - githooks userinterfaces\n @@ command-list.txt: gitk mainporcelain\n gitmailmap userinterfaces\n gitmodules userinterfaces\n10: 8baf1db4d30 ! 8: ea98b37e41a docs: move multi-pack-index docs to man section 5\n @@ Metadata\n Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - docs: move multi-pack-index docs to man section 5\n + docs: move index format docs to man section 5\n \n Continue the move of existing Documentation/technical/* protocol and\n file-format documentation into our main documentation space by moving\n - the multi-pack-index documentation over.\n + the index format documentation.\n \n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/Makefile ##\n -@@ Documentation/Makefile: MAN5_TXT += gitformat-bundle.txt\n - MAN5_TXT += gitformat-chunk.txt\n +@@ Documentation/Makefile: MAN1_TXT += gitweb.txt\n + MAN5_TXT += gitattributes.txt\n + MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += gitformat-commit-graph.txt\n - MAN5_TXT += gitformat-index.txt\n -+MAN5_TXT += gitformat-multi-pack-index.txt\n - MAN5_TXT += gitformat-pack-cruft.txt\n - MAN5_TXT += gitformat-pack.txt\n - MAN5_TXT += gitformat-signature.txt\n -@@ Documentation/Makefile: TECH_DOCS += ToolsForGit\n - TECH_DOCS += technical/bitmap-format\n ++MAN5_TXT += gitformat-index.txt\n + MAN5_TXT += githooks.txt\n + MAN5_TXT += gitignore.txt\n + MAN5_TXT += gitmailmap.txt\n +@@ Documentation/Makefile: TECH_DOCS += technical/bitmap-format\n + TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n + TECH_DOCS += technical/http-protocol\n +-TECH_DOCS += technical/index-format\n TECH_DOCS += technical/long-running-process-protocol\n --TECH_DOCS += technical/multi-pack-index\n - TECH_DOCS += technical/pack-heuristics\n - TECH_DOCS += technical/parallel-checkout\n - TECH_DOCS += technical/partial-clone\n + TECH_DOCS += technical/multi-pack-index\n + TECH_DOCS += technical/pack-format\n \n - ## Documentation/git-multi-pack-index.txt ##\n -@@ Documentation/git-multi-pack-index.txt: $ git multi-pack-index verify\n - \n - SEE ALSO\n - --------\n --See link:technical/multi-pack-index.html[The Multi-Pack-Index Design\n --Document] and linkgit:gitformat-pack[5] for more information on the\n -+See linkgit:git-multi-pack-index[1] and\n -+linkgit:gitformat-multi-pack-index[5] for more information on the\n - multi-pack-index feature and its file format.\n - \n - \n -\n - ## Documentation/technical/multi-pack-index.txt => Documentation/gitformat-multi-pack-index.txt ##\n + ## Documentation/technical/index-format.txt => Documentation/gitformat-index.txt ##\n @@\n --Multi-Pack-Index (MIDX) Design Notes\n --====================================\n -+gitformat-multi-pack-index(5)\n -+=============================\n ++gitformat-index(5)\n ++==================\n +\n +NAME\n +----\n -+gitformat-multi-pack-index - The multi-pack-index file format\n ++gitformat-index - Git index format\n +\n +SYNOPSIS\n +--------\n +[verse]\n -+$GIT_DIR/objects/pack/multi-pack-index\n ++$GIT_DIR/index\n +\n +DESCRIPTION\n +-----------\n ++\n + Git index format\n +-================\n \n - The Git object directory contains a 'pack' directory containing\n - packfiles (with suffix \".pack\") and pack-indexes (with suffix\n -@@ Documentation/gitformat-multi-pack-index.txt: Related Links\n + == The Git index file has the following format\n \n - [2] https://lore.kernel.org/git/alpine.DEB.2.20.1803091557510.23109@alexmv-linux/\n - Git Merge 2018 Contributor's summit notes (includes discussion of MIDX)\n +@@ Documentation/gitformat-index.txt: The remaining data of each directory block is grouped by type:\n + with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,\n + tools should avoid interacting with a sparse index unless they understand\n + this extension.\n +\n +GIT\n +---\n +Part of the linkgit:git[1] suite\n \n - ## Documentation/gitformat-pack.txt ##\n -@@ Documentation/gitformat-pack.txt: packs arranged in MIDX order (with the preferred pack coming first).\n - The MIDX's reverse index is stored in the optional 'RIDX' chunk within\n - the MIDX itself.\n - \n -+SEE ALSO\n -+--------\n -+\n -+linkgit:gitformat-multi-pack-index[5]\n -+\n - GIT\n - ---\n - Part of the linkgit:git[1] suite\n -\n ## command-list.txt ##\n -@@ command-list.txt: gitformat-bundle developerinterfaces\n - gitformat-chunk developerinterfaces\n +@@ command-list.txt: giteveryday guide\n + gitfaq guide\n + gitformat-bundle developerinterfaces\n gitformat-commit-graph developerinterfaces\n - gitformat-index developerinterfaces\n -+gitformat-multi-pack-index developerinterfaces\n - gitformat-pack developerinterfaces\n - gitformat-pack-cruft developerinterfaces\n - gitformat-signature developerinterfaces\n ++gitformat-index developerinterfaces\n + gitglossary guide\n + githooks userinterfaces\n + gitignore userinterfaces\n -: ----------- > 9: 42a4a3c3be8 docs: move signature docs to man section 5\n 8: 3505fa86039 ! 10: 576c1fef4b3 docs: move pack format docs to man section 5\n @@ Commit message\n location.\n \n By moving these we can properly link from the newly created\n - gitformat-commit-graph do to a gitformat-chunk-format manpage we build\n - by default.\n + gitformat-commit-graph to a gitformat-chunk-format page.\n \n - Creating a \"gitformat-pack-bitmap\" from\n - \"Documentation/technical/bitmap-format\" might logically be part of\n - this change, but it's left out for now due to a conflict with the\n - in-flight ac/bitmap-lookup-table series.\n + Integrating \"Documentation/technical/bitmap-format.txt\" and\n + \"Documentation/technical/cruft-packs.txt\" might logically be part of\n + this change, but as those cover parts of the wider \"pack\n + format\" (including associated files) that's documented outside of\n + \"Documentation/technical/pack-format.txt\" let's leave those for now,\n + subsequent commit(s) will address those.\n \n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n @@ Documentation/Makefile: MAN1_TXT += gitweb.txt\n MAN5_TXT += gitformat-bundle.txt\n +MAN5_TXT += gitformat-chunk.txt\n MAN5_TXT += gitformat-commit-graph.txt\n -+MAN5_TXT += gitformat-index.txt\n -+MAN5_TXT += gitformat-pack-cruft.txt\n + MAN5_TXT += gitformat-index.txt\n +MAN5_TXT += gitformat-pack.txt\n -+MAN5_TXT += gitformat-signature.txt\n + MAN5_TXT += gitformat-signature.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n - MAN5_TXT += gitmailmap.txt\n -@@ Documentation/Makefile: TECH_DOCS += MyFirstObjectWalk\n - TECH_DOCS += SubmittingPatches\n - TECH_DOCS += ToolsForGit\n - TECH_DOCS += technical/bitmap-format\n --TECH_DOCS += technical/cruft-packs\n - TECH_DOCS += technical/hash-function-transition\n +@@ Documentation/Makefile: TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n --TECH_DOCS += technical/index-format\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n -TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\n -@@ Documentation/Makefile: TECH_DOCS += technical/racy-git\n - TECH_DOCS += technical/reftable\n - TECH_DOCS += technical/send-pack-pipeline\n - TECH_DOCS += technical/shallow\n --TECH_DOCS += technical/signature-format\n - TECH_DOCS += technical/trivial-merge\n - SP_ARTICLES += $(TECH_DOCS)\n - SP_ARTICLES += technical/api-index\n \n ## Documentation/config/pack.txt ##\n @@ Documentation/config/pack.txt: permuted into their appropriate location when writing a new bitmap.\n @@ Documentation/gitformat-commit-graph.txt: All multi-byte numbers are in network\n The remaining data in the body is described one chunk at a time, and\n these chunks may be given in any order. Chunks are required unless\n \n - ## Documentation/technical/index-format.txt => Documentation/gitformat-index.txt ##\n -@@\n -+gitformat-index(5)\n -+==================\n -+\n -+NAME\n -+----\n -+gitformat-index - Git index format\n -+\n -+SYNOPSIS\n -+--------\n -+[verse]\n -+$GIT_DIR/index\n -+\n -+DESCRIPTION\n -+-----------\n -+\n - Git index format\n --================\n - \n - == The Git index file has the following format\n - \n + ## Documentation/gitformat-index.txt ##\n @@ Documentation/gitformat-index.txt: Git index format\n entry is encoded as if the path name for the previous entry is an\n empty string). At the beginning of an entry, an integer N in the\n @@ Documentation/gitformat-index.txt: Git index format\n by a NUL-terminated string S. Removing N bytes from the end of the\n path name for the previous entry, and replacing it with the string S\n yields the path name for this entry.\n -@@ Documentation/gitformat-index.txt: The remaining data of each directory block is grouped by type:\n - with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,\n - tools should avoid interacting with a sparse index unless they understand\n - this extension.\n -+\n -+GIT\n -+---\n -+Part of the linkgit:git[1] suite\n -\n - ## Documentation/technical/cruft-packs.txt => Documentation/gitformat-pack-cruft.txt ##\n -@@\n --= Cruft packs\n -+gitformat-pack-cruft(5)\n -+=======================\n -+\n -+NAME\n -+----\n -+gitformat-pack-cruft - The cruft pack file format\n -+\n -+SYNOPSIS\n -+--------\n -+[verse]\n -+$GIT_DIR/objects/pack/pack-*.mtimes\n -+\n -+DESCRIPTION\n -+-----------\n - \n - The cruft packs feature offer an alternative to Git's traditional mechanism of\n - removing unreachable objects. This document provides an overview of Git's\n -@@ Documentation/gitformat-pack-cruft.txt: same.\n - To remove unreachable objects from your repository, Git offers `git repack -Ad`\n - (see linkgit:git-repack[1]). Quoting from the documentation:\n - \n --[quote]\n -+----\n - [...] unreachable objects in a previous pack become loose, unpacked objects,\n - instead of being left in the old pack. [...] loose unreachable objects will be\n - pruned according to normal expiry rules with the next 'git gc' invocation.\n -+----\n - \n - Unreachable objects aren't removed immediately, since doing so could race with\n - an incoming push which may reference an object which is about to be deleted.\n -@@ Documentation/gitformat-pack-cruft.txt: which aren't already stored in an earlier cruft pack) is significantly more\n - complicated to construct, and so aren't pursued here. The obvious drawback to\n - the current implementation is that the entire cruft pack must be re-written from\n - scratch.\n -+\n -+GIT\n -+---\n -+Part of the linkgit:git[1] suite\n \n ## Documentation/technical/pack-format.txt => Documentation/gitformat-pack.txt ##\n @@\n @@ Documentation/gitformat-pack.txt: packs arranged in MIDX order (with the preferr\n +\n +GIT\n +---\n -+Part of the linkgit:git[1] suite\n -\n - ## Documentation/technical/signature-format.txt => Documentation/gitformat-signature.txt ##\n -@@\n --Git signature format\n --====================\n -+gitformat-signature(5)\n -+======================\n - \n --== Overview\n -+NAME\n -+----\n -+gitformat-signature - Git cryptographic signature formats\n -+\n -+SYNOPSIS\n -+--------\n -+[verse]\n -+<[tag|commit] object header(s)>\n -+\n -+\n -+DESCRIPTION\n -+-----------\n - \n - Git uses cryptographic signatures in various places, currently objects (tags,\n - commits, mergetags) and transactions (pushes). In every case, the command which\n -@@ Documentation/gitformat-signature.txt: Date: Wed Jun 15 09:13:29 2016 +0000\n - # gpg: There is no indication that the signature belongs to the owner.\n - # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189\n - ----\n -+\n -+GIT\n -+---\n +Part of the linkgit:git[1] suite\n \n ## Documentation/gitprotocol-pack.txt ##\n @@ command-list.txt: gitdiffcore guide\n gitformat-bundle developerinterfaces\n +gitformat-chunk developerinterfaces\n gitformat-commit-graph developerinterfaces\n -+gitformat-index developerinterfaces\n + gitformat-index developerinterfaces\n +gitformat-pack developerinterfaces\n -+gitformat-pack-cruft developerinterfaces\n -+gitformat-signature developerinterfaces\n + gitformat-signature developerinterfaces\n gitglossary guide\n githooks userinterfaces\n - gitignore userinterfaces\n \n ## pack-revindex.h ##\n @@\n -: ----------- > 11: b9dde9788d4 docs: move cruft pack docs to gitformat-pack\n 9: c4a7fe9d439 = 12: c572688c525 docs: move http-protocol docs to man section 5\n-- \n2.37.1.1233.g61622908797\n\n"},{"id":"460633","messageId":"patch-v8-02.12-aebb56da6e9-20220804T162138Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v8-00.12-00000000000-20220804T162138Z-avarab@gmail.com","subject":"[PATCH v8 02/12] help.c: remove common category behavior from drop_prefix() behavior","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-04T16:28:31Z","receivedAt":"2022-08-04T16:29:00Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the behavior of the \"git\" prefix stripping for CAT_guide so\nthat we don't try to strip the \"git-\" prefix in that case. We should\nbe stripping either \"git\" or \"git-\" depending on the category. This\nchange makes it easier to add extra \"category\" conditions in\nsubsequent commits.\n\nBefore this we'd in principle strip a \"git-\" prefix from a \"guide\" in\ncommand-list.txt, in practice we have no such entry there. As we don't\nhave any entry that looks like \"git-foo\" in command-list.txt this\nchanges nothing in practice, but it makes the intent of the code\nclearer. In that hypothetical case we'd now strip it down to \"-foo\",\nnot \"foo\".\n\nWhen this code was added in cfb22a02ab5 (help: use command-list.h for\ncommon command list, 2018-05-10) the only entries in command-list.txt\nthat didn't begin with \"git-\" were \"gitweb\" and \"gitk\".\n\nThen when the \"guides\" special-case was added in 1b81d8cb19d (help:\nuse command-list.txt for the source of guides, 2018-05-20) we had the\nvarious \"git\" (not \"git-\") prefixed \"guide\" entries, which the\n\"CAT_guide\" case handles.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n help.c | 9 +++++----\n 1 file changed, 5 insertions(+), 4 deletions(-)\n\ndiff --git a/help.c b/help.c\nindex 7e594d291b0..8a09f18a3d9 100644\n--- a/help.c\n+++ b/help.c\n@@ -44,16 +44,17 @@ static struct category_description main_categories[] = {\n static const char *drop_prefix(const char *name, uint32_t category)\n {\n \tconst char *new_name;\n-\tconst char *prefix = NULL;\n+\tconst char *prefix;\n \n-\tif (skip_prefix(name, \"git-\", &new_name))\n-\t\treturn new_name;\n \tswitch (category) {\n \tcase CAT_guide:\n \t\tprefix = \"git\";\n \t\tbreak;\n+\tdefault:\n+\t\tprefix = \"git-\";\n+\t\tbreak;\n \t}\n-\tif (prefix && skip_prefix(name, prefix, &new_name))\n+\tif (skip_prefix(name, prefix, &new_name))\n \t\treturn new_name;\n \n \treturn name;\n-- \n2.37.1.1233.g61622908797\n\n"},{"id":"460634","messageId":"patch-v8-03.12-6c3c072de6f-20220804T162138Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v8-00.12-00000000000-20220804T162138Z-avarab@gmail.com","subject":"[PATCH v8 03/12] git help doc: use \"\" instead of \"\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-04T16:28:32Z","receivedAt":"2022-08-04T16:29:03Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Replace the use of \"\" originally introduced (as \"GUIDE\") in\na133737b809 (doc: include --guide option description for \"git help\",\n2013-04-02) with the more generic \"\". The \"\" placeholder is\nmore generic, and one we'll be able to use as we introduce new\ndocumentation categories.\n\nLet's also add \"\" to the \"git help -h\" output, when it was made\nto use parse_option() in in 41eb33bd0cb (help: use parseopt,\n2008-02-24).\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-help.txt | 8 ++++----\n builtin/help.c | 2 +-\n 2 files changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 239c68db457..bead763fd29 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -9,14 +9,14 @@ SYNOPSIS\n --------\n [verse]\n 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\n-'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n+'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n \n DESCRIPTION\n -----------\n \n-With no options and no '' or '' given, the synopsis of the 'git'\n+With no options and no '' or '' given, the synopsis of the 'git'\n command and a list of the most commonly used Git commands are printed\n on the standard output.\n \n@@ -26,8 +26,8 @@ printed on the standard output.\n If the option `--guides` or `-g` is given, a list of the\n Git concept guides is also printed on the standard output.\n \n-If a command, or a guide, is given, a manual page for that command or\n-guide is brought up. The 'man' program is used by default for this\n+If a command or other documentation is given, the relevant manual page\n+will be brought up. The 'man' program is used by default for this\n purpose, but this can be overridden by other options or configuration\n variables.\n \ndiff --git a/builtin/help.c b/builtin/help.c\nindex 222f994f863..dec82d1be27 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -81,7 +81,7 @@ static struct option builtin_help_options[] = {\n \n static const char * const builtin_help_usage[] = {\n \t\"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n-\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] []\"),\n+\tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [|]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n \tNULL\n-- \n2.37.1.1233.g61622908797\n\n"},{"id":"460635","messageId":"patch-v8-04.12-d12db4a9540-20220804T162138Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v8-00.12-00000000000-20220804T162138Z-avarab@gmail.com","subject":"[PATCH v8 04/12] git docs: add a category for user-facing file, repo and command UX","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-04T16:28:33Z","receivedAt":"2022-08-04T16:29:08Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"Repository, command and file interfaces\" section in the\nmain \"git help git\" manual page. Move things that belong under this\nnew criteria from the generic \"Guides\" section.\n\nThe \"Guides\" section was added in f442f28a81b (git.txt: add list of\nguides, 2020-08-05). It makes sense to have e.g. \"giteveryday(7)\" and\n\"gitfaq(7)\" listed under \"Guides\".\n\nBut placing e.g. \"gitignore(5)\" in it is stretching the meaning of\nwhat a \"guide\" is, ideally that section should list things similar to\n\"giteveryday(7)\" and \"gitcore-tutorial(7)\".\n\nAn alternate name that was considered for this new section was \"User\nformats\", for consistency with the nomenclature used for man section 5\nin general. My man(1) lists it as \"File formats and conventions,\ne.g. /etc/passwd\".\n\nSo calling this \"git help --formats\" or \"git help --user-formats\"\nwould make sense for e.g. gitignore(5), but would be stretching it\nsomewhat for githooks(5), and would seem really suspect for the likes\nof gitcli(7).\n\nLet's instead pick a name that's closer to the generic term \"User\ninterface\", which is really what this documentation discusses: General\nuser-interface documentation that doesn't obviously belong elsewhere.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-help.txt | 14 ++++++++++++++\n Documentation/git.txt | 8 ++++++++\n Makefile | 1 +\n builtin/help.c | 9 +++++++++\n command-list.txt | 21 +++++++++++++--------\n help.c | 12 ++++++++++++\n help.h | 1 +\n t/t0012-help.sh | 12 +++++++++++-\n 9 files changed, 70 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 4f801f4e4c9..28eb940a9b8 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchingrepositories.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n+\tcmds-userinterfaces.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\n \ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex bead763fd29..4eb03bd6c38 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -12,6 +12,7 @@ SYNOPSIS\n 'git help' [[-i|--info] [-m|--man] [-w|--web]] [|]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n+'git help' [--user-interfaces]\n \n DESCRIPTION\n -----------\n@@ -69,6 +70,19 @@ OPTIONS\n --guides::\n \tPrints a list of the Git concept guides on the standard output.\n \n+--user-interfaces::\n+\tPrints a list of the repository, command and file interfaces\n+\tdocumentation on the standard output.\n++\n+In-repository file interfaces such as `.git/info/exclude` are\n+documented here (see linkgit:gitrepository-layout[5]), as well as\n+in-tree configuration such as `.mailmap` (see linkgit:gitmailmap[5]).\n++\n+This section of the documentation also covers general or widespread\n+user-interface conventions (e.g. linkgit:gitcli[7]), and\n+pseudo-configuration such as the file-based `.git/hooks/*` interface\n+described in linkgit:githooks[5].\n+\n -i::\n --info::\n \tDisplay manual page for the command in the 'info' format. The\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 47a6095ff40..945a1ebd3b1 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -339,6 +339,14 @@ The following documentation pages are guides about Git concepts.\n \n include::cmds-guide.txt[]\n \n+Repository, command and file interfaces\n+---------------------------------------\n+\n+This documentation discusses repository and command interfaces which\n+users are expected to interact with directly. See `--user-formats` in\n+linkgit:git-help[1] for more details on the critera.\n+\n+include::cmds-userinterfaces.txt[]\n \n Configuration Mechanism\n -----------------------\ndiff --git a/Makefile b/Makefile\nindex 2ec9b2dc6bb..e8adeb09f1c 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -3531,6 +3531,7 @@ check-docs::\n \t\tsed -e '1,/^### command list/d' \\\n \t\t -e '/^#/d' \\\n \t\t -e '/guide$$/d' \\\n+\t\t -e '/interfaces$$/d' \\\n \t\t -e 's/[ \t].*//' \\\n \t\t -e 's/^/listed /' command-list.txt; \\\n \t\t$(MAKE) -C Documentation print-man1 | \\\ndiff --git a/builtin/help.c b/builtin/help.c\nindex dec82d1be27..1ab1c8a0dd7 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -43,6 +43,7 @@ static enum help_action {\n \tHELP_ACTION_ALL = 1,\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n+\tHELP_ACTION_USER_INTERFACES,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -69,6 +70,9 @@ static struct option builtin_help_options[] = {\n \n \tOPT_CMDMODE('g', \"guides\", &cmd_mode, N_(\"print list of useful guides\"),\n \t\t HELP_ACTION_GUIDES),\n+\tOPT_CMDMODE(0, \"user-interfaces\", &cmd_mode,\n+\t\t N_(\"print list of user-facing repository, command and file interfaces\"),\n+\t\t HELP_ACTION_USER_INTERFACES),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -84,6 +88,7 @@ static const char * const builtin_help_usage[] = {\n \tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [|]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n+\t\"git help [--user-interfaces]\",\n \tNULL\n };\n \n@@ -654,6 +659,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\topt_mode_usage(argc, \"--config-for-completion\", help_format);\n \t\tlist_config_help(SHOW_CONFIG_VARS);\n \t\treturn 0;\n+\tcase HELP_ACTION_USER_INTERFACES:\n+\t\topt_mode_usage(argc, \"--user-interfaces\", help_format);\n+\t\tlist_user_interfaces_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n \t\t\t help_format);\ndiff --git a/command-list.txt b/command-list.txt\nindex 9bd6f3c48f4..1d45303e14c 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -43,6 +43,11 @@\n # specified here, which can only have \"guide\" attribute and nothing\n # else.\n #\n+# User-facing repository, command and file interfaces such as\n+# documentation for the .gitmodules, .mailmap etc. files lives in man\n+# sections 5 and 7. These entries can only have the \"userinterfaces\"\n+# attribute and nothing else.\n+#\n ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -192,8 +197,8 @@ git-verify-tag ancillaryinterrogators\n git-whatchanged ancillaryinterrogators complete\n git-worktree mainporcelain\n git-write-tree plumbingmanipulators\n-gitattributes guide\n-gitcli guide\n+gitattributes userinterfaces\n+gitcli userinterfaces\n gitcore-tutorial guide\n gitcredentials guide\n gitcvs-migration guide\n@@ -201,15 +206,15 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitglossary guide\n-githooks guide\n-gitignore guide\n+githooks userinterfaces\n+gitignore userinterfaces\n gitk mainporcelain\n-gitmailmap guide\n-gitmodules guide\n+gitmailmap userinterfaces\n+gitmodules userinterfaces\n gitnamespaces guide\n gitremote-helpers guide\n-gitrepository-layout guide\n-gitrevisions guide\n+gitrepository-layout userinterfaces\n+gitrevisions userinterfaces\n gitsubmodules guide\n gittutorial guide\n gittutorial-2 guide\ndiff --git a/help.c b/help.c\nindex 8a09f18a3d9..3e2a78863b7 100644\n--- a/help.c\n+++ b/help.c\n@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_plumbinginterrogators, N_(\"Low-level Commands / Interrogators\") },\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n+\t{ CAT_userinterfaces, N_(\"User-facing repository, command and file interfaces\") },\n \t{ 0, NULL }\n };\n \n@@ -48,6 +49,7 @@ static const char *drop_prefix(const char *name, uint32_t category)\n \n \tswitch (category) {\n \tcase CAT_guide:\n+\tcase CAT_userinterfaces:\n \t\tprefix = \"git\";\n \t\tbreak;\n \tdefault:\n@@ -433,6 +435,16 @@ void list_guides_help(void)\n \tputchar('\\n');\n }\n \n+void list_user_interfaces_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_userinterfaces, N_(\"User-facing repository, command and file interfaces:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex 971a3ad855a..243104c27a7 100644\n--- a/help.h\n+++ b/help.h\n@@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num)\n void list_common_cmds_help(void);\n void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n+void list_user_interfaces_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex 6c33a436901..bee5ed12203 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -44,6 +44,8 @@ test_expect_success 'invalid usage' '\n \ttest_expect_code 129 git help -g add &&\n \ttest_expect_code 129 git help -a -g &&\n \n+\ttest_expect_code 129 git help --user-interfaces add &&\n+\n \ttest_expect_code 129 git help -g -c &&\n \ttest_expect_code 129 git help --config-for-completion add &&\n \ttest_expect_code 129 git help --config-sections-for-completion add\n@@ -104,9 +106,9 @@ test_expect_success 'git help' '\n \ttest_i18ngrep \"^ commit \" help.output &&\n \ttest_i18ngrep \"^ fetch \" help.output\n '\n+\n test_expect_success 'git help -g' '\n \tgit help -g >help.output &&\n-\ttest_i18ngrep \"^ attributes \" help.output &&\n \ttest_i18ngrep \"^ everyday \" help.output &&\n \ttest_i18ngrep \"^ tutorial \" help.output\n '\n@@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' '\n \ttest_cmp expect test-browser.log\n '\n \n+test_expect_success 'git help --user-interfaces' '\n+\tgit help --user-interfaces >help.output &&\n+\tgrep \"^ attributes \" help.output &&\n+\tgrep \"^ mailmap \" help.output\n+'\n+\n test_expect_success 'git help -c' '\n \tgit help -c >help.output &&\n \tcat >expect <<-\\EOF &&\n@@ -220,6 +228,8 @@ test_expect_success \"'git help -a' section spacing\" '\n \tLow-level Commands / Syncing Repositories\n \n \tLow-level Commands / Internal Helpers\n+\n+\tUser-facing repository, command and file interfaces\n \tEOF\n \ttest_cmp expect actual\n '\n-- \n2.37.1.1233.g61622908797\n\n"},{"id":"460636","messageId":"patch-v8-05.12-f76e775bfdd-20220804T162138Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v8-00.12-00000000000-20220804T162138Z-avarab@gmail.com","subject":"[PATCH v8 05/12] git docs: add a category for file formats, protocols and interfaces","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-04T16:28:34Z","receivedAt":"2022-08-04T16:29:09Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Create a new \"File formats, protocols and other developer interfaces\"\nsection in the main \"git help git\" manual page and start moving the\ndocumentation that now lives in \"Documentation/technical/*.git\" over\nto it. This complements the newly added and adjacent \"Repository,\ncommand and file interfaces\" section.\n\nThis makes the technical documentation more accessible and\ndiscoverable. Before this we wouldn't install it by default, and had\nno ability to build man page versions of them. The links to them from\nour existing documentation link to the generated HTML version of these\ndocs.\n\nSo let's start moving those over, starting with just the\n\"bundle-format.txt\" documentation added in 7378ec90e1c (doc: describe\nGit bundle format, 2020-02-07). We'll now have a new\ngitformat-bundle(5) man page. Subsequent commits will move more git\ninternal format documentation over.\n\nUnfortunately the syntax of the current Documentation/technical/*.txt\nis not the same (when it comes to section headings etc.) as our\nDocumentation/*.txt documentation, so change the relevant bits of\nsyntax as we're moving this over.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 3 +-\n Documentation/git-bundle.txt | 14 +++---\n Documentation/git-help.txt | 5 +++\n Documentation/git.txt | 9 ++++\n ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++---\n Documentation/lint-man-section-order.perl | 3 ++\n builtin/help.c | 9 ++++\n command-list.txt | 5 +++\n help.c | 12 +++++\n help.h | 1 +\n t/t0012-help.sh | 2 +\n 11 files changed, 94 insertions(+), 13 deletions(-)\n rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 28eb940a9b8..1a4a545f44a 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -24,6 +24,7 @@ MAN1_TXT += gitweb.txt\n \n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n+MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -95,7 +96,6 @@ TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n-TECH_DOCS += technical/bundle-format\n TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-synchingrepositories.txt \\\n \tcmds-synchelpers.txt \\\n \tcmds-guide.txt \\\n+\tcmds-developerinterfaces.txt \\\n \tcmds-userinterfaces.txt \\\n \tcmds-purehelpers.txt \\\n \tcmds-foreignscminterface.txt\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 7685b570455..f0b1282b918 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -56,10 +56,9 @@ using \"thin packs\", bundles created using exclusions are smaller in\n size. That they're \"thin\" under the hood is merely noted here as a\n curiosity, and as a reference to other documentation.\n \n-See link:technical/bundle-format.html[the `bundle-format`\n-documentation] for more details and the discussion of \"thin pack\" in\n-link:technical/pack-format.html[the pack format documentation] for\n-further details.\n+See linkgit:gitformat-bundle[5] for more details and the discussion of\n+\"thin pack\" in link:technical/pack-format.html[the pack format\n+documentation] for further details.\n \n OPTIONS\n -------\n@@ -77,7 +76,7 @@ verify ::\n \tcommits exist and are fully linked in the current repository.\n \tThen, 'git bundle' prints a list of missing commits, if any.\n \tFinally, information about additional capabilities, such as \"object\n-\tfilter\", is printed. See \"Capabilities\" in link:technical/bundle-format.html\n+\tfilter\", is printed. See \"Capabilities\" in linkgit:gitformat-bundle[5]\n \tfor more information. The exit code is zero for success, but will\n \tbe nonzero if the bundle file is invalid.\n \n@@ -337,6 +336,11 @@ You can also see what references it offers:\n $ git ls-remote mybundle\n ----------------\n \n+FILE FORMAT\n+-----------\n+\n+See linkgit:gitformat-bundle[5].\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 4eb03bd6c38..2b0b5e390dc 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -13,6 +13,7 @@ SYNOPSIS\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n 'git help' [--user-interfaces]\n+'git help' [--developer-interfaces]\n \n DESCRIPTION\n -----------\n@@ -83,6 +84,10 @@ user-interface conventions (e.g. linkgit:gitcli[7]), and\n pseudo-configuration such as the file-based `.git/hooks/*` interface\n described in linkgit:githooks[5].\n \n+--developer-interfaces::\n+\tPrint list of file formats, protocols and other developer\n+\tinterfaces documentation on the standard output.\n+\n -i::\n --info::\n \tDisplay manual page for the command in the 'info' format. The\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 945a1ebd3b1..0ef7f5e4ece 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -348,6 +348,15 @@ linkgit:git-help[1] for more details on the critera.\n \n include::cmds-userinterfaces.txt[]\n \n+File formats, protocols and other developer interfaces\n+------------------------------------------------------\n+\n+This documentation discusses file formats, over-the-wire protocols and\n+other git developer interfaces. See `--developer-interfaces` in\n+linkgit:git-help[1].\n+\n+include::cmds-developerinterfaces.txt[]\n+\n Configuration Mechanism\n -----------------------\n \ndiff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt\nsimilarity index 79%\nrename from Documentation/technical/bundle-format.txt\nrename to Documentation/gitformat-bundle.txt\nindex b9be8644cf5..6a9d9e5bf6f 100644\n--- a/Documentation/technical/bundle-format.txt\n+++ b/Documentation/gitformat-bundle.txt\n@@ -1,11 +1,33 @@\n-= Git bundle v2 format\n+gitformat-bundle(5)\n+===================\n \n-The Git bundle format is a format that represents both refs and Git objects.\n+NAME\n+----\n+gitformat-bundle - The bundle file format\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+*.bundle\n+*.bdl\n+\n+DESCRIPTION\n+-----------\n+\n+The Git bundle format is a format that represents both refs and Git\n+objects. A bundle is a header in a format similar to\n+linkgit:git-show-ref[1] followed by a pack in *.pack format.\n \n-== Format\n+The format is created and read by the linkgit:git-bundle[1] command,\n+and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1].\n+\n+\n+FORMAT\n+------\n \n We will use ABNF notation to define the Git bundle format. See\n-protocol-common.txt for the details.\n+link:technical/protocol-common.html for the details.\n \n A v2 bundle looks like this:\n \n@@ -36,7 +58,9 @@ value = *(%01-09 / %0b-FF)\n pack = ... ; packfile\n ----\n \n-== Semantics\n+\n+SEMANTICS\n+---------\n \n A Git bundle consists of several parts.\n \n@@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id.\n This is a comment and it has no specific meaning. The writer of the bundle MAY\n put any string here. The reader of the bundle MUST ignore the comment.\n \n-=== Note on the shallow clone and a Git bundle\n+Note on the shallow clone and a Git bundle\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n Note that the prerequisites does not represent a shallow-clone boundary. The\n semantics of the prerequisites and the shallow-clone boundaries are different,\n and the Git bundle v2 format cannot represent a shallow clone repository.\n \n-== Capabilities\n+CAPABILITIES\n+------------\n \n Because there is no opportunity for negotiation, unknown capabilities cause 'git\n bundle' to abort.\n@@ -79,3 +105,7 @@ bundle' to abort.\n * `filter` specifies an object filter as in the `--filter` option in\n linkgit:git-rev-list[1]. The resulting pack-file must be marked as a\n `.promisor` pack-file after it is unbundled.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl\nindex 425377dfeb7..02408a0062f 100755\n--- a/Documentation/lint-man-section-order.perl\n+++ b/Documentation/lint-man-section-order.perl\n@@ -32,6 +32,9 @@\n \t\t'SEE ALSO' => {\n \t\t\torder => $order++,\n \t\t},\n+\t\t'FILE FORMAT' => {\n+\t\t\torder => $order++,\n+\t\t},\n \t\t'GIT' => {\n \t\t\trequired => 1,\n \t\t\torder => $order++,\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 1ab1c8a0dd7..09ac4289f13 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -44,6 +44,7 @@ static enum help_action {\n \tHELP_ACTION_GUIDES,\n \tHELP_ACTION_CONFIG,\n \tHELP_ACTION_USER_INTERFACES,\n+\tHELP_ACTION_DEVELOPER_INTERFACES,\n \tHELP_ACTION_CONFIG_FOR_COMPLETION,\n \tHELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,\n } cmd_mode;\n@@ -73,6 +74,9 @@ static struct option builtin_help_options[] = {\n \tOPT_CMDMODE(0, \"user-interfaces\", &cmd_mode,\n \t\t N_(\"print list of user-facing repository, command and file interfaces\"),\n \t\t HELP_ACTION_USER_INTERFACES),\n+\tOPT_CMDMODE(0, \"developer-interfaces\", &cmd_mode,\n+\t\t N_(\"print list of file formats, protocols and other developer interfaces\"),\n+\t\t HELP_ACTION_DEVELOPER_INTERFACES),\n \tOPT_CMDMODE('c', \"config\", &cmd_mode, N_(\"print all configuration variable names\"),\n \t\t HELP_ACTION_CONFIG),\n \tOPT_CMDMODE_F(0, \"config-for-completion\", &cmd_mode, \"\",\n@@ -89,6 +93,7 @@ static const char * const builtin_help_usage[] = {\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n \t\"git help [--user-interfaces]\",\n+\t\"git help [--developer-interfaces]\",\n \tNULL\n };\n \n@@ -663,6 +668,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\topt_mode_usage(argc, \"--user-interfaces\", help_format);\n \t\tlist_user_interfaces_help();\n \t\treturn 0;\n+\tcase HELP_ACTION_DEVELOPER_INTERFACES:\n+\t\topt_mode_usage(argc, \"--developer-interfaces\", help_format);\n+\t\tlist_developer_interfaces_help();\n+\t\treturn 0;\n \tcase HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:\n \t\topt_mode_usage(argc, \"--config-sections-for-completion\",\n \t\t\t help_format);\ndiff --git a/command-list.txt b/command-list.txt\nindex 1d45303e14c..1950c4ccd9c 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -48,6 +48,10 @@\n # sections 5 and 7. These entries can only have the \"userinterfaces\"\n # attribute and nothing else.\n #\n+# Git's file formats and protocols, such as documentation for the\n+# *.bundle format lives in man section 5. These entries can only have\n+# the \"developerinterfaces\" attribute and nothing else.\n+#\n ### command list (do not change this line)\n # command name category [category] [category]\n git-add mainporcelain worktree\n@@ -205,6 +209,7 @@ gitcvs-migration guide\n gitdiffcore guide\n giteveryday guide\n gitfaq guide\n+gitformat-bundle developerinterfaces\n gitglossary guide\n githooks userinterfaces\n gitignore userinterfaces\ndiff --git a/help.c b/help.c\nindex 3e2a78863b7..991e33f8a6e 100644\n--- a/help.c\n+++ b/help.c\n@@ -39,6 +39,7 @@ static struct category_description main_categories[] = {\n \t{ CAT_synchingrepositories, N_(\"Low-level Commands / Syncing Repositories\") },\n \t{ CAT_purehelpers, N_(\"Low-level Commands / Internal Helpers\") },\n \t{ CAT_userinterfaces, N_(\"User-facing repository, command and file interfaces\") },\n+\t{ CAT_developerinterfaces, N_(\"Developer-facing file file formats, protocols and interfaces\") },\n \t{ 0, NULL }\n };\n \n@@ -50,6 +51,7 @@ static const char *drop_prefix(const char *name, uint32_t category)\n \tswitch (category) {\n \tcase CAT_guide:\n \tcase CAT_userinterfaces:\n+\tcase CAT_developerinterfaces:\n \t\tprefix = \"git\";\n \t\tbreak;\n \tdefault:\n@@ -445,6 +447,16 @@ void list_user_interfaces_help(void)\n \tputchar('\\n');\n }\n \n+void list_developer_interfaces_help(void)\n+{\n+\tstruct category_description catdesc[] = {\n+\t\t{ CAT_developerinterfaces, N_(\"File formats, protocols and other developer interfaces:\") },\n+\t\t{ 0, NULL }\n+\t};\n+\tprint_cmd_by_category(catdesc, NULL);\n+\tputchar('\\n');\n+}\n+\n static int get_alias(const char *var, const char *value, void *data)\n {\n \tstruct string_list *list = data;\ndiff --git a/help.h b/help.h\nindex 243104c27a7..af073a7a026 100644\n--- a/help.h\n+++ b/help.h\n@@ -23,6 +23,7 @@ void list_common_cmds_help(void);\n void list_all_cmds_help(int show_external_commands, int show_aliases);\n void list_guides_help(void);\n void list_user_interfaces_help(void);\n+void list_developer_interfaces_help(void);\n \n void list_all_main_cmds(struct string_list *list);\n void list_all_other_cmds(struct string_list *list);\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex bee5ed12203..4ed2f242eb2 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -230,6 +230,8 @@ test_expect_success \"'git help -a' section spacing\" '\n \tLow-level Commands / Internal Helpers\n \n \tUser-facing repository, command and file interfaces\n+\n+\tDeveloper-facing file file formats, protocols and interfaces\n \tEOF\n \ttest_cmp expect actual\n '\n-- \n2.37.1.1233.g61622908797\n\n"},{"id":"460637","messageId":"patch-v8-06.12-df3ef265d45-20220804T162138Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v8-00.12-00000000000-20220804T162138Z-avarab@gmail.com","subject":"[PATCH v8 06/12] docs: move commit-graph format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-04T16:28:35Z","receivedAt":"2022-08-04T16:29:20Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space.\n\nBy moving the documentation for the commit-graph format into man\nsection 5 and the new \"developerinterfaces\" category. This change is\nsplit from subsequent commits due to the relatively large amount of\nASCIIDOC formatting changes that are required.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-commit-graph.txt | 5 ++\n ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------\n Documentation/technical/chunk-format.txt | 4 +-\n command-list.txt | 1 +\n 5 files changed, 41 insertions(+), 17 deletions(-)\n rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (88%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 1a4a545f44a..e7bd72bb84e 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -25,6 +25,7 @@ MAN1_TXT += gitweb.txt\n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n+MAN5_TXT += gitformat-commit-graph.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex e1f48c95b3c..047decdb65b 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append\n ------------------------------------------------\n \n \n+FILE FORMAT\n+-----------\n+\n+see linkgit:gitformat-commit-graph[5].\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt\nsimilarity index 88%\nrename from Documentation/technical/commit-graph-format.txt\nrename to Documentation/gitformat-commit-graph.txt\nindex 484b185ba98..108dc2295c0 100644\n--- a/Documentation/technical/commit-graph-format.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -1,5 +1,18 @@\n-Git commit graph format\n-=======================\n+gitformat-commit-graph(5)\n+=========================\n+\n+NAME\n+----\n+gitformat-commit-graph - Git commit graph format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/info/commit-graph\n+$GIT_DIR/objects/info/commit-graphs/*\n+\n+DESCRIPTION\n+-----------\n \n The Git commit graph stores a list of commit OIDs and some associated\n metadata, including:\n@@ -30,7 +43,7 @@ and hash type.\n \n All multi-byte numbers are in network byte order.\n \n-HEADER:\n+=== HEADER:\n \n 4-byte signature:\n The signature is: {'C', 'G', 'P', 'H'}\n@@ -52,7 +65,7 @@ HEADER:\n We infer the length (H*B) of the Base Graphs chunk\n from this value.\n \n-CHUNK LOOKUP:\n+=== CHUNK LOOKUP:\n \n (C + 1) * 12 bytes listing the table of contents for the chunks:\n First 4 bytes describe the chunk id. Value 0 is a terminating label.\n@@ -68,17 +81,17 @@ CHUNK LOOKUP:\n these chunks may be given in any order. Chunks are required unless\n otherwise specified.\n \n-CHUNK DATA:\n+=== CHUNK DATA:\n \n- OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n+==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n The ith entry, F[i], stores the number of OIDs with first\n byte at most i. Thus F[255] stores the total\n number of commits (N).\n \n- OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n+==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n The OIDs for all commits in the graph, sorted in ascending order.\n \n- Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n+==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n * The first H bytes are for the OID of the root tree.\n * The next 8 bytes are for the positions of the first two parents\n of the ith commit. Stores value 0x70000000 if no parent in that\n@@ -93,7 +106,7 @@ CHUNK DATA:\n 2 bits of the lowest byte, storing the 33rd and 34th bit of the\n commit time.\n \n- Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n+==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n * This list of 4-byte values store corrected commit date offsets for the\n commits, arranged in the same order as commit data chunk.\n * If the corrected commit date offset cannot be stored within 31 bits,\n@@ -104,7 +117,7 @@ CHUNK DATA:\n by compatible versions of Git and in case of split commit-graph chains,\n the topmost layer also has Generation Data chunk.\n \n- Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n+==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n * This list of 8-byte values stores the corrected commit date offsets\n for commits with corrected commit date offsets that cannot be\n stored within 31 bits.\n@@ -112,7 +125,7 @@ CHUNK DATA:\n chunk is present and atleast one corrected commit date offset cannot\n be stored within 31 bits.\n \n- Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n+==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n This list of 4-byte values store the second through nth parents for\n all octopus merges. The second parent value in the commit data stores\n an array position within this list along with the most-significant bit\n@@ -120,14 +133,14 @@ CHUNK DATA:\n positions for the parents until reaching a value with the most-significant\n bit on. The other bits correspond to the position of the last parent.\n \n- Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n+==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters\n from commit 0 to commit i (inclusive) in lexicographic order. The Bloom\n filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header\n length), where BIDX[-1] is 0.\n * The BIDX chunk is ignored if the BDAT chunk is not present.\n \n- Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n+==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n * It starts with header consisting of three unsigned 32-bit integers:\n - Version of the hash algorithm being used. We currently only support\n \tvalue 1 which corresponds to the 32-bit version of the murmur3 hash\n@@ -147,13 +160,13 @@ CHUNK DATA:\n of length one, with either all bits set to zero or one respectively.\n * The BDAT chunk is present if and only if BIDX is present.\n \n- Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n+==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n This list of H-byte hashes describe a set of B commit-graph files that\n form a commit-graph chain. The graph position for the ith commit in this\n file's OID Lookup chunk is equal to i plus the number of commits in all\n base graphs. If B is non-zero, this chunk must exist.\n \n-TRAILER:\n+=== TRAILER:\n \n \tH-byte HASH-checksum of all of the above.\n \n@@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote\n possibly erroneous data in these chunks with the IDs \"GDAT\" and \"GDOV\". By\n changing the IDs, newer versions of Git will silently ignore those older\n chunks and write the new information without trusting the incorrect data.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/chunk-format.txt b/Documentation/technical/chunk-format.txt\nindex 593614fceda..f36ce42f37c 100644\n--- a/Documentation/technical/chunk-format.txt\n+++ b/Documentation/technical/chunk-format.txt\n@@ -6,7 +6,7 @@ sections of the file. This allows structured access to a large file by\n scanning a small \"table of contents\" for the remaining data. This common\n format is used by the `commit-graph` and `multi-pack-index` files. See\n link:technical/pack-format.html[the `multi-pack-index` format] and\n-link:technical/commit-graph-format.html[the `commit-graph` format] for\n+the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n how they use the chunks to describe structured data.\n \n A chunk-based file format begins with some header information custom to\n@@ -108,7 +108,7 @@ for future formats:\n * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()`\n in `commit-graph.c` for how the chunk-format API is used to write and\n parse the commit-graph file format documented in\n- link:technical/commit-graph-format.html[the commit-graph file format].\n+ the commit-graph file format in linkgit:gitformat-commit-graph[5].\n \n * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n in `midx.c` for how the chunk-format API is used to write and\ndiff --git a/command-list.txt b/command-list.txt\nindex 1950c4ccd9c..3afcfcd35f0 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -210,6 +210,7 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle developerinterfaces\n+gitformat-commit-graph developerinterfaces\n gitglossary guide\n githooks userinterfaces\n gitignore userinterfaces\n-- \n2.37.1.1233.g61622908797\n\n"},{"id":"460638","messageId":"patch-v8-08.12-ea98b37e41a-20220804T162138Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v8-00.12-00000000000-20220804T162138Z-avarab@gmail.com","subject":"[PATCH v8 08/12] docs: move index format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-04T16:28:37Z","receivedAt":"2022-08-04T16:29:24Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe index format documentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 2 +-\n .../index-format.txt => gitformat-index.txt} | 20 ++++++++++++++++++-\n command-list.txt | 1 +\n 3 files changed, 21 insertions(+), 2 deletions(-)\n rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex b53f3c12843..029067a77d5 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -26,6 +26,7 @@ MAN1_TXT += gitweb.txt\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += gitformat-commit-graph.txt\n+MAN5_TXT += gitformat-index.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -104,7 +105,6 @@ TECH_DOCS += technical/bitmap-format\n TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n-TECH_DOCS += technical/index-format\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-format\ndiff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt\nsimilarity index 98%\nrename from Documentation/technical/index-format.txt\nrename to Documentation/gitformat-index.txt\nindex f691c20ab0a..9c3844298b8 100644\n--- a/Documentation/technical/index-format.txt\n+++ b/Documentation/gitformat-index.txt\n@@ -1,5 +1,19 @@\n+gitformat-index(5)\n+==================\n+\n+NAME\n+----\n+gitformat-index - Git index format\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/index\n+\n+DESCRIPTION\n+-----------\n+\n Git index format\n-================\n \n == The Git index file has the following format\n \n@@ -402,3 +416,7 @@ The remaining data of each directory block is grouped by type:\n with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,\n tools should avoid interacting with a sparse index unless they understand\n this extension.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/command-list.txt b/command-list.txt\nindex ed859fdd798..5e8d8386683 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -211,6 +211,7 @@ giteveryday guide\n gitfaq guide\n gitformat-bundle developerinterfaces\n gitformat-commit-graph developerinterfaces\n+gitformat-index developerinterfaces\n gitglossary guide\n githooks userinterfaces\n gitignore userinterfaces\n-- \n2.37.1.1233.g61622908797\n\n"},{"id":"460639","messageId":"patch-v8-09.12-42a4a3c3be8-20220804T162138Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v8-00.12-00000000000-20220804T162138Z-avarab@gmail.com","subject":"[PATCH v8 09/12] docs: move signature docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-04T16:28:38Z","receivedAt":"2022-08-04T16:29:27Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe signature format documentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 2 +-\n ...ure-format.txt => gitformat-signature.txt} | 21 ++++++++++++++++---\n command-list.txt | 1 +\n 3 files changed, 20 insertions(+), 4 deletions(-)\n rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 029067a77d5..d122d1751d8 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -27,6 +27,7 @@ MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n MAN5_TXT += gitformat-commit-graph.txt\n MAN5_TXT += gitformat-index.txt\n+MAN5_TXT += gitformat-signature.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n@@ -115,7 +116,6 @@ TECH_DOCS += technical/racy-git\n TECH_DOCS += technical/reftable\n TECH_DOCS += technical/send-pack-pipeline\n TECH_DOCS += technical/shallow\n-TECH_DOCS += technical/signature-format\n TECH_DOCS += technical/trivial-merge\n SP_ARTICLES += $(TECH_DOCS)\n SP_ARTICLES += technical/api-index\ndiff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt\nsimilarity index 96%\nrename from Documentation/technical/signature-format.txt\nrename to Documentation/gitformat-signature.txt\nindex 166721be6f6..a249869fafa 100644\n--- a/Documentation/technical/signature-format.txt\n+++ b/Documentation/gitformat-signature.txt\n@@ -1,7 +1,18 @@\n-Git signature format\n-====================\n+gitformat-signature(5)\n+======================\n \n-== Overview\n+NAME\n+----\n+gitformat-signature - Git cryptographic signature formats\n+\n+SYNOPSIS\n+--------\n+[verse]\n+<[tag|commit] object header(s)>\n+\n+\n+DESCRIPTION\n+-----------\n \n Git uses cryptographic signatures in various places, currently objects (tags,\n commits, mergetags) and transactions (pushes). In every case, the command which\n@@ -200,3 +211,7 @@ Date: Wed Jun 15 09:13:29 2016 +0000\n # gpg: There is no indication that the signature belongs to the owner.\n # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/command-list.txt b/command-list.txt\nindex 5e8d8386683..68212e3c1bd 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -212,6 +212,7 @@ gitfaq guide\n gitformat-bundle developerinterfaces\n gitformat-commit-graph developerinterfaces\n gitformat-index developerinterfaces\n+gitformat-signature developerinterfaces\n gitglossary guide\n githooks userinterfaces\n gitignore userinterfaces\n-- \n2.37.1.1233.g61622908797\n\n"},{"id":"460640","messageId":"patch-v8-07.12-daafbf9ae90-20220804T162138Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v8-00.12-00000000000-20220804T162138Z-avarab@gmail.com","subject":"[PATCH v8 07/12] docs: move protocol-related docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-04T16:28:36Z","receivedAt":"2022-08-04T16:29:30Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space. By moving\nthe things that discuss the protocol we can properly link from\ne.g. lsrefs.unborn and protocol.version documentation to a manpage we\nbuild by default.\n\nSo far we have been using the \"gitformat-\" prefix for the\ndocumentation we've been moving over from Documentation/technical/*,\nbut for protocol documentation let's use \"gitprotocol-*\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 8 +++---\n Documentation/config/lsrefs.txt | 2 +-\n Documentation/config/protocol.txt | 2 +-\n Documentation/git-upload-pack.txt | 5 ++--\n Documentation/gitformat-bundle.txt | 2 +-\n ...ities.txt => gitprotocol-capabilities.txt} | 28 +++++++++++++++----\n ...ocol-common.txt => gitprotocol-common.txt} | 23 +++++++++++++--\n ...pack-protocol.txt => gitprotocol-pack.txt} | 24 +++++++++++++---\n .../protocol-v2.txt => gitprotocol-v2.txt} | 25 +++++++++++++----\n Documentation/technical/api-simple-ipc.txt | 2 +-\n Documentation/technical/http-protocol.txt | 6 ++--\n .../long-running-process-protocol.txt | 2 +-\n Documentation/technical/packfile-uri.txt | 2 +-\n Documentation/technical/partial-clone.txt | 2 +-\n command-list.txt | 4 +++\n refspec.h | 2 +-\n t/t5551-http-fetch-smart.sh | 4 +--\n 17 files changed, 106 insertions(+), 37 deletions(-)\n rename Documentation/{technical/protocol-capabilities.txt => gitprotocol-capabilities.txt} (96%)\n rename Documentation/{technical/protocol-common.txt => gitprotocol-common.txt} (89%)\n rename Documentation/{technical/pack-protocol.txt => gitprotocol-pack.txt} (98%)\n rename Documentation/{technical/protocol-v2.txt => gitprotocol-v2.txt} (98%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex e7bd72bb84e..b53f3c12843 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -30,6 +30,10 @@ MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n MAN5_TXT += gitmailmap.txt\n MAN5_TXT += gitmodules.txt\n+MAN5_TXT += gitprotocol-capabilities.txt\n+MAN5_TXT += gitprotocol-common.txt\n+MAN5_TXT += gitprotocol-pack.txt\n+MAN5_TXT += gitprotocol-v2.txt\n MAN5_TXT += gitrepository-layout.txt\n MAN5_TXT += gitweb.conf.txt\n \n@@ -105,12 +109,8 @@ TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n-TECH_DOCS += technical/pack-protocol\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\n-TECH_DOCS += technical/protocol-capabilities\n-TECH_DOCS += technical/protocol-common\n-TECH_DOCS += technical/protocol-v2\n TECH_DOCS += technical/racy-git\n TECH_DOCS += technical/reftable\n TECH_DOCS += technical/send-pack-pipeline\ndiff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.txt\nindex adeda0f24d3..3d88fb0badb 100644\n--- a/Documentation/config/lsrefs.txt\n+++ b/Documentation/config/lsrefs.txt\n@@ -1,7 +1,7 @@\n lsrefs.unborn::\n \tMay be \"advertise\" (the default), \"allow\", or \"ignore\". If \"advertise\",\n \tthe server will respond to the client sending \"unborn\" (as described in\n-\tprotocol-v2.txt) and will advertise support for this feature during the\n+\tlinkgit:gitprotocol-v2[5]) and will advertise support for this feature during the\n \tprotocol v2 capability advertisement. \"allow\" is the same as\n \t\"advertise\" except that the server will not advertise support for this\n \tfeature; this is useful for load-balanced servers that cannot be\ndiff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt\nindex 756591d77b0..57603818514 100644\n--- a/Documentation/config/protocol.txt\n+++ b/Documentation/config/protocol.txt\n@@ -58,6 +58,6 @@ protocol.version::\n * `1` - the original wire protocol with the addition of a version string\n in the initial response from the server.\n \n-* `2` - link:technical/protocol-v2.html[wire protocol version 2].\n+* `2` - Wire protocol version 2, see linkgit:gitprotocol-v2[5].\n \n --\ndiff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt\nindex 8f87b23ea86..3409e0d36d1 100644\n--- a/Documentation/git-upload-pack.txt\n+++ b/Documentation/git-upload-pack.txt\n@@ -40,9 +40,8 @@ OPTIONS\n \tUsed by linkgit:git-http-backend[1] to serve up\n \t`$GIT_URL/info/refs?service=git-upload-pack` requests. See\n \t\"Smart Clients\" in link:technical/http-protocol.html[the HTTP\n-\ttransfer protocols] documentation and \"HTTP Transport\" in\n-\tlink:technical/protocol-v2.html[the Git Wire Protocol, Version\n-\t2] documentation. Also understood by\n+\ttransfer protocols] documentation and \"HTTP Transport\" in the\n+\tlinkgit:gitprotocol-v2[5] documentation. Also understood by\n \tlinkgit:git-receive-pack[1].\n \n ::\ndiff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.txt\nindex 6a9d9e5bf6f..00e0a20e657 100644\n--- a/Documentation/gitformat-bundle.txt\n+++ b/Documentation/gitformat-bundle.txt\n@@ -27,7 +27,7 @@ FORMAT\n ------\n \n We will use ABNF notation to define the Git bundle format. See\n-link:technical/protocol-common.html for the details.\n+linkgit:gitprotocol-common[5] for the details.\n \n A v2 bundle looks like this:\n \ndiff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/gitprotocol-capabilities.txt\nsimilarity index 96%\nrename from Documentation/technical/protocol-capabilities.txt\nrename to Documentation/gitprotocol-capabilities.txt\nindex 9dfade930da..c6dcc7d565d 100644\n--- a/Documentation/technical/protocol-capabilities.txt\n+++ b/Documentation/gitprotocol-capabilities.txt\n@@ -1,8 +1,20 @@\n-Git Protocol Capabilities\n-=========================\n+gitprotocol-capabilities(5)\n+===========================\n+\n+NAME\n+----\n+gitprotocol-capabilities - Protocol v0 and v1 capabilities\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n NOTE: this document describes capabilities for versions 0 and 1 of the pack\n-protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]\n+protocol. For version 2, please refer to the linkgit:gitprotocol-v2[5]\n doc.\n \n Servers SHOULD support all capabilities defined in this document.\n@@ -77,7 +89,7 @@ interleaved with S-R-Q.\n multi_ack_detailed\n ------------------\n This is an extension of multi_ack that permits client to better\n-understand the server's in-memory state. See pack-protocol.txt,\n+understand the server's in-memory state. See linkgit:gitprotocol-pack[5],\n section \"Packfile Negotiation\" for more information.\n \n no-done\n@@ -281,7 +293,7 @@ a packfile upload and reference update. If the pushing client requests\n this capability, after unpacking and updating references the server\n will respond with whether the packfile unpacked successfully and if\n each reference was updated successfully. If any of those were not\n-successful, it will send back an error message. See pack-protocol.txt\n+successful, it will send back an error message. See linkgit:gitprotocol-pack[5]\n for example messages.\n \n report-status-v2\n@@ -292,7 +304,7 @@ adding new \"option\" directives in order to support reference rewritten by\n the \"proc-receive\" hook. The \"proc-receive\" hook may handle a command\n for a pseudo-reference which may create or update a reference with\n different name, new-oid, and old-oid. While the capability\n-'report-status' cannot report for such case. See pack-protocol.txt\n+'report-status' cannot report for such case. See linkgit:gitprotocol-pack[5]\n for details.\n \n delete-refs\n@@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The\n current implementation uses trace2 session IDs (see\n link:api-trace2.html[api-trace2] for details), but this may change and users of\n the session ID should not rely on this fact.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-common.txt b/Documentation/gitprotocol-common.txt\nsimilarity index 89%\nrename from Documentation/technical/protocol-common.txt\nrename to Documentation/gitprotocol-common.txt\nindex ecedb34bba5..1486651bd10 100644\n--- a/Documentation/technical/protocol-common.txt\n+++ b/Documentation/gitprotocol-common.txt\n@@ -1,5 +1,20 @@\n-Documentation Common to Pack and Http Protocols\n-===============================================\n+gitprotocol-common(5)\n+=====================\n+\n+NAME\n+----\n+gitprotocol-common - Things common to various protocols\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n+\n+This document sets defines things common to various over-the-wire\n+protocols and file formats used in Git.\n \n ABNF Notation\n -------------\n@@ -97,3 +112,7 @@ Examples (as C-style strings):\n \"000bfoobar\\n\" \"foobar\\n\"\n \"0004\" \"\"\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitprotocol-pack.txt\nsimilarity index 98%\nrename from Documentation/technical/pack-protocol.txt\nrename to Documentation/gitprotocol-pack.txt\nindex e13a2c064d1..8a4de6decd0 100644\n--- a/Documentation/technical/pack-protocol.txt\n+++ b/Documentation/gitprotocol-pack.txt\n@@ -1,5 +1,17 @@\n-Packfile transfer protocols\n-===========================\n+gitprotocol-pack(5)\n+===================\n+\n+NAME\n+----\n+gitprotocol-pack - How packs are transferred over-the-wire\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n Git supports transferring data in packfiles over the ssh://, git://, http:// and\n file:// transports. There exist two sets of protocols, one for pushing\n@@ -18,7 +30,7 @@ pkt-line Format\n ---------------\n \n The descriptions below build on the pkt-line format described in\n-protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless\n+linkgit:gitprotocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless\n otherwise noted the usual pkt-line LF rules apply: the sender SHOULD\n include a LF, but the receiver MUST NOT complain if it is not present.\n \n@@ -60,7 +72,7 @@ Each Extra Parameter takes the form of `=` or ``.\n \n Servers that receive any such Extra Parameters MUST ignore all\n unrecognized keys. Currently, the only Extra Parameter recognized is\n-\"version\" with a value of '1' or '2'. See protocol-v2.txt for more\n+\"version\" with a value of '1' or '2'. See linkgit:gitprotocol-v2[5] for more\n information on protocol version 2.\n \n Git Transport\n@@ -707,3 +719,7 @@ An example client/server communication might look like this:\n S: 0018ok refs/heads/debug\\n\n S: 002ang refs/heads/master non-fast-forward\\n\n ----\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/protocol-v2.txt b/Documentation/gitprotocol-v2.txt\nsimilarity index 98%\nrename from Documentation/technical/protocol-v2.txt\nrename to Documentation/gitprotocol-v2.txt\nindex 8a877d27e23..d6105e07408 100644\n--- a/Documentation/technical/protocol-v2.txt\n+++ b/Documentation/gitprotocol-v2.txt\n@@ -1,5 +1,17 @@\n-Git Wire Protocol, Version 2\n-============================\n+gitprotocol-v2(5)\n+=================\n+\n+NAME\n+----\n+gitprotocol-v2 - Git Wire Protocol, Version 2\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+DESCRIPTION\n+-----------\n \n This document presents a specification for a version 2 of Git's wire\n protocol. Protocol v2 will improve upon v1 in the following ways:\n@@ -26,8 +38,7 @@ Packet-Line Framing\n -------------------\n \n All communication is done using packet-line framing, just as in v1. See\n-`Documentation/technical/pack-protocol.txt` and\n-`Documentation/technical/protocol-common.txt` for more information.\n+linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-common[5] for more information.\n \n In protocol v2 these special packets will have the following semantics:\n \n@@ -42,7 +53,7 @@ Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`. More information can be\n-found in `pack-protocol.txt` and `http-protocol.txt`, as well as the\n+found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the\n `GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n@@ -566,3 +577,7 @@ and associated requested information, each separated by a single space.\n \tattr = \"size\"\n \n \tobj-info = obj-id SP obj-size\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt\nindex d79ad323e67..d44ada98e7d 100644\n--- a/Documentation/technical/api-simple-ipc.txt\n+++ b/Documentation/technical/api-simple-ipc.txt\n@@ -78,7 +78,7 @@ client and an optional response message from the server. Both the\n client and server messages are unlimited in length and are terminated\n with a flush packet.\n \n-The pkt-line routines (Documentation/technical/protocol-common.txt)\n+The pkt-line routines (linkgit:gitprotocol-common[5])\n are used to simplify buffer management during message generation,\n transmission, and reception. A flush packet is used to mark the end\n of the message. This allows the sender to incrementally generate and\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt\nindex cc5126cfeda..8bd672d55bb 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/technical/http-protocol.txt\n@@ -222,7 +222,7 @@ smart server reply:\n S: 0000\n \n The client may send Extra Parameters (see\n-Documentation/technical/pack-protocol.txt) as a colon-separated string\n+linkgit:gitprotocol-pack[5]) as a colon-separated string\n in the Git-Protocol HTTP header.\n \n Uses the `--http-backend-info-refs` option to\n@@ -518,5 +518,5 @@ References\n \n http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n-link:technical/pack-protocol.html\n-link:technical/protocol-capabilities.html\n+linkgit:gitprotocol-pack[5]\n+linkgit:gitprotocol-capabilities[5]\ndiff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt\nindex aa0aa9af1c2..6f33654b428 100644\n--- a/Documentation/technical/long-running-process-protocol.txt\n+++ b/Documentation/technical/long-running-process-protocol.txt\n@@ -3,7 +3,7 @@ Long-running process protocol\n \n This protocol is used when Git needs to communicate with an external\n process throughout the entire life of a single Git command. All\n-communication is in pkt-line format (see technical/protocol-common.txt)\n+communication is in pkt-line format (see linkgit:gitprotocol-common[5])\n over standard input and standard output.\n \n Handshake\ndiff --git a/Documentation/technical/packfile-uri.txt b/Documentation/technical/packfile-uri.txt\nindex 1eb525fe760..9d453d47651 100644\n--- a/Documentation/technical/packfile-uri.txt\n+++ b/Documentation/technical/packfile-uri.txt\n@@ -18,7 +18,7 @@ a `packfile-uris` argument, the server MAY send a `packfile-uris` section\n directly before the `packfile` section (right after `wanted-refs` if it is\n sent) containing URIs of any of the given protocols. The URIs point to\n packfiles that use only features that the client has declared that it supports\n-(e.g. ofs-delta and thin-pack). See protocol-v2.txt for the documentation of\n+(e.g. ofs-delta and thin-pack). See linkgit:gitprotocol-v2[5] for the documentation of\n this section.\n \n Clients should then download and index all the given URIs (in addition to\ndiff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt\nindex 99f0eb30406..92fcee2bfff 100644\n--- a/Documentation/technical/partial-clone.txt\n+++ b/Documentation/technical/partial-clone.txt\n@@ -79,7 +79,7 @@ Design Details\n upload-pack negotiation.\n +\n This uses the existing capability discovery mechanism.\n-See \"filter\" in Documentation/technical/pack-protocol.txt.\n+See \"filter\" in linkgit:gitprotocol-pack[5].\n \n - Clients pass a \"filter-spec\" to clone and fetch which is passed to the\n server to request filtering during packfile construction.\ndiff --git a/command-list.txt b/command-list.txt\nindex 3afcfcd35f0..ed859fdd798 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -218,6 +218,10 @@ gitk mainporcelain\n gitmailmap userinterfaces\n gitmodules userinterfaces\n gitnamespaces guide\n+gitprotocol-capabilities developerinterfaces\n+gitprotocol-common developerinterfaces\n+gitprotocol-pack developerinterfaces\n+gitprotocol-v2 developerinterfaces\n gitremote-helpers guide\n gitrepository-layout userinterfaces\n gitrevisions userinterfaces\ndiff --git a/refspec.h b/refspec.h\nindex 8b79891d321..8c0c4469933 100644\n--- a/refspec.h\n+++ b/refspec.h\n@@ -69,7 +69,7 @@ int valid_remote_name(const char *name);\n struct strvec;\n /*\n * Determine what values to pass to the peer in ref-prefix lines\n- * (see Documentation/technical/protocol-v2.txt).\n+ * (see linkgit:gitprotocol-v2[5]).\n */\n void refspec_ref_prefixes(const struct refspec *rs,\n \t\t\t struct strvec *ref_prefixes);\ndiff --git a/t/t5551-http-fetch-smart.sh b/t/t5551-http-fetch-smart.sh\nindex 245532df881..6a38294a476 100755\n--- a/t/t5551-http-fetch-smart.sh\n+++ b/t/t5551-http-fetch-smart.sh\n@@ -181,8 +181,8 @@ test_expect_success 'no-op half-auth fetch does not require a password' '\n \t# This is not possible with protocol v2, since both objects and refs\n \t# are obtained from the \"git-upload-pack\" path. A solution to this is\n \t# to teach the server and client to be able to inline ls-refs requests\n-\t# as an Extra Parameter (see pack-protocol.txt), so that \"info/refs\"\n-\t# can serve refs, just like it does in protocol v0.\n+\t# as an Extra Parameter (see \"git help gitformat-pack-protocol\"), so that\n+\t# \"info/refs\" can serve refs, just like it does in protocol v0.\n \tGIT_TEST_PROTOCOL_VERSION=0 git --git-dir=half-auth fetch &&\n \texpect_askpass none\n '\n-- \n2.37.1.1233.g61622908797\n\n"},{"id":"460641","messageId":"patch-v8-10.12-576c1fef4b3-20220804T162138Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v8-00.12-00000000000-20220804T162138Z-avarab@gmail.com","subject":"[PATCH v8 10/12] docs: move pack format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-04T16:28:39Z","receivedAt":"2022-08-04T16:29:32Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe various documentation pertaining to the *.pack format and related\nfiles, and updating things that refer to it to link to the new\nlocation.\n\nBy moving these we can properly link from the newly created\ngitformat-commit-graph to a gitformat-chunk-format page.\n\nIntegrating \"Documentation/technical/bitmap-format.txt\" and\n\"Documentation/technical/cruft-packs.txt\" might logically be part of\nthis change, but as those cover parts of the wider \"pack\nformat\" (including associated files) that's documented outside of\n\"Documentation/technical/pack-format.txt\" let's leave those for now,\nsubsequent commit(s) will address those.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 3 +-\n Documentation/config/pack.txt | 2 +-\n Documentation/git-bundle.txt | 3 +-\n Documentation/git-multi-pack-index.txt | 4 +--\n .../chunk-format.txt => gitformat-chunk.txt} | 25 +++++++++++---\n Documentation/gitformat-commit-graph.txt | 2 +-\n Documentation/gitformat-index.txt | 2 +-\n .../pack-format.txt => gitformat-pack.txt} | 34 +++++++++++++++++--\n Documentation/gitprotocol-pack.txt | 2 +-\n .../howto/recover-corrupted-object-harder.txt | 2 +-\n .../technical/hash-function-transition.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n cache.h | 3 +-\n command-list.txt | 2 ++\n pack-revindex.h | 2 +-\n 15 files changed, 68 insertions(+), 22 deletions(-)\n rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (91%)\n rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex d122d1751d8..d4a4a8c8b7d 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -25,8 +25,10 @@ MAN1_TXT += gitweb.txt\n # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n MAN5_TXT += gitattributes.txt\n MAN5_TXT += gitformat-bundle.txt\n+MAN5_TXT += gitformat-chunk.txt\n MAN5_TXT += gitformat-commit-graph.txt\n MAN5_TXT += gitformat-index.txt\n+MAN5_TXT += gitformat-pack.txt\n MAN5_TXT += gitformat-signature.txt\n MAN5_TXT += githooks.txt\n MAN5_TXT += gitignore.txt\n@@ -108,7 +110,6 @@ TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n-TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n TECH_DOCS += technical/parallel-checkout\n TECH_DOCS += technical/partial-clone\ndiff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt\nindex ad7f73a1ead..3e581eab84a 100644\n--- a/Documentation/config/pack.txt\n+++ b/Documentation/config/pack.txt\n@@ -166,7 +166,7 @@ permuted into their appropriate location when writing a new bitmap.\n \n pack.writeReverseIndex::\n \tWhen true, git will write a corresponding .rev file (see:\n-\tlink:../technical/pack-format.html[Documentation/technical/pack-format.txt])\n+\tlinkgit:gitformat-pack[5])\n \tfor each new packfile that it writes in all places except for\n \tlinkgit:git-fast-import[1] and in the bulk checkin mechanism.\n \tDefaults to false.\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex f0b1282b918..6da61722431 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -57,8 +57,7 @@ size. That they're \"thin\" under the hood is merely noted here as a\n curiosity, and as a reference to other documentation.\n \n See linkgit:gitformat-bundle[5] for more details and the discussion of\n-\"thin pack\" in link:technical/pack-format.html[the pack format\n-documentation] for further details.\n+\"thin pack\" in linkgit:gitformat-pack[5] for further details.\n \n OPTIONS\n -------\ndiff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt\nindex c588fb91af1..a48c3d5ea63 100644\n--- a/Documentation/git-multi-pack-index.txt\n+++ b/Documentation/git-multi-pack-index.txt\n@@ -128,8 +128,8 @@ $ git multi-pack-index verify\n SEE ALSO\n --------\n See link:technical/multi-pack-index.html[The Multi-Pack-Index Design\n-Document] and link:technical/pack-format.html[The Multi-Pack-Index\n-Format] for more information on the multi-pack-index feature.\n+Document] and linkgit:gitformat-pack[5] for more information on the\n+multi-pack-index feature and its file format.\n \n \n GIT\ndiff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt\nsimilarity index 91%\nrename from Documentation/technical/chunk-format.txt\nrename to Documentation/gitformat-chunk.txt\nindex f36ce42f37c..57202ede273 100644\n--- a/Documentation/technical/chunk-format.txt\n+++ b/Documentation/gitformat-chunk.txt\n@@ -1,11 +1,24 @@\n-Chunk-based file formats\n-========================\n+gitformat-chunk(5)\n+==================\n+\n+NAME\n+----\n+gitformat-chunk - Chunk-based file formats\n+\n+SYNOPSIS\n+--------\n+\n+Used by linkgit:gitformat-commit-graph[5] and the \"MIDX\" format (see\n+the pack format documentation in linkgit:gitformat-pack[5]).\n+\n+DESCRIPTION\n+-----------\n \n Some file formats in Git use a common concept of \"chunks\" to describe\n sections of the file. This allows structured access to a large file by\n scanning a small \"table of contents\" for the remaining data. This common\n format is used by the `commit-graph` and `multi-pack-index` files. See\n-link:technical/pack-format.html[the `multi-pack-index` format] and\n+the `multi-pack-index` format in linkgit:gitformat-pack[5] and\n the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n how they use the chunks to describe structured data.\n \n@@ -113,4 +126,8 @@ for future formats:\n * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n in `midx.c` for how the chunk-format API is used to write and\n parse the multi-pack-index file format documented in\n- link:technical/pack-format.html[the multi-pack-index file format].\n+ the multi-pack-index file format section of linkgit:gitformat-pack[5].\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt\nindex 108dc2295c0..7324665716d 100644\n--- a/Documentation/gitformat-commit-graph.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -75,7 +75,7 @@ All multi-byte numbers are in network byte order.\n ID appears at most once.\n \n The CHUNK LOOKUP matches the table of contents from\n- link:technical/chunk-format.html[the chunk-based file format].\n+ the chunk-based file format, see linkgit:gitformat-chunk[5]\n \n The remaining data in the body is described one chunk at a time, and\n these chunks may be given in any order. Chunks are required unless\ndiff --git a/Documentation/gitformat-index.txt b/Documentation/gitformat-index.txt\nindex 9c3844298b8..015cb21bdc0 100644\n--- a/Documentation/gitformat-index.txt\n+++ b/Documentation/gitformat-index.txt\n@@ -139,7 +139,7 @@ Git index format\n entry is encoded as if the path name for the previous entry is an\n empty string). At the beginning of an entry, an integer N in the\n variable width encoding (the same encoding as the offset is encoded\n- for OFS_DELTA pack entries; see pack-format.txt) is stored, followed\n+ for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed\n by a NUL-terminated string S. Removing N bytes from the end of the\n path name for the previous entry, and replacing it with the string S\n yields the path name for this entry.\ndiff --git a/Documentation/technical/pack-format.txt b/Documentation/gitformat-pack.txt\nsimilarity index 95%\nrename from Documentation/technical/pack-format.txt\nrename to Documentation/gitformat-pack.txt\nindex b520aa9c45b..546c99f8871 100644\n--- a/Documentation/technical/pack-format.txt\n+++ b/Documentation/gitformat-pack.txt\n@@ -1,5 +1,29 @@\n-Git pack format\n-===============\n+gitformat-pack(5)\n+=================\n+\n+NAME\n+----\n+gitformat-pack - Git pack format\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+$GIT_DIR/objects/pack/pack-*.{pack,idx}\n+$GIT_DIR/objects/pack/pack-*.rev\n+$GIT_DIR/objects/pack/multi-pack-index\n+\n+DESCRIPTION\n+-----------\n+\n+The Git pack format is now Git stores most of its primary repository\n+data. Over the lietime af a repository loose objects (if any) and\n+smaller packs are consolidated into larger pack(s). See\n+linkgit:git-gc[1] and linkgit:git-pack-objects[1].\n+\n+The pack format is also used over-the-wire, see\n+e.g. linkgit:gitprotocol-v2[5], as well as being a part of\n+other container formats in the case of linkgit:gitformat-bundle[5].\n \n == Checksums and object IDs\n \n@@ -356,7 +380,7 @@ CHUNK LOOKUP:\n \t using the next chunk position if necessary.)\n \n \tThe CHUNK LOOKUP matches the table of contents from\n-\tlink:technical/chunk-format.html[the chunk-based file format].\n+\tthe chunk-based file format, see linkgit:gitformat-chunk[5].\n \n \tThe remaining data in the body is described one chunk at a time, and\n \tthese chunks may be given in any order. Chunks are required unless\n@@ -482,3 +506,7 @@ packs arranged in MIDX order (with the preferred pack coming first).\n \n The MIDX's reverse index is stored in the optional 'RIDX' chunk within\n the MIDX itself.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.txt\nindex 8a4de6decd0..93b30b88450 100644\n--- a/Documentation/gitprotocol-pack.txt\n+++ b/Documentation/gitprotocol-pack.txt\n@@ -467,7 +467,7 @@ Now that the client and server have finished negotiation about what\n the minimal amount of data that needs to be sent to the client is, the server\n will construct and send the required data in packfile format.\n \n-See pack-format.txt for what the packfile itself actually looks like.\n+See linkgit:gitformat-pack[5] for what the packfile itself actually looks like.\n \n If 'side-band' or 'side-band-64k' capabilities have been specified by\n the client, the server will send the packfile data multiplexed.\ndiff --git a/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.txt\nindex 8994e2559ea..5efb4fe81ff 100644\n--- a/Documentation/howto/recover-corrupted-object-harder.txt\n+++ b/Documentation/howto/recover-corrupted-object-harder.txt\n@@ -68,7 +68,7 @@ Note that the \"object\" file isn't fit for feeding straight to zlib; it\n has the git packed object header, which is variable-length. We want to\n strip that off so we can start playing with the zlib data directly. You\n can either work your way through it manually (the format is described in\n-link:../technical/pack-format.html[Documentation/technical/pack-format.txt]),\n+linkgit:gitformat-pack[5]),\n or you can walk through it in a debugger. I did the latter, creating a\n valid pack like:\n \ndiff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt\nindex 260224b0331..e2ac36dd210 100644\n--- a/Documentation/technical/hash-function-transition.txt\n+++ b/Documentation/technical/hash-function-transition.txt\n@@ -205,7 +205,7 @@ SHA-1 content.\n Object storage\n ~~~~~~~~~~~~~~\n Loose objects use zlib compression and packed objects use the packed\n-format described in Documentation/technical/pack-format.txt, just like\n+format described in linkgit:gitformat-pack[5], just like\n today. The content that is compressed and stored uses SHA-256 content\n instead of SHA-1 content.\n \ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 865074bed4e..ca9decdd952 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -3133,7 +3133,7 @@ those \"loose\" objects.\n You can save space and make Git faster by moving these loose objects in\n to a \"pack file\", which stores a group of objects in an efficient\n compressed format; the details of how pack files are formatted can be\n-found in link:technical/pack-format.html[pack format].\n+found in link:gitformat-pack[5].\n \n To put the loose objects into a pack, just run git repack:\n \ndiff --git a/cache.h b/cache.h\nindex 4aa1bd079d5..302810b353a 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -475,8 +475,7 @@ extern struct index_state the_index;\n \n /*\n * Values in this enum (except those outside the 3 bit range) are part\n- * of pack file format. See Documentation/technical/pack-format.txt\n- * for more information.\n+ * of pack file format. See gitformat-pack(5) for more information.\n */\n enum object_type {\n \tOBJ_BAD = -1,\ndiff --git a/command-list.txt b/command-list.txt\nindex 68212e3c1bd..5394eefb6ee 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -210,8 +210,10 @@ gitdiffcore guide\n giteveryday guide\n gitfaq guide\n gitformat-bundle developerinterfaces\n+gitformat-chunk developerinterfaces\n gitformat-commit-graph developerinterfaces\n gitformat-index developerinterfaces\n+gitformat-pack developerinterfaces\n gitformat-signature developerinterfaces\n gitglossary guide\n githooks userinterfaces\ndiff --git a/pack-revindex.h b/pack-revindex.h\nindex 74f4eae668d..4974e75eb4d 100644\n--- a/pack-revindex.h\n+++ b/pack-revindex.h\n@@ -22,7 +22,7 @@\n *\n * - pack position refers to an object's position within a non-existent pack\n * described by the MIDX. The pack structure is described in\n- * Documentation/technical/pack-format.txt.\n+ * gitformat-pack(5).\n *\n * It is effectively a concatanation of all packs in the MIDX (ordered by\n * their numeric ID within the MIDX) in their original order within each\n-- \n2.37.1.1233.g61622908797\n\n"},{"id":"460642","messageId":"patch-v8-11.12-b9dde9788d4-20220804T162138Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v8-00.12-00000000000-20220804T162138Z-avarab@gmail.com","subject":"[PATCH v8 11/12] docs: move cruft pack docs to gitformat-pack","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-04T16:28:40Z","receivedAt":"2022-08-04T16:29:34Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Integrate the cruft packs documentation initially added in\n3d89a8c1180 (Documentation/technical: add cruft-packs.txt, 2022-05-20)\nto the newly created \"gitformat-pack\" documentation.\n\nLike the \"bitmap-format\" added before it in\n0d4455a3ab0 (documentation: add documentation for the bitmap format,\n2013-11-14) the \"cruft-packs\" were documented in their own file.\n\nAs the diff move detection will show there is no change to\n\"Documentation/technical/cruft-packs.txt\" here except to move it, and\nto \"indent\" the existing sections by adding an extra \"=\" to them.\n\nWe could similarly convert the \"bitmap-format.txt\", but let's leave it\nfor now due to a conflict with the in-flight ac/bitmap-lookup-table\nseries.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 -\n Documentation/gitformat-pack.txt | 126 ++++++++++++++++++++++++\n Documentation/technical/cruft-packs.txt | 123 -----------------------\n 3 files changed, 126 insertions(+), 124 deletions(-)\n delete mode 100644 Documentation/technical/cruft-packs.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex d4a4a8c8b7d..41a070ab593 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -105,7 +105,6 @@ TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n-TECH_DOCS += technical/cruft-packs\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n TECH_DOCS += technical/long-running-process-protocol\ndiff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt\nindex 546c99f8871..e06af02f211 100644\n--- a/Documentation/gitformat-pack.txt\n+++ b/Documentation/gitformat-pack.txt\n@@ -11,6 +11,7 @@ SYNOPSIS\n [verse]\n $GIT_DIR/objects/pack/pack-*.{pack,idx}\n $GIT_DIR/objects/pack/pack-*.rev\n+$GIT_DIR/objects/pack/pack-*.mtimes\n $GIT_DIR/objects/pack/multi-pack-index\n \n DESCRIPTION\n@@ -507,6 +508,131 @@ packs arranged in MIDX order (with the preferred pack coming first).\n The MIDX's reverse index is stored in the optional 'RIDX' chunk within\n the MIDX itself.\n \n+== cruft packs\n+\n+The cruft packs feature offer an alternative to Git's traditional mechanism of\n+removing unreachable objects. This document provides an overview of Git's\n+pruning mechanism, and how a cruft pack can be used instead to accomplish the\n+same.\n+\n+=== Background\n+\n+To remove unreachable objects from your repository, Git offers `git repack -Ad`\n+(see linkgit:git-repack[1]). Quoting from the documentation:\n+\n+----\n+[...] unreachable objects in a previous pack become loose, unpacked objects,\n+instead of being left in the old pack. [...] loose unreachable objects will be\n+pruned according to normal expiry rules with the next 'git gc' invocation.\n+----\n+\n+Unreachable objects aren't removed immediately, since doing so could race with\n+an incoming push which may reference an object which is about to be deleted.\n+Instead, those unreachable objects are stored as loose objects and stay that way\n+until they are older than the expiration window, at which point they are removed\n+by linkgit:git-prune[1].\n+\n+Git must store these unreachable objects loose in order to keep track of their\n+per-object mtimes. If these unreachable objects were written into one big pack,\n+then either freshening that pack (because an object contained within it was\n+re-written) or creating a new pack of unreachable objects would cause the pack's\n+mtime to get updated, and the objects within it would never leave the expiration\n+window. Instead, objects are stored loose in order to keep track of the\n+individual object mtimes and avoid a situation where all cruft objects are\n+freshened at once.\n+\n+This can lead to undesirable situations when a repository contains many\n+unreachable objects which have not yet left the grace period. Having large\n+directories in the shards of `.git/objects` can lead to decreased performance in\n+the repository. But given enough unreachable objects, this can lead to inode\n+starvation and degrade the performance of the whole system. Since we\n+can never pack those objects, these repositories often take up a large amount of\n+disk space, since we can only zlib compress them, but not store them in delta\n+chains.\n+\n+=== Cruft packs\n+\n+A cruft pack eliminates the need for storing unreachable objects in a loose\n+state by including the per-object mtimes in a separate file alongside a single\n+pack containing all loose objects.\n+\n+A cruft pack is written by `git repack --cruft` when generating a new pack.\n+linkgit:git-pack-objects[1]'s `--cruft` option. Note that `git repack --cruft`\n+is a classic all-into-one repack, meaning that everything in the resulting pack is\n+reachable, and everything else is unreachable. Once written, the `--cruft`\n+option instructs `git repack` to generate another pack containing only objects\n+not packed in the previous step (which equates to packing all unreachable\n+objects together). This progresses as follows:\n+\n+ 1. Enumerate every object, marking any object which is (a) not contained in a\n+ kept-pack, and (b) whose mtime is within the grace period as a traversal\n+ tip.\n+\n+ 2. Perform a reachability traversal based on the tips gathered in the previous\n+ step, adding every object along the way to the pack.\n+\n+ 3. Write the pack out, along with a `.mtimes` file that records the per-object\n+ timestamps.\n+\n+This mode is invoked internally by linkgit:git-repack[1] when instructed to\n+write a cruft pack. Crucially, the set of in-core kept packs is exactly the set\n+of packs which will not be deleted by the repack; in other words, they contain\n+all of the repository's reachable objects.\n+\n+When a repository already has a cruft pack, `git repack --cruft` typically only\n+adds objects to it. An exception to this is when `git repack` is given the\n+`--cruft-expiration` option, which allows the generated cruft pack to omit\n+expired objects instead of waiting for linkgit:git-gc[1] to expire those objects\n+later on.\n+\n+It is linkgit:git-gc[1] that is typically responsible for removing expired\n+unreachable objects.\n+\n+=== Caution for mixed-version environments\n+\n+Repositories that have cruft packs in them will continue to work with any older\n+version of Git. Note, however, that previous versions of Git which do not\n+understand the `.mtimes` file will use the cruft pack's mtime as the mtime for\n+all of the objects in it. In other words, do not expect older (pre-cruft pack)\n+versions of Git to interpret or even read the contents of the `.mtimes` file.\n+\n+Note that having mixed versions of Git GC-ing the same repository can lead to\n+unreachable objects never being completely pruned. This can happen under the\n+following circumstances:\n+\n+ - An older version of Git running GC explodes the contents of an existing\n+ cruft pack loose, using the cruft pack's mtime.\n+ - A newer version running GC collects those loose objects into a cruft pack,\n+ where the .mtime file reflects the loose object's actual mtimes, but the\n+ cruft pack mtime is \"now\".\n+\n+Repeating this process will lead to unreachable objects not getting pruned as a\n+result of repeatedly resetting the objects' mtimes to the present time.\n+\n+If you are GC-ing repositories in a mixed version environment, consider omitting\n+the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and\n+leaving the `gc.cruftPacks` configuration unset until all writers understand\n+cruft packs.\n+\n+=== Alternatives\n+\n+Notable alternatives to this design include:\n+\n+ - The location of the per-object mtime data, and\n+ - Storing unreachable objects in multiple cruft packs.\n+\n+On the location of mtime data, a new auxiliary file tied to the pack was chosen\n+to avoid complicating the `.idx` format. If the `.idx` format were ever to gain\n+support for optional chunks of data, it may make sense to consolidate the\n+`.mtimes` format into the `.idx` itself.\n+\n+Storing unreachable objects among multiple cruft packs (e.g., creating a new\n+cruft pack during each repacking operation including only unreachable objects\n+which aren't already stored in an earlier cruft pack) is significantly more\n+complicated to construct, and so aren't pursued here. The obvious drawback to\n+the current implementation is that the entire cruft pack must be re-written from\n+scratch.\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/cruft-packs.txt b/Documentation/technical/cruft-packs.txt\ndeleted file mode 100644\nindex d81f3a8982f..00000000000\n--- a/Documentation/technical/cruft-packs.txt\n+++ /dev/null\n@@ -1,123 +0,0 @@\n-= Cruft packs\n-\n-The cruft packs feature offer an alternative to Git's traditional mechanism of\n-removing unreachable objects. This document provides an overview of Git's\n-pruning mechanism, and how a cruft pack can be used instead to accomplish the\n-same.\n-\n-== Background\n-\n-To remove unreachable objects from your repository, Git offers `git repack -Ad`\n-(see linkgit:git-repack[1]). Quoting from the documentation:\n-\n-[quote]\n-[...] unreachable objects in a previous pack become loose, unpacked objects,\n-instead of being left in the old pack. [...] loose unreachable objects will be\n-pruned according to normal expiry rules with the next 'git gc' invocation.\n-\n-Unreachable objects aren't removed immediately, since doing so could race with\n-an incoming push which may reference an object which is about to be deleted.\n-Instead, those unreachable objects are stored as loose objects and stay that way\n-until they are older than the expiration window, at which point they are removed\n-by linkgit:git-prune[1].\n-\n-Git must store these unreachable objects loose in order to keep track of their\n-per-object mtimes. If these unreachable objects were written into one big pack,\n-then either freshening that pack (because an object contained within it was\n-re-written) or creating a new pack of unreachable objects would cause the pack's\n-mtime to get updated, and the objects within it would never leave the expiration\n-window. Instead, objects are stored loose in order to keep track of the\n-individual object mtimes and avoid a situation where all cruft objects are\n-freshened at once.\n-\n-This can lead to undesirable situations when a repository contains many\n-unreachable objects which have not yet left the grace period. Having large\n-directories in the shards of `.git/objects` can lead to decreased performance in\n-the repository. But given enough unreachable objects, this can lead to inode\n-starvation and degrade the performance of the whole system. Since we\n-can never pack those objects, these repositories often take up a large amount of\n-disk space, since we can only zlib compress them, but not store them in delta\n-chains.\n-\n-== Cruft packs\n-\n-A cruft pack eliminates the need for storing unreachable objects in a loose\n-state by including the per-object mtimes in a separate file alongside a single\n-pack containing all loose objects.\n-\n-A cruft pack is written by `git repack --cruft` when generating a new pack.\n-linkgit:git-pack-objects[1]'s `--cruft` option. Note that `git repack --cruft`\n-is a classic all-into-one repack, meaning that everything in the resulting pack is\n-reachable, and everything else is unreachable. Once written, the `--cruft`\n-option instructs `git repack` to generate another pack containing only objects\n-not packed in the previous step (which equates to packing all unreachable\n-objects together). This progresses as follows:\n-\n- 1. Enumerate every object, marking any object which is (a) not contained in a\n- kept-pack, and (b) whose mtime is within the grace period as a traversal\n- tip.\n-\n- 2. Perform a reachability traversal based on the tips gathered in the previous\n- step, adding every object along the way to the pack.\n-\n- 3. Write the pack out, along with a `.mtimes` file that records the per-object\n- timestamps.\n-\n-This mode is invoked internally by linkgit:git-repack[1] when instructed to\n-write a cruft pack. Crucially, the set of in-core kept packs is exactly the set\n-of packs which will not be deleted by the repack; in other words, they contain\n-all of the repository's reachable objects.\n-\n-When a repository already has a cruft pack, `git repack --cruft` typically only\n-adds objects to it. An exception to this is when `git repack` is given the\n-`--cruft-expiration` option, which allows the generated cruft pack to omit\n-expired objects instead of waiting for linkgit:git-gc[1] to expire those objects\n-later on.\n-\n-It is linkgit:git-gc[1] that is typically responsible for removing expired\n-unreachable objects.\n-\n-== Caution for mixed-version environments\n-\n-Repositories that have cruft packs in them will continue to work with any older\n-version of Git. Note, however, that previous versions of Git which do not\n-understand the `.mtimes` file will use the cruft pack's mtime as the mtime for\n-all of the objects in it. In other words, do not expect older (pre-cruft pack)\n-versions of Git to interpret or even read the contents of the `.mtimes` file.\n-\n-Note that having mixed versions of Git GC-ing the same repository can lead to\n-unreachable objects never being completely pruned. This can happen under the\n-following circumstances:\n-\n- - An older version of Git running GC explodes the contents of an existing\n- cruft pack loose, using the cruft pack's mtime.\n- - A newer version running GC collects those loose objects into a cruft pack,\n- where the .mtime file reflects the loose object's actual mtimes, but the\n- cruft pack mtime is \"now\".\n-\n-Repeating this process will lead to unreachable objects not getting pruned as a\n-result of repeatedly resetting the objects' mtimes to the present time.\n-\n-If you are GC-ing repositories in a mixed version environment, consider omitting\n-the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and\n-leaving the `gc.cruftPacks` configuration unset until all writers understand\n-cruft packs.\n-\n-== Alternatives\n-\n-Notable alternatives to this design include:\n-\n- - The location of the per-object mtime data, and\n- - Storing unreachable objects in multiple cruft packs.\n-\n-On the location of mtime data, a new auxiliary file tied to the pack was chosen\n-to avoid complicating the `.idx` format. If the `.idx` format were ever to gain\n-support for optional chunks of data, it may make sense to consolidate the\n-`.mtimes` format into the `.idx` itself.\n-\n-Storing unreachable objects among multiple cruft packs (e.g., creating a new\n-cruft pack during each repacking operation including only unreachable objects\n-which aren't already stored in an earlier cruft pack) is significantly more\n-complicated to construct, and so aren't pursued here. The obvious drawback to\n-the current implementation is that the entire cruft pack must be re-written from\n-scratch.\n-- \n2.37.1.1233.g61622908797\n\n"},{"id":"460643","messageId":"patch-v8-12.12-c572688c525-20220804T162138Z-avarab@gmail.com","threadId":"56715","inReplyTo":"cover-v8-00.12-00000000000-20220804T162138Z-avarab@gmail.com","subject":"[PATCH v8 12/12] docs: move http-protocol docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-04T16:28:41Z","receivedAt":"2022-08-04T16:29:36Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the move of existing Documentation/technical/* protocol and\nfile-format documentation into our main documentation space by moving\nthe http-protocol.txt documentation over. I'm renaming it to\n\"protocol-http\" to be consistent with other things in the new\ngitformat-protocol-* namespace.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 2 +-\n Documentation/git-upload-pack.txt | 6 ++--\n ...http-protocol.txt => gitprotocol-http.txt} | 29 ++++++++++++++++---\n Documentation/gitprotocol-pack.txt | 2 +-\n Documentation/gitprotocol-v2.txt | 4 +--\n command-list.txt | 1 +\n 6 files changed, 33 insertions(+), 11 deletions(-)\n rename Documentation/{technical/http-protocol.txt => gitprotocol-http.txt} (98%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 41a070ab593..346bbcf8be7 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -36,6 +36,7 @@ MAN5_TXT += gitmailmap.txt\n MAN5_TXT += gitmodules.txt\n MAN5_TXT += gitprotocol-capabilities.txt\n MAN5_TXT += gitprotocol-common.txt\n+MAN5_TXT += gitprotocol-http.txt\n MAN5_TXT += gitprotocol-pack.txt\n MAN5_TXT += gitprotocol-v2.txt\n MAN5_TXT += gitrepository-layout.txt\n@@ -106,7 +107,6 @@ TECH_DOCS += SubmittingPatches\n TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bitmap-format\n TECH_DOCS += technical/hash-function-transition\n-TECH_DOCS += technical/http-protocol\n TECH_DOCS += technical/long-running-process-protocol\n TECH_DOCS += technical/multi-pack-index\n TECH_DOCS += technical/pack-heuristics\ndiff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt\nindex 3409e0d36d1..3f89d640772 100644\n--- a/Documentation/git-upload-pack.txt\n+++ b/Documentation/git-upload-pack.txt\n@@ -39,9 +39,9 @@ OPTIONS\n --http-backend-info-refs::\n \tUsed by linkgit:git-http-backend[1] to serve up\n \t`$GIT_URL/info/refs?service=git-upload-pack` requests. See\n-\t\"Smart Clients\" in link:technical/http-protocol.html[the HTTP\n-\ttransfer protocols] documentation and \"HTTP Transport\" in the\n-\tlinkgit:gitprotocol-v2[5] documentation. Also understood by\n+\t\"Smart Clients\" in linkgit:gitprotocol-http[5] and \"HTTP\n+\tTransport\" in in the linkgit:gitprotocol-v2[5]\n+\tdocumentation. Also understood by\n \tlinkgit:git-receive-pack[1].\n \n ::\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/gitprotocol-http.txt\nsimilarity index 98%\nrename from Documentation/technical/http-protocol.txt\nrename to Documentation/gitprotocol-http.txt\nindex 8bd672d55bb..ccc13f0a407 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/gitprotocol-http.txt\n@@ -1,5 +1,19 @@\n-HTTP transfer protocols\n-=======================\n+gitprotocol-http(5)\n+===================\n+\n+NAME\n+----\n+gitprotocol-http - Git HTTP-based protocols\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+\n+\n+\n+DESCRIPTION\n+-----------\n \n Git supports two HTTP based transfer protocols. A \"dumb\" protocol\n which requires only a standard HTTP server on the server end of the\n@@ -512,11 +526,18 @@ the id obtained through ref discovery as old_id.\n \n TODO: Document this further.\n \n-\n-References\n+REFERENCES\n ----------\n \n http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n+\n+SEE ALSO\n+--------\n+\n linkgit:gitprotocol-pack[5]\n linkgit:gitprotocol-capabilities[5]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.txt\nindex 93b30b88450..dd4108b7a3b 100644\n--- a/Documentation/gitprotocol-pack.txt\n+++ b/Documentation/gitprotocol-pack.txt\n@@ -17,7 +17,7 @@ Git supports transferring data in packfiles over the ssh://, git://, http:// and\n file:// transports. There exist two sets of protocols, one for pushing\n data from a client to a server and another for fetching data from a\n server to a client. The three transports (ssh, git, file) use the same\n-protocol to transfer data. http is documented in http-protocol.txt.\n+protocol to transfer data. http is documented in linkgit:gitprotocol-http[5].\n \n The processes invoked in the canonical Git implementation are 'upload-pack'\n on the server side and 'fetch-pack' on the client side for fetching data;\ndiff --git a/Documentation/gitprotocol-v2.txt b/Documentation/gitprotocol-v2.txt\nindex d6105e07408..c9c0f9160b2 100644\n--- a/Documentation/gitprotocol-v2.txt\n+++ b/Documentation/gitprotocol-v2.txt\n@@ -53,7 +53,7 @@ Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`. More information can be\n-found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the\n+found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the\n `GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n@@ -77,7 +77,7 @@ HTTP Transport\n ~~~~~~~~~~~~~~\n \n When using the http:// or https:// transport a client makes a \"smart\"\n-info/refs request as described in `http-protocol.txt` and requests that\n+info/refs request as described in linkgit:gitprotocol-http[5] and requests that\n v2 be used by supplying \"version=2\" in the `Git-Protocol` header.\n \n C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0\ndiff --git a/command-list.txt b/command-list.txt\nindex 5394eefb6ee..f96bdabd7d9 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -224,6 +224,7 @@ gitmodules userinterfaces\n gitnamespaces guide\n gitprotocol-capabilities developerinterfaces\n gitprotocol-common developerinterfaces\n+gitprotocol-http developerinterfaces\n gitprotocol-pack developerinterfaces\n gitprotocol-v2 developerinterfaces\n gitremote-helpers guide\n-- \n2.37.1.1233.g61622908797\n\n"},{"id":"460644","messageId":"220804.867d3ot1gt.gmgdl@evledraar.gmail.com","threadId":"56715","inReplyTo":"xmqqbkt1cohu.fsf@gitster.g","subject":"Re: [PATCH v7 07/10] docs: move protocol-related docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-04T16:29:39Z","receivedAt":"2022-08-04T16:31:21Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Wed, Aug 03 2022, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason writes:\n>\n>> Continue the move of existing Documentation/technical/* protocol and\n>> file-format documentation into our main documentation space. By moving\n>> the things that discuss the protocol we can properly link from\n>> e.g. lsrefs.unborn and protocol.version documentation to a manpage we\n>> build by default.\n>>\n>> So far we have been using the \"gitformat-\" prefix for the\n>> documentation we've been moving over from Documentation/technical/*,\n>> but for protocol documentation let's use \"gitprotocol-*\".\n>>\n>> Signed-off-by: Ævar Arnfjörð Bjarmason \n>> ---\n>> Documentation/Makefile | 8 +++---\n>> Documentation/config/lsrefs.txt | 2 +-\n>> Documentation/config/protocol.txt | 2 +-\n>> Documentation/git-upload-pack.txt | 5 ++--\n>> Documentation/gitformat-bundle.txt | 2 +-\n>> ...ities.txt => gitprotocol-capabilities.txt} | 28 +++++++++++++++----\n>> ...ocol-common.txt => gitprotocol-common.txt} | 23 +++++++++++++--\n>> ...pack-protocol.txt => gitprotocol-pack.txt} | 24 +++++++++++++---\n>> .../protocol-v2.txt => gitprotocol-v2.txt} | 25 +++++++++++++----\n>> Documentation/technical/api-simple-ipc.txt | 2 +-\n>> Documentation/technical/http-protocol.txt | 6 ++--\n>> .../long-running-process-protocol.txt | 2 +-\n>> Documentation/technical/packfile-uri.txt | 2 +-\n>> Documentation/technical/partial-clone.txt | 2 +-\n>> command-list.txt | 5 +++-\n>> refspec.h | 2 +-\n>> t/t5551-http-fetch-smart.sh | 4 +--\n>> 17 files changed, 106 insertions(+), 38 deletions(-)\n>\n> OK, I see nothing unexpected.\n>\n> There is a silent \"oops that is a screw-up in the previous step that\n> can be buried in this patch that renames 4 files and hopefully nobody\n> would notice\" included, which should be removed by fixing the original\n> screw-up in the previous step, though.\n\nI tried to address all your other concerns in the just-sent v8, but I\ndon't think there's any rename fix-up here, but maybe I'm missing\nsomething. These files are all being moved to their new\ngitprotocol-*.txt homes (and weren't moved in preceding commits).\n"},{"id":"460656","messageId":"xmqqles34xij.fsf@gitster.g","threadId":"56715","inReplyTo":"220804.867d3ot1gt.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH v7 07/10] docs: move protocol-related docs to man section 5","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-04T19:30:28Z","receivedAt":"2022-08-04T19:30:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> I tried to address all your other concerns in the just-sent v8, but I\n> don't think there's any rename fix-up here, but maybe I'm missing\n> something. These files are all being moved to their new\n> gitprotocol-*.txt homes (and weren't moved in preceding commits).\n\nSorry, I thought it was rather obvious from what I wrote in my\nreview for the step before this one.\n\nThis is an \"oops\" fix-up buried in other changes in 07/10 that fixes\nthe duplicated entry made in the previous step.\n\n> diff --git a/command-list.txt b/command-list.txt\n> index 44e244a76f6..ed859fdd798 100644\n> --- a/command-list.txt\n> +++ b/command-list.txt\n> @@ -210,7 +210,6 @@ gitdiffcore guide\n> giteveryday guide\n> gitfaq guide\n> gitformat-bundle developerinterfaces\n> -gitformat-bundle developerinterfaces\n> gitformat-commit-graph developerinterfaces\n> gitglossary guide\n> githooks userinterfaces\n"},{"id":"460671","messageId":"xmqqo7wz3e1u.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-v8-01.12-8ae30ce2e80-20220804T162138Z-avarab@gmail.com","subject":"Re: [PATCH v8 01/12] help.c: refactor drop_prefix() to use a \"switch\" statement\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-04T21:16:13Z","receivedAt":"2022-08-04T21:16:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> This means that we'd in principle strip \"git-foo\" down to \"foo\" if\n> it's in CAT_guide. That doesn't make much sense, and we don't have\n> such an entry in command-list.txt, but let's preserve that behavior\n> for now.\n\nThat makes sense. I guess the previous round of this step tried to\nsay the same thing, but it didn't \"click\" to me. The updated text\ndoes make sense.\n"},{"id":"460673","messageId":"xmqqk07n3dxs.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-v8-06.12-df3ef265d45-20220804T162138Z-avarab@gmail.com","subject":"Re: [PATCH v8 06/12] docs: move commit-graph format docs to man section 5","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-04T21:18:39Z","receivedAt":"2022-08-04T21:18:45Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Continue the move of existing Documentation/technical/* protocol and\n> file-format documentation into our main documentation space.\n> ...\n> diff --git a/command-list.txt b/command-list.txt\n> index 1950c4ccd9c..3afcfcd35f0 100644\n> --- a/command-list.txt\n> +++ b/command-list.txt\n> @@ -210,6 +210,7 @@ gitdiffcore guide\n> giteveryday guide\n> gitfaq guide\n> gitformat-bundle developerinterfaces\n> +gitformat-commit-graph developerinterfaces\n> gitglossary guide\n> githooks userinterfaces\n> gitignore userinterfaces\n\nThis round the entire patch looks good to me, including this file.\n"},{"id":"460674","messageId":"xmqqedxv3dnz.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-v8-08.12-ea98b37e41a-20220804T162138Z-avarab@gmail.com","subject":"Re: [PATCH v8 08/12] docs: move index format docs to man section 5","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-04T21:24:32Z","receivedAt":"2022-08-04T21:24:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Continue the move of existing Documentation/technical/* protocol and\n> file-format documentation into our main documentation space by moving\n> the index format documentation.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/Makefile | 2 +-\n> .../index-format.txt => gitformat-index.txt} | 20 ++++++++++++++++++-\n> command-list.txt | 1 +\n> 3 files changed, 21 insertions(+), 2 deletions(-)\n> rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)\n\nOK, the corresponding step in the previous round mixed the index\nformat and the bundle format together with formats of pack-related\nfiles in a single patch, but now we have a separate patch for the\nindex on its own, which we are seeing here.\n\nNothing unexpected in the patch. Very cleanly done.\n\nThanks.\n"},{"id":"460675","messageId":"xmqqa68j3dm2.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-v8-09.12-42a4a3c3be8-20220804T162138Z-avarab@gmail.com","subject":"Re: [PATCH v8 09/12] docs: move signature docs to man section 5","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-04T21:25:41Z","receivedAt":"2022-08-04T21:25:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Continue the move of existing Documentation/technical/* protocol and\n> file-format documentation into our main documentation space by moving\n> the signature format documentation.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n\nExactly the same comment as the one for the previous one (index)\napplies to this step (signature). Nicely done, without anything\nunexpected.\n\n"},{"id":"460676","messageId":"xmqq5yj73d6l.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-v8-11.12-b9dde9788d4-20220804T162138Z-avarab@gmail.com","subject":"Re: [PATCH v8 11/12] docs: move cruft pack docs to gitformat-pack","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-04T21:34:58Z","receivedAt":"2022-08-04T21:35:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Integrate the cruft packs documentation initially added in\n> 3d89a8c1180 (Documentation/technical: add cruft-packs.txt, 2022-05-20)\n> to the newly created \"gitformat-pack\" documentation.\n>\n> Like the \"bitmap-format\" added before it in\n> 0d4455a3ab0 (documentation: add documentation for the bitmap format,\n> 2013-11-14) the \"cruft-packs\" were documented in their own file.\n>\n> As the diff move detection will show there is no change to\n> \"Documentation/technical/cruft-packs.txt\" here except to move it, and\n> to \"indent\" the existing sections by adding an extra \"=\" to them.\n>\n> We could similarly convert the \"bitmap-format.txt\", but let's leave it\n> for now due to a conflict with the in-flight ac/bitmap-lookup-table\n> series.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n\nOK, so this round we roll the \"cruft packs\" into the main \"pack file\nformat\" documentation, because the former is merely a minor deviation\nat file format level (i.e. comes with an extra .mtimes file) and the\nphilosophy behind how they are meant to be used is what makes them,\nthat is mostly the same as the normal packs, different.\n\nThat makes sense to me, and I agree that in the longer term we may\nwant to treat the pack bitmap format documentation the same way.\n\n"},{"id":"460677","messageId":"xmqq1qtv3d3a.fsf@gitster.g","threadId":"56715","inReplyTo":"cover-v8-00.12-00000000000-20220804T162138Z-avarab@gmail.com","subject":"Re: [PATCH v8 00/12] docs: create & use \"(user|developer) interfaces\" categories","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-04T21:36:57Z","receivedAt":"2022-08-04T21:37:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> See the v5 for a general overview:\n> https://lore.kernel.org/git/cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com/\n>\n> Ævar Arnfjörð Bjarmason (12):\n> help.c: refactor drop_prefix() to use a \"switch\" statement\"\n> help.c: remove common category behavior from drop_prefix() behavior\n> git help doc: use \"\" instead of \"\"\n> git docs: add a category for user-facing file, repo and command UX\n> git docs: add a category for file formats, protocols and interfaces\n> docs: move commit-graph format docs to man section 5\n> docs: move protocol-related docs to man section 5\n> docs: move index format docs to man section 5\n> docs: move signature docs to man section 5\n> docs: move pack format docs to man section 5\n> docs: move cruft pack docs to gitformat-pack\n> docs: move http-protocol docs to man section 5\n\nOK, I have to admit that my eyes were a bit too tired to give a\nfine-toothed-comb review, but between range-diff output and a full\nreading of the new ones that range-diff did not match with the old\nround, I did not find anything unexpected. Looking good.\n\nThanks.\n"},{"id":"460702","messageId":"220805.86h72rrsuc.gmgdl@evledraar.gmail.com","threadId":"56715","inReplyTo":"xmqq5yj73d6l.fsf@gitster.g","subject":"Re: [PATCH v8 11/12] docs: move cruft pack docs to gitformat-pack","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-05T08:29:08Z","receivedAt":"2022-08-05T08:35:41Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Thu, Aug 04 2022, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason writes:\n>\n>> Integrate the cruft packs documentation initially added in\n>> 3d89a8c1180 (Documentation/technical: add cruft-packs.txt, 2022-05-20)\n>> to the newly created \"gitformat-pack\" documentation.\n>>\n>> Like the \"bitmap-format\" added before it in\n>> 0d4455a3ab0 (documentation: add documentation for the bitmap format,\n>> 2013-11-14) the \"cruft-packs\" were documented in their own file.\n>>\n>> As the diff move detection will show there is no change to\n>> \"Documentation/technical/cruft-packs.txt\" here except to move it, and\n>> to \"indent\" the existing sections by adding an extra \"=\" to them.\n>>\n>> We could similarly convert the \"bitmap-format.txt\", but let's leave it\n>> for now due to a conflict with the in-flight ac/bitmap-lookup-table\n>> series.\n>>\n>> Signed-off-by: Ævar Arnfjörð Bjarmason \n>> ---\n>\n> OK, so this round we roll the \"cruft packs\" into the main \"pack file\n> format\" documentation, because the former is merely a minor deviation\n> at file format level (i.e. comes with an extra .mtimes file) and the\n> philosophy behind how they are meant to be used is what makes them,\n> that is mostly the same as the normal packs, different.\n\nYes, perhaps we should split all of these out, but it's a smaller\nlogical change to just bundle the ones that were split out into the main\ndocumentation.\n\n> That makes sense to me, and I agree that in the longer term we may\n> want to treat the pack bitmap format documentation the same way.\n\nI have that patch locally already, and figured I'd send it in shortly\nafter this lands. I just didn't want to burden you with the merge\nconflict with c7e7f5dd814 (Documentation/technical: describe bitmap\nlookup table extension, 2022-07-20).\n\nThe merge conflict is relatively easy to deal with, I included a\nresolution in the v3 of this series (but ejected the change out of v4):\nhttps://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/\n\nI can still re-roll with it if you'd like it sooner than later, or\nac/bitmap-lookup-table could be re-rolled on top of this topic\neventually (it seems it needs an eventual re-roll anyway due to SHA-256\nflakyness).\n\nOr we could just go with the status quo here and leave it until the dust\neventually settles, which is what I went with so far.\n"},{"id":"460703","messageId":"220805.86czdfrsoj.gmgdl@evledraar.gmail.com","threadId":"56715","inReplyTo":"xmqqles34xij.fsf@gitster.g","subject":"Re: [PATCH v7 07/10] docs: move protocol-related docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-05T08:36:56Z","receivedAt":"2022-08-05T08:39:10Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Thu, Aug 04 2022, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason writes:\n>\n>> I tried to address all your other concerns in the just-sent v8, but I\n>> don't think there's any rename fix-up here, but maybe I'm missing\n>> something. These files are all being moved to their new\n>> gitprotocol-*.txt homes (and weren't moved in preceding commits).\n>\n> Sorry, I thought it was rather obvious from what I wrote in my\n> review for the step before this one.\n>\n> This is an \"oops\" fix-up buried in other changes in 07/10 that fixes\n> the duplicated entry made in the previous step.\n\nAh!, sorry about not spotting that. I see I misread the \"that renames 4\nfiles[...]\" part of your reply.\n\nAnd when I was looking at this patch I'd already locally fixed the\nearlier commit that had the duplicate command-list.txt entry, so I\ncouldn't see any issue with the rest of the commit either :)\n\nIn any case, it's all sorted in the v8, thanks!\n"},{"id":"460718","messageId":"xmqq35ea1xgj.fsf@gitster.g","threadId":"56715","inReplyTo":"220805.86h72rrsuc.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH v8 11/12] docs: move cruft pack docs to gitformat-pack","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-05T16:12:12Z","receivedAt":"2022-08-05T16:12:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n>> That makes sense to me, and I agree that in the longer term we may\n>> want to treat the pack bitmap format documentation the same way.\n>\n> I have that patch locally already, and figured I'd send it in shortly\n> after this lands. I just didn't want to burden you with the merge\n> conflict with c7e7f5dd814 (Documentation/technical: describe bitmap\n> lookup table extension, 2022-07-20).\n>\n> The merge conflict is relatively easy to deal with, I included a\n> resolution in the v3 of this series (but ejected the change out of v4):\n> https://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/\n>\n> I can still re-roll with it if you'd like it sooner than later, or\n> ac/bitmap-lookup-table could be re-rolled on top of this topic\n> eventually (it seems it needs an eventual re-roll anyway due to SHA-256\n> flakyness).\n>\n> Or we could just go with the status quo here and leave it until the dust\n> eventually settles, which is what I went with so far.\n\nLet's go slowly. Others may feel differently and prefer separate\nmanual pages for .mtimes and .bitmap formats instead. They have\nmore info to form their opinions after this round lands.\n\nThanks.\n"},{"id":"466851","messageId":"20221108180417.GB1731@szeder.dev","threadId":"56715","inReplyTo":"patch-v8-06.12-df3ef265d45-20220804T162138Z-avarab@gmail.com","subject":"Re: [PATCH v8 06/12] docs: move commit-graph format docs to man section 5","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2022-11-08T18:04:17Z","receivedAt":"2022-11-08T18:04:27Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"On Thu, Aug 04, 2022 at 06:28:35PM +0200, Ævar Arnfjörð Bjarmason wrote:\n> Continue the move of existing Documentation/technical/* protocol and\n> file-format documentation into our main documentation space.\n> \n> By moving the documentation for the commit-graph format into man\n> section 5 and the new \"developerinterfaces\" category. This change is\n> split from subsequent commits due to the relatively large amount of\n> ASCIIDOC formatting changes that are required.\n\nSo after this series I got a couple of gitformat-* manpages, but,\nalas, most of them render improperly: a lot of paragraphs are for some\nreason fixed width even in a fullscreen terminal window, and their\nwidth is more than 80 chars, so they are rather awkward in a\nstandard-width terminal. This also affects the html version, where\nthose paragraphs are rendered with a fixed-width font.\n\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/Makefile | 1 +\n> Documentation/git-commit-graph.txt | 5 ++\n> ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------\n> Documentation/technical/chunk-format.txt | 4 +-\n> command-list.txt | 1 +\n> 5 files changed, 41 insertions(+), 17 deletions(-)\n> rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (88%)\n> \n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 1a4a545f44a..e7bd72bb84e 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -25,6 +25,7 @@ MAN1_TXT += gitweb.txt\n> # man5 / man7 guides (note: new guides should also be added to command-list.txt)\n> MAN5_TXT += gitattributes.txt\n> MAN5_TXT += gitformat-bundle.txt\n> +MAN5_TXT += gitformat-commit-graph.txt\n> MAN5_TXT += githooks.txt\n> MAN5_TXT += gitignore.txt\n> MAN5_TXT += gitmailmap.txt\n> diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\n> index e1f48c95b3c..047decdb65b 100644\n> --- a/Documentation/git-commit-graph.txt\n> +++ b/Documentation/git-commit-graph.txt\n> @@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append\n> ------------------------------------------------\n> \n> \n> +FILE FORMAT\n> +-----------\n> +\n> +see linkgit:gitformat-commit-graph[5].\n> +\n> GIT\n> ---\n> Part of the linkgit:git[1] suite\n> diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt\n> similarity index 88%\n> rename from Documentation/technical/commit-graph-format.txt\n> rename to Documentation/gitformat-commit-graph.txt\n> index 484b185ba98..108dc2295c0 100644\n> --- a/Documentation/technical/commit-graph-format.txt\n> +++ b/Documentation/gitformat-commit-graph.txt\n> @@ -1,5 +1,18 @@\n> -Git commit graph format\n> -=======================\n> +gitformat-commit-graph(5)\n> +=========================\n> +\n> +NAME\n> +----\n> +gitformat-commit-graph - Git commit graph format\n> +\n> +SYNOPSIS\n> +--------\n> +[verse]\n> +$GIT_DIR/objects/info/commit-graph\n> +$GIT_DIR/objects/info/commit-graphs/*\n> +\n> +DESCRIPTION\n> +-----------\n> \n> The Git commit graph stores a list of commit OIDs and some associated\n> metadata, including:\n> @@ -30,7 +43,7 @@ and hash type.\n> \n> All multi-byte numbers are in network byte order.\n> \n> -HEADER:\n> +=== HEADER:\n> \n> 4-byte signature:\n> The signature is: {'C', 'G', 'P', 'H'}\n> @@ -52,7 +65,7 @@ HEADER:\n> We infer the length (H*B) of the Base Graphs chunk\n> from this value.\n> \n> -CHUNK LOOKUP:\n> +=== CHUNK LOOKUP:\n> \n> (C + 1) * 12 bytes listing the table of contents for the chunks:\n> First 4 bytes describe the chunk id. Value 0 is a terminating label.\n> @@ -68,17 +81,17 @@ CHUNK LOOKUP:\n> these chunks may be given in any order. Chunks are required unless\n> otherwise specified.\n> \n> -CHUNK DATA:\n> +=== CHUNK DATA:\n> \n> - OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n> +==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)\n> The ith entry, F[i], stores the number of OIDs with first\n> byte at most i. Thus F[255] stores the total\n> number of commits (N).\n> \n> - OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n> +==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)\n> The OIDs for all commits in the graph, sorted in ascending order.\n> \n> - Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n> +==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)\n> * The first H bytes are for the OID of the root tree.\n> * The next 8 bytes are for the positions of the first two parents\n> of the ith commit. Stores value 0x70000000 if no parent in that\n> @@ -93,7 +106,7 @@ CHUNK DATA:\n> 2 bits of the lowest byte, storing the 33rd and 34th bit of the\n> commit time.\n> \n> - Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n> +==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]\n> * This list of 4-byte values store corrected commit date offsets for the\n> commits, arranged in the same order as commit data chunk.\n> * If the corrected commit date offset cannot be stored within 31 bits,\n> @@ -104,7 +117,7 @@ CHUNK DATA:\n> by compatible versions of Git and in case of split commit-graph chains,\n> the topmost layer also has Generation Data chunk.\n> \n> - Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n> +==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]\n> * This list of 8-byte values stores the corrected commit date offsets\n> for commits with corrected commit date offsets that cannot be\n> stored within 31 bits.\n> @@ -112,7 +125,7 @@ CHUNK DATA:\n> chunk is present and atleast one corrected commit date offset cannot\n> be stored within 31 bits.\n> \n> - Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n> +==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n> This list of 4-byte values store the second through nth parents for\n> all octopus merges. The second parent value in the commit data stores\n> an array position within this list along with the most-significant bit\n> @@ -120,14 +133,14 @@ CHUNK DATA:\n> positions for the parents until reaching a value with the most-significant\n> bit on. The other bits correspond to the position of the last parent.\n> \n> - Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n> +==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]\n> * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters\n> from commit 0 to commit i (inclusive) in lexicographic order. The Bloom\n> filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header\n> length), where BIDX[-1] is 0.\n> * The BIDX chunk is ignored if the BDAT chunk is not present.\n> \n> - Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n> +==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]\n> * It starts with header consisting of three unsigned 32-bit integers:\n> - Version of the hash algorithm being used. We currently only support\n> \tvalue 1 which corresponds to the 32-bit version of the murmur3 hash\n> @@ -147,13 +160,13 @@ CHUNK DATA:\n> of length one, with either all bits set to zero or one respectively.\n> * The BDAT chunk is present if and only if BIDX is present.\n> \n> - Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n> +==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n> This list of H-byte hashes describe a set of B commit-graph files that\n> form a commit-graph chain. The graph position for the ith commit in this\n> file's OID Lookup chunk is equal to i plus the number of commits in all\n> base graphs. If B is non-zero, this chunk must exist.\n> \n> -TRAILER:\n> +=== TRAILER:\n> \n> \tH-byte HASH-checksum of all of the above.\n> \n> @@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote\n> possibly erroneous data in these chunks with the IDs \"GDAT\" and \"GDOV\". By\n> changing the IDs, newer versions of Git will silently ignore those older\n> chunks and write the new information without trusting the incorrect data.\n> +\n> +GIT\n> +---\n> +Part of the linkgit:git[1] suite\n> diff --git a/Documentation/technical/chunk-format.txt b/Documentation/technical/chunk-format.txt\n> index 593614fceda..f36ce42f37c 100644\n> --- a/Documentation/technical/chunk-format.txt\n> +++ b/Documentation/technical/chunk-format.txt\n> @@ -6,7 +6,7 @@ sections of the file. This allows structured access to a large file by\n> scanning a small \"table of contents\" for the remaining data. This common\n> format is used by the `commit-graph` and `multi-pack-index` files. See\n> link:technical/pack-format.html[the `multi-pack-index` format] and\n> -link:technical/commit-graph-format.html[the `commit-graph` format] for\n> +the `commit-graph` format in linkgit:gitformat-commit-graph[5] for\n> how they use the chunks to describe structured data.\n> \n> A chunk-based file format begins with some header information custom to\n> @@ -108,7 +108,7 @@ for future formats:\n> * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()`\n> in `commit-graph.c` for how the chunk-format API is used to write and\n> parse the commit-graph file format documented in\n> - link:technical/commit-graph-format.html[the commit-graph file format].\n> + the commit-graph file format in linkgit:gitformat-commit-graph[5].\n> \n> * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`\n> in `midx.c` for how the chunk-format API is used to write and\n> diff --git a/command-list.txt b/command-list.txt\n> index 1950c4ccd9c..3afcfcd35f0 100644\n> --- a/command-list.txt\n> +++ b/command-list.txt\n> @@ -210,6 +210,7 @@ gitdiffcore guide\n> giteveryday guide\n> gitfaq guide\n> gitformat-bundle developerinterfaces\n> +gitformat-commit-graph developerinterfaces\n> gitglossary guide\n> githooks userinterfaces\n> gitignore userinterfaces\n> -- \n> 2.37.1.1233.g61622908797\n> \n"},{"id":"466886","messageId":"221108.86mt91qmkq.gmgdl@evledraar.gmail.com","threadId":"56715","inReplyTo":"20221108180417.GB1731@szeder.dev","subject":"Re: [PATCH v8 06/12] docs: move commit-graph format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-11-08T19:16:49Z","receivedAt":"2022-11-08T19:21:32Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Tue, Nov 08 2022, SZEDER Gábor wrote:\n\n> On Thu, Aug 04, 2022 at 06:28:35PM +0200, Ævar Arnfjörð Bjarmason wrote:\n>> Continue the move of existing Documentation/technical/* protocol and\n>> file-format documentation into our main documentation space.\n>> \n>> By moving the documentation for the commit-graph format into man\n>> section 5 and the new \"developerinterfaces\" category. This change is\n>> split from subsequent commits due to the relatively large amount of\n>> ASCIIDOC formatting changes that are required.\n>\n> So after this series I got a couple of gitformat-* manpages, but,\n> alas, most of them render improperly: a lot of paragraphs are for some\n> reason fixed width even in a fullscreen terminal window, and their\n> width is more than 80 chars, so they are rather awkward in a\n> standard-width terminal. This also affects the html version, where\n> those paragraphs are rendered with a fixed-width font.\n\nDo you have examples of that, and are these cases where the formatting\nwas different before the move from Documentation/technical/*\n\nI'm aware of e.g. gitformat-commit-graph(5) being somewhat funny, and\nmay have missed some cases, but I think that was also the case before...\n"},{"id":"466901","messageId":"20221108212741.GC1731@szeder.dev","threadId":"56715","inReplyTo":"221108.86mt91qmkq.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH v8 06/12] docs: move commit-graph format docs to man section 5","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2022-11-08T21:27:41Z","receivedAt":"2022-11-08T21:27:48Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"On Tue, Nov 08, 2022 at 08:16:49PM +0100, Ævar Arnfjörð Bjarmason wrote:\n> \n> On Tue, Nov 08 2022, SZEDER Gábor wrote:\n> \n> > On Thu, Aug 04, 2022 at 06:28:35PM +0200, Ævar Arnfjörð Bjarmason wrote:\n> >> Continue the move of existing Documentation/technical/* protocol and\n> >> file-format documentation into our main documentation space.\n> >> \n> >> By moving the documentation for the commit-graph format into man\n> >> section 5 and the new \"developerinterfaces\" category. This change is\n> >> split from subsequent commits due to the relatively large amount of\n> >> ASCIIDOC formatting changes that are required.\n> >\n> > So after this series I got a couple of gitformat-* manpages, but,\n> > alas, most of them render improperly: a lot of paragraphs are for some\n> > reason fixed width even in a fullscreen terminal window, and their\n> > width is more than 80 chars, so they are rather awkward in a\n> > standard-width terminal. This also affects the html version, where\n> > those paragraphs are rendered with a fixed-width font.\n> \n> Do you have examples of that\n\nHere's the description of two chunks copy-pasted from 'man\ngitformat-commit-graph' in a full-screen terminal, the first being\nproperly formatted (i.e. line length adjusted to the width of the\nterminal), the latter having fixed-width:\n\n Generation Data Overflow (ID: {G, D, O, 2 }) [Optional]\n • This list of 8-byte values stores the corrected commit date offsets for commits with corrected commit date offsets that cannot be stored within 31 bits.\n\n • Generation Data Overflow chunk is present only when Generation Data chunk is present and atleast one corrected commit date offset cannot be stored within 31 bits.\n\n Extra Edge List (ID: {E, D, G, E}) [Optional]\n This list of 4-byte values store the second through nth parents for\n all octopus merges. The second parent value in the commit data stores\n an array position within this list along with the most-significant bit\n on. Starting at that array position, iterate through this list of commit\n positions for the parents until reaching a value with the most-significant\n bit on. The other bits correspond to the position of the last parent.\n\nThere are similar formating issues in 'gitformat-index' and\n'gitformat-pack' as well. I can see these both with AsciiDoc and\nAsciidoctor.\n\n> and are these cases where the formatting\n> was different before the move from Documentation/technical/*\n> \n> I'm aware of e.g. gitformat-commit-graph(5) being somewhat funny, and\n> may have missed some cases, but I think that was also the case before...\n\nI'm not sure about \"before\", because 'make man' never built and\ninstalled these gitformat-* manpages before this series.\n\n"},{"id":"466929","messageId":"221109.86bkpgriso.gmgdl@evledraar.gmail.com","threadId":"56715","inReplyTo":"20221108212741.GC1731@szeder.dev","subject":"Re: [PATCH v8 06/12] docs: move commit-graph format docs to man section 5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-11-09T01:34:03Z","receivedAt":"2022-11-09T01:57:51Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Tue, Nov 08 2022, SZEDER Gábor wrote:\n\n> On Tue, Nov 08, 2022 at 08:16:49PM +0100, Ævar Arnfjörð Bjarmason wrote:\n>> \n>> On Tue, Nov 08 2022, SZEDER Gábor wrote:\n>> \n>> > On Thu, Aug 04, 2022 at 06:28:35PM +0200, Ævar Arnfjörð Bjarmason wrote:\n>> >> Continue the move of existing Documentation/technical/* protocol and\n>> >> file-format documentation into our main documentation space.\n>> >> \n>> >> By moving the documentation for the commit-graph format into man\n>> >> section 5 and the new \"developerinterfaces\" category. This change is\n>> >> split from subsequent commits due to the relatively large amount of\n>> >> ASCIIDOC formatting changes that are required.\n>> >\n>> > So after this series I got a couple of gitformat-* manpages, but,\n>> > alas, most of them render improperly: a lot of paragraphs are for some\n>> > reason fixed width even in a fullscreen terminal window, and their\n>> > width is more than 80 chars, so they are rather awkward in a\n>> > standard-width terminal. This also affects the html version, where\n>> > those paragraphs are rendered with a fixed-width font.\n>> \n>> Do you have examples of that\n>\n> Here's the description of two chunks copy-pasted from 'man\n> gitformat-commit-graph' in a full-screen terminal, the first being\n> properly formatted (i.e. line length adjusted to the width of the\n> terminal), the latter having fixed-width:\n>\n> Generation Data Overflow (ID: {G, D, O, 2 }) [Optional]\n> • This list of 8-byte values stores the corrected commit date offsets for commits with corrected commit date offsets that cannot be stored within 31 bits.\n>\n> • Generation Data Overflow chunk is present only when Generation Data chunk is present and atleast one corrected commit date offset cannot be stored within 31 bits.\n>\n> Extra Edge List (ID: {E, D, G, E}) [Optional]\n> This list of 4-byte values store the second through nth parents for\n> all octopus merges. The second parent value in the commit data stores\n> an array position within this list along with the most-significant bit\n> on. Starting at that array position, iterate through this list of commit\n> positions for the parents until reaching a value with the most-significant\n> bit on. The other bits correspond to the position of the last parent.\n>\n> There are similar formating issues in 'gitformat-index' and\n> 'gitformat-pack' as well. I can see these both with AsciiDoc and\n> Asciidoctor.\n\nYeah, they look pretty bad.\n\n>> and are these cases where the formatting\n>> was different before the move from Documentation/technical/*\n>> \n>> I'm aware of e.g. gitformat-commit-graph(5) being somewhat funny, and\n>> may have missed some cases, but I think that was also the case before...\n>\n> I'm not sure about \"before\", because 'make man' never built and\n> installed these gitformat-* manpages before this series.\n\nIn the case of \"gitformat-commit-graph\" there was never a \"html\" version\nof it before c0f6dd49f19 (Merge branch 'ab/tech-docs-to-help',\n2022-08-14). But if you check out c0f6dd49f19^1 and:\n\t\n\tdiff --git a/Documentation/Makefile b/Documentation/Makefile\n\tindex 4f801f4e4c9..d7a066a68d0 100644\n\t--- a/Documentation/Makefile\n\t+++ b/Documentation/Makefile\n\t@@ -96,6 +96,7 @@ TECH_DOCS += SubmittingPatches\n\t TECH_DOCS += ToolsForGit\n\t TECH_DOCS += technical/bitmap-format\n\t TECH_DOCS += technical/bundle-format\n\t+TECH_DOCS += technical/commit-graph-format\n\t TECH_DOCS += technical/cruft-packs\n\t TECH_DOCS += technical/hash-function-transition\n\t TECH_DOCS += technical/http-protoco\n\nThen \"make html\" you'll see what the formatting was like before. Here's\ngenerated versions of those & git-scm.com's version for comparison:\n\n\thttps://vm.nix.is/~avar/noindex/2022-11-09-gitdocs/commit-graph-format.html\n\thttps://git-scm.com/docs/gitformat-commit-graph\n https://vm.nix.is/~avar/noindex/2022-11-09-gitdocs/index-format.html\n\thttps://git-scm.com/docs/gitformat-index\n https://vm.nix.is/~avar/noindex/2022-11-09-gitdocs/pack-format.html\n https://git-scm.com/docs/gitformat-pack\n\nThey should obviously be fixed, but I left that out of scope of that\nseries. If it was a fix-syntax-nits-while-at-it it would have been a lot\nlonger, and some of it's in some pseudo-syntax that was never quite\nvalid markdown. E.g. commit-graph-format.txt tried to use link:* syntax\nin block-quoted text.\n\nWhat I found *mostly* worked was to use \"==\" for sections, which\ne.g. for gitformat-commit-graph ends up formatting it nicely as long as\nit's followed by a bullet-point list, but as you show with \"This lits of\n4-byte...\" that doesn't do the trick when it's not a list, instead it\nuses the literal formatting (which almost the entire body of the text\nused before).\n\nI think the most minimal way of fixing it is to de-indent the opening\nline of those sections, e.g.:\n\t\n\tdiff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt\n\tindex 31cad585e23..84df4a3ed03 100644\n\t--- a/Documentation/gitformat-commit-graph.txt\n\t+++ b/Documentation/gitformat-commit-graph.txt\n\t@@ -67,17 +67,17 @@ All multi-byte numbers are in network byte order.\n\t \n\t === CHUNK LOOKUP:\n\t \n\t- (C + 1) * 12 bytes listing the table of contents for the chunks:\n\t+(C + 1) * 12 bytes listing the table of contents for the chunks:\n\t First 4 bytes describe the chunk id. Value 0 is a terminating label.\n\t Other 8 bytes provide the byte-offset in current file for chunk to\n\t start. (Chunks are ordered contiguously in the file, so you can infer\n\t the length using the next chunk position if necessary.) Each chunk\n\t ID appears at most once.\n\t \n\t- The CHUNK LOOKUP matches the table of contents from\n\t+The CHUNK LOOKUP matches the table of contents from\n\t the chunk-based file format, see linkgit:gitformat-chunk[5]\n\t \n\t- The remaining data in the body is described one chunk at a time, and\n\t+The remaining data in the body is described one chunk at a time, and\n\t these chunks may be given in any order. Chunks are required unless\n\t otherwise specified.\n\t \n\t@@ -126,7 +126,7 @@ All multi-byte numbers are in network byte order.\n\t be stored within 31 bits.\n\t \n\t ==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n\t- This list of 4-byte values store the second through nth parents for\n\t+This list of 4-byte values store the second through nth parents for\n\t all octopus merges. The second parent value in the commit data stores\n\t an array position within this list along with the most-significant bit\n\t on. Starting at that array position, iterate through this list of commit\n\t\nSeems to fix those \"flow\" issues for me, i.e. it's now a normal\nparagraph, instead of a block-quoted fixed-width text.\n"},{"id":"467691","messageId":"patch-1.1-1c1434bba31-20221121T141411Z-avarab@gmail.com","threadId":"56715","inReplyTo":"221109.86bkpgriso.gmgdl@evledraar.gmail.com","subject":"[PATCH] docs: de-indent first paragraph of gitformat-* to flow the text","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-11-21T14:15:50Z","receivedAt":"2022-11-21T14:16:34Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix formatting issues with the documentation added to the new\ngitformat-* namespace in c0f6dd49f19 (Merge branch\n'ab/tech-docs-to-help', 2022-08-14).\n\nAs this documentation didn't have a wide audience before that, some of\nthese formatting issues pre-dated that change. See [1] for details.\n\nBut the end result of having some paragraphs use \"

\" in the HTML\noutput, and to have others wrapped in \"

\" doesn't look\nnice. The most minimal way to fix this is to de-indent the opening\nline of paragraphs that don't start with another formatting\nelement (e.g. \"*\" or \"-\" would already format them as text). Let's do\nthat.\n\n1. https://lore.kernel.org/git/221109.86bkpgriso.gmgdl@evledraar.gmail.com/\n\nReported-by: SZEDER Gábor \nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n\nThere's a lot more to fix in these gitformat-* docs (as their\nformatting was funny before), but this is a minimal change to fix the\nmost major issues.\n\n Documentation/gitformat-commit-graph.txt | 10 ++--\n Documentation/gitformat-index.txt        | 74 ++++++++++++------------\n Documentation/gitformat-pack.txt         |  4 +-\n 3 files changed, 44 insertions(+), 44 deletions(-)\n\ndiff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt\nindex 31cad585e23..219265a0c7a 100644\n--- a/Documentation/gitformat-commit-graph.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -67,17 +67,17 @@ All multi-byte numbers are in network byte order.\n \n === CHUNK LOOKUP:\n \n-  (C + 1) * 12 bytes listing the table of contents for the chunks:\n+(C + 1) * 12 bytes listing the table of contents for the chunks:\n       First 4 bytes describe the chunk id. Value 0 is a terminating label.\n       Other 8 bytes provide the byte-offset in current file for chunk to\n       start. (Chunks are ordered contiguously in the file, so you can infer\n       the length using the next chunk position if necessary.) Each chunk\n       ID appears at most once.\n \n-  The CHUNK LOOKUP matches the table of contents from\n+The CHUNK LOOKUP matches the table of contents from\n   the chunk-based file format, see linkgit:gitformat-chunk[5]\n \n-  The remaining data in the body is described one chunk at a time, and\n+The remaining data in the body is described one chunk at a time, and\n   these chunks may be given in any order. Chunks are required unless\n   otherwise specified.\n \n@@ -126,7 +126,7 @@ All multi-byte numbers are in network byte order.\n       be stored within 31 bits.\n \n ==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]\n-      This list of 4-byte values store the second through nth parents for\n+This list of 4-byte values store the second through nth parents for\n       all octopus merges. The second parent value in the commit data stores\n       an array position within this list along with the most-significant bit\n       on. Starting at that array position, iterate through this list of commit\n@@ -161,7 +161,7 @@ All multi-byte numbers are in network byte order.\n     * The BDAT chunk is present if and only if BIDX is present.\n \n ==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]\n-      This list of H-byte hashes describe a set of B commit-graph files that\n+This list of H-byte hashes describe a set of B commit-graph files that\n       form a commit-graph chain. The graph position for the ith commit in this\n       file's OID Lookup chunk is equal to i plus the number of commits in all\n       base graphs.  If B is non-zero, this chunk must exist.\ndiff --git a/Documentation/gitformat-index.txt b/Documentation/gitformat-index.txt\nindex 015cb21bdc0..bbc188b9e65 100644\n--- a/Documentation/gitformat-index.txt\n+++ b/Documentation/gitformat-index.txt\n@@ -17,7 +17,7 @@ Git index format\n \n == The Git index file has the following format\n \n-  All binary numbers are in network byte order.\n+All binary numbers are in network byte order.\n   In a repository using the traditional SHA-1, checksums and object IDs\n   (object names) mentioned below are all computed using SHA-1.  Similarly,\n   in SHA-256 repositories, these values are computed using SHA-256.\n@@ -51,12 +51,12 @@ Git index format\n \n == Index entry\n \n-  Index entries are sorted in ascending order on the name field,\n+Index entries are sorted in ascending order on the name field,\n   interpreted as a string of unsigned bytes (i.e. memcmp() order, no\n   localization, no special casing of directory separator '/'). Entries\n   with the same name are sorted by their stage field.\n \n-  An index entry typically represents a file. However, if sparse-checkout\n+An index entry typically represents a file. However, if sparse-checkout\n   is enabled in cone mode (`core.sparseCheckoutCone` is enabled) and the\n   `extensions.sparseIndex` extension is enabled, then the index may\n   contain entries for directories outside of the sparse-checkout definition.\n@@ -103,7 +103,7 @@ Git index format\n \n   Object name for the represented object\n \n-  A 16-bit 'flags' field split into (high to low bits)\n+A 16-bit 'flags' field split into (high to low bits)\n \n     1-bit assume-valid flag\n \n@@ -114,7 +114,7 @@ Git index format\n     12-bit name length if the length is less than 0xFFF; otherwise 0xFFF\n     is stored in this field.\n \n-  (Version 3 or later) A 16-bit field, only applicable if the\n+(Version 3 or later) A 16-bit field, only applicable if the\n   \"extended flag\" above is 1, split into (high to low bits).\n \n     1-bit reserved for future\n@@ -125,16 +125,16 @@ Git index format\n \n     13-bit unused, must be zero\n \n-  Entry path name (variable length) relative to top level directory\n+Entry path name (variable length) relative to top level directory\n     (without leading slash). '/' is used as path separator. The special\n     path components \".\", \"..\" and \".git\" (without quotes) are disallowed.\n     Trailing slash is also disallowed.\n \n-    The exact encoding is undefined, but the '.' and '/' characters\n+The exact encoding is undefined, but the '.' and '/' characters\n     are encoded in 7-bit ASCII and the encoding cannot contain a NUL\n     byte (iow, this is a UNIX pathname).\n \n-  (Version 4) In version 4, the entry path name is prefix-compressed\n+(Version 4) In version 4, the entry path name is prefix-compressed\n     relative to the path name for the previous entry (the very first\n     entry is encoded as if the path name for the previous entry is an\n     empty string).  At the beginning of an entry, an integer N in the\n@@ -144,20 +144,20 @@ Git index format\n     path name for the previous entry, and replacing it with the string S\n     yields the path name for this entry.\n \n-  1-8 nul bytes as necessary to pad the entry to a multiple of eight bytes\n+1-8 nul bytes as necessary to pad the entry to a multiple of eight bytes\n   while keeping the name NUL-terminated.\n \n-  (Version 4) In version 4, the padding after the pathname does not\n+(Version 4) In version 4, the padding after the pathname does not\n   exist.\n \n-  Interpretation of index entries in split index mode is completely\n+Interpretation of index entries in split index mode is completely\n   different. See below for details.\n \n == Extensions\n \n === Cache tree\n \n-  Since the index does not record entries for directories, the cache\n+Since the index does not record entries for directories, the cache\n   entries cannot describe tree objects that already exist in the object\n   database for regions of the index that are unchanged from an existing\n   commit. The cache tree extension stores a recursive tree structure that\n@@ -168,26 +168,26 @@ Git index format\n   as `HEAD^{tree}`, since sections of the index can be skipped when a tree\n   comparison demonstrates equality.\n \n-  The recursive tree structure uses nodes that store a number of cache\n+The recursive tree structure uses nodes that store a number of cache\n   entries, a list of subnodes, and an object ID (OID). The OID references\n   the existing tree for that node, if it is known to exist. The subnodes\n   correspond to subdirectories that themselves have cache tree nodes. The\n   number of cache entries corresponds to the number of cache entries in\n   the index that describe paths within that tree's directory.\n \n-  The extension tracks the full directory structure in the cache tree\n+The extension tracks the full directory structure in the cache tree\n   extension, but this is generally smaller than the full cache entry list.\n \n-  When a path is updated in index, Git invalidates all nodes of the\n+When a path is updated in index, Git invalidates all nodes of the\n   recursive cache tree corresponding to the parent directories of that\n   path. We store these tree nodes as being \"invalid\" by using \"-1\" as the\n   number of cache entries. Invalid nodes still store a span of index\n   entries, allowing Git to focus its efforts when reconstructing a full\n   cache tree.\n \n-  The signature for this extension is { 'T', 'R', 'E', 'E' }.\n+The signature for this extension is { 'T', 'R', 'E', 'E' }.\n \n-  A series of entries fill the entire extension; each of which\n+A series of entries fill the entire extension; each of which\n   consists of:\n \n   - NUL-terminated path component (relative to its parent directory);\n@@ -205,12 +205,12 @@ Git index format\n   - Object name for the object that would result from writing this span\n     of index as a tree.\n \n-  An entry can be in an invalidated state and is represented by having\n+An entry can be in an invalidated state and is represented by having\n   a negative number in the entry_count field. In this case, there is no\n   object name and the next entry starts immediately after the newline.\n   When writing an invalid entry, -1 should always be used as entry_count.\n \n-  The entries are written out in the top-down, depth-first order.  The\n+The entries are written out in the top-down, depth-first order.  The\n   first entry represents the root level of the repository, followed by the\n   first subtree--let's call this A--of the root level (with its name\n   relative to the root level), followed by the first subtree of A (with\n@@ -219,19 +219,19 @@ Git index format\n \n === Resolve undo\n \n-  A conflict is represented in the index as a set of higher stage entries.\n+A conflict is represented in the index as a set of higher stage entries.\n   When a conflict is resolved (e.g. with \"git add path\"), these higher\n   stage entries will be removed and a stage-0 entry with proper resolution\n   is added.\n \n-  When these higher stage entries are removed, they are saved in the\n+When these higher stage entries are removed, they are saved in the\n   resolve undo extension, so that conflicts can be recreated (e.g. with\n   \"git checkout -m\"), in case users want to redo a conflict resolution\n   from scratch.\n \n-  The signature for this extension is { 'R', 'E', 'U', 'C' }.\n+The signature for this extension is { 'R', 'E', 'U', 'C' }.\n \n-  A series of entries fill the entire extension; each of which\n+A series of entries fill the entire extension; each of which\n   consists of:\n \n   - NUL-terminated pathname the entry describes (relative to the root of\n@@ -246,13 +246,13 @@ Git index format\n \n === Split index\n \n-  In split index mode, the majority of index entries could be stored\n+In split index mode, the majority of index entries could be stored\n   in a separate file. This extension records the changes to be made on\n   top of that to produce the final index.\n \n-  The signature for this extension is { 'l', 'i', 'n', 'k' }.\n+The signature for this extension is { 'l', 'i', 'n', 'k' }.\n \n-  The extension consists of:\n+The extension consists of:\n \n   - Hash of the shared index file. The shared index file path\n     is $GIT_DIR/sharedindex.. If all bits are zero, the\n@@ -273,17 +273,17 @@ Git index format\n     first index entry, the second \"1\" bit to the second entry and so\n     on. Replaced entries may have empty path names to save space.\n \n-  The remaining index entries after replaced ones will be added to the\n+The remaining index entries after replaced ones will be added to the\n   final index. These added entries are also sorted by entry name then\n   stage.\n \n == Untracked cache\n \n-  Untracked cache saves the untracked file list and necessary data to\n+Untracked cache saves the untracked file list and necessary data to\n   verify the cache. The signature for this extension is { 'U', 'N',\n   'T', 'R' }.\n \n-  The extension starts with\n+The extension starts with\n \n   - A sequence of NUL-terminated strings, preceded by the size of the\n     sequence in variable width encoding. Each string describes the\n@@ -341,11 +341,11 @@ The remaining data of each directory block is grouped by type:\n \n == File System Monitor cache\n \n-  The file system monitor cache tracks files for which the core.fsmonitor\n+The file system monitor cache tracks files for which the core.fsmonitor\n   hook has told us about changes.  The signature for this extension is\n   { 'F', 'S', 'M', 'N' }.\n \n-  The extension starts with\n+The extension starts with\n \n   - 32-bit version number: the current supported versions are 1 and 2.\n \n@@ -366,16 +366,16 @@ The remaining data of each directory block is grouped by type:\n \n == End of Index Entry\n \n-  The End of Index Entry (EOIE) is used to locate the end of the variable\n+The End of Index Entry (EOIE) is used to locate the end of the variable\n   length index entries and the beginning of the extensions. Code can take\n   advantage of this to quickly locate the index extensions without having\n   to parse through all of the index entries.\n \n-  Because it must be able to be loaded before the variable length cache\n+Because it must be able to be loaded before the variable length cache\n   entries and other index extensions, this extension must be written last.\n   The signature for this extension is { 'E', 'O', 'I', 'E' }.\n \n-  The extension consists of:\n+The extension consists of:\n \n   - 32-bit offset to the end of the index entries\n \n@@ -389,12 +389,12 @@ The remaining data of each directory block is grouped by type:\n \n == Index Entry Offset Table\n \n-  The Index Entry Offset Table (IEOT) is used to help address the CPU\n+The Index Entry Offset Table (IEOT) is used to help address the CPU\n   cost of loading the index by enabling multi-threading the process of\n   converting cache entries from the on-disk format to the in-memory format.\n   The signature for this extension is { 'I', 'E', 'O', 'T' }.\n \n-  The extension consists of:\n+The extension consists of:\n \n   - 32-bit version (currently 1)\n \n@@ -407,7 +407,7 @@ The remaining data of each directory block is grouped by type:\n \n == Sparse Directory Entries\n \n-  When using sparse-checkout in cone mode, some entire directories within\n+When using sparse-checkout in cone mode, some entire directories within\n   the index can be summarized by pointing to a tree object instead of the\n   entire expanded list of paths within that tree. An index containing such\n   entries is a \"sparse index\". Index format versions 4 and less were not\ndiff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt\nindex e06af02f211..8a0e8dd160d 100644\n--- a/Documentation/gitformat-pack.txt\n+++ b/Documentation/gitformat-pack.txt\n@@ -294,10 +294,10 @@ Pack file entry: <+\n \n   - The same trailer as a v1 pack file:\n \n-    A copy of the pack checksum at the end of\n+A copy of the pack checksum at the end of\n     corresponding packfile.\n \n-    Index checksum of all of the above.\n+Index checksum of all of the above.\n \n == pack-*.rev files have the format:\n \n-- \n2.38.0.1524.gdb7bac9ecc9\n\n"},{"id":"467700","messageId":"Y3u8mzT6UN9DoOB7@coredump.intra.peff.net","threadId":"56715","inReplyTo":"patch-1.1-1c1434bba31-20221121T141411Z-avarab@gmail.com","subject":"Re: [PATCH] docs: de-indent first paragraph of gitformat-* to flow the text","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2022-11-21T17:59:55Z","receivedAt":"2022-11-21T18:00:54Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Nov 21, 2022 at 03:15:50PM +0100, Ævar Arnfjörð Bjarmason wrote:\n\n> But the end result of having some paragraphs use \"
\" in the HTML\n> output, and to have others wrapped in \"
\" doesn't look\n> nice. The most minimal way to fix this is to de-indent the opening\n> line of paragraphs that don't start with another formatting\n> element (e.g. \"*\" or \"-\" would already format them as text). Let's do\n> that.\n\nIs there any reason to just touch the opening line of the paragraphs,\nand not change the indent of the whole thing? I understand that doing\nthe first line is sufficient to convince asciidoc to do what we want,\nand the diff is technically fewer lines, but the result is rather\nconfusing for people who will work on the source in the future.\n\n> There's a lot more to fix in these gitformat-* docs (as their\n> formatting was funny before), but this is a minimal change to fix the\n> most major issues.\n\nI briefly looked at doc-diff output here. Most of them looked obviously\ncorrect (though since there isn't a lot of context in the doc-diff, it's\nsometimes hard to tell), but a few were questionable:\n\n> @@ -103,7 +103,7 @@ Git index format\n>  \n>    Object name for the represented object\n>  \n> -  A 16-bit 'flags' field split into (high to low bits)\n> +A 16-bit 'flags' field split into (high to low bits)\n>  \n>      1-bit assume-valid flag\n\nThis puts \"A 16-bit flags field\" at a different indent than the\nparagraph before, but I think it is part of a list. It is less indented\nthan the follow-on paragraph (\"1-bit assume-valid flag\"), but I think\nthat is correct, as it is a sub-list of the 16-bit flags.\n\nI know you said that formatting problems remain, and certainly this was\nnot right before your patch either. But I think your patch makes it\nworse, because it pulls the touched line out of the list (and all of the\nadjacent parts are still rendered as code blocks, making the structure\neven less clear).\n\n> @@ -114,7 +114,7 @@ Git index format\n>      12-bit name length if the length is less than 0xFFF; otherwise 0xFFF\n>      is stored in this field.\n>  \n> -  (Version 3 or later) A 16-bit field, only applicable if the\n> +(Version 3 or later) A 16-bit field, only applicable if the\n>    \"extended flag\" above is 1, split into (high to low bits).\n>  \n>      1-bit reserved for future\n\nThis is the same (it's the same list).\n\n> @@ -125,16 +125,16 @@ Git index format\n>  \n>      13-bit unused, must be zero\n>  \n> -  Entry path name (variable length) relative to top level directory\n> +Entry path name (variable length) relative to top level directory\n>      (without leading slash). '/' is used as path separator. The special\n>      path components \".\", \"..\" and \".git\" (without quotes) are disallowed.\n>      Trailing slash is also disallowed.\n\nAnd I think this is supposed to be part of that same list, too, but now\nis de-dented.\n\n> -    The exact encoding is undefined, but the '.' and '/' characters\n> +The exact encoding is undefined, but the '.' and '/' characters\n>      are encoded in 7-bit ASCII and the encoding cannot contain a NUL\n>      byte (iow, this is a UNIX pathname).\n\nThis is supposed to be a continuation of the earlier \"Entry path name\"\nitem, but now is at the same top-level. Which is not right, but arguably\nis not worse than before your patch.\n\n>  \n> -  (Version 4) In version 4, the entry path name is prefix-compressed\n> +(Version 4) In version 4, the entry path name is prefix-compressed\n>      relative to the path name for the previous entry (the very first\n>      entry is encoded as if the path name for the previous entry is an\n>      empty string).  At the beginning of an entry, an integer N in the\n\nAnd this one is another top-level part of the list.\n\n> --- a/Documentation/gitformat-pack.txt\n> +++ b/Documentation/gitformat-pack.txt\n> @@ -294,10 +294,10 @@ Pack file entry: <+\n>  \n>    - The same trailer as a v1 pack file:\n>  \n> -    A copy of the pack checksum at the end of\n> +A copy of the pack checksum at the end of\n>      corresponding packfile.\n>  \n> -    Index checksum of all of the above.\n> +Index checksum of all of the above.\n\nThese are supposed to be list items of \"The same trailer as...\" above.\nNow they're de-dented, which I think is worse than the state before your\npatch.\n\nI don't want to say \"we must fix all format problems at once\", but I\nthink in the cases I pointed out that trying to fix the code-block\nproblem is a losing battle, because the list-like nature is being made\nworse. And they probably should remain untouched until somebody is\nwilling to turn them into actual list elements and continuation markers.\n\n-Peff\n"},{"id":"467733","messageId":"xmqqmt8ju8ou.fsf@gitster.g","threadId":"56715","inReplyTo":"patch-1.1-1c1434bba31-20221121T141411Z-avarab@gmail.com","subject":"Re: [PATCH] docs: de-indent first paragraph of gitformat-* to flow the text","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-11-22T00:36:17Z","receivedAt":"2022-11-22T00:36:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason   writes:\n\n> Fix formatting issues with the documentation added to the new\n> gitformat-* namespace in c0f6dd49f19 (Merge branch\n> 'ab/tech-docs-to-help', 2022-08-14).\n\nI think I saw you do this before, but please refrain from blaming a\nmerge UNLESS there is a regression between the tip of the topic\ngetting merged c0f6dd49f19^2 and the result of the merge c0f6dd49f19\nas it is confusing.\n\n>  === CHUNK LOOKUP:\n>  \n> -  (C + 1) * 12 bytes listing the table of contents for the chunks:\n> +(C + 1) * 12 bytes listing the table of contents for the chunks:\n>        First 4 bytes describe the chunk id. Value 0 is a terminating label.\n>        Other 8 bytes provide the byte-offset in current file for chunk to\n>        start. (Chunks are ordered contiguously in the file, so you can infer\n>        the length using the next chunk position if necessary.) Each chunk\n>        ID appears at most once.\n>  \n> -  The CHUNK LOOKUP matches the table of contents from\n> +The CHUNK LOOKUP matches the table of contents from\n>    the chunk-based file format, see linkgit:gitformat-chunk[5]\n\nThis makes the result awkward to read for those of us who consume\nthe text in the source form.  I do not think a one-time cost of\nreindenting the whole paragraph (and reviewing the patch to do so)\noutweighs the cost of burdening the readers with the awkwardness.\n\n"}]}