From patchwork Mon Jul 18 13:29:27 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= X-Patchwork-Id: 12921276 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 11D13CCA47F for ; Mon, 18 Jul 2022 13:29:48 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233484AbiGRN3q (ORCPT ); Mon, 18 Jul 2022 09:29:46 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53934 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233360AbiGRN3n (ORCPT ); Mon, 18 Jul 2022 09:29:43 -0400 Received: from mail-wr1-x42a.google.com (mail-wr1-x42a.google.com [IPv6:2a00:1450:4864:20::42a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 93CA962FB for ; Mon, 18 Jul 2022 06:29:42 -0700 (PDT) Received: by mail-wr1-x42a.google.com with SMTP id v16so1225514wrr.6 for ; Mon, 18 Jul 2022 06:29:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=++pjL6Wqrgp5T8LlIQOVb+SeF+nGGYMuS4FNlnr5Gbs=; b=lxVY9gG3/jiWamwFPCVgHtJdt9+a57tayo/igU7lXe4tztbW5yDJEFXz4T/efyl5FE cdCWw3tYSX7/JexHP3LyJK0inCsqd4TICk7VWQgQ39W7vCCyI15F1E8Q2RQxqc4pbwWq rIEheWUEjMb0LjJ8QvFs3WQmnPeNoxKcwvKM4IadVmpigvUSpK1r8nUf48B4P/nUJa/0 XR3mwaF1OLCDkdZLbmVPri+3i/k0i3Ibp7seFTtP/IMcqzlLgtQ7Ztg+991mjeuspXet gQ0S2f8uMNPnR+kRRFXEoWgjBilGJTcu3dcz5e5/g9ZGRwWxYM7ormuJCBLKroKVXMXo om6A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=++pjL6Wqrgp5T8LlIQOVb+SeF+nGGYMuS4FNlnr5Gbs=; b=po/mMC13VOPIIasj3Vju4/Q02e227J4U2KYQIS28DN8bse5wTPlE3E2aos6kj2OctB 3H4OsH/bsYDh+tO1+qIgoQCdr2vlIJbHOn0uLE3J26p6K+z48HWUzFJy5suqM28Qbdry bMUQzAiFEkiF4iqsnQ2N0Mio03PBwYn/SnyKqR+Keg72lfDAxXSr2XcldarJ7zfgEcPJ gE0d+61kxUnKII2OZPGktUqJwDsFZrUDjnEfTbRp0326MdjH9ptswxbeanyNQLB/zTKx aVqyGGtHpyDLD9EavJ/iXkNenN3ctfdH2nEC7QxgjZkQ74I9FXOEGTXdLqHsF89baAE3 /5Wg== X-Gm-Message-State: AJIora8Mwbr/3NStoVYqkrXtoNKQ+Db+yxLj30uhMUX4F+hP4cp1hDXq wqS8EVEkIyLNM6D5t8El2/QZcbb0Tj8esA== X-Google-Smtp-Source: AGRyM1vIjAEcO80YGYMAeNxxn8gkcyjFRfYe7bn/zcSBlQg7YBLpCrqe841lajhvSSY/IEeQt14MMQ== X-Received: by 2002:a05:6000:1883:b0:205:c0cb:33c6 with SMTP id a3-20020a056000188300b00205c0cb33c6mr23736363wri.39.1658150980769; Mon, 18 Jul 2022 06:29:40 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id p4-20020a1c5444000000b003a30572072esm14277296wmi.6.2022.07.18.06.29.39 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Jul 2022 06:29:39 -0700 (PDT) From: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= To: git@vger.kernel.org Cc: Junio C Hamano , Eric Sunshine , Philippe Blain , Derrick Stolee , Taylor Blau , Jeff King , Teng Long , =?utf-8?b?w4Z2?= =?utf-8?b?YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= Subject: [PATCH v4 1/8] help.c: BUG() out if "help --guides" can't remove "git" prefixes Date: Mon, 18 Jul 2022 15:29:27 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1032.gb00b5447790 In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Adjust code added in 929d9192828 (git docs: split "User-facing file formats" off from "Guides", 2021-06-04) to be more strict about the prefix trimming of the "guides" category. There are no guides in the command-list.txt that don't start with "git", and we're unlikely to ever add any, if we do we can remove this BUG() invocation, but in the meantime this makes the intent more clear. 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 --- help.c | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/help.c b/help.c index 41c41c2aa11..24ac50f62fe 100644 --- a/help.c +++ b/help.c @@ -47,10 +47,14 @@ static const char *drop_prefix(const char *name, uint32_t category) 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: + if (!skip_prefix(name, "git", &new_name)) + BUG("category #%d but no 'git' prefix?", category); return new_name; + } return name; - } static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask) From patchwork Mon Jul 18 13:29:28 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= X-Patchwork-Id: 12921277 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 8A2CAC43334 for ; Mon, 18 Jul 2022 13:29:53 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233634AbiGRN3w (ORCPT ); Mon, 18 Jul 2022 09:29:52 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54002 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233360AbiGRN3s (ORCPT ); Mon, 18 Jul 2022 09:29:48 -0400 Received: from mail-wm1-x32b.google.com (mail-wm1-x32b.google.com [IPv6:2a00:1450:4864:20::32b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 0EA76C06 for ; Mon, 18 Jul 2022 06:29:44 -0700 (PDT) Received: by mail-wm1-x32b.google.com with SMTP id b6so6606095wmq.5 for ; Mon, 18 Jul 2022 06:29:43 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=mDMgFH3L/sNKi9IWgbx8mP1scbZWxEOoRW7DJ+GwyQ4=; b=Puv4UVe47wlj+CyRZYxyHl4PhcyqTQkiEq+TduMeXMXCFNNXnHDR79AHOvY8iBuxsP wW/Y+pYY1icVh6J9e+Zuf5b8N7Ht7PVqTbzeuC2QQFmYGlpxjh59f7d/4ixOOSULk52D 4Y2EQsk7BUSFTshF5PqETv1/bmSNkeEsRG4mJC7PrXA4SnvFT8ZSshC5hdwKygIsrydi bsTM8quJz4vFQ+6dK3XlemMXvAcJr6kzPvHR4hS1N1Vxpdu2tJuGpqRuBUrWNs/Rzk/j M5jLmVq/6GwGAC/FLtOojqzmJR6Og2S5qY03egKQdlu3i91QgcUEc1yO7qEO5R/hsiRB T2mQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=mDMgFH3L/sNKi9IWgbx8mP1scbZWxEOoRW7DJ+GwyQ4=; b=bd6C+QP5HIRZan4x7H7k3P6P37ABQ+4cbTvCSzpAf9I1qTy5KeigO4I/6YerGqg10I tbvOwLmrBBwZjCM/XTa1EnAnIzUuL9A90m+jAv1Asf9qZMSVN9IgxhjAUaFNyUvVjSg9 v02ZIdQ501esBRFeSyxnst2Ft6YGMeXyTwq19dOzFI1OtZkt6d5DD/m6M7Gah0NRQ6L5 lgIOaIpVXd9CGKfkV7I82Hi/N/6lYPrIQXWa4ryFMWnEozkSfDaZX4ogxTb+l5dBC3xr 6h0nlV95dwOGO7yaRNKWbJLUuzvfdtkOxqOj/X8umHXsVhHxkk2MeNtZW3M7MlMiQ/uc avmw== X-Gm-Message-State: AJIora+oNNNiN1SpvhKL0tiKMfNTxP8zZNtAiGrSQnj785BHTdtrMzGs 48c9Nyiy9VeQLDG63U7REfIoHbcme84RGA== X-Google-Smtp-Source: AGRyM1tk1BEwkV7S0VHGBH4510fxU01Xj2dk135Mxa8V7qu0yoduJDIO/C793CrTWIuDMrC+S/AshA== X-Received: by 2002:a1c:4c0f:0:b0:3a3:1401:7660 with SMTP id z15-20020a1c4c0f000000b003a314017660mr9871354wmf.8.1658150982038; Mon, 18 Jul 2022 06:29:42 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id p4-20020a1c5444000000b003a30572072esm14277296wmi.6.2022.07.18.06.29.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Jul 2022 06:29:41 -0700 (PDT) From: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= To: git@vger.kernel.org Cc: Junio C Hamano , Eric Sunshine , Philippe Blain , Derrick Stolee , Taylor Blau , Jeff King , Teng Long , =?utf-8?b?w4Z2?= =?utf-8?b?YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= Subject: [PATCH v4 2/8] git docs: split "User-facing file formats" off from "Guides" Date: Mon, 18 Jul 2022 15:29:28 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1032.gb00b5447790 In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Create a new "User-facing file formats" section in the main "git help git" manual page. The "Guides" section was added to the manual page in f442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense to list all that documentation. But placing e.g. "gitignore(5)" in it is stretching the meaning of what a "guide" is, ideally that section should list things similar to "giteveryday(7)" and "gitcore-tutorial(7)". We take a wide view of what's considered a "user format", it's not just a file format, but e.g. githooks(5) also belongs, since the layout of the ".git/hooks/" and the placement of hooks in it is something the user might be expected to interact with. Signed-off-by: Ævar Arnfjörð Bjarmason --- Documentation/Makefile | 1 + Documentation/git-help.txt | 13 +++++++++---- Documentation/git.txt | 7 +++++++ Makefile | 1 + builtin/help.c | 10 +++++++++- command-list.txt | 16 ++++++++++------ help.c | 12 ++++++++++++ help.h | 1 + t/t0012-help.sh | 12 +++++++++++- 9 files changed, 61 insertions(+), 12 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 4f801f4e4c9..08b896a3c4c 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ cmds-synchingrepositories.txt \ cmds-synchelpers.txt \ cmds-guide.txt \ + cmds-userformats.txt \ cmds-purehelpers.txt \ cmds-foreignscminterface.txt diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 239c68db457..6c285709040 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -9,14 +9,15 @@ SYNOPSIS -------- [verse] 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases] -'git help' [[-i|--info] [-m|--man] [-w|--web]] [|] +'git help' [[-i|--info] [-m|--man] [-w|--web]] [||] 'git help' [-g|--guides] 'git help' [-c|--config] +'git help' [--user-formats] 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 +27,8 @@ printed on the standard output. If the option `--guides` or `-g` is given, a list of the Git concept guides is also printed on the standard output. -If a command, or a guide, is given, a manual page for that command or -guide is brought up. The 'man' program is used by default for this +If a command or other documentation is given, the relevant manual page +will be brought up. The 'man' program is used by default for this purpose, but this can be overridden by other options or configuration variables. @@ -69,6 +70,10 @@ OPTIONS --guides:: Prints a list of the Git concept guides on the standard output. +--user-formats:: + Prints a list of the Git user-facing format documentation on + the standard output. + -i:: --info:: Display manual page for the command in the 'info' format. The diff --git a/Documentation/git.txt b/Documentation/git.txt index 302607a4967..9b03bbc3851 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -339,6 +339,13 @@ The following documentation pages are guides about Git concepts. include::cmds-guide.txt[] +User-facing file formats +------------------------ + +This documentation discusses file formats that users are expected to +edit. These can also be listed with 'git help --user-formats'. + +include::cmds-userformats.txt[] Configuration Mechanism ----------------------- diff --git a/Makefile b/Makefile index 04d0fd1fe60..e24db1d52e2 100644 --- a/Makefile +++ b/Makefile @@ -3489,6 +3489,7 @@ check-docs:: sed -e '1,/^### command list/d' \ -e '/^#/d' \ -e '/guide$$/d' \ + -e '/formats$$/d' \ -e 's/[ ].*//' \ -e 's/^/listed /' command-list.txt; \ $(MAKE) -C Documentation print-man1 | \ diff --git a/builtin/help.c b/builtin/help.c index 222f994f863..b0164b774c2 100644 --- a/builtin/help.c +++ b/builtin/help.c @@ -43,6 +43,7 @@ static enum help_action { HELP_ACTION_ALL = 1, HELP_ACTION_GUIDES, HELP_ACTION_CONFIG, + HELP_ACTION_USER_FORMATS, HELP_ACTION_CONFIG_FOR_COMPLETION, HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION, } cmd_mode; @@ -69,6 +70,8 @@ static struct option builtin_help_options[] = { OPT_CMDMODE('g', "guides", &cmd_mode, N_("print list of useful guides"), HELP_ACTION_GUIDES), + OPT_CMDMODE(0, "user-formats", &cmd_mode, N_("print list of user-facing file formats"), + HELP_ACTION_USER_FORMATS), OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"), HELP_ACTION_CONFIG), OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "", @@ -81,9 +84,10 @@ static struct option builtin_help_options[] = { static const char * const builtin_help_usage[] = { "git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]", - N_("git help [[-i|--info] [-m|--man] [-w|--web]] []"), + N_("git help [[-i|--info] [-m|--man] [-w|--web]] [|]"), "git help [-g|--guides]", "git help [-c|--config]", + "git help [--user-formats]", NULL }; @@ -654,6 +658,10 @@ int cmd_help(int argc, const char **argv, const char *prefix) opt_mode_usage(argc, "--config-for-completion", help_format); list_config_help(SHOW_CONFIG_VARS); return 0; + case HELP_ACTION_USER_FORMATS: + opt_mode_usage(argc, "--user-formats", help_format); + list_user_formats_help(); + return 0; case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION: opt_mode_usage(argc, "--config-sections-for-completion", help_format); diff --git a/command-list.txt b/command-list.txt index 9bd6f3c48f4..c1eace8f7ad 100644 --- a/command-list.txt +++ b/command-list.txt @@ -43,6 +43,10 @@ # specified here, which can only have "guide" attribute and nothing # else. # +# User-facing file formats such as documentation for the .gitmodules, +# .mailmap etc. files lives in man section 5. These entries can only +# have the "userformats" attribute and nothing else. +# ### command list (do not change this line) # command name category [category] [category] git-add mainporcelain worktree @@ -192,7 +196,7 @@ git-verify-tag ancillaryinterrogators git-whatchanged ancillaryinterrogators complete git-worktree mainporcelain git-write-tree plumbingmanipulators -gitattributes guide +gitattributes userformats gitcli guide gitcore-tutorial guide gitcredentials guide @@ -201,14 +205,14 @@ gitdiffcore guide giteveryday guide gitfaq guide gitglossary guide -githooks guide -gitignore guide +githooks userformats +gitignore userformats gitk mainporcelain -gitmailmap guide -gitmodules guide +gitmailmap userformats +gitmodules userformats gitnamespaces guide gitremote-helpers guide -gitrepository-layout guide +gitrepository-layout userformats gitrevisions guide gitsubmodules guide gittutorial guide diff --git a/help.c b/help.c index 24ac50f62fe..17ba210cf4e 100644 --- a/help.c +++ b/help.c @@ -38,6 +38,7 @@ static struct category_description main_categories[] = { { CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") }, { CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") }, { CAT_purehelpers, N_("Low-level Commands / Internal Helpers") }, + { CAT_userformats, N_("Git user-facing file formats") }, { 0, NULL } }; @@ -50,6 +51,7 @@ static const char *drop_prefix(const char *name, uint32_t category) switch (category) { case CAT_guide: + case CAT_userformats: if (!skip_prefix(name, "git", &new_name)) BUG("category #%d but no 'git' prefix?", category); return new_name; @@ -430,6 +432,16 @@ void list_guides_help(void) putchar('\n'); } +void list_user_formats_help(void) +{ + struct category_description catdesc[] = { + { CAT_userformats, N_("Git user-facing file formats:") }, + { 0, NULL } + }; + print_cmd_by_category(catdesc, NULL); + putchar('\n'); +} + static int get_alias(const char *var, const char *value, void *data) { struct string_list *list = data; diff --git a/help.h b/help.h index 971a3ad855a..d8b744178ec 100644 --- a/help.h +++ b/help.h @@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num) void list_common_cmds_help(void); void list_all_cmds_help(int show_external_commands, int show_aliases); void list_guides_help(void); +void list_user_formats_help(void); void list_all_main_cmds(struct string_list *list); void list_all_other_cmds(struct string_list *list); diff --git a/t/t0012-help.sh b/t/t0012-help.sh index 6c33a436901..91b5318aa32 100755 --- a/t/t0012-help.sh +++ b/t/t0012-help.sh @@ -44,6 +44,8 @@ test_expect_success 'invalid usage' ' test_expect_code 129 git help -g add && test_expect_code 129 git help -a -g && + test_expect_code 129 git help --user-formats add && + test_expect_code 129 git help -g -c && test_expect_code 129 git help --config-for-completion add && test_expect_code 129 git help --config-sections-for-completion add @@ -104,9 +106,9 @@ test_expect_success 'git help' ' test_i18ngrep "^ commit " help.output && test_i18ngrep "^ fetch " help.output ' + test_expect_success 'git help -g' ' git help -g >help.output && - test_i18ngrep "^ attributes " help.output && test_i18ngrep "^ everyday " help.output && test_i18ngrep "^ tutorial " help.output ' @@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' ' test_cmp expect test-browser.log ' +test_expect_success 'git help --user-formats' ' + git help --user-formats >help.output && + grep "^ attributes " help.output && + grep "^ mailmap " help.output +' + test_expect_success 'git help -c' ' git help -c >help.output && cat >expect <<-\EOF && @@ -220,6 +228,8 @@ test_expect_success "'git help -a' section spacing" ' Low-level Commands / Syncing Repositories Low-level Commands / Internal Helpers + + Git user-facing file formats EOF test_cmp expect actual ' From patchwork Mon Jul 18 13:29:29 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= X-Patchwork-Id: 12921278 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 98478C433EF for ; Mon, 18 Jul 2022 13:29:55 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233666AbiGRN3x (ORCPT ); Mon, 18 Jul 2022 09:29:53 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54048 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233534AbiGRN3u (ORCPT ); Mon, 18 Jul 2022 09:29:50 -0400 Received: from mail-wm1-x32f.google.com (mail-wm1-x32f.google.com [IPv6:2a00:1450:4864:20::32f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 4CB8862FB for ; Mon, 18 Jul 2022 06:29:45 -0700 (PDT) Received: by mail-wm1-x32f.google.com with SMTP id h14-20020a1ccc0e000000b0039eff745c53so7328742wmb.5 for ; Mon, 18 Jul 2022 06:29:45 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=M/gPwoaJvB4ssiaKk+eXfds43JjO9a6Rjv/bxCZmoMI=; b=BD3IVpSIyPpTtbdAVhsNk3oXBZNgMaLZUyovJEKvE7pOb1L5OtOZ3JewiPvlPGQpEq nx1Z+qhxApQW3ug9AZgCcvTIf7Wg8j7uzRqPH0BNynxm5DIWa6IXb/5AkNizwJSSdS46 V4CzcOwtJedTghd6wMvZLKtkpQaB+36SELq8q303/XWb5b5aNHYcaq3nO4k6PJCbfmq6 eJvhjUC1U1cWNgg8fvhQBKKjCvImxAWMXSIDpK4V6JFZ6bj/2myZKlDXHX06EeXyYN4w ioFdgWPCojKdml54R+R+qm3dPm4Cr3Y268P5RcfuqK7UVi7LibN0RG/FnpGnnqxs4zWc CRxg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=M/gPwoaJvB4ssiaKk+eXfds43JjO9a6Rjv/bxCZmoMI=; b=dJaRe+KpQMv/oeEb65s0PItwqjQBOySbulm7tEjXwdC965EPWwZbL7+/ae3MG7MWMv V4X7h3conksOf3G/ChWvRNaEWmNdtW9UHxneWICSJbgB8LLfFa0nc1JARCLk/yPPwvx4 FYizXnECjP2tPTuAM0IoWFiSvZyiJq51cOxkzJia3R17zb1HGdGc9K+sXdskvyz96MIT klmwcQzKGRg9GSm0GMs02FmpWed+ho7YrUgFrJH9W6VbxLTpHO/c0okJGahMskJhkekJ grq5WHPqXLyOwbK3EDybBAEfxkj0cTU7iJ2khkb29xhpYuV+dfeokPq/sGFWqx7L9HXn PpqA== X-Gm-Message-State: AJIora+4VvYjS/sHCBnflT1bsHWUTWqvmOHIKZbpkdU7LTdVF/D6L8/Q U28+U+wJbis5SZnElgc/2uOyZpSRK9F1Ng== X-Google-Smtp-Source: AGRyM1tlvxSREEiOUkjfeeF1miCdKWxg5hzJWNljVh6Q71n78aXcozoGCVkwiiQFyzsrLqKeyBvoWQ== X-Received: by 2002:a05:600c:3542:b0:3a1:6855:1153 with SMTP id i2-20020a05600c354200b003a168551153mr26751422wmq.121.1658150983355; Mon, 18 Jul 2022 06:29:43 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id p4-20020a1c5444000000b003a30572072esm14277296wmi.6.2022.07.18.06.29.42 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Jul 2022 06:29:42 -0700 (PDT) From: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= To: git@vger.kernel.org Cc: Junio C Hamano , Eric Sunshine , Philippe Blain , Derrick Stolee , Taylor Blau , Jeff King , Teng Long , =?utf-8?b?w4Z2?= =?utf-8?b?YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= Subject: [PATCH v4 3/8] git docs: create a "Git file formats and protocols" section Date: Mon, 18 Jul 2022 15:29:29 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1032.gb00b5447790 In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Create a new "Git file formats and protocols" 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 compliments the newly added and adjacent "User-facing file formats" 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 --- Documentation/Makefile | 3 +- Documentation/git-bundle.txt | 12 +++-- Documentation/git-help.txt | 1 + Documentation/git.txt | 8 ++++ ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++--- Documentation/lint-man-section-order.perl | 3 ++ builtin/help.c | 8 ++++ command-list.txt | 5 +++ help.c | 12 +++++ help.h | 1 + t/t0012-help.sh | 2 + 11 files changed, 87 insertions(+), 12 deletions(-) rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%) diff --git a/Documentation/Makefile b/Documentation/Makefile index 08b896a3c4c..404139274e7 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 @@ -291,6 +291,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ cmds-synchelpers.txt \ cmds-guide.txt \ cmds-userformats.txt \ + cmds-gitformats.txt \ cmds-purehelpers.txt \ cmds-foreignscminterface.txt diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 7685b570455..1aeae09f082 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 ------- @@ -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 6c285709040..a91126ba802 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-formats] +'git help' [--git-formats] DESCRIPTION ----------- diff --git a/Documentation/git.txt b/Documentation/git.txt index 9b03bbc3851..1980a0e29cd 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -347,6 +347,14 @@ edit. These can also be listed with 'git help --user-formats'. include::cmds-userformats.txt[] +Git file formats and protocols +------------------------------ + +This documentation discusses the file formats and protocols that git +itself uses. These can also be listed with 'git help --git-formats'. + +include::cmds-gitformats.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 b9be8644cf5..6a9d9e5bf6f 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 + + +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. -== 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 425377dfeb7..02408a0062f 100755 --- a/Documentation/lint-man-section-order.perl +++ b/Documentation/lint-man-section-order.perl @@ -32,6 +32,9 @@ 'SEE ALSO' => { order => $order++, }, + 'FILE FORMAT' => { + order => $order++, + }, 'GIT' => { required => 1, order => $order++, diff --git a/builtin/help.c b/builtin/help.c index b0164b774c2..3ff2c5d17a7 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_FORMATS, + HELP_ACTION_GIT_FORMATS, HELP_ACTION_CONFIG_FOR_COMPLETION, HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION, } cmd_mode; @@ -72,6 +73,8 @@ static struct option builtin_help_options[] = { HELP_ACTION_GUIDES), OPT_CMDMODE(0, "user-formats", &cmd_mode, N_("print list of user-facing file formats"), HELP_ACTION_USER_FORMATS), + OPT_CMDMODE(0, "git-formats", &cmd_mode, N_("print list of internal file formats and network protocols"), + HELP_ACTION_GIT_FORMATS), OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"), HELP_ACTION_CONFIG), OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "", @@ -88,6 +91,7 @@ static const char * const builtin_help_usage[] = { "git help [-g|--guides]", "git help [-c|--config]", "git help [--user-formats]", + "git help [--git-formats]", NULL }; @@ -662,6 +666,10 @@ int cmd_help(int argc, const char **argv, const char *prefix) opt_mode_usage(argc, "--user-formats", help_format); list_user_formats_help(); return 0; + case HELP_ACTION_GIT_FORMATS: + opt_mode_usage(argc, "--git-formats", help_format); + list_git_formats_help(); + return 0; case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION: opt_mode_usage(argc, "--config-sections-for-completion", help_format); diff --git a/command-list.txt b/command-list.txt index c1eace8f7ad..1794a7279bc 100644 --- a/command-list.txt +++ b/command-list.txt @@ -47,6 +47,10 @@ # .mailmap etc. files lives in man section 5. These entries can only # have the "userformats" attribute and nothing else. # +# Git internal file formats and protocols, such as documentation for the +# *.bundle format lives in man section 5. These entries can only have +# the "gitformats" attribute and nothing else. +# ### command list (do not change this line) # command name category [category] [category] git-add mainporcelain worktree @@ -204,6 +208,7 @@ gitcvs-migration guide gitdiffcore guide giteveryday guide gitfaq guide +gitformat-bundle gitformats gitglossary guide githooks userformats gitignore userformats diff --git a/help.c b/help.c index 17ba210cf4e..68b1dc70aff 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_userformats, N_("Git user-facing file formats") }, + { CAT_gitformats, N_("Git internal file formats and protocols") }, { 0, NULL } }; @@ -52,6 +53,7 @@ static const char *drop_prefix(const char *name, uint32_t category) { case CAT_guide: case CAT_userformats: + case CAT_gitformats: if (!skip_prefix(name, "git", &new_name)) BUG("category #%d but no 'git' prefix?", category); return new_name; @@ -442,6 +444,16 @@ void list_user_formats_help(void) putchar('\n'); } +void list_git_formats_help(void) +{ + struct category_description catdesc[] = { + { CAT_gitformats, N_("Internal file formats and protocols:") }, + { 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 d8b744178ec..173bd890ce3 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_formats_help(void); +void list_git_formats_help(void); void list_all_main_cmds(struct string_list *list); void list_all_other_cmds(struct string_list *list); diff --git a/t/t0012-help.sh b/t/t0012-help.sh index 91b5318aa32..0e291cb91e8 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 Git user-facing file formats + + Git internal file formats and protocols EOF test_cmp expect actual ' From patchwork Mon Jul 18 13:29:30 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= X-Patchwork-Id: 12921279 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id C349BC43334 for ; Mon, 18 Jul 2022 13:29:56 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233776AbiGRN3z (ORCPT ); Mon, 18 Jul 2022 09:29:55 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54124 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233610AbiGRN3v (ORCPT ); Mon, 18 Jul 2022 09:29:51 -0400 Received: from mail-wr1-x429.google.com (mail-wr1-x429.google.com [IPv6:2a00:1450:4864:20::429]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8FAF3DF76 for ; Mon, 18 Jul 2022 06:29:46 -0700 (PDT) Received: by mail-wr1-x429.google.com with SMTP id a5so17024615wrx.12 for ; Mon, 18 Jul 2022 06:29:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=cxGGwbNa3SdI8jfI7yQVlvW+bNDgr6xD71NqfIfk8gg=; b=PdmQ7AwLCpBUZisUvlWAQmbKD2E8/ay+SdP82l2CJUXEDh37SAbGn3o/z+FutwejR2 6IMbUj933y8QwNpEwiVWq65jLXCgru1OYapozzH8cpQzNftRTm3hVjf+QLKMNq39a7VO wmaIWF8Cl00zkgiFsn25M2EaYgRkE62YzukFg2cu7DoiII9E2PrJGNens0ijmHuldcp4 PduLPifoTMZWTKavl/FoP7NJHcUcLxhDWvPHM5AaD9BDCcg7O5W41RCnZtdcBBvH3ns+ KyCNxwLE4V/8mKdp07MSIQmG/W5NwXOzB8K/ZSUaW0Av9EXJMgd1svNz+30SWhL/L4kh ilgg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=cxGGwbNa3SdI8jfI7yQVlvW+bNDgr6xD71NqfIfk8gg=; b=uWGk20GVp8x1Ej5q2e70tzInkKeAnML4hPbq/NOCM576Yq8Ngg09aZumT3j/4OtjMu hTsCLdxXZvfHsxb7ixs/LLka4zmEqSrOSD63PmIJkfINymNUrwesF7R9sbuEW9CNxXdy ijuLQTNyJSwTzUutMPgW0DKWz9KtPijKBf1rpCmJnZ79ypUOG0K8j+LNo/3DLqw7M/Mz pKhK0lJNqFzeZlchE/qryvmnlW/e0YBr44+qTj4ouPtkKNAGj7tB/mFkbXLOZQ1s5UB8 FUm4lU+JXmY4aqU/k38gNwAjOie1rKsJxJC323WDVf89kgzLmg3rmSwyvpXDAC7Ad2yH tP2A== X-Gm-Message-State: AJIora/1KQnOu/l1TbcHSdZCfNvm2k+zRbGhBTu9QwFHX9yzsuBtqNEj JERbiybsyO+3mZ0B18GaKTGxLmLScL/fOg== X-Google-Smtp-Source: AGRyM1sjuUKkXxHbHBT42JKJSr4gHQuVqAUn+n+SmotzjgPcPRXZBzbhzUbGxinKX5LyawJ31ZL7jg== X-Received: by 2002:adf:efcf:0:b0:21d:944c:9248 with SMTP id i15-20020adfefcf000000b0021d944c9248mr23230933wrp.382.1658150984545; Mon, 18 Jul 2022 06:29:44 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id p4-20020a1c5444000000b003a30572072esm14277296wmi.6.2022.07.18.06.29.43 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Jul 2022 06:29:43 -0700 (PDT) From: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= To: git@vger.kernel.org Cc: Junio C Hamano , Eric Sunshine , Philippe Blain , Derrick Stolee , Taylor Blau , Jeff King , Teng Long , =?utf-8?b?w4Z2?= =?utf-8?b?YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= Subject: [PATCH v4 4/8] docs: move commit-graph format docs to man section 5 Date: Mon, 18 Jul 2022 15:29:30 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1032.gb00b5447790 In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org 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 "gitformats" 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 --- 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 404139274e7..cc6870cce41 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 e1f48c95b3c..047decdb65b 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 484b185ba98..108dc2295c0 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 593614fceda..f36ce42f37c 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 1794a7279bc..66e6a0ba217 100644 --- a/command-list.txt +++ b/command-list.txt @@ -209,6 +209,7 @@ gitdiffcore guide giteveryday guide gitfaq guide gitformat-bundle gitformats +gitformat-commit-graph gitformats gitglossary guide githooks userformats gitignore userformats From patchwork Mon Jul 18 13:29:31 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= X-Patchwork-Id: 12921280 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6C151C43334 for ; Mon, 18 Jul 2022 13:29:59 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233788AbiGRN35 (ORCPT ); Mon, 18 Jul 2022 09:29:57 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54152 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233627AbiGRN3w (ORCPT ); Mon, 18 Jul 2022 09:29:52 -0400 Received: from mail-wm1-x333.google.com (mail-wm1-x333.google.com [IPv6:2a00:1450:4864:20::333]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id B2025F5B5 for ; Mon, 18 Jul 2022 06:29:47 -0700 (PDT) Received: by mail-wm1-x333.google.com with SMTP id v67-20020a1cac46000000b003a1888b9d36so9829525wme.0 for ; Mon, 18 Jul 2022 06:29:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=xUYYCztqDDmvCtJkTTK81yFvGfXLI7r5lip2GMrvU1k=; b=YVs4j5Lb3H8o8n9rp3uODyoFpSOLPF+3an+Gtwd/zuB0obok/TX0Urcz0vrpqOlTSm 9KtF/hYlIcX9AHDusUZXo+DKPIxpJNheY65SbJ6VrMCR42FhWIsC5nUthO7pSG2rJsWS lMasle5slfvaIm2W2ndwx7jMsdHctscWStjQp86+Hw35zoI2yUG7HvoWlLCnhpY0sXkC l67plX50qc7+cD/u4A0iMzEwdxZdeTo1TZQET9qvcI4kv+17kvUFZPyEJ87faCsSfhyR Jh/8Z/Qvzl52k+17CtMFsztsGOF7KHUdphAThJj8PlqgMPyHPm9fTdoMd0KPdBGkAfE2 gxIg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=xUYYCztqDDmvCtJkTTK81yFvGfXLI7r5lip2GMrvU1k=; b=lLjYJ5Egqtg6bhFA38wqoK24sOxp2/T8GRcQCMLghh21oNSoGVaB/+vSG427ANwB/E Oy2tx00+RQncI2Vsn664rGj+vNDa+8pSk4JtYO4dPY+I5PHeL80ld0YkeeB1+HUfyuJI 8lIhwHYUdEDHA5Ha45lR+MLJN1p90OJ3qi0J4Vj4wVgoY8og35LznBgGA7rvAPhUUQoy ojL3rNh3GPMzWN6DFsYduLzJuSm+wWdfB5t37G3he80NBOs5Guu82mVuzsl6+NgUEBK9 4FPNKhnUN6/BEBUAN/720oaPmb54aX5i1Yk1z+3ZuQIsIqiLLByfb3DBHYkv5XP2sXqN GMgA== X-Gm-Message-State: AJIora9Dcax3x7qKf2YB/Pd+O1OXaay1JwXrvfZEavBObFZ0bNEjZJs5 Y+oRVJyn0CycwrW2huLbW7hLZBpmlnpsoA== X-Google-Smtp-Source: AGRyM1uisYncixFzdTuvOQJtmNg5tW7rA+81a2kYmfE78DYNDC2QTOFngAXdUGLANIF0446rmv7BFA== X-Received: by 2002:a7b:cbd4:0:b0:3a3:20eb:2b80 with SMTP id n20-20020a7bcbd4000000b003a320eb2b80mr706259wmi.175.1658150985647; Mon, 18 Jul 2022 06:29:45 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id p4-20020a1c5444000000b003a30572072esm14277296wmi.6.2022.07.18.06.29.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Jul 2022 06:29:44 -0700 (PDT) From: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= To: git@vger.kernel.org Cc: Junio C Hamano , Eric Sunshine , Philippe Blain , Derrick Stolee , Taylor Blau , Jeff King , Teng Long , =?utf-8?b?w4Z2?= =?utf-8?b?YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= Subject: [PATCH v4 5/8] docs: move protocol-related docs to man section 5 Date: Mon, 18 Jul 2022 15:29:31 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1032.gb00b5447790 In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org 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. Signed-off-by: Ævar Arnfjörð Bjarmason --- Documentation/Makefile | 8 +++--- Documentation/config/lsrefs.txt | 2 +- Documentation/config/protocol.txt | 2 +- Documentation/git-upload-pack.txt | 5 ++-- Documentation/gitformat-bundle.txt | 2 +- ...otocol.txt => gitformat-pack-protocol.txt} | 22 +++++++++++++-- ...xt => gitformat-protocol-capabilities.txt} | 28 +++++++++++++++---- ...mmon.txt => gitformat-protocol-common.txt} | 23 +++++++++++++-- ...tocol-v2.txt => gitformat-protocol-v2.txt} | 24 +++++++++++++--- Documentation/technical/api-simple-ipc.txt | 2 +- Documentation/technical/http-protocol.txt | 6 ++-- .../long-running-process-protocol.txt | 2 +- Documentation/technical/partial-clone.txt | 2 +- command-list.txt | 4 +++ t/t5551-http-fetch-smart.sh | 4 +-- 15 files changed, 103 insertions(+), 33 deletions(-) rename Documentation/{technical/pack-protocol.txt => gitformat-pack-protocol.txt} (98%) rename Documentation/{technical/protocol-capabilities.txt => gitformat-protocol-capabilities.txt} (96%) rename Documentation/{technical/protocol-common.txt => gitformat-protocol-common.txt} (88%) rename Documentation/{technical/protocol-v2.txt => gitformat-protocol-v2.txt} (98%) diff --git a/Documentation/Makefile b/Documentation/Makefile index cc6870cce41..adc1404d380 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -26,6 +26,10 @@ MAN1_TXT += gitweb.txt MAN5_TXT += gitattributes.txt MAN5_TXT += gitformat-bundle.txt MAN5_TXT += gitformat-commit-graph.txt +MAN5_TXT += gitformat-pack-protocol.txt +MAN5_TXT += gitformat-protocol-capabilities.txt +MAN5_TXT += gitformat-protocol-common.txt +MAN5_TXT += gitformat-protocol-v2.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt MAN5_TXT += gitmailmap.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 adeda0f24d3..e9efe498c01 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:gitformat-protocol-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 756591d77b0..bf18a70a924 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:gitformat-protocol-v2[5]. -- diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 8f87b23ea86..754619222f6 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:gitformat-protocol-v2[5] documentation. Also understood by linkgit:git-receive-pack[1]. :: diff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.txt index 6a9d9e5bf6f..3d60d9067e4 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:gitformat-protocol-common[5] for the details. A v2 bundle looks like this: diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt similarity index 98% rename from Documentation/technical/pack-protocol.txt rename to Documentation/gitformat-pack-protocol.txt index e13a2c064d1..b665af5b690 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/gitformat-pack-protocol.txt @@ -1,5 +1,17 @@ -Packfile transfer protocols -=========================== +gitformat-pack-protocol(5) +========================== + +NAME +---- +gitformat-pack-protocol - 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:gitformat-protocol-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. @@ -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-capabilities.txt b/Documentation/gitformat-protocol-capabilities.txt similarity index 96% rename from Documentation/technical/protocol-capabilities.txt rename to Documentation/gitformat-protocol-capabilities.txt index 9dfade930da..2e89f40ddb1 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/gitformat-protocol-capabilities.txt @@ -1,8 +1,20 @@ -Git Protocol Capabilities -========================= +gitformat-protocol-capabilities(5) +================================== + +NAME +---- +gitformat-protocol-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:gitformat-protocol-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:gitformat-pack-protocol[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:gitformat-pack-protocol[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:gitformat-pack-protocol[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/gitformat-protocol-common.txt similarity index 88% rename from Documentation/technical/protocol-common.txt rename to Documentation/gitformat-protocol-common.txt index ecedb34bba5..6e1e1624e2d 100644 --- a/Documentation/technical/protocol-common.txt +++ b/Documentation/gitformat-protocol-common.txt @@ -1,5 +1,20 @@ -Documentation Common to Pack and Http Protocols -=============================================== +gitformat-protocol-common(5) +============================ + +NAME +---- +gitformat-protocol-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/protocol-v2.txt b/Documentation/gitformat-protocol-v2.txt similarity index 98% rename from Documentation/technical/protocol-v2.txt rename to Documentation/gitformat-protocol-v2.txt index 8a877d27e23..ae4fcc84e37 100644 --- a/Documentation/technical/protocol-v2.txt +++ b/Documentation/gitformat-protocol-v2.txt @@ -1,5 +1,17 @@ -Git Wire Protocol, Version 2 -============================ +gitformat-protocol-v2(5) +======================== + +NAME +---- +gitformat-protocol-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,7 +38,7 @@ Packet-Line Framing ------------------- All communication is done using packet-line framing, just as in v1. See -`Documentation/technical/pack-protocol.txt` and +linkgit:gitformat-pack-protocol[5] and `Documentation/technical/protocol-common.txt` for more information. In protocol v2 these special packets will have the following semantics: @@ -42,7 +54,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:gitformat-pack-protocol[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 +578,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 d79ad323e67..945c21bbc38 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:gitformat-protocol-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 cc5126cfeda..9d9c7acd512 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:gitformat-pack-protocol[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:gitformat-pack-protocol[5] +linkgit:gitformat-protocol-capabilities[5] diff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt index aa0aa9af1c2..c6922ce6ccc 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:gitformat-protocol-common[5]) over standard input and standard output. Handshake diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt index 99f0eb30406..9d5199d5c6c 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:gitformat-pack-protocol[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 66e6a0ba217..bec0fa690aa 100644 --- a/command-list.txt +++ b/command-list.txt @@ -210,6 +210,10 @@ giteveryday guide gitfaq guide gitformat-bundle gitformats gitformat-commit-graph gitformats +gitformat-pack-protocol gitformats +gitformat-protocol-capabilities gitformats +gitformat-protocol-common gitformats +gitformat-protocol-v2 gitformats gitglossary guide githooks userformats gitignore userformats diff --git a/t/t5551-http-fetch-smart.sh b/t/t5551-http-fetch-smart.sh index b9351a732f6..d17f77dda6f 100755 --- a/t/t5551-http-fetch-smart.sh +++ b/t/t5551-http-fetch-smart.sh @@ -175,8 +175,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 patchwork Mon Jul 18 13:29:32 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= X-Patchwork-Id: 12921283 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 82700C433EF for ; Mon, 18 Jul 2022 13:30:20 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233395AbiGRNaS (ORCPT ); Mon, 18 Jul 2022 09:30:18 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54244 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233690AbiGRN3y (ORCPT ); Mon, 18 Jul 2022 09:29:54 -0400 Received: from mail-wm1-x32c.google.com (mail-wm1-x32c.google.com [IPv6:2a00:1450:4864:20::32c]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 453AB11164 for ; Mon, 18 Jul 2022 06:29:49 -0700 (PDT) Received: by mail-wm1-x32c.google.com with SMTP id h127-20020a1c2185000000b003a2fa488efdso8669wmh.4 for ; Mon, 18 Jul 2022 06:29:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=oNSex2qLcisqUD2iVmyRTAMbAgkkdlD0RQNjyhftM6w=; b=kFYrTnzswhn8bWrlVhia11iMsnMvcuVZ5jC2SqfOgG4jCQpM1ynTf2EWBj0+rZNOn6 XOxiBR/ohu2oXcdaAJoU+UwKlBXZwLUhmLhbcS83BnWaC08k9iTAfGG3T9EEF5ABU4gQ 2k3ygCVMruaVAvnQ6JLtcgTh4EybNETj/0LR0Hf9V+omTEYSGya9ZOzyTlfEUz5h1vQ+ NuM+bz2mfbslG3mvFtMiPvX8A3sJRWItgWYYYC6SEUirxcRGnS2twl4TbU8J/EyId7xw i6+xgQu+n7pGrVeEZbeql3rtuuTaU+3BipQnk1CtjrErqSSxC8g5NCbE1pNuHiz4XKnK 4ihQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=oNSex2qLcisqUD2iVmyRTAMbAgkkdlD0RQNjyhftM6w=; b=3gZCGMg4pvcikl4IV/+75OOpDvbIYNYMO6tPZq0csc570xSZHlAeNYIz5A7KZmoVbv 1s+s0NCgx0Rgqoh8Fe1ZSR9HzjkSm5wIIJjXHakJm5ll+kFEZQyLWOimrer/TukOw40I paet4KryTUv341tRuOrJACAzItc5kTL++vrPoG2QuYOsKLhzgD6p7pRlIxWWsK1YwAPT +fVVJPEhi//JrRiYfCz4iFP6twRjnOmkrAxivP0e9Vs4WbpaIFLbqnMFElMaRPvXr5ZE dW+FgetN8ZCt+2Rzyf7SYX3b9QTZzno/+K9W4zrLEMCfEak5h2JpOVRXF4Nrhbm7HEg0 T8Cg== X-Gm-Message-State: AJIora8IjnPLH60xpuadG5nu/THcz4BA6HBbFPzPpwV8LRHmWseeKpbE KF3+ERmPqUAwKVe1YivLv5VggXLQJJj1gg== X-Google-Smtp-Source: AGRyM1sDZzPFjWWCo6g0LjmEGFe64Yw92N6NtUCWJBImkB8Up2WDEkr+uEjsYD5fhmeaWR4ao8o3Vw== X-Received: by 2002:a05:600c:3845:b0:3a3:19e8:829e with SMTP id s5-20020a05600c384500b003a319e8829emr5397183wmr.11.1658150987110; Mon, 18 Jul 2022 06:29:47 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id p4-20020a1c5444000000b003a30572072esm14277296wmi.6.2022.07.18.06.29.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Jul 2022 06:29:46 -0700 (PDT) From: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= To: git@vger.kernel.org Cc: Junio C Hamano , Eric Sunshine , Philippe Blain , Derrick Stolee , Taylor Blau , Jeff King , Teng Long , =?utf-8?b?w4Z2?= =?utf-8?b?YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= Subject: [PATCH v4 6/8] docs: move pack format docs to man section 5 Date: Mon, 18 Jul 2022 15:29:32 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1032.gb00b5447790 In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org 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 do to a gitformat-chunk-format manpage we build by default. Creating a "gitformat-pack-bitmap" from "Documentation/technical/bitmap-format" might logically be part of this change, but it's left out for now due to a conflict with the in-flight ac/bitmap-lookup-table series. Signed-off-by: Ævar Arnfjörð Bjarmason --- Documentation/Makefile | 9 ++--- Documentation/config/pack.txt | 2 +- Documentation/git-bundle.txt | 3 +- Documentation/git-multi-pack-index.txt | 4 +-- .../chunk-format.txt => gitformat-chunk.txt} | 27 ++++++++++++--- Documentation/gitformat-commit-graph.txt | 2 +- .../index-format.txt => gitformat-index.txt} | 22 ++++++++++-- ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++++-- Documentation/gitformat-pack-protocol.txt | 2 +- .../pack-format.txt => gitformat-pack.txt} | 34 +++++++++++++++++-- ...ure-format.txt => gitformat-signature.txt} | 21 ++++++++++-- .../howto/recover-corrupted-object-harder.txt | 2 +- .../technical/hash-function-transition.txt | 2 +- Documentation/user-manual.txt | 2 +- cache.h | 3 +- command-list.txt | 5 +++ pack-revindex.h | 2 +- 17 files changed, 132 insertions(+), 32 deletions(-) rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (90%) rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%) rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%) rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%) rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%) diff --git a/Documentation/Makefile b/Documentation/Makefile index adc1404d380..b4d2361dfc7 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -25,11 +25,16 @@ 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-cruft.txt MAN5_TXT += gitformat-pack-protocol.txt +MAN5_TXT += gitformat-pack.txt MAN5_TXT += gitformat-protocol-capabilities.txt MAN5_TXT += gitformat-protocol-common.txt MAN5_TXT += gitformat-protocol-v2.txt +MAN5_TXT += gitformat-signature.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt MAN5_TXT += gitmailmap.txt @@ -101,13 +106,10 @@ 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/index-format 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 @@ -115,7 +117,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/config/pack.txt b/Documentation/config/pack.txt index ad7f73a1ead..3e581eab84a 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 1aeae09f082..4c6c41e1a09 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 c588fb91af1..a48c3d5ea63 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 90% rename from Documentation/technical/chunk-format.txt rename to Documentation/gitformat-chunk.txt index f36ce42f37c..784c5d987de 100644 --- a/Documentation/technical/chunk-format.txt +++ b/Documentation/gitformat-chunk.txt @@ -1,12 +1,25 @@ -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 `commit-graph` format in linkgit:gitformat-commit-graph[5] for +the `multi-pack-index` format in linkgit:gitformat-pack[5] and +link:technical/commit-graph-format.html[the `commit-graph` format] for how they use the chunks to describe structured data. A chunk-based file format begins with some header information custom to @@ -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 108dc2295c0..7324665716d 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/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 65da0daaa56..5f3ed10d2db 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 @@ -127,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. @@ -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/Documentation/technical/cruft-packs.txt b/Documentation/gitformat-pack-cruft.txt similarity index 96% rename from Documentation/technical/cruft-packs.txt rename to Documentation/gitformat-pack-cruft.txt index d81f3a8982f..908f752bd84 100644 --- a/Documentation/technical/cruft-packs.txt +++ b/Documentation/gitformat-pack-cruft.txt @@ -1,4 +1,17 @@ -= Cruft packs +gitformat-pack-cruft(5) +======================= + +NAME +---- +gitformat-pack-cruft - The cruft pack file format + +SYNOPSIS +-------- +[verse] +$GIT_DIR/objects/pack/pack-*.mtimes + +DESCRIPTION +----------- The cruft packs feature offer an alternative to Git's traditional mechanism of removing unreachable objects. This document provides an overview of Git's @@ -10,10 +23,11 @@ same. 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. @@ -121,3 +135,7 @@ 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/gitformat-pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt index b665af5b690..f1bfd6705d9 100644 --- a/Documentation/gitformat-pack-protocol.txt +++ b/Documentation/gitformat-pack-protocol.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/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 b520aa9c45b..5b21d0f2521 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:gitformat-protocol-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/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 166721be6f6..a249869fafa 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/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.txt index 8994e2559ea..5efb4fe81ff 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 260224b0331..e2ac36dd210 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 865074bed4e..ca9decdd952 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 ac5ab4ef9d3..82755c7c0aa 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 bec0fa690aa..c364557fe09 100644 --- a/command-list.txt +++ b/command-list.txt @@ -209,11 +209,16 @@ gitdiffcore guide giteveryday guide gitfaq guide gitformat-bundle gitformats +gitformat-chunk gitformats gitformat-commit-graph gitformats +gitformat-index gitformats +gitformat-pack gitformats +gitformat-pack-cruft gitformats gitformat-pack-protocol gitformats gitformat-protocol-capabilities gitformats gitformat-protocol-common gitformats gitformat-protocol-v2 gitformats +gitformat-signature gitformats gitglossary guide githooks userformats gitignore userformats diff --git a/pack-revindex.h b/pack-revindex.h index 74f4eae668d..4974e75eb4d 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 patchwork Mon Jul 18 13:29:33 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= X-Patchwork-Id: 12921281 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 5847BCCA479 for ; Mon, 18 Jul 2022 13:30:00 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233794AbiGRN37 (ORCPT ); Mon, 18 Jul 2022 09:29:59 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54106 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233360AbiGRN3x (ORCPT ); Mon, 18 Jul 2022 09:29:53 -0400 Received: from mail-wm1-x334.google.com (mail-wm1-x334.google.com [IPv6:2a00:1450:4864:20::334]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 753EE11814 for ; Mon, 18 Jul 2022 06:29:50 -0700 (PDT) Received: by mail-wm1-x334.google.com with SMTP id v67-20020a1cac46000000b003a1888b9d36so9829605wme.0 for ; Mon, 18 Jul 2022 06:29:50 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=Kk1OlPc4NUzDRxo4DRmVB0qDv0ZN5NGpXJZ+LHYNOOA=; b=IyfQGkqjkRNyjIUSW0InQCbpDIjLgig5+o8yTSuZAO2eZk4+nqad5EwpIfcX05AWH/ /bVek44ZAu4pvqw+3AT0ojRJ1/itOlDk2qRRPtndxFknc9b8VABG76dOacMMRWE1WKv2 QTUZEUcKCwEKB9ZhuQ6s1bInzc3mKWhZbJLzmhDJPsIQOK55dhXJr25qEK5iuJWouUxD RrrnlmEIicLPW7qDPN2WqUVZla8YrFHODDe98qr1U8712cKeNcjwN8dzlzjGOUHNi/XA 1H3JMbZEa4SJfJsyNPWNia/KekwZ93v9fW3p5ehl3vYkiBIDsj+np3MwzSQ0msmlkRMQ R5ug== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=Kk1OlPc4NUzDRxo4DRmVB0qDv0ZN5NGpXJZ+LHYNOOA=; b=PhREZdDyJGgXUqkJ8KZmus58WblDWsIxirX7QsToUSay7UpMRse/HEeCGwA2DZ3LkA nLKskpBmNk/aRQ6EsgyoN/iKkHtaQa+FXc3YALzXk2n31OawgTzLojS6RZY0jAWauOe7 y4kt0m9YNCOrqP+4wiYCirTIJtifm4G4qIvu1iq0Mm9SavZkBtjFc8/G7RxlXtYf6rN1 TvJY8KhL9jUlrjeQ0Lbo9Ps1lUqksJidYfJgq9rajhi48B2cXTNGC/c6uxdNXIDLXMog SYwUDA2dcS9aEWgRL+CpxcY0OqSL7ZjRrHMLm2zEP+EbEBar2kcKKYNZEkN6H5tcEME+ FlAA== X-Gm-Message-State: AJIora8a0o8MUcoSPOMbZqchnmuU/osF2Zu0sPZ5ystEwNiVnO3Ie16C LCbGnJWEsSmuOtNOf5d9+K4fYpmQpJzi5g== X-Google-Smtp-Source: AGRyM1txDtnjIFvo+vXPaVGE16swMFA/uRGyJNQlUB5Oa3XV4YZan/SdGqZqcYIPw7+o8MNHgOg0ag== X-Received: by 2002:a05:600c:2211:b0:3a3:2149:88e1 with SMTP id z17-20020a05600c221100b003a3214988e1mr204100wml.8.1658150988295; Mon, 18 Jul 2022 06:29:48 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id p4-20020a1c5444000000b003a30572072esm14277296wmi.6.2022.07.18.06.29.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Jul 2022 06:29:47 -0700 (PDT) From: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= To: git@vger.kernel.org Cc: Junio C Hamano , Eric Sunshine , Philippe Blain , Derrick Stolee , Taylor Blau , Jeff King , Teng Long , =?utf-8?b?w4Z2?= =?utf-8?b?YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= Subject: [PATCH v4 7/8] docs: move http-protocol docs to man section 5 Date: Mon, 18 Jul 2022 15:29:33 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1032.gb00b5447790 In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org 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 --- Documentation/Makefile | 2 +- Documentation/git-upload-pack.txt | 6 ++-- Documentation/gitformat-pack-protocol.txt | 2 +- ...otocol.txt => gitformat-protocol-http.txt} | 29 ++++++++++++++++--- Documentation/gitformat-protocol-v2.txt | 4 +-- command-list.txt | 1 + 6 files changed, 33 insertions(+), 11 deletions(-) rename Documentation/{technical/http-protocol.txt => gitformat-protocol-http.txt} (98%) diff --git a/Documentation/Makefile b/Documentation/Makefile index b4d2361dfc7..44757823e96 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -33,6 +33,7 @@ MAN5_TXT += gitformat-pack-protocol.txt MAN5_TXT += gitformat-pack.txt MAN5_TXT += gitformat-protocol-capabilities.txt MAN5_TXT += gitformat-protocol-common.txt +MAN5_TXT += gitformat-protocol-http.txt MAN5_TXT += gitformat-protocol-v2.txt MAN5_TXT += gitformat-signature.txt MAN5_TXT += githooks.txt @@ -107,7 +108,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 754619222f6..720697df3a0 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:gitformat-protocol-v2[5] documentation. Also understood by + "Smart Clients" in linkgit:gitformat-protocol-http[5] and + "HTTP Transport" in link:technical/protocol-v2.html[the Git + Wire Protocol, Version 2] documentation. Also understood by linkgit:git-receive-pack[1]. :: diff --git a/Documentation/gitformat-pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt index f1bfd6705d9..c82b926e661 100644 --- a/Documentation/gitformat-pack-protocol.txt +++ b/Documentation/gitformat-pack-protocol.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:gitformat-protocol-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/technical/http-protocol.txt b/Documentation/gitformat-protocol-http.txt similarity index 98% rename from Documentation/technical/http-protocol.txt rename to Documentation/gitformat-protocol-http.txt index 9d9c7acd512..b85fc86abf6 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/gitformat-protocol-http.txt @@ -1,5 +1,19 @@ -HTTP transfer protocols -======================= +gitformat-protocol-http(5) +========================== + +NAME +---- +gitformat-protocol-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:gitformat-pack-protocol[5] linkgit:gitformat-protocol-capabilities[5] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitformat-protocol-v2.txt b/Documentation/gitformat-protocol-v2.txt index ae4fcc84e37..e29bc4b6a68 100644 --- a/Documentation/gitformat-protocol-v2.txt +++ b/Documentation/gitformat-protocol-v2.txt @@ -54,7 +54,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:gitformat-pack-protocol[5] and `http-protocol.txt`, as well as the +found in linkgit:gitformat-pack-protocol[5] and linkgit:gitformat-protocol-http[5], as well as the `GIT_PROTOCOL` definition in `git.txt`. In all cases the response from the server is the capability advertisement. @@ -78,7 +78,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:gitformat-protocol-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 c364557fe09..c87b07e779c 100644 --- a/command-list.txt +++ b/command-list.txt @@ -217,6 +217,7 @@ gitformat-pack-cruft gitformats gitformat-pack-protocol gitformats gitformat-protocol-capabilities gitformats gitformat-protocol-common gitformats +gitformat-protocol-http gitformats gitformat-protocol-v2 gitformats gitformat-signature gitformats gitglossary guide From patchwork Mon Jul 18 13:29:34 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= X-Patchwork-Id: 12921282 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id E1A45C433EF for ; Mon, 18 Jul 2022 13:30:17 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233884AbiGRNaQ (ORCPT ); Mon, 18 Jul 2022 09:30:16 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54246 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233728AbiGRN3y (ORCPT ); Mon, 18 Jul 2022 09:29:54 -0400 Received: from mail-wm1-x32d.google.com (mail-wm1-x32d.google.com [IPv6:2a00:1450:4864:20::32d]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 2694311C03 for ; Mon, 18 Jul 2022 06:29:51 -0700 (PDT) Received: by mail-wm1-x32d.google.com with SMTP id j29-20020a05600c1c1d00b003a2fdafdefbso7343942wms.2 for ; Mon, 18 Jul 2022 06:29:50 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=DtpRmMyreB5N942esupAHqZ4ZC9LA5qFDn74kMgovGE=; b=RVAMDxmzHzH66pq+XC0/svkshzkuquiR2tWb6LjMPRYrsM30wrmAt2MqQay8nxu5kL dn3wd9Wn3pgo0O7wGCuWYw/45wrUCadt05sS6SKd7vLgjtKB9h9e7t8mjW5f+ic3d6Yw FUyQ8PpEa+vYOwZvRTuhUx3lXQUL6Bb286+ZWYhrObvV60Z1nCuDDe8BlDuO4uznooFa Yf/Fa51Gf+KW/l33i0rcLeIcpZcjfB/5ozqRqUarPYlxo8u1ndoxMqT9owwhtyk0AHrl MEFnDgsF3Fg1kokHHHzBuQ9o0OTWVG/jCJB6gwDrvVXMIWY4vS6w32jdkSzVdSM1ANfe vAHg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=DtpRmMyreB5N942esupAHqZ4ZC9LA5qFDn74kMgovGE=; b=kDYq8KqtreMVNq7uGQZkgsaiY9NX0KpHI5h26/1VhRuIZJnJ7YoTpHUT1i+dTu550a /LbfBuSWvsGRw+QCk1gNg8pUr1UHKhW3Sn4qgrQLD4xoktzMOVIZ21G7A+7lAV7ETGDq I2sYIKyatJs7knFBgX64nfm0QvMBBShAzFFePFPpdeSoaYvLUd+EzfKV+CGdfNU2N8Gq zDNMn+JnLHjqTKKhMCHaJnJFSoVEtDE0CL312bTbK871ChEXhC3/HMQr/RVoJMEINGGt Qb2CzWkFXiBuNK/DQDwmZj5sD7iecZPfLXZSRD3LepFmGpANWmeHiPgRwxG/WtiGZJlL zv/g== X-Gm-Message-State: AJIora/D5Hq7MDyXuUDP65r6Kib3jhNNd0LT8Gu7hoRObq1gRcaNxxaO eNS0RsXI0GW8QuQIFBvfdhVQsfu8/FYl2g== X-Google-Smtp-Source: AGRyM1v2C9w771O3C7SxMBNar2BfEFJcmttt1CzFBXZUD9tBpFmRFgJ3HnvDVo/2QqWhF6+6oa1DjA== X-Received: by 2002:a05:600c:4f83:b0:3a1:9c7c:9ea3 with SMTP id n3-20020a05600c4f8300b003a19c7c9ea3mr32708258wmq.39.1658150989261; Mon, 18 Jul 2022 06:29:49 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id p4-20020a1c5444000000b003a30572072esm14277296wmi.6.2022.07.18.06.29.48 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Jul 2022 06:29:48 -0700 (PDT) From: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= To: git@vger.kernel.org Cc: Junio C Hamano , Eric Sunshine , Philippe Blain , Derrick Stolee , Taylor Blau , Jeff King , Teng Long , =?utf-8?b?w4Z2?= =?utf-8?b?YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= Subject: [PATCH v4 8/8] docs: move multi-pack-index docs to man section 5 Date: Mon, 18 Jul 2022 15:29:34 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1032.gb00b5447790 In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space by moving the multi-pack-index documentation over. Signed-off-by: Ævar Arnfjörð Bjarmason --- Documentation/Makefile | 2 +- Documentation/git-multi-pack-index.txt | 5 +++-- ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++++++++++++-- Documentation/gitformat-pack.txt | 5 +++++ command-list.txt | 1 + 5 files changed, 28 insertions(+), 5 deletions(-) rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%) diff --git a/Documentation/Makefile b/Documentation/Makefile index 44757823e96..984d86a96d3 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -28,6 +28,7 @@ MAN5_TXT += gitformat-bundle.txt MAN5_TXT += gitformat-chunk.txt MAN5_TXT += gitformat-commit-graph.txt MAN5_TXT += gitformat-index.txt +MAN5_TXT += gitformat-multi-pack-index.txt MAN5_TXT += gitformat-pack-cruft.txt MAN5_TXT += gitformat-pack-protocol.txt MAN5_TXT += gitformat-pack.txt @@ -109,7 +110,6 @@ TECH_DOCS += ToolsForGit TECH_DOCS += technical/bitmap-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/long-running-process-protocol -TECH_DOCS += technical/multi-pack-index TECH_DOCS += technical/pack-heuristics TECH_DOCS += technical/parallel-checkout TECH_DOCS += technical/partial-clone diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt index a48c3d5ea63..a147e047c91 100644 --- a/Documentation/git-multi-pack-index.txt +++ b/Documentation/git-multi-pack-index.txt @@ -127,8 +127,9 @@ $ git multi-pack-index verify SEE ALSO -------- -See link:technical/multi-pack-index.html[The Multi-Pack-Index Design -Document] and linkgit:gitformat-pack[5] for more information on the + +See linkgit:git-multi-pack-index[1] and +linkgit:gitformat-multi-pack-index[5] for more information on the multi-pack-index feature and its file format. diff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/gitformat-multi-pack-index.txt similarity index 94% rename from Documentation/technical/multi-pack-index.txt rename to Documentation/gitformat-multi-pack-index.txt index f2221d2b441..3bca1e7b10d 100644 --- a/Documentation/technical/multi-pack-index.txt +++ b/Documentation/gitformat-multi-pack-index.txt @@ -1,5 +1,17 @@ -Multi-Pack-Index (MIDX) Design Notes -==================================== +gitformat-multi-pack-index(5) +============================= + +NAME +---- +gitformat-multi-pack-index - The multi-pack-index file format + +SYNOPSIS +-------- +[verse] +$GIT_DIR/objects/pack/multi-pack-index + +DESCRIPTION +----------- The Git object directory contains a 'pack' directory containing packfiles (with suffix ".pack") and pack-indexes (with suffix @@ -98,3 +110,7 @@ Related Links [2] https://lore.kernel.org/git/alpine.DEB.2.20.1803091557510.23109@alexmv-linux/ Git Merge 2018 Contributor's summit notes (includes discussion of MIDX) + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt index 5b21d0f2521..06b469c6944 100644 --- a/Documentation/gitformat-pack.txt +++ b/Documentation/gitformat-pack.txt @@ -507,6 +507,11 @@ 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. +SEE ALSO +-------- + +linkgit:gitformat-multi-pack-index[5] + GIT --- Part of the linkgit:git[1] suite diff --git a/command-list.txt b/command-list.txt index c87b07e779c..a802f5b3369 100644 --- a/command-list.txt +++ b/command-list.txt @@ -212,6 +212,7 @@ gitformat-bundle gitformats gitformat-chunk gitformats gitformat-commit-graph gitformats gitformat-index gitformats +gitformat-multi-pack-index gitformats gitformat-pack gitformats gitformat-pack-cruft gitformats gitformat-pack-protocol gitformats