From 2f8b3ea662269e5f8e05228eb7a816606559ca23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Thu, 4 Aug 2022 18:28:30 +0200 Subject: [PATCH 01/12] help.c: refactor drop_prefix() to use a "switch" statement" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refactor the drop_prefix() function in in help.c to make it easier to strip prefixes from categories that aren't "CAT_guide". There are no functional changes here, by doing this we make a subsequent functional change's diff smaller. As before we first try to strip "git-" unconditionally, if that works we'll return the stripped string. Then we'll strip "git" if the command is in "CAT_guide". This means that we'd in principle strip "git-foo" down to "foo" if it's in CAT_guide. That doesn't make much sense, and we don't have such an entry in command-list.txt, but let's preserve that behavior for now. While we're at it remove a stray newline that had been added after the "return name;" statement. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- help.c | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/help.c b/help.c index 41c41c2aa1..7e594d291b 100644 --- a/help.c +++ b/help.c @@ -44,13 +44,19 @@ static struct category_description main_categories[] = { static const char *drop_prefix(const char *name, uint32_t category) { const char *new_name; + const char *prefix = NULL; if (skip_prefix(name, "git-", &new_name)) return new_name; - if (category == CAT_guide && skip_prefix(name, "git", &new_name)) + switch (category) { + case CAT_guide: + prefix = "git"; + break; + } + if (prefix && skip_prefix(name, prefix, &new_name)) return new_name; - return name; + return name; } static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask) From 936b8eb6c83fa2773b489dc365ab0cce47ba83f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Thu, 4 Aug 2022 18:28:31 +0200 Subject: [PATCH 02/12] help.c: remove common category behavior from drop_prefix() behavior MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change the behavior of the "git" prefix stripping for CAT_guide so that we don't try to strip the "git-" prefix in that case. We should be stripping either "git" or "git-" depending on the category. This change makes it easier to add extra "category" conditions in subsequent commits. Before this we'd in principle strip a "git-" prefix from a "guide" in command-list.txt, in practice we have no such entry there. As we don't have any entry that looks like "git-foo" in command-list.txt this changes nothing in practice, but it makes the intent of the code clearer. In that hypothetical case we'd now strip it down to "-foo", not "foo". When this code was added in cfb22a02ab5 (help: use command-list.h for common command list, 2018-05-10) the only entries in command-list.txt that didn't begin with "git-" were "gitweb" and "gitk". Then when the "guides" special-case was added in 1b81d8cb19d (help: use command-list.txt for the source of guides, 2018-05-20) we had the various "git" (not "git-") prefixed "guide" entries, which the "CAT_guide" case handles. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- help.c | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/help.c b/help.c index 7e594d291b..8a09f18a3d 100644 --- a/help.c +++ b/help.c @@ -44,16 +44,17 @@ static struct category_description main_categories[] = { static const char *drop_prefix(const char *name, uint32_t category) { const char *new_name; - const char *prefix = NULL; + const char *prefix; - if (skip_prefix(name, "git-", &new_name)) - return new_name; switch (category) { case CAT_guide: prefix = "git"; break; + default: + prefix = "git-"; + break; } - if (prefix && skip_prefix(name, prefix, &new_name)) + if (skip_prefix(name, prefix, &new_name)) return new_name; return name; From dba1e5392f431e57d6a8daacf879a255b49d57fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Thu, 4 Aug 2022 18:28:32 +0200 Subject: [PATCH 03/12] git help doc: use "" instead of "" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the use of "" originally introduced (as "GUIDE") in a133737b809 (doc: include --guide option description for "git help", 2013-04-02) with the more generic "". The "" placeholder is more generic, and one we'll be able to use as we introduce new documentation categories. Let's also add "" to the "git help -h" output, when it was made to use parse_option() in in 41eb33bd0cb (help: use parseopt, 2008-02-24). Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/git-help.txt | 8 ++++---- builtin/help.c | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 239c68db45..bead763fd2 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -9,14 +9,14 @@ SYNOPSIS -------- [verse] 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases] -'git help' [[-i|--info] [-m|--man] [-w|--web]] [|] +'git help' [[-i|--info] [-m|--man] [-w|--web]] [|] 'git help' [-g|--guides] 'git help' [-c|--config] DESCRIPTION ----------- -With no options and no '' or '' given, the synopsis of the 'git' +With no options and no '' or '' given, the synopsis of the 'git' command and a list of the most commonly used Git commands are printed on the standard output. @@ -26,8 +26,8 @@ printed on the standard output. If the option `--guides` or `-g` is given, a list of the Git concept guides is also printed on the standard output. -If a command, or a guide, is given, a manual page for that command or -guide is brought up. The 'man' program is used by default for this +If a command or other documentation is given, the relevant manual page +will be brought up. The 'man' program is used by default for this purpose, but this can be overridden by other options or configuration variables. diff --git a/builtin/help.c b/builtin/help.c index 222f994f86..dec82d1be2 100644 --- a/builtin/help.c +++ b/builtin/help.c @@ -81,7 +81,7 @@ static struct option builtin_help_options[] = { static const char * const builtin_help_usage[] = { "git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]", - N_("git help [[-i|--info] [-m|--man] [-w|--web]] []"), + N_("git help [[-i|--info] [-m|--man] [-w|--web]] [|]"), "git help [-g|--guides]", "git help [-c|--config]", NULL From d976c5100fb5f55f648d8b400bcbda1116b82dec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Thu, 4 Aug 2022 18:28:33 +0200 Subject: [PATCH 04/12] git docs: add a category for user-facing file, repo and command UX MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Create a new "Repository, command and file interfaces" section in the main "git help git" manual page. Move things that belong under this new criteria from the generic "Guides" section. The "Guides" section was added in f442f28a81b (git.txt: add list of guides, 2020-08-05). It makes sense to have e.g. "giteveryday(7)" and "gitfaq(7)" listed under "Guides". But placing e.g. "gitignore(5)" in it is stretching the meaning of what a "guide" is, ideally that section should list things similar to "giteveryday(7)" and "gitcore-tutorial(7)". An alternate name that was considered for this new section was "User formats", for consistency with the nomenclature used for man section 5 in general. My man(1) lists it as "File formats and conventions, e.g. /etc/passwd". So calling this "git help --formats" or "git help --user-formats" would make sense for e.g. gitignore(5), but would be stretching it somewhat for githooks(5), and would seem really suspect for the likes of gitcli(7). Let's instead pick a name that's closer to the generic term "User interface", which is really what this documentation discusses: General user-interface documentation that doesn't obviously belong elsewhere. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/Makefile | 1 + Documentation/git-help.txt | 14 ++++++++++++++ Documentation/git.txt | 8 ++++++++ Makefile | 1 + builtin/help.c | 9 +++++++++ command-list.txt | 21 +++++++++++++-------- help.c | 12 ++++++++++++ help.h | 1 + t/t0012-help.sh | 12 +++++++++++- 9 files changed, 70 insertions(+), 9 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 4f801f4e4c..28eb940a9b 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ cmds-synchingrepositories.txt \ cmds-synchelpers.txt \ cmds-guide.txt \ + cmds-userinterfaces.txt \ cmds-purehelpers.txt \ cmds-foreignscminterface.txt diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index bead763fd2..4eb03bd6c3 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -12,6 +12,7 @@ SYNOPSIS 'git help' [[-i|--info] [-m|--man] [-w|--web]] [|] 'git help' [-g|--guides] 'git help' [-c|--config] +'git help' [--user-interfaces] DESCRIPTION ----------- @@ -69,6 +70,19 @@ OPTIONS --guides:: Prints a list of the Git concept guides on the standard output. +--user-interfaces:: + Prints a list of the repository, command and file interfaces + documentation on the standard output. ++ +In-repository file interfaces such as `.git/info/exclude` are +documented here (see linkgit:gitrepository-layout[5]), as well as +in-tree configuration such as `.mailmap` (see linkgit:gitmailmap[5]). ++ +This section of the documentation also covers general or widespread +user-interface conventions (e.g. linkgit:gitcli[7]), and +pseudo-configuration such as the file-based `.git/hooks/*` interface +described in linkgit:githooks[5]. + -i:: --info:: Display manual page for the command in the 'info' format. The diff --git a/Documentation/git.txt b/Documentation/git.txt index 302607a496..f69d32e1e7 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -339,6 +339,14 @@ The following documentation pages are guides about Git concepts. include::cmds-guide.txt[] +Repository, command and file interfaces +--------------------------------------- + +This documentation discusses repository and command interfaces which +users are expected to interact with directly. See `--user-formats` in +linkgit:git-help[1] for more details on the critera. + +include::cmds-userinterfaces.txt[] Configuration Mechanism ----------------------- diff --git a/Makefile b/Makefile index 1624471bad..ea0ef7df73 100644 --- a/Makefile +++ b/Makefile @@ -3532,6 +3532,7 @@ check-docs:: sed -e '1,/^### command list/d' \ -e '/^#/d' \ -e '/guide$$/d' \ + -e '/interfaces$$/d' \ -e 's/[ ].*//' \ -e 's/^/listed /' command-list.txt; \ $(MAKE) -C Documentation print-man1 | \ diff --git a/builtin/help.c b/builtin/help.c index dec82d1be2..1ab1c8a0dd 100644 --- a/builtin/help.c +++ b/builtin/help.c @@ -43,6 +43,7 @@ static enum help_action { HELP_ACTION_ALL = 1, HELP_ACTION_GUIDES, HELP_ACTION_CONFIG, + HELP_ACTION_USER_INTERFACES, HELP_ACTION_CONFIG_FOR_COMPLETION, HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION, } cmd_mode; @@ -69,6 +70,9 @@ static struct option builtin_help_options[] = { OPT_CMDMODE('g', "guides", &cmd_mode, N_("print list of useful guides"), HELP_ACTION_GUIDES), + OPT_CMDMODE(0, "user-interfaces", &cmd_mode, + N_("print list of user-facing repository, command and file interfaces"), + HELP_ACTION_USER_INTERFACES), OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"), HELP_ACTION_CONFIG), OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "", @@ -84,6 +88,7 @@ static const char * const builtin_help_usage[] = { N_("git help [[-i|--info] [-m|--man] [-w|--web]] [|]"), "git help [-g|--guides]", "git help [-c|--config]", + "git help [--user-interfaces]", NULL }; @@ -654,6 +659,10 @@ int cmd_help(int argc, const char **argv, const char *prefix) opt_mode_usage(argc, "--config-for-completion", help_format); list_config_help(SHOW_CONFIG_VARS); return 0; + case HELP_ACTION_USER_INTERFACES: + opt_mode_usage(argc, "--user-interfaces", help_format); + list_user_interfaces_help(); + return 0; case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION: opt_mode_usage(argc, "--config-sections-for-completion", help_format); diff --git a/command-list.txt b/command-list.txt index 9bd6f3c48f..1d45303e14 100644 --- a/command-list.txt +++ b/command-list.txt @@ -43,6 +43,11 @@ # specified here, which can only have "guide" attribute and nothing # else. # +# User-facing repository, command and file interfaces such as +# documentation for the .gitmodules, .mailmap etc. files lives in man +# sections 5 and 7. These entries can only have the "userinterfaces" +# attribute and nothing else. +# ### command list (do not change this line) # command name category [category] [category] git-add mainporcelain worktree @@ -192,8 +197,8 @@ git-verify-tag ancillaryinterrogators git-whatchanged ancillaryinterrogators complete git-worktree mainporcelain git-write-tree plumbingmanipulators -gitattributes guide -gitcli guide +gitattributes userinterfaces +gitcli userinterfaces gitcore-tutorial guide gitcredentials guide gitcvs-migration guide @@ -201,15 +206,15 @@ gitdiffcore guide giteveryday guide gitfaq guide gitglossary guide -githooks guide -gitignore guide +githooks userinterfaces +gitignore userinterfaces gitk mainporcelain -gitmailmap guide -gitmodules guide +gitmailmap userinterfaces +gitmodules userinterfaces gitnamespaces guide gitremote-helpers guide -gitrepository-layout guide -gitrevisions guide +gitrepository-layout userinterfaces +gitrevisions userinterfaces gitsubmodules guide gittutorial guide gittutorial-2 guide diff --git a/help.c b/help.c index 8a09f18a3d..3e2a78863b 100644 --- a/help.c +++ b/help.c @@ -38,6 +38,7 @@ static struct category_description main_categories[] = { { CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") }, { CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") }, { CAT_purehelpers, N_("Low-level Commands / Internal Helpers") }, + { CAT_userinterfaces, N_("User-facing repository, command and file interfaces") }, { 0, NULL } }; @@ -48,6 +49,7 @@ static const char *drop_prefix(const char *name, uint32_t category) switch (category) { case CAT_guide: + case CAT_userinterfaces: prefix = "git"; break; default: @@ -433,6 +435,16 @@ void list_guides_help(void) putchar('\n'); } +void list_user_interfaces_help(void) +{ + struct category_description catdesc[] = { + { CAT_userinterfaces, N_("User-facing repository, command and file interfaces:") }, + { 0, NULL } + }; + print_cmd_by_category(catdesc, NULL); + putchar('\n'); +} + static int get_alias(const char *var, const char *value, void *data) { struct string_list *list = data; diff --git a/help.h b/help.h index 971a3ad855..243104c27a 100644 --- a/help.h +++ b/help.h @@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num) void list_common_cmds_help(void); void list_all_cmds_help(int show_external_commands, int show_aliases); void list_guides_help(void); +void list_user_interfaces_help(void); void list_all_main_cmds(struct string_list *list); void list_all_other_cmds(struct string_list *list); diff --git a/t/t0012-help.sh b/t/t0012-help.sh index 6c33a43690..bee5ed1220 100755 --- a/t/t0012-help.sh +++ b/t/t0012-help.sh @@ -44,6 +44,8 @@ test_expect_success 'invalid usage' ' test_expect_code 129 git help -g add && test_expect_code 129 git help -a -g && + test_expect_code 129 git help --user-interfaces add && + test_expect_code 129 git help -g -c && test_expect_code 129 git help --config-for-completion add && test_expect_code 129 git help --config-sections-for-completion add @@ -104,9 +106,9 @@ test_expect_success 'git help' ' test_i18ngrep "^ commit " help.output && test_i18ngrep "^ fetch " help.output ' + test_expect_success 'git help -g' ' git help -g >help.output && - test_i18ngrep "^ attributes " help.output && test_i18ngrep "^ everyday " help.output && test_i18ngrep "^ tutorial " help.output ' @@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' ' test_cmp expect test-browser.log ' +test_expect_success 'git help --user-interfaces' ' + git help --user-interfaces >help.output && + grep "^ attributes " help.output && + grep "^ mailmap " help.output +' + test_expect_success 'git help -c' ' git help -c >help.output && cat >expect <<-\EOF && @@ -220,6 +228,8 @@ test_expect_success "'git help -a' section spacing" ' Low-level Commands / Syncing Repositories Low-level Commands / Internal Helpers + + User-facing repository, command and file interfaces EOF test_cmp expect actual ' From 844739ba275e451e44f09a61c4ce0458a8df6077 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Thu, 4 Aug 2022 18:28:34 +0200 Subject: [PATCH 05/12] git docs: add a category for file formats, protocols and interfaces MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Create a new "File formats, protocols and other developer interfaces" section in the main "git help git" manual page and start moving the documentation that now lives in "Documentation/technical/*.git" over to it. This complements the newly added and adjacent "Repository, command and file interfaces" section. This makes the technical documentation more accessible and discoverable. Before this we wouldn't install it by default, and had no ability to build man page versions of them. The links to them from our existing documentation link to the generated HTML version of these docs. So let's start moving those over, starting with just the "bundle-format.txt" documentation added in 7378ec90e1c (doc: describe Git bundle format, 2020-02-07). We'll now have a new gitformat-bundle(5) man page. Subsequent commits will move more git internal format documentation over. Unfortunately the syntax of the current Documentation/technical/*.txt is not the same (when it comes to section headings etc.) as our Documentation/*.txt documentation, so change the relevant bits of syntax as we're moving this over. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/Makefile | 3 +- Documentation/git-bundle.txt | 14 +++--- Documentation/git-help.txt | 5 +++ Documentation/git.txt | 9 ++++ ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++--- Documentation/lint-man-section-order.perl | 3 ++ builtin/help.c | 9 ++++ command-list.txt | 5 +++ help.c | 12 +++++ help.h | 1 + t/t0012-help.sh | 2 + 11 files changed, 94 insertions(+), 13 deletions(-) rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%) diff --git a/Documentation/Makefile b/Documentation/Makefile index 28eb940a9b..1a4a545f44 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -24,6 +24,7 @@ MAN1_TXT += gitweb.txt # man5 / man7 guides (note: new guides should also be added to command-list.txt) MAN5_TXT += gitattributes.txt +MAN5_TXT += gitformat-bundle.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt MAN5_TXT += gitmailmap.txt @@ -95,7 +96,6 @@ TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches TECH_DOCS += ToolsForGit TECH_DOCS += technical/bitmap-format -TECH_DOCS += technical/bundle-format TECH_DOCS += technical/cruft-packs TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol @@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ cmds-synchingrepositories.txt \ cmds-synchelpers.txt \ cmds-guide.txt \ + cmds-developerinterfaces.txt \ cmds-userinterfaces.txt \ cmds-purehelpers.txt \ cmds-foreignscminterface.txt diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 7685b57045..f0b1282b91 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -56,10 +56,9 @@ using "thin packs", bundles created using exclusions are smaller in size. That they're "thin" under the hood is merely noted here as a curiosity, and as a reference to other documentation. -See link:technical/bundle-format.html[the `bundle-format` -documentation] for more details and the discussion of "thin pack" in -link:technical/pack-format.html[the pack format documentation] for -further details. +See linkgit:gitformat-bundle[5] for more details and the discussion of +"thin pack" in link:technical/pack-format.html[the pack format +documentation] for further details. OPTIONS ------- @@ -77,7 +76,7 @@ verify :: commits exist and are fully linked in the current repository. Then, 'git bundle' prints a list of missing commits, if any. Finally, information about additional capabilities, such as "object - filter", is printed. See "Capabilities" in link:technical/bundle-format.html + filter", is printed. See "Capabilities" in linkgit:gitformat-bundle[5] for more information. The exit code is zero for success, but will be nonzero if the bundle file is invalid. @@ -337,6 +336,11 @@ You can also see what references it offers: $ git ls-remote mybundle ---------------- +FILE FORMAT +----------- + +See linkgit:gitformat-bundle[5]. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 4eb03bd6c3..2b0b5e390d 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -13,6 +13,7 @@ SYNOPSIS 'git help' [-g|--guides] 'git help' [-c|--config] 'git help' [--user-interfaces] +'git help' [--developer-interfaces] DESCRIPTION ----------- @@ -83,6 +84,10 @@ user-interface conventions (e.g. linkgit:gitcli[7]), and pseudo-configuration such as the file-based `.git/hooks/*` interface described in linkgit:githooks[5]. +--developer-interfaces:: + Print list of file formats, protocols and other developer + interfaces documentation on the standard output. + -i:: --info:: Display manual page for the command in the 'info' format. The diff --git a/Documentation/git.txt b/Documentation/git.txt index f69d32e1e7..f064951b5c 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -348,6 +348,15 @@ linkgit:git-help[1] for more details on the critera. include::cmds-userinterfaces.txt[] +File formats, protocols and other developer interfaces +------------------------------------------------------ + +This documentation discusses file formats, over-the-wire protocols and +other git developer interfaces. See `--developer-interfaces` in +linkgit:git-help[1]. + +include::cmds-developerinterfaces.txt[] + Configuration Mechanism ----------------------- diff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt similarity index 79% rename from Documentation/technical/bundle-format.txt rename to Documentation/gitformat-bundle.txt index b9be8644cf..6a9d9e5bf6 100644 --- a/Documentation/technical/bundle-format.txt +++ b/Documentation/gitformat-bundle.txt @@ -1,11 +1,33 @@ -= Git bundle v2 format +gitformat-bundle(5) +=================== -The Git bundle format is a format that represents both refs and Git objects. +NAME +---- +gitformat-bundle - The bundle file format -== Format + +SYNOPSIS +-------- +[verse] +*.bundle +*.bdl + +DESCRIPTION +----------- + +The Git bundle format is a format that represents both refs and Git +objects. A bundle is a header in a format similar to +linkgit:git-show-ref[1] followed by a pack in *.pack format. + +The format is created and read by the linkgit:git-bundle[1] command, +and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1]. + + +FORMAT +------ We will use ABNF notation to define the Git bundle format. See -protocol-common.txt for the details. +link:technical/protocol-common.html for the details. A v2 bundle looks like this: @@ -36,7 +58,9 @@ value = *(%01-09 / %0b-FF) pack = ... ; packfile ---- -== Semantics + +SEMANTICS +--------- A Git bundle consists of several parts. @@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id. This is a comment and it has no specific meaning. The writer of the bundle MAY put any string here. The reader of the bundle MUST ignore the comment. -=== Note on the shallow clone and a Git bundle +Note on the shallow clone and a Git bundle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Note that the prerequisites does not represent a shallow-clone boundary. The semantics of the prerequisites and the shallow-clone boundaries are different, and the Git bundle v2 format cannot represent a shallow clone repository. -== Capabilities +CAPABILITIES +------------ Because there is no opportunity for negotiation, unknown capabilities cause 'git bundle' to abort. @@ -79,3 +105,7 @@ bundle' to abort. * `filter` specifies an object filter as in the `--filter` option in linkgit:git-rev-list[1]. The resulting pack-file must be marked as a `.promisor` pack-file after it is unbundled. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl index 425377dfeb..02408a0062 100755 --- a/Documentation/lint-man-section-order.perl +++ b/Documentation/lint-man-section-order.perl @@ -32,6 +32,9 @@ my %SECTIONS; 'SEE ALSO' => { order => $order++, }, + 'FILE FORMAT' => { + order => $order++, + }, 'GIT' => { required => 1, order => $order++, diff --git a/builtin/help.c b/builtin/help.c index 1ab1c8a0dd..09ac4289f1 100644 --- a/builtin/help.c +++ b/builtin/help.c @@ -44,6 +44,7 @@ static enum help_action { HELP_ACTION_GUIDES, HELP_ACTION_CONFIG, HELP_ACTION_USER_INTERFACES, + HELP_ACTION_DEVELOPER_INTERFACES, HELP_ACTION_CONFIG_FOR_COMPLETION, HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION, } cmd_mode; @@ -73,6 +74,9 @@ static struct option builtin_help_options[] = { OPT_CMDMODE(0, "user-interfaces", &cmd_mode, N_("print list of user-facing repository, command and file interfaces"), HELP_ACTION_USER_INTERFACES), + OPT_CMDMODE(0, "developer-interfaces", &cmd_mode, + N_("print list of file formats, protocols and other developer interfaces"), + HELP_ACTION_DEVELOPER_INTERFACES), OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"), HELP_ACTION_CONFIG), OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "", @@ -89,6 +93,7 @@ static const char * const builtin_help_usage[] = { "git help [-g|--guides]", "git help [-c|--config]", "git help [--user-interfaces]", + "git help [--developer-interfaces]", NULL }; @@ -663,6 +668,10 @@ int cmd_help(int argc, const char **argv, const char *prefix) opt_mode_usage(argc, "--user-interfaces", help_format); list_user_interfaces_help(); return 0; + case HELP_ACTION_DEVELOPER_INTERFACES: + opt_mode_usage(argc, "--developer-interfaces", help_format); + list_developer_interfaces_help(); + return 0; case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION: opt_mode_usage(argc, "--config-sections-for-completion", help_format); diff --git a/command-list.txt b/command-list.txt index 1d45303e14..1950c4ccd9 100644 --- a/command-list.txt +++ b/command-list.txt @@ -48,6 +48,10 @@ # sections 5 and 7. These entries can only have the "userinterfaces" # attribute and nothing else. # +# Git's file formats and protocols, such as documentation for the +# *.bundle format lives in man section 5. These entries can only have +# the "developerinterfaces" attribute and nothing else. +# ### command list (do not change this line) # command name category [category] [category] git-add mainporcelain worktree @@ -205,6 +209,7 @@ gitcvs-migration guide gitdiffcore guide giteveryday guide gitfaq guide +gitformat-bundle developerinterfaces gitglossary guide githooks userinterfaces gitignore userinterfaces diff --git a/help.c b/help.c index 3e2a78863b..991e33f8a6 100644 --- a/help.c +++ b/help.c @@ -39,6 +39,7 @@ static struct category_description main_categories[] = { { CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") }, { CAT_purehelpers, N_("Low-level Commands / Internal Helpers") }, { CAT_userinterfaces, N_("User-facing repository, command and file interfaces") }, + { CAT_developerinterfaces, N_("Developer-facing file file formats, protocols and interfaces") }, { 0, NULL } }; @@ -50,6 +51,7 @@ static const char *drop_prefix(const char *name, uint32_t category) switch (category) { case CAT_guide: case CAT_userinterfaces: + case CAT_developerinterfaces: prefix = "git"; break; default: @@ -445,6 +447,16 @@ void list_user_interfaces_help(void) putchar('\n'); } +void list_developer_interfaces_help(void) +{ + struct category_description catdesc[] = { + { CAT_developerinterfaces, N_("File formats, protocols and other developer interfaces:") }, + { 0, NULL } + }; + print_cmd_by_category(catdesc, NULL); + putchar('\n'); +} + static int get_alias(const char *var, const char *value, void *data) { struct string_list *list = data; diff --git a/help.h b/help.h index 243104c27a..af073a7a02 100644 --- a/help.h +++ b/help.h @@ -23,6 +23,7 @@ void list_common_cmds_help(void); void list_all_cmds_help(int show_external_commands, int show_aliases); void list_guides_help(void); void list_user_interfaces_help(void); +void list_developer_interfaces_help(void); void list_all_main_cmds(struct string_list *list); void list_all_other_cmds(struct string_list *list); diff --git a/t/t0012-help.sh b/t/t0012-help.sh index bee5ed1220..4ed2f242eb 100755 --- a/t/t0012-help.sh +++ b/t/t0012-help.sh @@ -230,6 +230,8 @@ test_expect_success "'git help -a' section spacing" ' Low-level Commands / Internal Helpers User-facing repository, command and file interfaces + + Developer-facing file file formats, protocols and interfaces EOF test_cmp expect actual ' From 8cbace93d270dc49f007a2c1922769240a22eca5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Thu, 4 Aug 2022 18:28:35 +0200 Subject: [PATCH 06/12] docs: move commit-graph format docs to man section 5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space. By moving the documentation for the commit-graph format into man section 5 and the new "developerinterfaces" category. This change is split from subsequent commits due to the relatively large amount of ASCIIDOC formatting changes that are required. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/Makefile | 1 + Documentation/git-commit-graph.txt | 5 ++ ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------ Documentation/technical/chunk-format.txt | 4 +- command-list.txt | 1 + 5 files changed, 41 insertions(+), 17 deletions(-) rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (88%) diff --git a/Documentation/Makefile b/Documentation/Makefile index 1a4a545f44..e7bd72bb84 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -25,6 +25,7 @@ MAN1_TXT += gitweb.txt # man5 / man7 guides (note: new guides should also be added to command-list.txt) MAN5_TXT += gitattributes.txt MAN5_TXT += gitformat-bundle.txt +MAN5_TXT += gitformat-commit-graph.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt MAN5_TXT += gitmailmap.txt diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index e1f48c95b3..047decdb65 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append ------------------------------------------------ +FILE FORMAT +----------- + +see linkgit:gitformat-commit-graph[5]. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt similarity index 88% rename from Documentation/technical/commit-graph-format.txt rename to Documentation/gitformat-commit-graph.txt index 484b185ba9..108dc2295c 100644 --- a/Documentation/technical/commit-graph-format.txt +++ b/Documentation/gitformat-commit-graph.txt @@ -1,5 +1,18 @@ -Git commit graph format -======================= +gitformat-commit-graph(5) +========================= + +NAME +---- +gitformat-commit-graph - Git commit graph format + +SYNOPSIS +-------- +[verse] +$GIT_DIR/objects/info/commit-graph +$GIT_DIR/objects/info/commit-graphs/* + +DESCRIPTION +----------- The Git commit graph stores a list of commit OIDs and some associated metadata, including: @@ -30,7 +43,7 @@ and hash type. All multi-byte numbers are in network byte order. -HEADER: +=== HEADER: 4-byte signature: The signature is: {'C', 'G', 'P', 'H'} @@ -52,7 +65,7 @@ HEADER: We infer the length (H*B) of the Base Graphs chunk from this value. -CHUNK LOOKUP: +=== CHUNK LOOKUP: (C + 1) * 12 bytes listing the table of contents for the chunks: First 4 bytes describe the chunk id. Value 0 is a terminating label. @@ -68,17 +81,17 @@ CHUNK LOOKUP: these chunks may be given in any order. Chunks are required unless otherwise specified. -CHUNK DATA: +=== CHUNK DATA: - OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes) +==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes) The ith entry, F[i], stores the number of OIDs with first byte at most i. Thus F[255] stores the total number of commits (N). - OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes) +==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes) The OIDs for all commits in the graph, sorted in ascending order. - Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes) +==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes) * The first H bytes are for the OID of the root tree. * The next 8 bytes are for the positions of the first two parents of the ith commit. Stores value 0x70000000 if no parent in that @@ -93,7 +106,7 @@ CHUNK DATA: 2 bits of the lowest byte, storing the 33rd and 34th bit of the commit time. - Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional] +==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional] * This list of 4-byte values store corrected commit date offsets for the commits, arranged in the same order as commit data chunk. * If the corrected commit date offset cannot be stored within 31 bits, @@ -104,7 +117,7 @@ CHUNK DATA: by compatible versions of Git and in case of split commit-graph chains, the topmost layer also has Generation Data chunk. - Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional] +==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional] * 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. @@ -112,7 +125,7 @@ CHUNK DATA: chunk is present and atleast one corrected commit date offset cannot be stored within 31 bits. - Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional] +==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional] This list of 4-byte values store the second through nth parents for all octopus merges. The second parent value in the commit data stores an array position within this list along with the most-significant bit @@ -120,14 +133,14 @@ CHUNK DATA: positions for the parents until reaching a value with the most-significant bit on. The other bits correspond to the position of the last parent. - Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional] +==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional] * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters from commit 0 to commit i (inclusive) in lexicographic order. The Bloom filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header length), where BIDX[-1] is 0. * The BIDX chunk is ignored if the BDAT chunk is not present. - Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional] +==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional] * It starts with header consisting of three unsigned 32-bit integers: - Version of the hash algorithm being used. We currently only support value 1 which corresponds to the 32-bit version of the murmur3 hash @@ -147,13 +160,13 @@ CHUNK DATA: of length one, with either all bits set to zero or one respectively. * The BDAT chunk is present if and only if BIDX is present. - Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional] +==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional] This list of H-byte hashes describe a set of B commit-graph files that form a commit-graph chain. The graph position for the ith commit in this file's OID Lookup chunk is equal to i plus the number of commits in all base graphs. If B is non-zero, this chunk must exist. -TRAILER: +=== TRAILER: H-byte HASH-checksum of all of the above. @@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote possibly erroneous data in these chunks with the IDs "GDAT" and "GDOV". By changing the IDs, newer versions of Git will silently ignore those older chunks and write the new information without trusting the incorrect data. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/chunk-format.txt b/Documentation/technical/chunk-format.txt index 593614fced..f36ce42f37 100644 --- a/Documentation/technical/chunk-format.txt +++ b/Documentation/technical/chunk-format.txt @@ -6,7 +6,7 @@ sections of the file. This allows structured access to a large file by scanning a small "table of contents" for the remaining data. This common format is used by the `commit-graph` and `multi-pack-index` files. See link:technical/pack-format.html[the `multi-pack-index` format] and -link:technical/commit-graph-format.html[the `commit-graph` format] for +the `commit-graph` format in linkgit:gitformat-commit-graph[5] for how they use the chunks to describe structured data. A chunk-based file format begins with some header information custom to @@ -108,7 +108,7 @@ for future formats: * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()` in `commit-graph.c` for how the chunk-format API is used to write and parse the commit-graph file format documented in - link:technical/commit-graph-format.html[the commit-graph file format]. + the commit-graph file format in linkgit:gitformat-commit-graph[5]. * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()` in `midx.c` for how the chunk-format API is used to write and diff --git a/command-list.txt b/command-list.txt index 1950c4ccd9..3afcfcd35f 100644 --- a/command-list.txt +++ b/command-list.txt @@ -210,6 +210,7 @@ gitdiffcore guide giteveryday guide gitfaq guide gitformat-bundle developerinterfaces +gitformat-commit-graph developerinterfaces gitglossary guide githooks userinterfaces gitignore userinterfaces From 5db921054e685a4dbaeb622acda53d6a154e947f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Thu, 4 Aug 2022 18:28:36 +0200 Subject: [PATCH 07/12] docs: move protocol-related docs to man section 5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space. By moving the things that discuss the protocol we can properly link from e.g. lsrefs.unborn and protocol.version documentation to a manpage we build by default. So far we have been using the "gitformat-" prefix for the documentation we've been moving over from Documentation/technical/*, but for protocol documentation let's use "gitprotocol-*". Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/Makefile | 8 +++--- Documentation/config/lsrefs.txt | 2 +- Documentation/config/protocol.txt | 2 +- Documentation/git-upload-pack.txt | 5 ++-- Documentation/gitformat-bundle.txt | 2 +- ...ities.txt => gitprotocol-capabilities.txt} | 28 +++++++++++++++---- ...ocol-common.txt => gitprotocol-common.txt} | 23 +++++++++++++-- ...pack-protocol.txt => gitprotocol-pack.txt} | 24 +++++++++++++--- .../protocol-v2.txt => gitprotocol-v2.txt} | 25 +++++++++++++---- Documentation/technical/api-simple-ipc.txt | 2 +- Documentation/technical/http-protocol.txt | 6 ++-- .../long-running-process-protocol.txt | 2 +- Documentation/technical/packfile-uri.txt | 2 +- Documentation/technical/partial-clone.txt | 2 +- command-list.txt | 4 +++ refspec.h | 2 +- t/t5551-http-fetch-smart.sh | 4 +-- 17 files changed, 106 insertions(+), 37 deletions(-) rename Documentation/{technical/protocol-capabilities.txt => gitprotocol-capabilities.txt} (96%) rename Documentation/{technical/protocol-common.txt => gitprotocol-common.txt} (89%) rename Documentation/{technical/pack-protocol.txt => gitprotocol-pack.txt} (98%) rename Documentation/{technical/protocol-v2.txt => gitprotocol-v2.txt} (98%) diff --git a/Documentation/Makefile b/Documentation/Makefile index e7bd72bb84..b53f3c1284 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -30,6 +30,10 @@ MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt MAN5_TXT += gitmailmap.txt MAN5_TXT += gitmodules.txt +MAN5_TXT += gitprotocol-capabilities.txt +MAN5_TXT += gitprotocol-common.txt +MAN5_TXT += gitprotocol-pack.txt +MAN5_TXT += gitprotocol-v2.txt MAN5_TXT += gitrepository-layout.txt MAN5_TXT += gitweb.conf.txt @@ -105,12 +109,8 @@ TECH_DOCS += technical/long-running-process-protocol TECH_DOCS += technical/multi-pack-index TECH_DOCS += technical/pack-format TECH_DOCS += technical/pack-heuristics -TECH_DOCS += technical/pack-protocol TECH_DOCS += technical/parallel-checkout TECH_DOCS += technical/partial-clone -TECH_DOCS += technical/protocol-capabilities -TECH_DOCS += technical/protocol-common -TECH_DOCS += technical/protocol-v2 TECH_DOCS += technical/racy-git TECH_DOCS += technical/reftable TECH_DOCS += technical/send-pack-pipeline diff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.txt index adeda0f24d..3d88fb0bad 100644 --- a/Documentation/config/lsrefs.txt +++ b/Documentation/config/lsrefs.txt @@ -1,7 +1,7 @@ lsrefs.unborn:: May be "advertise" (the default), "allow", or "ignore". If "advertise", the server will respond to the client sending "unborn" (as described in - protocol-v2.txt) and will advertise support for this feature during the + linkgit:gitprotocol-v2[5]) and will advertise support for this feature during the protocol v2 capability advertisement. "allow" is the same as "advertise" except that the server will not advertise support for this feature; this is useful for load-balanced servers that cannot be diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt index 756591d77b..5760381851 100644 --- a/Documentation/config/protocol.txt +++ b/Documentation/config/protocol.txt @@ -58,6 +58,6 @@ protocol.version:: * `1` - the original wire protocol with the addition of a version string in the initial response from the server. -* `2` - link:technical/protocol-v2.html[wire protocol version 2]. +* `2` - Wire protocol version 2, see linkgit:gitprotocol-v2[5]. -- diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 8f87b23ea8..3409e0d36d 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -40,9 +40,8 @@ OPTIONS Used by linkgit:git-http-backend[1] to serve up `$GIT_URL/info/refs?service=git-upload-pack` requests. See "Smart Clients" in link:technical/http-protocol.html[the HTTP - transfer protocols] documentation and "HTTP Transport" in - link:technical/protocol-v2.html[the Git Wire Protocol, Version - 2] documentation. Also understood by + transfer protocols] documentation and "HTTP Transport" in the + linkgit:gitprotocol-v2[5] documentation. Also understood by linkgit:git-receive-pack[1]. :: diff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.txt index 6a9d9e5bf6..00e0a20e65 100644 --- a/Documentation/gitformat-bundle.txt +++ b/Documentation/gitformat-bundle.txt @@ -27,7 +27,7 @@ FORMAT ------ We will use ABNF notation to define the Git bundle format. See -link:technical/protocol-common.html for the details. +linkgit:gitprotocol-common[5] for the details. A v2 bundle looks like this: diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/gitprotocol-capabilities.txt similarity index 96% rename from Documentation/technical/protocol-capabilities.txt rename to Documentation/gitprotocol-capabilities.txt index 9dfade930d..c6dcc7d565 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/gitprotocol-capabilities.txt @@ -1,8 +1,20 @@ -Git Protocol Capabilities -========================= +gitprotocol-capabilities(5) +=========================== + +NAME +---- +gitprotocol-capabilities - Protocol v0 and v1 capabilities + +SYNOPSIS +-------- +[verse] + + +DESCRIPTION +----------- NOTE: this document describes capabilities for versions 0 and 1 of the pack -protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2] +protocol. For version 2, please refer to the linkgit:gitprotocol-v2[5] doc. Servers SHOULD support all capabilities defined in this document. @@ -77,7 +89,7 @@ interleaved with S-R-Q. multi_ack_detailed ------------------ This is an extension of multi_ack that permits client to better -understand the server's in-memory state. See pack-protocol.txt, +understand the server's in-memory state. See linkgit:gitprotocol-pack[5], section "Packfile Negotiation" for more information. no-done @@ -281,7 +293,7 @@ a packfile upload and reference update. If the pushing client requests this capability, after unpacking and updating references the server will respond with whether the packfile unpacked successfully and if each reference was updated successfully. If any of those were not -successful, it will send back an error message. See pack-protocol.txt +successful, it will send back an error message. See linkgit:gitprotocol-pack[5] for example messages. report-status-v2 @@ -292,7 +304,7 @@ adding new "option" directives in order to support reference rewritten by the "proc-receive" hook. The "proc-receive" hook may handle a command for a pseudo-reference which may create or update a reference with different name, new-oid, and old-oid. While the capability -'report-status' cannot report for such case. See pack-protocol.txt +'report-status' cannot report for such case. See linkgit:gitprotocol-pack[5] for details. delete-refs @@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The current implementation uses trace2 session IDs (see link:api-trace2.html[api-trace2] for details), but this may change and users of the session ID should not rely on this fact. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/protocol-common.txt b/Documentation/gitprotocol-common.txt similarity index 89% rename from Documentation/technical/protocol-common.txt rename to Documentation/gitprotocol-common.txt index ecedb34bba..1486651bd1 100644 --- a/Documentation/technical/protocol-common.txt +++ b/Documentation/gitprotocol-common.txt @@ -1,5 +1,20 @@ -Documentation Common to Pack and Http Protocols -=============================================== +gitprotocol-common(5) +===================== + +NAME +---- +gitprotocol-common - Things common to various protocols + +SYNOPSIS +-------- +[verse] + + +DESCRIPTION +----------- + +This document sets defines things common to various over-the-wire +protocols and file formats used in Git. ABNF Notation ------------- @@ -97,3 +112,7 @@ Examples (as C-style strings): "000bfoobar\n" "foobar\n" "0004" "" ---- + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitprotocol-pack.txt similarity index 98% rename from Documentation/technical/pack-protocol.txt rename to Documentation/gitprotocol-pack.txt index e13a2c064d..8a4de6decd 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/gitprotocol-pack.txt @@ -1,5 +1,17 @@ -Packfile transfer protocols -=========================== +gitprotocol-pack(5) +=================== + +NAME +---- +gitprotocol-pack - How packs are transferred over-the-wire + +SYNOPSIS +-------- +[verse] + + +DESCRIPTION +----------- Git supports transferring data in packfiles over the ssh://, git://, http:// and file:// transports. There exist two sets of protocols, one for pushing @@ -18,7 +30,7 @@ pkt-line Format --------------- The descriptions below build on the pkt-line format described in -protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless +linkgit:gitprotocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless otherwise noted the usual pkt-line LF rules apply: the sender SHOULD include a LF, but the receiver MUST NOT complain if it is not present. @@ -60,7 +72,7 @@ Each Extra Parameter takes the form of `=` or ``. Servers that receive any such Extra Parameters MUST ignore all unrecognized keys. Currently, the only Extra Parameter recognized is -"version" with a value of '1' or '2'. See protocol-v2.txt for more +"version" with a value of '1' or '2'. See linkgit:gitprotocol-v2[5] for more information on protocol version 2. Git Transport @@ -707,3 +719,7 @@ An example client/server communication might look like this: S: 0018ok refs/heads/debug\n S: 002ang refs/heads/master non-fast-forward\n ---- + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/gitprotocol-v2.txt similarity index 98% rename from Documentation/technical/protocol-v2.txt rename to Documentation/gitprotocol-v2.txt index 8a877d27e2..d6105e0740 100644 --- a/Documentation/technical/protocol-v2.txt +++ b/Documentation/gitprotocol-v2.txt @@ -1,5 +1,17 @@ -Git Wire Protocol, Version 2 -============================ +gitprotocol-v2(5) +================= + +NAME +---- +gitprotocol-v2 - Git Wire Protocol, Version 2 + +SYNOPSIS +-------- +[verse] + + +DESCRIPTION +----------- This document presents a specification for a version 2 of Git's wire protocol. Protocol v2 will improve upon v1 in the following ways: @@ -26,8 +38,7 @@ Packet-Line Framing ------------------- All communication is done using packet-line framing, just as in v1. See -`Documentation/technical/pack-protocol.txt` and -`Documentation/technical/protocol-common.txt` for more information. +linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-common[5] for more information. In protocol v2 these special packets will have the following semantics: @@ -42,7 +53,7 @@ Initial Client Request In general a client can request to speak protocol v2 by sending `version=2` through the respective side-channel for the transport being used which inevitably sets `GIT_PROTOCOL`. More information can be -found in `pack-protocol.txt` and `http-protocol.txt`, as well as the +found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the `GIT_PROTOCOL` definition in `git.txt`. In all cases the response from the server is the capability advertisement. @@ -566,3 +577,7 @@ and associated requested information, each separated by a single space. attr = "size" obj-info = obj-id SP obj-size + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt index d79ad323e6..d44ada98e7 100644 --- a/Documentation/technical/api-simple-ipc.txt +++ b/Documentation/technical/api-simple-ipc.txt @@ -78,7 +78,7 @@ client and an optional response message from the server. Both the client and server messages are unlimited in length and are terminated with a flush packet. -The pkt-line routines (Documentation/technical/protocol-common.txt) +The pkt-line routines (linkgit:gitprotocol-common[5]) are used to simplify buffer management during message generation, transmission, and reception. A flush packet is used to mark the end of the message. This allows the sender to incrementally generate and diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt index cc5126cfed..8bd672d55b 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/technical/http-protocol.txt @@ -222,7 +222,7 @@ smart server reply: S: 0000 The client may send Extra Parameters (see -Documentation/technical/pack-protocol.txt) as a colon-separated string +linkgit:gitprotocol-pack[5]) as a colon-separated string in the Git-Protocol HTTP header. Uses the `--http-backend-info-refs` option to @@ -518,5 +518,5 @@ References http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)] http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1] -link:technical/pack-protocol.html -link:technical/protocol-capabilities.html +linkgit:gitprotocol-pack[5] +linkgit:gitprotocol-capabilities[5] diff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt index aa0aa9af1c..6f33654b42 100644 --- a/Documentation/technical/long-running-process-protocol.txt +++ b/Documentation/technical/long-running-process-protocol.txt @@ -3,7 +3,7 @@ Long-running process protocol This protocol is used when Git needs to communicate with an external process throughout the entire life of a single Git command. All -communication is in pkt-line format (see technical/protocol-common.txt) +communication is in pkt-line format (see linkgit:gitprotocol-common[5]) over standard input and standard output. Handshake diff --git a/Documentation/technical/packfile-uri.txt b/Documentation/technical/packfile-uri.txt index 1eb525fe76..9d453d4765 100644 --- a/Documentation/technical/packfile-uri.txt +++ b/Documentation/technical/packfile-uri.txt @@ -18,7 +18,7 @@ a `packfile-uris` argument, the server MAY send a `packfile-uris` section directly before the `packfile` section (right after `wanted-refs` if it is sent) containing URIs of any of the given protocols. The URIs point to packfiles that use only features that the client has declared that it supports -(e.g. ofs-delta and thin-pack). See protocol-v2.txt for the documentation of +(e.g. ofs-delta and thin-pack). See linkgit:gitprotocol-v2[5] for the documentation of this section. Clients should then download and index all the given URIs (in addition to diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt index 99f0eb3040..92fcee2bff 100644 --- a/Documentation/technical/partial-clone.txt +++ b/Documentation/technical/partial-clone.txt @@ -79,7 +79,7 @@ Design Details upload-pack negotiation. + This uses the existing capability discovery mechanism. -See "filter" in Documentation/technical/pack-protocol.txt. +See "filter" in linkgit:gitprotocol-pack[5]. - Clients pass a "filter-spec" to clone and fetch which is passed to the server to request filtering during packfile construction. diff --git a/command-list.txt b/command-list.txt index 3afcfcd35f..ed859fdd79 100644 --- a/command-list.txt +++ b/command-list.txt @@ -218,6 +218,10 @@ gitk mainporcelain gitmailmap userinterfaces gitmodules userinterfaces gitnamespaces guide +gitprotocol-capabilities developerinterfaces +gitprotocol-common developerinterfaces +gitprotocol-pack developerinterfaces +gitprotocol-v2 developerinterfaces gitremote-helpers guide gitrepository-layout userinterfaces gitrevisions userinterfaces diff --git a/refspec.h b/refspec.h index 8b79891d32..8c0c446993 100644 --- a/refspec.h +++ b/refspec.h @@ -69,7 +69,7 @@ int valid_remote_name(const char *name); struct strvec; /* * Determine what values to pass to the peer in ref-prefix lines - * (see Documentation/technical/protocol-v2.txt). + * (see linkgit:gitprotocol-v2[5]). */ void refspec_ref_prefixes(const struct refspec *rs, struct strvec *ref_prefixes); diff --git a/t/t5551-http-fetch-smart.sh b/t/t5551-http-fetch-smart.sh index 245532df88..6a38294a47 100755 --- a/t/t5551-http-fetch-smart.sh +++ b/t/t5551-http-fetch-smart.sh @@ -181,8 +181,8 @@ test_expect_success 'no-op half-auth fetch does not require a password' ' # This is not possible with protocol v2, since both objects and refs # are obtained from the "git-upload-pack" path. A solution to this is # to teach the server and client to be able to inline ls-refs requests - # as an Extra Parameter (see pack-protocol.txt), so that "info/refs" - # can serve refs, just like it does in protocol v0. + # as an Extra Parameter (see "git help gitformat-pack-protocol"), so that + # "info/refs" can serve refs, just like it does in protocol v0. GIT_TEST_PROTOCOL_VERSION=0 git --git-dir=half-auth fetch && expect_askpass none ' From 00d3e8d7dd9ece6fe89dafff384ff32444754211 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Thu, 4 Aug 2022 18:28:37 +0200 Subject: [PATCH 08/12] docs: move index format docs to man section 5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space by moving the index format documentation. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/Makefile | 2 +- .../index-format.txt => gitformat-index.txt} | 20 ++++++++++++++++++- command-list.txt | 1 + 3 files changed, 21 insertions(+), 2 deletions(-) rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%) diff --git a/Documentation/Makefile b/Documentation/Makefile index b53f3c1284..029067a77d 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -26,6 +26,7 @@ MAN1_TXT += gitweb.txt MAN5_TXT += gitattributes.txt MAN5_TXT += gitformat-bundle.txt MAN5_TXT += gitformat-commit-graph.txt +MAN5_TXT += gitformat-index.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt MAN5_TXT += gitmailmap.txt @@ -104,7 +105,6 @@ TECH_DOCS += technical/bitmap-format TECH_DOCS += technical/cruft-packs TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol -TECH_DOCS += technical/index-format TECH_DOCS += technical/long-running-process-protocol TECH_DOCS += technical/multi-pack-index TECH_DOCS += technical/pack-format diff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt similarity index 98% rename from Documentation/technical/index-format.txt rename to Documentation/gitformat-index.txt index 65da0daaa5..41491d2a07 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/gitformat-index.txt @@ -1,5 +1,19 @@ +gitformat-index(5) +================== + +NAME +---- +gitformat-index - Git index format + +SYNOPSIS +-------- +[verse] +$GIT_DIR/index + +DESCRIPTION +----------- + Git index format -================ == The Git index file has the following format @@ -404,3 +418,7 @@ The remaining data of each directory block is grouped by type: with signature { 's', 'd', 'i', 'r' }. Like the split-index extension, tools should avoid interacting with a sparse index unless they understand this extension. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/command-list.txt b/command-list.txt index ed859fdd79..5e8d838668 100644 --- a/command-list.txt +++ b/command-list.txt @@ -211,6 +211,7 @@ giteveryday guide gitfaq guide gitformat-bundle developerinterfaces gitformat-commit-graph developerinterfaces +gitformat-index developerinterfaces gitglossary guide githooks userinterfaces gitignore userinterfaces From 20516890dc86c2949419287d59b4f3df7e7972e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Thu, 4 Aug 2022 18:28:38 +0200 Subject: [PATCH 09/12] docs: move signature docs to man section 5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space by moving the signature format documentation. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/Makefile | 2 +- ...ure-format.txt => gitformat-signature.txt} | 21 ++++++++++++++++--- command-list.txt | 1 + 3 files changed, 20 insertions(+), 4 deletions(-) rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%) diff --git a/Documentation/Makefile b/Documentation/Makefile index 029067a77d..d122d1751d 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -27,6 +27,7 @@ MAN5_TXT += gitattributes.txt MAN5_TXT += gitformat-bundle.txt MAN5_TXT += gitformat-commit-graph.txt MAN5_TXT += gitformat-index.txt +MAN5_TXT += gitformat-signature.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt MAN5_TXT += gitmailmap.txt @@ -115,7 +116,6 @@ TECH_DOCS += technical/racy-git TECH_DOCS += technical/reftable TECH_DOCS += technical/send-pack-pipeline TECH_DOCS += technical/shallow -TECH_DOCS += technical/signature-format TECH_DOCS += technical/trivial-merge SP_ARTICLES += $(TECH_DOCS) SP_ARTICLES += technical/api-index diff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt similarity index 96% rename from Documentation/technical/signature-format.txt rename to Documentation/gitformat-signature.txt index 166721be6f..a249869faf 100644 --- a/Documentation/technical/signature-format.txt +++ b/Documentation/gitformat-signature.txt @@ -1,7 +1,18 @@ -Git signature format -==================== +gitformat-signature(5) +====================== -== Overview +NAME +---- +gitformat-signature - Git cryptographic signature formats + +SYNOPSIS +-------- +[verse] +<[tag|commit] object header(s)> + + +DESCRIPTION +----------- Git uses cryptographic signatures in various places, currently objects (tags, commits, mergetags) and transactions (pushes). In every case, the command which @@ -200,3 +211,7 @@ Date: Wed Jun 15 09:13:29 2016 +0000 # gpg: There is no indication that the signature belongs to the owner. # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 ---- + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/command-list.txt b/command-list.txt index 5e8d838668..68212e3c1b 100644 --- a/command-list.txt +++ b/command-list.txt @@ -212,6 +212,7 @@ gitfaq guide gitformat-bundle developerinterfaces gitformat-commit-graph developerinterfaces gitformat-index developerinterfaces +gitformat-signature developerinterfaces gitglossary guide githooks userinterfaces gitignore userinterfaces From 977c47b46d4d4e5b25afd548c1bd6c108afad632 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Thu, 4 Aug 2022 18:28:39 +0200 Subject: [PATCH 10/12] docs: move pack format docs to man section 5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space by moving the various documentation pertaining to the *.pack format and related files, and updating things that refer to it to link to the new location. By moving these we can properly link from the newly created gitformat-commit-graph to a gitformat-chunk-format page. Integrating "Documentation/technical/bitmap-format.txt" and "Documentation/technical/cruft-packs.txt" might logically be part of this change, but as those cover parts of the wider "pack format" (including associated files) that's documented outside of "Documentation/technical/pack-format.txt" let's leave those for now, subsequent commit(s) will address those. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/Makefile | 3 +- Documentation/config/pack.txt | 2 +- Documentation/git-bundle.txt | 3 +- Documentation/git-multi-pack-index.txt | 4 +-- .../chunk-format.txt => gitformat-chunk.txt} | 25 +++++++++++--- Documentation/gitformat-commit-graph.txt | 2 +- Documentation/gitformat-index.txt | 2 +- .../pack-format.txt => gitformat-pack.txt} | 34 +++++++++++++++++-- Documentation/gitprotocol-pack.txt | 2 +- .../howto/recover-corrupted-object-harder.txt | 2 +- .../technical/hash-function-transition.txt | 2 +- Documentation/user-manual.txt | 2 +- cache.h | 3 +- command-list.txt | 2 ++ pack-revindex.h | 2 +- 15 files changed, 68 insertions(+), 22 deletions(-) rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (91%) rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%) diff --git a/Documentation/Makefile b/Documentation/Makefile index d122d1751d..d4a4a8c8b7 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -25,8 +25,10 @@ MAN1_TXT += gitweb.txt # man5 / man7 guides (note: new guides should also be added to command-list.txt) MAN5_TXT += gitattributes.txt MAN5_TXT += gitformat-bundle.txt +MAN5_TXT += gitformat-chunk.txt MAN5_TXT += gitformat-commit-graph.txt MAN5_TXT += gitformat-index.txt +MAN5_TXT += gitformat-pack.txt MAN5_TXT += gitformat-signature.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt @@ -108,7 +110,6 @@ TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol TECH_DOCS += technical/long-running-process-protocol TECH_DOCS += technical/multi-pack-index -TECH_DOCS += technical/pack-format TECH_DOCS += technical/pack-heuristics TECH_DOCS += technical/parallel-checkout TECH_DOCS += technical/partial-clone diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt index ad7f73a1ea..3e581eab84 100644 --- a/Documentation/config/pack.txt +++ b/Documentation/config/pack.txt @@ -166,7 +166,7 @@ permuted into their appropriate location when writing a new bitmap. pack.writeReverseIndex:: When true, git will write a corresponding .rev file (see: - link:../technical/pack-format.html[Documentation/technical/pack-format.txt]) + linkgit:gitformat-pack[5]) for each new packfile that it writes in all places except for linkgit:git-fast-import[1] and in the bulk checkin mechanism. Defaults to false. diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index f0b1282b91..6da6172243 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -57,8 +57,7 @@ size. That they're "thin" under the hood is merely noted here as a curiosity, and as a reference to other documentation. See linkgit:gitformat-bundle[5] for more details and the discussion of -"thin pack" in link:technical/pack-format.html[the pack format -documentation] for further details. +"thin pack" in linkgit:gitformat-pack[5] for further details. OPTIONS ------- diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt index c588fb91af..a48c3d5ea6 100644 --- a/Documentation/git-multi-pack-index.txt +++ b/Documentation/git-multi-pack-index.txt @@ -128,8 +128,8 @@ $ git multi-pack-index verify SEE ALSO -------- See link:technical/multi-pack-index.html[The Multi-Pack-Index Design -Document] and link:technical/pack-format.html[The Multi-Pack-Index -Format] for more information on the multi-pack-index feature. +Document] and linkgit:gitformat-pack[5] for more information on the +multi-pack-index feature and its file format. GIT diff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt similarity index 91% rename from Documentation/technical/chunk-format.txt rename to Documentation/gitformat-chunk.txt index f36ce42f37..57202ede27 100644 --- a/Documentation/technical/chunk-format.txt +++ b/Documentation/gitformat-chunk.txt @@ -1,11 +1,24 @@ -Chunk-based file formats -======================== +gitformat-chunk(5) +================== + +NAME +---- +gitformat-chunk - Chunk-based file formats + +SYNOPSIS +-------- + +Used by linkgit:gitformat-commit-graph[5] and the "MIDX" format (see +the pack format documentation in linkgit:gitformat-pack[5]). + +DESCRIPTION +----------- Some file formats in Git use a common concept of "chunks" to describe sections of the file. This allows structured access to a large file by scanning a small "table of contents" for the remaining data. This common format is used by the `commit-graph` and `multi-pack-index` files. See -link:technical/pack-format.html[the `multi-pack-index` format] and +the `multi-pack-index` format in linkgit:gitformat-pack[5] and the `commit-graph` format in linkgit:gitformat-commit-graph[5] for how they use the chunks to describe structured data. @@ -113,4 +126,8 @@ for future formats: * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()` in `midx.c` for how the chunk-format API is used to write and parse the multi-pack-index file format documented in - link:technical/pack-format.html[the multi-pack-index file format]. + the multi-pack-index file format section of linkgit:gitformat-pack[5]. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt index 108dc2295c..7324665716 100644 --- a/Documentation/gitformat-commit-graph.txt +++ b/Documentation/gitformat-commit-graph.txt @@ -75,7 +75,7 @@ All multi-byte numbers are in network byte order. ID appears at most once. The CHUNK LOOKUP matches the table of contents from - link:technical/chunk-format.html[the chunk-based file format]. + the chunk-based file format, see linkgit:gitformat-chunk[5] The remaining data in the body is described one chunk at a time, and these chunks may be given in any order. Chunks are required unless diff --git a/Documentation/gitformat-index.txt b/Documentation/gitformat-index.txt index 41491d2a07..5f3ed10d2d 100644 --- a/Documentation/gitformat-index.txt +++ b/Documentation/gitformat-index.txt @@ -141,7 +141,7 @@ Git index format entry is encoded as if the path name for the previous entry is an empty string). At the beginning of an entry, an integer N in the variable width encoding (the same encoding as the offset is encoded - for OFS_DELTA pack entries; see pack-format.txt) is stored, followed + for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed by a NUL-terminated string S. Removing N bytes from the end of the path name for the previous entry, and replacing it with the string S yields the path name for this entry. diff --git a/Documentation/technical/pack-format.txt b/Documentation/gitformat-pack.txt similarity index 95% rename from Documentation/technical/pack-format.txt rename to Documentation/gitformat-pack.txt index b520aa9c45..546c99f887 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/gitformat-pack.txt @@ -1,5 +1,29 @@ -Git pack format -=============== +gitformat-pack(5) +================= + +NAME +---- +gitformat-pack - Git pack format + + +SYNOPSIS +-------- +[verse] +$GIT_DIR/objects/pack/pack-*.{pack,idx} +$GIT_DIR/objects/pack/pack-*.rev +$GIT_DIR/objects/pack/multi-pack-index + +DESCRIPTION +----------- + +The Git pack format is now Git stores most of its primary repository +data. Over the lietime af a repository loose objects (if any) and +smaller packs are consolidated into larger pack(s). See +linkgit:git-gc[1] and linkgit:git-pack-objects[1]. + +The pack format is also used over-the-wire, see +e.g. linkgit:gitprotocol-v2[5], as well as being a part of +other container formats in the case of linkgit:gitformat-bundle[5]. == Checksums and object IDs @@ -356,7 +380,7 @@ CHUNK LOOKUP: using the next chunk position if necessary.) The CHUNK LOOKUP matches the table of contents from - link:technical/chunk-format.html[the chunk-based file format]. + the chunk-based file format, see linkgit:gitformat-chunk[5]. The remaining data in the body is described one chunk at a time, and these chunks may be given in any order. Chunks are required unless @@ -482,3 +506,7 @@ packs arranged in MIDX order (with the preferred pack coming first). The MIDX's reverse index is stored in the optional 'RIDX' chunk within the MIDX itself. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.txt index 8a4de6decd..93b30b8845 100644 --- a/Documentation/gitprotocol-pack.txt +++ b/Documentation/gitprotocol-pack.txt @@ -467,7 +467,7 @@ Now that the client and server have finished negotiation about what the minimal amount of data that needs to be sent to the client is, the server will construct and send the required data in packfile format. -See pack-format.txt for what the packfile itself actually looks like. +See linkgit:gitformat-pack[5] for what the packfile itself actually looks like. If 'side-band' or 'side-band-64k' capabilities have been specified by the client, the server will send the packfile data multiplexed. diff --git a/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.txt index 8994e2559e..5efb4fe81f 100644 --- a/Documentation/howto/recover-corrupted-object-harder.txt +++ b/Documentation/howto/recover-corrupted-object-harder.txt @@ -68,7 +68,7 @@ Note that the "object" file isn't fit for feeding straight to zlib; it has the git packed object header, which is variable-length. We want to strip that off so we can start playing with the zlib data directly. You can either work your way through it manually (the format is described in -link:../technical/pack-format.html[Documentation/technical/pack-format.txt]), +linkgit:gitformat-pack[5]), or you can walk through it in a debugger. I did the latter, creating a valid pack like: diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt index 260224b033..e2ac36dd21 100644 --- a/Documentation/technical/hash-function-transition.txt +++ b/Documentation/technical/hash-function-transition.txt @@ -205,7 +205,7 @@ SHA-1 content. Object storage ~~~~~~~~~~~~~~ Loose objects use zlib compression and packed objects use the packed -format described in Documentation/technical/pack-format.txt, just like +format described in linkgit:gitformat-pack[5], just like today. The content that is compressed and stored uses SHA-256 content instead of SHA-1 content. diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 865074bed4..ca9decdd95 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -3133,7 +3133,7 @@ those "loose" objects. You can save space and make Git faster by moving these loose objects in to a "pack file", which stores a group of objects in an efficient compressed format; the details of how pack files are formatted can be -found in link:technical/pack-format.html[pack format]. +found in link:gitformat-pack[5]. To put the loose objects into a pack, just run git repack: diff --git a/cache.h b/cache.h index ac5ab4ef9d..82755c7c0a 100644 --- a/cache.h +++ b/cache.h @@ -475,8 +475,7 @@ extern struct index_state the_index; /* * Values in this enum (except those outside the 3 bit range) are part - * of pack file format. See Documentation/technical/pack-format.txt - * for more information. + * of pack file format. See gitformat-pack(5) for more information. */ enum object_type { OBJ_BAD = -1, diff --git a/command-list.txt b/command-list.txt index 68212e3c1b..5394eefb6e 100644 --- a/command-list.txt +++ b/command-list.txt @@ -210,8 +210,10 @@ gitdiffcore guide giteveryday guide gitfaq guide gitformat-bundle developerinterfaces +gitformat-chunk developerinterfaces gitformat-commit-graph developerinterfaces gitformat-index developerinterfaces +gitformat-pack developerinterfaces gitformat-signature developerinterfaces gitglossary guide githooks userinterfaces diff --git a/pack-revindex.h b/pack-revindex.h index 74f4eae668..4974e75eb4 100644 --- a/pack-revindex.h +++ b/pack-revindex.h @@ -22,7 +22,7 @@ * * - pack position refers to an object's position within a non-existent pack * described by the MIDX. The pack structure is described in - * Documentation/technical/pack-format.txt. + * gitformat-pack(5). * * It is effectively a concatanation of all packs in the MIDX (ordered by * their numeric ID within the MIDX) in their original order within each From 6b6029dd1d347ce2c83a43afc275c5641b514ab4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Thu, 4 Aug 2022 18:28:40 +0200 Subject: [PATCH 11/12] docs: move cruft pack docs to gitformat-pack MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Integrate the cruft packs documentation initially added in 3d89a8c1180 (Documentation/technical: add cruft-packs.txt, 2022-05-20) to the newly created "gitformat-pack" documentation. Like the "bitmap-format" added before it in 0d4455a3ab0 (documentation: add documentation for the bitmap format, 2013-11-14) the "cruft-packs" were documented in their own file. As the diff move detection will show there is no change to "Documentation/technical/cruft-packs.txt" here except to move it, and to "indent" the existing sections by adding an extra "=" to them. We could similarly convert the "bitmap-format.txt", but let's leave it for now due to a conflict with the in-flight ac/bitmap-lookup-table series. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/Makefile | 1 - Documentation/gitformat-pack.txt | 126 ++++++++++++++++++++++++ Documentation/technical/cruft-packs.txt | 123 ----------------------- 3 files changed, 126 insertions(+), 124 deletions(-) delete mode 100644 Documentation/technical/cruft-packs.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index d4a4a8c8b7..41a070ab59 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -105,7 +105,6 @@ TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches TECH_DOCS += ToolsForGit TECH_DOCS += technical/bitmap-format -TECH_DOCS += technical/cruft-packs TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol TECH_DOCS += technical/long-running-process-protocol diff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt index 546c99f887..e06af02f21 100644 --- a/Documentation/gitformat-pack.txt +++ b/Documentation/gitformat-pack.txt @@ -11,6 +11,7 @@ SYNOPSIS [verse] $GIT_DIR/objects/pack/pack-*.{pack,idx} $GIT_DIR/objects/pack/pack-*.rev +$GIT_DIR/objects/pack/pack-*.mtimes $GIT_DIR/objects/pack/multi-pack-index DESCRIPTION @@ -507,6 +508,131 @@ packs arranged in MIDX order (with the preferred pack coming first). The MIDX's reverse index is stored in the optional 'RIDX' chunk within the MIDX itself. +== cruft packs + +The cruft packs feature offer an alternative to Git's traditional mechanism of +removing unreachable objects. This document provides an overview of Git's +pruning mechanism, and how a cruft pack can be used instead to accomplish the +same. + +=== Background + +To remove unreachable objects from your repository, Git offers `git repack -Ad` +(see linkgit:git-repack[1]). Quoting from the documentation: + +---- +[...] unreachable objects in a previous pack become loose, unpacked objects, +instead of being left in the old pack. [...] loose unreachable objects will be +pruned according to normal expiry rules with the next 'git gc' invocation. +---- + +Unreachable objects aren't removed immediately, since doing so could race with +an incoming push which may reference an object which is about to be deleted. +Instead, those unreachable objects are stored as loose objects and stay that way +until they are older than the expiration window, at which point they are removed +by linkgit:git-prune[1]. + +Git must store these unreachable objects loose in order to keep track of their +per-object mtimes. If these unreachable objects were written into one big pack, +then either freshening that pack (because an object contained within it was +re-written) or creating a new pack of unreachable objects would cause the pack's +mtime to get updated, and the objects within it would never leave the expiration +window. Instead, objects are stored loose in order to keep track of the +individual object mtimes and avoid a situation where all cruft objects are +freshened at once. + +This can lead to undesirable situations when a repository contains many +unreachable objects which have not yet left the grace period. Having large +directories in the shards of `.git/objects` can lead to decreased performance in +the repository. But given enough unreachable objects, this can lead to inode +starvation and degrade the performance of the whole system. Since we +can never pack those objects, these repositories often take up a large amount of +disk space, since we can only zlib compress them, but not store them in delta +chains. + +=== Cruft packs + +A cruft pack eliminates the need for storing unreachable objects in a loose +state by including the per-object mtimes in a separate file alongside a single +pack containing all loose objects. + +A cruft pack is written by `git repack --cruft` when generating a new pack. +linkgit:git-pack-objects[1]'s `--cruft` option. Note that `git repack --cruft` +is a classic all-into-one repack, meaning that everything in the resulting pack is +reachable, and everything else is unreachable. Once written, the `--cruft` +option instructs `git repack` to generate another pack containing only objects +not packed in the previous step (which equates to packing all unreachable +objects together). This progresses as follows: + + 1. Enumerate every object, marking any object which is (a) not contained in a + kept-pack, and (b) whose mtime is within the grace period as a traversal + tip. + + 2. Perform a reachability traversal based on the tips gathered in the previous + step, adding every object along the way to the pack. + + 3. Write the pack out, along with a `.mtimes` file that records the per-object + timestamps. + +This mode is invoked internally by linkgit:git-repack[1] when instructed to +write a cruft pack. Crucially, the set of in-core kept packs is exactly the set +of packs which will not be deleted by the repack; in other words, they contain +all of the repository's reachable objects. + +When a repository already has a cruft pack, `git repack --cruft` typically only +adds objects to it. An exception to this is when `git repack` is given the +`--cruft-expiration` option, which allows the generated cruft pack to omit +expired objects instead of waiting for linkgit:git-gc[1] to expire those objects +later on. + +It is linkgit:git-gc[1] that is typically responsible for removing expired +unreachable objects. + +=== Caution for mixed-version environments + +Repositories that have cruft packs in them will continue to work with any older +version of Git. Note, however, that previous versions of Git which do not +understand the `.mtimes` file will use the cruft pack's mtime as the mtime for +all of the objects in it. In other words, do not expect older (pre-cruft pack) +versions of Git to interpret or even read the contents of the `.mtimes` file. + +Note that having mixed versions of Git GC-ing the same repository can lead to +unreachable objects never being completely pruned. This can happen under the +following circumstances: + + - An older version of Git running GC explodes the contents of an existing + cruft pack loose, using the cruft pack's mtime. + - A newer version running GC collects those loose objects into a cruft pack, + where the .mtime file reflects the loose object's actual mtimes, but the + cruft pack mtime is "now". + +Repeating this process will lead to unreachable objects not getting pruned as a +result of repeatedly resetting the objects' mtimes to the present time. + +If you are GC-ing repositories in a mixed version environment, consider omitting +the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and +leaving the `gc.cruftPacks` configuration unset until all writers understand +cruft packs. + +=== Alternatives + +Notable alternatives to this design include: + + - The location of the per-object mtime data, and + - Storing unreachable objects in multiple cruft packs. + +On the location of mtime data, a new auxiliary file tied to the pack was chosen +to avoid complicating the `.idx` format. If the `.idx` format were ever to gain +support for optional chunks of data, it may make sense to consolidate the +`.mtimes` format into the `.idx` itself. + +Storing unreachable objects among multiple cruft packs (e.g., creating a new +cruft pack during each repacking operation including only unreachable objects +which aren't already stored in an earlier cruft pack) is significantly more +complicated to construct, and so aren't pursued here. The obvious drawback to +the current implementation is that the entire cruft pack must be re-written from +scratch. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/technical/cruft-packs.txt b/Documentation/technical/cruft-packs.txt deleted file mode 100644 index d81f3a8982..0000000000 --- a/Documentation/technical/cruft-packs.txt +++ /dev/null @@ -1,123 +0,0 @@ -= Cruft packs - -The cruft packs feature offer an alternative to Git's traditional mechanism of -removing unreachable objects. This document provides an overview of Git's -pruning mechanism, and how a cruft pack can be used instead to accomplish the -same. - -== Background - -To remove unreachable objects from your repository, Git offers `git repack -Ad` -(see linkgit:git-repack[1]). Quoting from the documentation: - -[quote] -[...] unreachable objects in a previous pack become loose, unpacked objects, -instead of being left in the old pack. [...] loose unreachable objects will be -pruned according to normal expiry rules with the next 'git gc' invocation. - -Unreachable objects aren't removed immediately, since doing so could race with -an incoming push which may reference an object which is about to be deleted. -Instead, those unreachable objects are stored as loose objects and stay that way -until they are older than the expiration window, at which point they are removed -by linkgit:git-prune[1]. - -Git must store these unreachable objects loose in order to keep track of their -per-object mtimes. If these unreachable objects were written into one big pack, -then either freshening that pack (because an object contained within it was -re-written) or creating a new pack of unreachable objects would cause the pack's -mtime to get updated, and the objects within it would never leave the expiration -window. Instead, objects are stored loose in order to keep track of the -individual object mtimes and avoid a situation where all cruft objects are -freshened at once. - -This can lead to undesirable situations when a repository contains many -unreachable objects which have not yet left the grace period. Having large -directories in the shards of `.git/objects` can lead to decreased performance in -the repository. But given enough unreachable objects, this can lead to inode -starvation and degrade the performance of the whole system. Since we -can never pack those objects, these repositories often take up a large amount of -disk space, since we can only zlib compress them, but not store them in delta -chains. - -== Cruft packs - -A cruft pack eliminates the need for storing unreachable objects in a loose -state by including the per-object mtimes in a separate file alongside a single -pack containing all loose objects. - -A cruft pack is written by `git repack --cruft` when generating a new pack. -linkgit:git-pack-objects[1]'s `--cruft` option. Note that `git repack --cruft` -is a classic all-into-one repack, meaning that everything in the resulting pack is -reachable, and everything else is unreachable. Once written, the `--cruft` -option instructs `git repack` to generate another pack containing only objects -not packed in the previous step (which equates to packing all unreachable -objects together). This progresses as follows: - - 1. Enumerate every object, marking any object which is (a) not contained in a - kept-pack, and (b) whose mtime is within the grace period as a traversal - tip. - - 2. Perform a reachability traversal based on the tips gathered in the previous - step, adding every object along the way to the pack. - - 3. Write the pack out, along with a `.mtimes` file that records the per-object - timestamps. - -This mode is invoked internally by linkgit:git-repack[1] when instructed to -write a cruft pack. Crucially, the set of in-core kept packs is exactly the set -of packs which will not be deleted by the repack; in other words, they contain -all of the repository's reachable objects. - -When a repository already has a cruft pack, `git repack --cruft` typically only -adds objects to it. An exception to this is when `git repack` is given the -`--cruft-expiration` option, which allows the generated cruft pack to omit -expired objects instead of waiting for linkgit:git-gc[1] to expire those objects -later on. - -It is linkgit:git-gc[1] that is typically responsible for removing expired -unreachable objects. - -== Caution for mixed-version environments - -Repositories that have cruft packs in them will continue to work with any older -version of Git. Note, however, that previous versions of Git which do not -understand the `.mtimes` file will use the cruft pack's mtime as the mtime for -all of the objects in it. In other words, do not expect older (pre-cruft pack) -versions of Git to interpret or even read the contents of the `.mtimes` file. - -Note that having mixed versions of Git GC-ing the same repository can lead to -unreachable objects never being completely pruned. This can happen under the -following circumstances: - - - An older version of Git running GC explodes the contents of an existing - cruft pack loose, using the cruft pack's mtime. - - A newer version running GC collects those loose objects into a cruft pack, - where the .mtime file reflects the loose object's actual mtimes, but the - cruft pack mtime is "now". - -Repeating this process will lead to unreachable objects not getting pruned as a -result of repeatedly resetting the objects' mtimes to the present time. - -If you are GC-ing repositories in a mixed version environment, consider omitting -the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and -leaving the `gc.cruftPacks` configuration unset until all writers understand -cruft packs. - -== Alternatives - -Notable alternatives to this design include: - - - The location of the per-object mtime data, and - - Storing unreachable objects in multiple cruft packs. - -On the location of mtime data, a new auxiliary file tied to the pack was chosen -to avoid complicating the `.idx` format. If the `.idx` format were ever to gain -support for optional chunks of data, it may make sense to consolidate the -`.mtimes` format into the `.idx` itself. - -Storing unreachable objects among multiple cruft packs (e.g., creating a new -cruft pack during each repacking operation including only unreachable objects -which aren't already stored in an earlier cruft pack) is significantly more -complicated to construct, and so aren't pursued here. The obvious drawback to -the current implementation is that the entire cruft pack must be re-written from -scratch. From 1e2320161d27684205f55ffa91f7f481d32863d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Thu, 4 Aug 2022 18:28:41 +0200 Subject: [PATCH 12/12] docs: move http-protocol docs to man section 5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space by moving the http-protocol.txt documentation over. I'm renaming it to "protocol-http" to be consistent with other things in the new gitformat-protocol-* namespace. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/Makefile | 2 +- Documentation/git-upload-pack.txt | 6 ++-- ...http-protocol.txt => gitprotocol-http.txt} | 29 ++++++++++++++++--- Documentation/gitprotocol-pack.txt | 2 +- Documentation/gitprotocol-v2.txt | 4 +-- command-list.txt | 1 + 6 files changed, 33 insertions(+), 11 deletions(-) rename Documentation/{technical/http-protocol.txt => gitprotocol-http.txt} (98%) diff --git a/Documentation/Makefile b/Documentation/Makefile index 41a070ab59..346bbcf8be 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -36,6 +36,7 @@ MAN5_TXT += gitmailmap.txt MAN5_TXT += gitmodules.txt MAN5_TXT += gitprotocol-capabilities.txt MAN5_TXT += gitprotocol-common.txt +MAN5_TXT += gitprotocol-http.txt MAN5_TXT += gitprotocol-pack.txt MAN5_TXT += gitprotocol-v2.txt MAN5_TXT += gitrepository-layout.txt @@ -106,7 +107,6 @@ TECH_DOCS += SubmittingPatches TECH_DOCS += ToolsForGit TECH_DOCS += technical/bitmap-format TECH_DOCS += technical/hash-function-transition -TECH_DOCS += technical/http-protocol TECH_DOCS += technical/long-running-process-protocol TECH_DOCS += technical/multi-pack-index TECH_DOCS += technical/pack-heuristics diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 3409e0d36d..3f89d64077 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -39,9 +39,9 @@ OPTIONS --http-backend-info-refs:: Used by linkgit:git-http-backend[1] to serve up `$GIT_URL/info/refs?service=git-upload-pack` requests. See - "Smart Clients" in link:technical/http-protocol.html[the HTTP - transfer protocols] documentation and "HTTP Transport" in the - linkgit:gitprotocol-v2[5] documentation. Also understood by + "Smart Clients" in linkgit:gitprotocol-http[5] and "HTTP + Transport" in in the linkgit:gitprotocol-v2[5] + documentation. Also understood by linkgit:git-receive-pack[1]. :: diff --git a/Documentation/technical/http-protocol.txt b/Documentation/gitprotocol-http.txt similarity index 98% rename from Documentation/technical/http-protocol.txt rename to Documentation/gitprotocol-http.txt index 8bd672d55b..ccc13f0a40 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/gitprotocol-http.txt @@ -1,5 +1,19 @@ -HTTP transfer protocols -======================= +gitprotocol-http(5) +=================== + +NAME +---- +gitprotocol-http - Git HTTP-based protocols + + +SYNOPSIS +-------- +[verse] + + + +DESCRIPTION +----------- Git supports two HTTP based transfer protocols. A "dumb" protocol which requires only a standard HTTP server on the server end of the @@ -512,11 +526,18 @@ the id obtained through ref discovery as old_id. TODO: Document this further. - -References +REFERENCES ---------- http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)] http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1] + +SEE ALSO +-------- + linkgit:gitprotocol-pack[5] linkgit:gitprotocol-capabilities[5] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.txt index 93b30b8845..dd4108b7a3 100644 --- a/Documentation/gitprotocol-pack.txt +++ b/Documentation/gitprotocol-pack.txt @@ -17,7 +17,7 @@ Git supports transferring data in packfiles over the ssh://, git://, http:// and file:// transports. There exist two sets of protocols, one for pushing data from a client to a server and another for fetching data from a server to a client. The three transports (ssh, git, file) use the same -protocol to transfer data. http is documented in http-protocol.txt. +protocol to transfer data. http is documented in linkgit:gitprotocol-http[5]. The processes invoked in the canonical Git implementation are 'upload-pack' on the server side and 'fetch-pack' on the client side for fetching data; diff --git a/Documentation/gitprotocol-v2.txt b/Documentation/gitprotocol-v2.txt index d6105e0740..c9c0f9160b 100644 --- a/Documentation/gitprotocol-v2.txt +++ b/Documentation/gitprotocol-v2.txt @@ -53,7 +53,7 @@ Initial Client Request In general a client can request to speak protocol v2 by sending `version=2` through the respective side-channel for the transport being used which inevitably sets `GIT_PROTOCOL`. More information can be -found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the +found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the `GIT_PROTOCOL` definition in `git.txt`. In all cases the response from the server is the capability advertisement. @@ -77,7 +77,7 @@ HTTP Transport ~~~~~~~~~~~~~~ When using the http:// or https:// transport a client makes a "smart" -info/refs request as described in `http-protocol.txt` and requests that +info/refs request as described in linkgit:gitprotocol-http[5] and requests that v2 be used by supplying "version=2" in the `Git-Protocol` header. C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0 diff --git a/command-list.txt b/command-list.txt index 5394eefb6e..f96bdabd7d 100644 --- a/command-list.txt +++ b/command-list.txt @@ -224,6 +224,7 @@ gitmodules userinterfaces gitnamespaces guide gitprotocol-capabilities developerinterfaces gitprotocol-common developerinterfaces +gitprotocol-http developerinterfaces gitprotocol-pack developerinterfaces gitprotocol-v2 developerinterfaces gitremote-helpers guide