From patchwork Tue Aug 2 12:56:50 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: 12934631 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 C9E12C19F2C for ; Tue, 2 Aug 2022 12:58:15 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S236977AbiHBM6O (ORCPT ); Tue, 2 Aug 2022 08:58:14 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41796 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236315AbiHBM6C (ORCPT ); Tue, 2 Aug 2022 08:58:02 -0400 Received: from mail-wr1-x431.google.com (mail-wr1-x431.google.com [IPv6:2a00:1450:4864:20::431]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 80CBC12616 for ; Tue, 2 Aug 2022 05:58:01 -0700 (PDT) Received: by mail-wr1-x431.google.com with SMTP id l4so17812377wrm.13 for ; Tue, 02 Aug 2022 05:58:01 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc; bh=HqO61h7mveACM6Jd2OCinin3ipsmHcU1AFh3ugoxELY=; b=YcalFBNwVT8i/e4/WOg3XR05u4TPUjLMjCkYPmTNLO/CRpQrnL1UDF05LWV2+Fd3CI ZceAWZUP73vJ7/xL5z7uYoQR3SjJhHErsylTTotUhB3XTVchoSFI5VFe6yrU8s70nVQG 9EMij9YTQCQMW+hlHNzKIfWlBpb8uoxS9KHm9y+2CFVT/KzUJ4FUumJZ3D7IxkGOcIP8 llPRPrT2BOtPXfzZeCsjoHBx0J3B0rx6FTRUL+A1+gvqfc2B9xAZyGpe+JU96kqv1tN4 rug90oGGVmyDhPdmbpObYzi6wZBN9aWtvQn9VrQfEtiWe9Bm2oGbqgOxPfOyS42Ggdlb IzTw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc; bh=HqO61h7mveACM6Jd2OCinin3ipsmHcU1AFh3ugoxELY=; b=tGArhy49LYd3+EuYflNUXAUpq4KhuAyUjKSI9su44JqXfKf3JKu2afrQwX9yuBo8eB R79OBfkcwXt/x70srTrtKfsB2xLwUl0EWduk9WrvYNKJ8bFz1AJWdDdagF6MKGUJhmOT 3bIWEZzN1i74h683FFLk+TCBwYe4TqFI6rIibukfNnt0gs9uGI5VudDskvDeWINemRNd OYlrMQXM8Q9zZqukrm3xyvFwtssWWI7I3tFS0MerdvYNZPEP+DnCEi3i5Y4bA7oYyinf 3kTXBDtvEh8R8H+tB00uIPmxDd7y85GOYDOucFj4+YDu818NQ/aKRokwcGnc8+t0BdEo 8lhw== X-Gm-Message-State: ACgBeo1v9WNUZ4flbbQb7rKpPH9ApaMjey+Ig6lkAtUQXcAHs1BYmASl xXwVhqQwpsjUIbgDgGiFg56lGBNdoR1Xfg== X-Google-Smtp-Source: AA6agR4srcDhTVcGha/D0fuEy5yN3Of4U7cCiqViFMVA4PFgDziT7k+x55blY8k0AbQCwk21MYOuow== X-Received: by 2002:a5d:4e52:0:b0:21f:15aa:1174 with SMTP id r18-20020a5d4e52000000b0021f15aa1174mr11387501wrt.106.1659445079623; Tue, 02 Aug 2022 05:57:59 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id t4-20020adfeb84000000b0021e45afa7b0sm15056145wrn.109.2022.08.02.05.57.58 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Aug 2022 05:57:58 -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 v7 01/10] help.c: refactor drop_prefix() to use a "switch" statement" Date: Tue, 2 Aug 2022 14:56:50 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1232.gc0cde427aa7 In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Refactor the drop_prefix() function in in help.c to make it easier to strip prefixes from categories that aren't "CAT_guide". There are no functional changes here, by doing this we make a subsequent functional change's diff smaller. As before we first try to strip "git-" unconditionally, if that works we'll return the stripped string. Then we'll strip "git" if the command is in "CAT_guide". This means that we'd in principle strip "git-gitfoo" down to "foo" if it's in CAT_guide. That doesn't make much sense, and we don't have such an entry in command-list.txt, but let's preserve that behavior for now. While we're at it remove a stray newline that had been added after the "return name;" statement. Signed-off-by: Ævar Arnfjörð Bjarmason --- help.c | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/help.c b/help.c index 41c41c2aa11..7e594d291b0 100644 --- a/help.c +++ b/help.c @@ -44,13 +44,19 @@ static struct category_description main_categories[] = { static const char *drop_prefix(const char *name, uint32_t category) { const char *new_name; + const char *prefix = NULL; if (skip_prefix(name, "git-", &new_name)) return new_name; - if (category == CAT_guide && skip_prefix(name, "git", &new_name)) + switch (category) { + case CAT_guide: + prefix = "git"; + break; + } + if (prefix && skip_prefix(name, prefix, &new_name)) return new_name; - return name; + return name; } static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask) From patchwork Tue Aug 2 12:56:51 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: 12934632 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 699B2C00140 for ; Tue, 2 Aug 2022 12:58:20 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S236858AbiHBM6Q (ORCPT ); Tue, 2 Aug 2022 08:58:16 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41802 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236506AbiHBM6D (ORCPT ); Tue, 2 Aug 2022 08:58:03 -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 91601D114 for ; Tue, 2 Aug 2022 05:58:02 -0700 (PDT) Received: by mail-wm1-x32d.google.com with SMTP id 8-20020a05600c024800b003a2fe343db1so6928235wmj.1 for ; Tue, 02 Aug 2022 05:58:02 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc; bh=Y3Rdy4quEAoENxHzcnWU0FjgMhu8xb2BrcxkhBgDtSM=; b=jFW8M2dQazMjNIgJvs+TQJYE/1eqPjz6fA5hXd2N2rdaB81V0JXATE5ebKEWevKahA FC6/PNQIj+xNeStyDD1k0av0+o8DH8u/8TMSFsZr5eiUzWBWCuWWXQ5tK+if9tJenMEG 2Qv8zHs/q1Pd9FiErjjslQ4a/G4TiGC+4I6c5ZnXFmpmv/U3Os5WXbsZ42OLHbvehFkZ oFmFaGtsDYDrUjAYxPzEwV3cFNUhmkZWBqOeXdpt/uMEhijCeP+a4fuOw4Rx1aqrnAoN qg71Yz4DVydHwxdUbsq7wI8vss/86wlL+xYryoSDxgyOFMVjkZi6K5YUPvPeZKZVxWJo kv7w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc; bh=Y3Rdy4quEAoENxHzcnWU0FjgMhu8xb2BrcxkhBgDtSM=; b=oqVlm5hoqSDEyz8m2z/WGAClyqHSVTmmnRhQm3lAjwgMO7KzTjRzFwtaAkhyUgL7Xk HA8yN0fiDYWAucau6MEp5TXrQ8L5GL5dACxrsFXP9HJA85/j8gMOKPilAiIpFxnKWjXg XoAevWsOet9do2ICJ2rIFwjvxbLWmxBFVK3qS6Xwni3vD+32phcmS8G/bzeOXeIKtQvw bBKvuKMREwNYZPQpXJbOQPpHmezH7lGF06AtM5fGfYqZFwF/G/hzFcTLY+lU9PZLRafZ /qa9rBa39thktjVeUyYrOxn0iqf0fW1Tk6sgx72jG5XkjWapDiIQELY9u314Ms/dEM5x UUIg== X-Gm-Message-State: ACgBeo1w1don3JVz/aa8rP2S26PQwUTbf0GFV/oXpzhpHJg60WL6VuMv MuxtZUIhFjJs2OLYr4FtwtLYKo/rxycoNw== X-Google-Smtp-Source: AA6agR59d1Vcx9UQlLW3ypyUO8bohVVAXLGw+sj6Eneo7y4A/3pT00UV6L9F2XhEE1OudUaJ3DtKSQ== X-Received: by 2002:a05:600c:1d81:b0:3a4:f189:8052 with SMTP id p1-20020a05600c1d8100b003a4f1898052mr370503wms.136.1659445080661; Tue, 02 Aug 2022 05:58:00 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id t4-20020adfeb84000000b0021e45afa7b0sm15056145wrn.109.2022.08.02.05.57.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Aug 2022 05:58:00 -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 v7 02/10] help.c: remove common category behavior from drop_prefix() behavior Date: Tue, 2 Aug 2022 14:56:51 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1232.gc0cde427aa7 In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Change the behavior of the "git" prefix stripping for CAT_guide so that we don't try to strip the "git-" prefix in that case. We should be stripping either "git" or "git-" depending on the category. This change makes it easier to add extra "category" conditions in subsequent commits. Before this we'd in principle strip a "git-" prefix from a "guide" in command-list.txt, in practice we have no such entry there. As we don't have any entry that looks like "git-gitfoo" in command-list.txt this changes nothing in practice, but it makes the intent of the code clearer. When this code was added in cfb22a02ab5 (help: use command-list.h for common command list, 2018-05-10) the only entries in command-list.txt that didn't begin with "git-" were "gitweb" and "gitk". Then when the "guides" special-case was added in 1b81d8cb19d (help: use command-list.txt for the source of guides, 2018-05-20) we had the various "git" (not "git-") prefixed "guide" entries, which the "CAT_guide" case handles. Signed-off-by: Ævar Arnfjörð Bjarmason --- help.c | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/help.c b/help.c index 7e594d291b0..8a09f18a3d9 100644 --- a/help.c +++ b/help.c @@ -44,16 +44,17 @@ static struct category_description main_categories[] = { static const char *drop_prefix(const char *name, uint32_t category) { const char *new_name; - const char *prefix = NULL; + const char *prefix; - if (skip_prefix(name, "git-", &new_name)) - return new_name; switch (category) { case CAT_guide: prefix = "git"; break; + default: + prefix = "git-"; + break; } - if (prefix && skip_prefix(name, prefix, &new_name)) + if (skip_prefix(name, prefix, &new_name)) return new_name; return name; From patchwork Tue Aug 2 12:56:52 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: 12934633 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 C7E5DC00140 for ; Tue, 2 Aug 2022 12:58:24 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S237055AbiHBM6V (ORCPT ); Tue, 2 Aug 2022 08:58:21 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41816 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236793AbiHBM6E (ORCPT ); Tue, 2 Aug 2022 08:58:04 -0400 Received: from mail-wr1-x42b.google.com (mail-wr1-x42b.google.com [IPv6:2a00:1450:4864:20::42b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7992712D22 for ; Tue, 2 Aug 2022 05:58:03 -0700 (PDT) Received: by mail-wr1-x42b.google.com with SMTP id j7so17795083wrh.3 for ; Tue, 02 Aug 2022 05:58:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc; bh=1WRQvpEnWfF3xHTI/Qhxe6+hvIeHJ+v7wmsDy8cTII0=; b=FtoQc4IXRnDVvdwDlNF/ABvQY6GHrEs+LshJwzIMD3TnYGHm+iikozku9opBNxFr5j iAZf6xe5WCaFIeYQ9Yhcz0k0U1Hc2Hm2yazIocqkqtKCwYYzHpZVlaeqmgELPTbwekBO hVkBSGsKTlRe17ctuWCgoa0IObWThAxrRTinx50v9gn6kPQ0d2VQZaut08i0zeQB5Hsl Aqe2o8rIob+jeUIEfWku2w/azUTHNXASnzgL5dr1mAcynBWfoioxDBzvPozLDJ7R8MDT NOMzGiLUIW7x5zai7LzUrjfXBTapy6JVzp7gdjhSZn6X4ikCtiTASkHmHRVNCJr6rGgl hUqQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc; bh=1WRQvpEnWfF3xHTI/Qhxe6+hvIeHJ+v7wmsDy8cTII0=; b=P+gtLJU4Ia7gpvhBMt8pJyjCgHgxcfwmdDJth8MsvVym2dydiAgyqznjvjwV4TuDGw lquRi8B9g7/SYqhevoHujqVwi6v1jH31P9YYJzVoyxY5vER/D7ss2IZGVwzrf0A1hFgd 9MLcFXMJ5HNjQK6qAxGXhZivQ0dTuDuyEg6DR4JtdHQcy8SgxAyCXWcfy+xyu/9mEV6I i+1pZOrB/jzIQp1CokvOyHN2F0uJQNTZi97OZ2mrFDSVV1F//BZp6YUndSKDGgw9wTax SCBBJHAnT09gP7m3jsczv7Y1colSltGvbq+EXjLLgKTYRDbznIrJLzc1ul4513OZcnty sNzA== X-Gm-Message-State: ACgBeo28z9Yot5Bl5td59DQbme+g+FjoTRkGtQ3MzKV9ur/P3xQMtlK5 TJLnUkXtWqZH1+bR+NwyR6OsylPCJ2dQrw== X-Google-Smtp-Source: AA6agR7bL/O7WzQXcw3qoWQqUfxrHUsoajtHXNN6++O8i3H6iitw2NnYh2IkxCkarpJIoIayDY2Wrw== X-Received: by 2002:a5d:6d0f:0:b0:220:76a3:b31d with SMTP id e15-20020a5d6d0f000000b0022076a3b31dmr984384wrq.581.1659445081724; Tue, 02 Aug 2022 05:58:01 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id t4-20020adfeb84000000b0021e45afa7b0sm15056145wrn.109.2022.08.02.05.58.00 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Aug 2022 05:58:01 -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 v7 03/10] git help doc: use "" instead of "" Date: Tue, 2 Aug 2022 14:56:52 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1232.gc0cde427aa7 In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Replace the use of "" originally introduced (as "GUIDE") in a133737b809 (doc: include --guide option description for "git help", 2013-04-02) with the more generic "". The "" placeholder is more generic, and one we'll be able to use as we introduce new documentation categories. Let's also add "" to the "git help -h" output, when it was made to use parse_option() in in 41eb33bd0cb (help: use parseopt, 2008-02-24). Signed-off-by: Ævar Arnfjörð Bjarmason --- Documentation/git-help.txt | 8 ++++---- builtin/help.c | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 239c68db457..bead763fd29 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -9,14 +9,14 @@ SYNOPSIS -------- [verse] 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases] -'git help' [[-i|--info] [-m|--man] [-w|--web]] [|] +'git help' [[-i|--info] [-m|--man] [-w|--web]] [|] 'git help' [-g|--guides] 'git help' [-c|--config] DESCRIPTION ----------- -With no options and no '' or '' given, the synopsis of the 'git' +With no options and no '' or '' given, the synopsis of the 'git' command and a list of the most commonly used Git commands are printed on the standard output. @@ -26,8 +26,8 @@ printed on the standard output. If the option `--guides` or `-g` is given, a list of the Git concept guides is also printed on the standard output. -If a command, or a guide, is given, a manual page for that command or -guide is brought up. The 'man' program is used by default for this +If a command or other documentation is given, the relevant manual page +will be brought up. The 'man' program is used by default for this purpose, but this can be overridden by other options or configuration variables. diff --git a/builtin/help.c b/builtin/help.c index 222f994f863..dec82d1be27 100644 --- a/builtin/help.c +++ b/builtin/help.c @@ -81,7 +81,7 @@ static struct option builtin_help_options[] = { static const char * const builtin_help_usage[] = { "git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]", - N_("git help [[-i|--info] [-m|--man] [-w|--web]] []"), + N_("git help [[-i|--info] [-m|--man] [-w|--web]] [|]"), "git help [-g|--guides]", "git help [-c|--config]", NULL From patchwork Tue Aug 2 12:56:53 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: 12934634 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 AED05C00140 for ; Tue, 2 Aug 2022 12:58:27 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S237072AbiHBM60 (ORCPT ); Tue, 2 Aug 2022 08:58:26 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41834 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236922AbiHBM6G (ORCPT ); Tue, 2 Aug 2022 08:58:06 -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 80B4713F7E for ; Tue, 2 Aug 2022 05:58:04 -0700 (PDT) Received: by mail-wm1-x32c.google.com with SMTP id v131-20020a1cac89000000b003a4bb3f786bso3093906wme.0 for ; Tue, 02 Aug 2022 05:58:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc; bh=pn4Kkw/YXRvm5telW43jXewUlFnRC0QP86Q/TkA6zhY=; b=FqvBkBfL+LXkDyn9yHaSfR/OkFvFvXpF6ye8c5LlwZKFTdYxAkC1FqJlfLdPSwLux3 JPDpL/bHKeAACid2sqTQbqo8T3VdShFS6Rq52iwHHGSPiR0U60ubvoF3HhYjKBclJgGP G/qN2yd2+8mOMxFesTb0ancBcI1tPBpTP9FhQ91VlJtMxwc7UsLPXiDK55C7MIiS5F3t xZwL4o4lScfs19d6z91Lsl/I5CbAmCb45/lHJ2hgd9lVgKNOjqD7GqzEu/u6LDWgUbol MIVI1ZZ3lK+T7zMsBbQjJ+HZb/EZS+eq1FYj7SI7Mn7RJO1OnS48o2dkqKqea6+9uLTj KUrQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc; bh=pn4Kkw/YXRvm5telW43jXewUlFnRC0QP86Q/TkA6zhY=; b=jNpgw0Po+eNjgwVF9FdPB1cch/M+u5f+2imCpI5mZvoH7gluLfWizKVYGfqpE1deTh K1D7PLVqM26Mt6OnhBPM0MWnEmIOMSsY1ksQbPvUhZE4eoq0CoVosZ43FrZyM31gSWut k01xwB9XWD5LtFf8Cw/N4ZEJy9NGBFCH2hNf37ehgls4mZ43x99FmZLMO+42TOjdMOXV UjhbrQNL4OQD6bdJu5g4EtqoK7bIH3mnbCgbUD7e+PA4rxFA8B+ze0l9ZXzmszNDbHfP rivZX/ThWGrV9TKHzpZN8KoXmkLch6Jvf6mCtI4On6cgpGCxnOOkRqIjJDvS+0aBZ5/l /NwA== X-Gm-Message-State: AJIora/wqvFxB1NGTc2mcnrNHcxCv9TS/h8rwctqk9T4xfNTkCcF/pl1 kk7mD3SQJcSh9jgH+JdB0x4x1/Xf/lzc5w== X-Google-Smtp-Source: AGRyM1stIV/Tg5ZkcHtLA4wrK56o5C2fDlDtEvBA8d/x4MRpppTuGdjfhT0H9nYb0buATehBqJq7Kg== X-Received: by 2002:a05:600c:1987:b0:3a3:2db1:d35b with SMTP id t7-20020a05600c198700b003a32db1d35bmr13271445wmq.14.1659445082711; Tue, 02 Aug 2022 05:58:02 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id t4-20020adfeb84000000b0021e45afa7b0sm15056145wrn.109.2022.08.02.05.58.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Aug 2022 05:58:02 -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 v7 04/10] git docs: add a category for user-facing file, repo and command UX Date: Tue, 2 Aug 2022 14:56:53 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1232.gc0cde427aa7 In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Create a new "Repository, command and file interfaces" section in the main "git help git" manual page. Move things that belong under this new criteria from the generic "Guides" section. The "Guides" section was added in f442f28a81b (git.txt: add list of guides, 2020-08-05). It makes sense to have e.g. "giteveryday(7)" and "gitfaq(7)" listed under "Guides". But placing e.g. "gitignore(5)" in it is stretching the meaning of what a "guide" is, ideally that section should list things similar to "giteveryday(7)" and "gitcore-tutorial(7)". An alternate name that was considered for this new section was "User formats", for consistency with the nomenclature used for man section 5 in general. My man(1) lists it as "File formats and conventions, e.g. /etc/passwd". So calling this "git help --formats" or "git help --user-formats" would make sense for e.g. gitignore(5), but would be stretching it somewhat for githooks(5), and would seem really suspect for the likes of gitcli(7). Let's instead pick a name that's closer to the generic term "User interface", which is really what this documentation discusses: General user-interface documentation that doesn't obviously belong elsewhere. Signed-off-by: Ævar Arnfjörð Bjarmason --- Documentation/Makefile | 1 + Documentation/git-help.txt | 14 ++++++++++++++ Documentation/git.txt | 8 ++++++++ Makefile | 1 + builtin/help.c | 9 +++++++++ command-list.txt | 21 +++++++++++++-------- help.c | 12 ++++++++++++ help.h | 1 + t/t0012-help.sh | 12 +++++++++++- 9 files changed, 70 insertions(+), 9 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 4f801f4e4c9..28eb940a9b8 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ cmds-synchingrepositories.txt \ cmds-synchelpers.txt \ cmds-guide.txt \ + cmds-userinterfaces.txt \ cmds-purehelpers.txt \ cmds-foreignscminterface.txt diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index bead763fd29..4eb03bd6c38 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -12,6 +12,7 @@ SYNOPSIS 'git help' [[-i|--info] [-m|--man] [-w|--web]] [|] 'git help' [-g|--guides] 'git help' [-c|--config] +'git help' [--user-interfaces] DESCRIPTION ----------- @@ -69,6 +70,19 @@ OPTIONS --guides:: Prints a list of the Git concept guides on the standard output. +--user-interfaces:: + Prints a list of the repository, command and file interfaces + documentation on the standard output. ++ +In-repository file interfaces such as `.git/info/exclude` are +documented here (see linkgit:gitrepository-layout[5]), as well as +in-tree configuration such as `.mailmap` (see linkgit:gitmailmap[5]). ++ +This section of the documentation also covers general or widespread +user-interface conventions (e.g. linkgit:gitcli[7]), and +pseudo-configuration such as the file-based `.git/hooks/*` interface +described in linkgit:githooks[5]. + -i:: --info:: Display manual page for the command in the 'info' format. The diff --git a/Documentation/git.txt b/Documentation/git.txt index 47a6095ff40..945a1ebd3b1 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -339,6 +339,14 @@ The following documentation pages are guides about Git concepts. include::cmds-guide.txt[] +Repository, command and file interfaces +--------------------------------------- + +This documentation discusses repository and command interfaces which +users are expected to interact with directly. See `--user-formats` in +linkgit:git-help[1] for more details on the critera. + +include::cmds-userinterfaces.txt[] Configuration Mechanism ----------------------- diff --git a/Makefile b/Makefile index 1624471badc..ea0ef7df734 100644 --- a/Makefile +++ b/Makefile @@ -3532,6 +3532,7 @@ check-docs:: sed -e '1,/^### command list/d' \ -e '/^#/d' \ -e '/guide$$/d' \ + -e '/interfaces$$/d' \ -e 's/[ ].*//' \ -e 's/^/listed /' command-list.txt; \ $(MAKE) -C Documentation print-man1 | \ diff --git a/builtin/help.c b/builtin/help.c index dec82d1be27..1ab1c8a0dd7 100644 --- a/builtin/help.c +++ b/builtin/help.c @@ -43,6 +43,7 @@ static enum help_action { HELP_ACTION_ALL = 1, HELP_ACTION_GUIDES, HELP_ACTION_CONFIG, + HELP_ACTION_USER_INTERFACES, HELP_ACTION_CONFIG_FOR_COMPLETION, HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION, } cmd_mode; @@ -69,6 +70,9 @@ static struct option builtin_help_options[] = { OPT_CMDMODE('g', "guides", &cmd_mode, N_("print list of useful guides"), HELP_ACTION_GUIDES), + OPT_CMDMODE(0, "user-interfaces", &cmd_mode, + N_("print list of user-facing repository, command and file interfaces"), + HELP_ACTION_USER_INTERFACES), OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"), HELP_ACTION_CONFIG), OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "", @@ -84,6 +88,7 @@ static const char * const builtin_help_usage[] = { N_("git help [[-i|--info] [-m|--man] [-w|--web]] [|]"), "git help [-g|--guides]", "git help [-c|--config]", + "git help [--user-interfaces]", NULL }; @@ -654,6 +659,10 @@ int cmd_help(int argc, const char **argv, const char *prefix) opt_mode_usage(argc, "--config-for-completion", help_format); list_config_help(SHOW_CONFIG_VARS); return 0; + case HELP_ACTION_USER_INTERFACES: + opt_mode_usage(argc, "--user-interfaces", help_format); + list_user_interfaces_help(); + return 0; case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION: opt_mode_usage(argc, "--config-sections-for-completion", help_format); diff --git a/command-list.txt b/command-list.txt index 9bd6f3c48f4..1d45303e14c 100644 --- a/command-list.txt +++ b/command-list.txt @@ -43,6 +43,11 @@ # specified here, which can only have "guide" attribute and nothing # else. # +# User-facing repository, command and file interfaces such as +# documentation for the .gitmodules, .mailmap etc. files lives in man +# sections 5 and 7. These entries can only have the "userinterfaces" +# attribute and nothing else. +# ### command list (do not change this line) # command name category [category] [category] git-add mainporcelain worktree @@ -192,8 +197,8 @@ git-verify-tag ancillaryinterrogators git-whatchanged ancillaryinterrogators complete git-worktree mainporcelain git-write-tree plumbingmanipulators -gitattributes guide -gitcli guide +gitattributes userinterfaces +gitcli userinterfaces gitcore-tutorial guide gitcredentials guide gitcvs-migration guide @@ -201,15 +206,15 @@ gitdiffcore guide giteveryday guide gitfaq guide gitglossary guide -githooks guide -gitignore guide +githooks userinterfaces +gitignore userinterfaces gitk mainporcelain -gitmailmap guide -gitmodules guide +gitmailmap userinterfaces +gitmodules userinterfaces gitnamespaces guide gitremote-helpers guide -gitrepository-layout guide -gitrevisions guide +gitrepository-layout userinterfaces +gitrevisions userinterfaces gitsubmodules guide gittutorial guide gittutorial-2 guide diff --git a/help.c b/help.c index 8a09f18a3d9..3e2a78863b7 100644 --- a/help.c +++ b/help.c @@ -38,6 +38,7 @@ static struct category_description main_categories[] = { { CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") }, { CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") }, { CAT_purehelpers, N_("Low-level Commands / Internal Helpers") }, + { CAT_userinterfaces, N_("User-facing repository, command and file interfaces") }, { 0, NULL } }; @@ -48,6 +49,7 @@ static const char *drop_prefix(const char *name, uint32_t category) switch (category) { case CAT_guide: + case CAT_userinterfaces: prefix = "git"; break; default: @@ -433,6 +435,16 @@ void list_guides_help(void) putchar('\n'); } +void list_user_interfaces_help(void) +{ + struct category_description catdesc[] = { + { CAT_userinterfaces, N_("User-facing repository, command and file interfaces:") }, + { 0, NULL } + }; + print_cmd_by_category(catdesc, NULL); + putchar('\n'); +} + static int get_alias(const char *var, const char *value, void *data) { struct string_list *list = data; diff --git a/help.h b/help.h index 971a3ad855a..243104c27a7 100644 --- a/help.h +++ b/help.h @@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num) void list_common_cmds_help(void); void list_all_cmds_help(int show_external_commands, int show_aliases); void list_guides_help(void); +void list_user_interfaces_help(void); void list_all_main_cmds(struct string_list *list); void list_all_other_cmds(struct string_list *list); diff --git a/t/t0012-help.sh b/t/t0012-help.sh index 6c33a436901..bee5ed12203 100755 --- a/t/t0012-help.sh +++ b/t/t0012-help.sh @@ -44,6 +44,8 @@ test_expect_success 'invalid usage' ' test_expect_code 129 git help -g add && test_expect_code 129 git help -a -g && + test_expect_code 129 git help --user-interfaces add && + test_expect_code 129 git help -g -c && test_expect_code 129 git help --config-for-completion add && test_expect_code 129 git help --config-sections-for-completion add @@ -104,9 +106,9 @@ test_expect_success 'git help' ' test_i18ngrep "^ commit " help.output && test_i18ngrep "^ fetch " help.output ' + test_expect_success 'git help -g' ' git help -g >help.output && - test_i18ngrep "^ attributes " help.output && test_i18ngrep "^ everyday " help.output && test_i18ngrep "^ tutorial " help.output ' @@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' ' test_cmp expect test-browser.log ' +test_expect_success 'git help --user-interfaces' ' + git help --user-interfaces >help.output && + grep "^ attributes " help.output && + grep "^ mailmap " help.output +' + test_expect_success 'git help -c' ' git help -c >help.output && cat >expect <<-\EOF && @@ -220,6 +228,8 @@ test_expect_success "'git help -a' section spacing" ' Low-level Commands / Syncing Repositories Low-level Commands / Internal Helpers + + User-facing repository, command and file interfaces EOF test_cmp expect actual ' From patchwork Tue Aug 2 12:56:54 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: 12934635 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 1DD8DC19F28 for ; Tue, 2 Aug 2022 12:58:29 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S236922AbiHBM62 (ORCPT ); Tue, 2 Aug 2022 08:58:28 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41836 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236925AbiHBM6H (ORCPT ); Tue, 2 Aug 2022 08:58:07 -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 8EB4D1580D for ; Tue, 2 Aug 2022 05:58:05 -0700 (PDT) Received: by mail-wm1-x32d.google.com with SMTP id c187-20020a1c35c4000000b003a30d88fe8eso8826661wma.2 for ; Tue, 02 Aug 2022 05:58:05 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc; bh=3dW+1xKlLvLlxKzgr/tHaHDb5MZPl4oe9nowe2+kGoc=; b=UmwjWo0l5HOxI6oUmckeDW8b2cys/LNSeA+U/7B0ayxFGhZyspJ76mahviuFC7FD5l Dhg4w3+HAejRMpqjYhq65djMNHAZBuh9yoK29W94cPbM8aFNjCpoAQruZlvZdtvDmele r9b3ThLXQbQf9vZRBukDDmKrVyWyK374L9rB8iw1WRLGgS3HgzjaVFD68uvyTZsWXbc2 n8Z4B+Yr14WOTfITwZ1Njox9PXiems5CCkuHLBkQ2xmtokeLt27UIfHi2HP+4bKAni/L i2bAXQR4bsWLzl+XSJhWvJAKNZK1iBofBggWmlXdzrh2sG2kSr8/swbgNB1ETDJrWd4I TSig== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc; bh=3dW+1xKlLvLlxKzgr/tHaHDb5MZPl4oe9nowe2+kGoc=; b=AGBN4aYZa/BDPeahdXwjMxIBoDPScvNiWTY1PLxWdeoYSaZLc/nr0AzVybbklMbxbf u/FGwjE3c5jQdlXDK6U17G8UJwRs8MHCW7Jtw3soQrLcaW3FpW50VjHEvCn6jfNPiL+3 cNAXFA4qujI+dEzG5YX8YFofUcoGB/GVhO/Hbcx4SjAHt+r/5CHnzS9F4c15ykMYUiQb D6Sdo99xu2SH71C5w8wmpDLeceFa06tTvwq/yNuni10YiJNvxg9691xek3pP+MombuJQ vHuNPDk85l0EsFEb21Jd3aSC/WBPxkvsE9Ol52rDRr50vPGXzZtDxyiE9VOA92HBtInl qYWQ== X-Gm-Message-State: AJIora/JBYO5zVFi0GKohaJ9JORIdlijODLKkzN2SqWPgqYq5IJX9lLY uw3060J+NxFvHIuXOpzsB3yZzbaCkgaDyQ== X-Google-Smtp-Source: AGRyM1tac7lc7LcbA+WfS00QJzKPjl6gojTAHr48bK0NT8rhoJZIblZSY2PNglmB48MrrKKEHQNL0w== X-Received: by 2002:a05:600c:5114:b0:3a3:3f7f:27ec with SMTP id o20-20020a05600c511400b003a33f7f27ecmr13701354wms.93.1659445083762; Tue, 02 Aug 2022 05:58:03 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id t4-20020adfeb84000000b0021e45afa7b0sm15056145wrn.109.2022.08.02.05.58.02 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Aug 2022 05:58:03 -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 v7 05/10] git docs: add a category for file formats, protocols and interfaces Date: Tue, 2 Aug 2022 14:56:54 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1232.gc0cde427aa7 In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Create a new "File formats, protocols and other developer interfaces" section in the main "git help git" manual page and start moving the documentation that now lives in "Documentation/technical/*.git" over to it. This complements the newly added and adjacent "Repository, command and file interfaces" section. This makes the technical documentation more accessible and discoverable. Before this we wouldn't install it by default, and had no ability to build man page versions of them. The links to them from our existing documentation link to the generated HTML version of these docs. So let's start moving those over, starting with just the "bundle-format.txt" documentation added in 7378ec90e1c (doc: describe Git bundle format, 2020-02-07). We'll now have a new gitformat-bundle(5) man page. Subsequent commits will move more git internal format documentation over. Unfortunately the syntax of the current Documentation/technical/*.txt is not the same (when it comes to section headings etc.) as our Documentation/*.txt documentation, so change the relevant bits of syntax as we're moving this over. Signed-off-by: Ævar Arnfjörð Bjarmason --- Documentation/Makefile | 3 +- Documentation/git-bundle.txt | 14 +++--- Documentation/git-help.txt | 5 +++ Documentation/git.txt | 9 ++++ ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++--- Documentation/lint-man-section-order.perl | 3 ++ builtin/help.c | 9 ++++ command-list.txt | 5 +++ help.c | 12 +++++ help.h | 1 + t/t0012-help.sh | 2 + 11 files changed, 94 insertions(+), 13 deletions(-) rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%) diff --git a/Documentation/Makefile b/Documentation/Makefile index 28eb940a9b8..1a4a545f44a 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -24,6 +24,7 @@ MAN1_TXT += gitweb.txt # man5 / man7 guides (note: new guides should also be added to command-list.txt) MAN5_TXT += gitattributes.txt +MAN5_TXT += gitformat-bundle.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt MAN5_TXT += gitmailmap.txt @@ -95,7 +96,6 @@ TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches TECH_DOCS += ToolsForGit TECH_DOCS += technical/bitmap-format -TECH_DOCS += technical/bundle-format TECH_DOCS += technical/cruft-packs TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol @@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ cmds-synchingrepositories.txt \ cmds-synchelpers.txt \ cmds-guide.txt \ + cmds-developerinterfaces.txt \ cmds-userinterfaces.txt \ cmds-purehelpers.txt \ cmds-foreignscminterface.txt diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 7685b570455..f0b1282b918 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -56,10 +56,9 @@ using "thin packs", bundles created using exclusions are smaller in size. That they're "thin" under the hood is merely noted here as a curiosity, and as a reference to other documentation. -See link:technical/bundle-format.html[the `bundle-format` -documentation] for more details and the discussion of "thin pack" in -link:technical/pack-format.html[the pack format documentation] for -further details. +See linkgit:gitformat-bundle[5] for more details and the discussion of +"thin pack" in link:technical/pack-format.html[the pack format +documentation] for further details. OPTIONS ------- @@ -77,7 +76,7 @@ verify :: commits exist and are fully linked in the current repository. Then, 'git bundle' prints a list of missing commits, if any. Finally, information about additional capabilities, such as "object - filter", is printed. See "Capabilities" in link:technical/bundle-format.html + filter", is printed. See "Capabilities" in linkgit:gitformat-bundle[5] for more information. The exit code is zero for success, but will be nonzero if the bundle file is invalid. @@ -337,6 +336,11 @@ You can also see what references it offers: $ git ls-remote mybundle ---------------- +FILE FORMAT +----------- + +See linkgit:gitformat-bundle[5]. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 4eb03bd6c38..2b0b5e390dc 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -13,6 +13,7 @@ SYNOPSIS 'git help' [-g|--guides] 'git help' [-c|--config] 'git help' [--user-interfaces] +'git help' [--developer-interfaces] DESCRIPTION ----------- @@ -83,6 +84,10 @@ user-interface conventions (e.g. linkgit:gitcli[7]), and pseudo-configuration such as the file-based `.git/hooks/*` interface described in linkgit:githooks[5]. +--developer-interfaces:: + Print list of file formats, protocols and other developer + interfaces documentation on the standard output. + -i:: --info:: Display manual page for the command in the 'info' format. The diff --git a/Documentation/git.txt b/Documentation/git.txt index 945a1ebd3b1..0ef7f5e4ece 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -348,6 +348,15 @@ linkgit:git-help[1] for more details on the critera. include::cmds-userinterfaces.txt[] +File formats, protocols and other developer interfaces +------------------------------------------------------ + +This documentation discusses file formats, over-the-wire protocols and +other git developer interfaces. See `--developer-interfaces` in +linkgit:git-help[1]. + +include::cmds-developerinterfaces.txt[] + Configuration Mechanism ----------------------- diff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt similarity index 79% rename from Documentation/technical/bundle-format.txt rename to Documentation/gitformat-bundle.txt index 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 1ab1c8a0dd7..09ac4289f13 100644 --- a/builtin/help.c +++ b/builtin/help.c @@ -44,6 +44,7 @@ static enum help_action { HELP_ACTION_GUIDES, HELP_ACTION_CONFIG, HELP_ACTION_USER_INTERFACES, + HELP_ACTION_DEVELOPER_INTERFACES, HELP_ACTION_CONFIG_FOR_COMPLETION, HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION, } cmd_mode; @@ -73,6 +74,9 @@ static struct option builtin_help_options[] = { OPT_CMDMODE(0, "user-interfaces", &cmd_mode, N_("print list of user-facing repository, command and file interfaces"), HELP_ACTION_USER_INTERFACES), + OPT_CMDMODE(0, "developer-interfaces", &cmd_mode, + N_("print list of file formats, protocols and other developer interfaces"), + HELP_ACTION_DEVELOPER_INTERFACES), OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"), HELP_ACTION_CONFIG), OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "", @@ -89,6 +93,7 @@ static const char * const builtin_help_usage[] = { "git help [-g|--guides]", "git help [-c|--config]", "git help [--user-interfaces]", + "git help [--developer-interfaces]", NULL }; @@ -663,6 +668,10 @@ int cmd_help(int argc, const char **argv, const char *prefix) opt_mode_usage(argc, "--user-interfaces", help_format); list_user_interfaces_help(); return 0; + case HELP_ACTION_DEVELOPER_INTERFACES: + opt_mode_usage(argc, "--developer-interfaces", help_format); + list_developer_interfaces_help(); + return 0; case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION: opt_mode_usage(argc, "--config-sections-for-completion", help_format); diff --git a/command-list.txt b/command-list.txt index 1d45303e14c..1950c4ccd9c 100644 --- a/command-list.txt +++ b/command-list.txt @@ -48,6 +48,10 @@ # sections 5 and 7. These entries can only have the "userinterfaces" # attribute and nothing else. # +# Git's file formats and protocols, such as documentation for the +# *.bundle format lives in man section 5. These entries can only have +# the "developerinterfaces" attribute and nothing else. +# ### command list (do not change this line) # command name category [category] [category] git-add mainporcelain worktree @@ -205,6 +209,7 @@ gitcvs-migration guide gitdiffcore guide giteveryday guide gitfaq guide +gitformat-bundle developerinterfaces gitglossary guide githooks userinterfaces gitignore userinterfaces diff --git a/help.c b/help.c index 3e2a78863b7..991e33f8a6e 100644 --- a/help.c +++ b/help.c @@ -39,6 +39,7 @@ static struct category_description main_categories[] = { { CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") }, { CAT_purehelpers, N_("Low-level Commands / Internal Helpers") }, { CAT_userinterfaces, N_("User-facing repository, command and file interfaces") }, + { CAT_developerinterfaces, N_("Developer-facing file file formats, protocols and interfaces") }, { 0, NULL } }; @@ -50,6 +51,7 @@ static const char *drop_prefix(const char *name, uint32_t category) switch (category) { case CAT_guide: case CAT_userinterfaces: + case CAT_developerinterfaces: prefix = "git"; break; default: @@ -445,6 +447,16 @@ void list_user_interfaces_help(void) putchar('\n'); } +void list_developer_interfaces_help(void) +{ + struct category_description catdesc[] = { + { CAT_developerinterfaces, N_("File formats, protocols and other developer interfaces:") }, + { 0, NULL } + }; + print_cmd_by_category(catdesc, NULL); + putchar('\n'); +} + static int get_alias(const char *var, const char *value, void *data) { struct string_list *list = data; diff --git a/help.h b/help.h index 243104c27a7..af073a7a026 100644 --- a/help.h +++ b/help.h @@ -23,6 +23,7 @@ void list_common_cmds_help(void); void list_all_cmds_help(int show_external_commands, int show_aliases); void list_guides_help(void); void list_user_interfaces_help(void); +void list_developer_interfaces_help(void); void list_all_main_cmds(struct string_list *list); void list_all_other_cmds(struct string_list *list); diff --git a/t/t0012-help.sh b/t/t0012-help.sh index bee5ed12203..4ed2f242eb2 100755 --- a/t/t0012-help.sh +++ b/t/t0012-help.sh @@ -230,6 +230,8 @@ test_expect_success "'git help -a' section spacing" ' Low-level Commands / Internal Helpers User-facing repository, command and file interfaces + + Developer-facing file file formats, protocols and interfaces EOF test_cmp expect actual ' From patchwork Tue Aug 2 12:56:55 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: 12934636 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 55F93C00140 for ; Tue, 2 Aug 2022 12:58:32 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S236752AbiHBM6a (ORCPT ); Tue, 2 Aug 2022 08:58:30 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41852 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236939AbiHBM6I (ORCPT ); Tue, 2 Aug 2022 08:58:08 -0400 Received: from mail-wm1-x32e.google.com (mail-wm1-x32e.google.com [IPv6:2a00:1450:4864:20::32e]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E17F012616 for ; Tue, 2 Aug 2022 05:58:06 -0700 (PDT) Received: by mail-wm1-x32e.google.com with SMTP id i128-20020a1c3b86000000b003a3a22178beso221222wma.3 for ; Tue, 02 Aug 2022 05:58:06 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc; bh=m4KKQWfNYzNH8mujpFsFBo2PP/tjf0m9MzNBSqePNWk=; b=VzS5nuf1qaYj9sqcUMx9bndgghmeAIIcHKkvM3LNhQUW3uI3YcRf1jhELYxnYjlFZ7 AyEFxwvRPWjFKqSDUKqpQZYk9e3frxTJdJ6DOWXvClAUpZwtOuyWDhF5Jg2iRKmtJyNl 8hWFfLM2MOgdcx26acoVWPJfyrIx3y+icdKt9vDTP9w8mgcOcyEQp05l8NdTNG91sJqN iQhf/JAxuEInlHI+usKQJ3L6JuaPKJ95iZikwI8HBYv9zDeLChzd1D/An4YVnRMq3Hqx Y2xpgZpwO2MOuRez/BSBAlPSsRyUQtLQUOeh/W0f7zrKOaOXGXkAPIDWpHvGx5wJD17Q Df3w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc; bh=m4KKQWfNYzNH8mujpFsFBo2PP/tjf0m9MzNBSqePNWk=; b=jXTGNW8QiLCOBabC8O9f20zdNTUqbILUpeT0p36Fgchk7BrZcrkwOa7QRefjso6wbX OaW1RJK9RnqRZ4hLeF+1KLbMmLIGpcssx3YmxMIP9GBz/8L+PJHusYsKsAeLt+VIJq3U xYS9BYzSM6eurPVtXkfzF6XNYLcjEi7P2mjAclzcvomz0rJgPaRWFKMcaI2UbD7udVlK DZNysbwB+J4A6OyjP6V4oy6wq8LhxbMYP+DJNxzeduDL/B0jjA+1nzFsRqnmvm1FX855 xo3lDRmUFE2lZ0dcbdNv6VoeyU5PPbywMvEawT8kITl0D9FzLvbMkP+SeKKWgrni15Z8 uS2w== X-Gm-Message-State: AJIora+oQQpSpKVmE8FhdHEf5NwCFKrJNb1V5vh/fOyY9mwVZxRjxpKf dXyTobOCawaYd+z3/Q8UCCNKX/GfACyZjw== X-Google-Smtp-Source: AGRyM1ulXq9rYgHhgsXsvJIZAPYS9OJjuRQpGnyb5txFIR1M6QUFe7kqiGd5qxqpVaUXwpj0WQQ9nQ== X-Received: by 2002:a05:600c:35c6:b0:3a3:4217:f06e with SMTP id r6-20020a05600c35c600b003a34217f06emr13633307wmq.95.1659445084915; Tue, 02 Aug 2022 05:58:04 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id t4-20020adfeb84000000b0021e45afa7b0sm15056145wrn.109.2022.08.02.05.58.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Aug 2022 05:58:04 -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 v7 06/10] docs: move commit-graph format docs to man section 5 Date: Tue, 2 Aug 2022 14:56:55 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1232.gc0cde427aa7 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 "developerinterfaces" category. This change is split from subsequent commits due to the relatively large amount of ASCIIDOC formatting changes that are required. Signed-off-by: Ævar Arnfjörð Bjarmason --- 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 | 2 + 5 files changed, 42 insertions(+), 17 deletions(-) rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (88%) diff --git a/Documentation/Makefile b/Documentation/Makefile index 1a4a545f44a..e7bd72bb84e 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 1950c4ccd9c..44e244a76f6 100644 --- a/command-list.txt +++ b/command-list.txt @@ -210,6 +210,8 @@ gitdiffcore guide giteveryday guide gitfaq guide gitformat-bundle developerinterfaces +gitformat-bundle developerinterfaces +gitformat-commit-graph developerinterfaces gitglossary guide githooks userinterfaces gitignore userinterfaces From patchwork Tue Aug 2 12:56:56 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: 12934637 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 AEDEFC19F28 for ; Tue, 2 Aug 2022 12:58:33 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S237018AbiHBM6d (ORCPT ); Tue, 2 Aug 2022 08:58:33 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41866 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236944AbiHBM6K (ORCPT ); Tue, 2 Aug 2022 08:58:10 -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 337EF15FC1 for ; Tue, 2 Aug 2022 05:58:07 -0700 (PDT) Received: by mail-wm1-x32c.google.com with SMTP id v131-20020a1cac89000000b003a4bb3f786bso3093997wme.0 for ; Tue, 02 Aug 2022 05:58:07 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc; bh=IP8pd/9PNNEE3llshjGOZ7KuaI8sljZivdRQ7GbvJjA=; b=iEokziOCRdaWEu7wFnN5NfW/Ya2QC4xi9i1AWfjtpH7gHd3i0jpfW149qiBXOW6Gku l5gGW8FM4SEIi8hyxeowuaC/11UbnJ62cX7brXq9A1P2N7FTgwoAcLoVa1yl2rPUyrgM DMEe2lFku3fPmemRyCYtjRcOfl/tLyQwTLSKkltjPXTcmtQYGkRo8PSJt9sewdABSXNC MfYOnAblI3L2ROY1oSZOzNCMNoh4excSmKFjqk2JmgbNM/4mONYheL5VhAVk/uQoy9uf k4dQ3QObjMkAUE9Wz+CN0Rjqp9BIH6WMED3XaHtknOPkcNn9lzHzQg+ssWyOxssS0h6X yKaQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc; bh=IP8pd/9PNNEE3llshjGOZ7KuaI8sljZivdRQ7GbvJjA=; b=bEu92I4WcNsoOQnsENK+UxESyL7HsruldQ5iuDXrKiOlE6rzFMTtPjGuCEralPwr7p x7JioI/V6gxLU1iTAC1eCihJNC3h1MYDCTFiCZKr4FhvZioWfVGmjpp+qu3q2LZ52+/7 6rec7RESTCIarp63A3ysLmwG2Xl2rC9nzrbkbYo3KElu+95CNknIhB6A5nemcR+ax11x 31vFxBA9tjGNclrgS36I1YkmzT4dOSFFjeNXMICQuG9vvQv9RfFkHT0bIHZfN5mLnADg kHUWdunlVclgXxHkWjGR/HkPQVG9Fc2wcQJJwhFz+2X6Xmav+da8KGwNBZylOehIOlPr R9cQ== X-Gm-Message-State: AJIora9/Vh1LYm6tQ3zlgHMcNErfW7hAalRRaJi7AIPgu+96ISUMnnuB VXXa1jCy/Prful7vkVgQLKXbm5FsDUdkOw== X-Google-Smtp-Source: AGRyM1uFAdBisg8tMAyLxhsdrPmJFJp1eyJCM2SbbvvXw5Gd1n7/F6pEiR9iPHWouoGdMOPkkliSGw== X-Received: by 2002:a7b:c7d2:0:b0:3a3:209d:cdc6 with SMTP id z18-20020a7bc7d2000000b003a3209dcdc6mr14629929wmk.55.1659445086123; Tue, 02 Aug 2022 05:58:06 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id t4-20020adfeb84000000b0021e45afa7b0sm15056145wrn.109.2022.08.02.05.58.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Aug 2022 05:58:05 -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 v7 07/10] docs: move protocol-related docs to man section 5 Date: Tue, 2 Aug 2022 14:56:56 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1232.gc0cde427aa7 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. So far we have been using the "gitformat-" prefix for the documentation we've been moving over from Documentation/technical/*, but for protocol documentation let's use "gitprotocol-*". Signed-off-by: Ævar Arnfjörð Bjarmason --- Documentation/Makefile | 8 +++--- Documentation/config/lsrefs.txt | 2 +- Documentation/config/protocol.txt | 2 +- Documentation/git-upload-pack.txt | 5 ++-- Documentation/gitformat-bundle.txt | 2 +- ...ities.txt => gitprotocol-capabilities.txt} | 28 +++++++++++++++---- ...ocol-common.txt => gitprotocol-common.txt} | 23 +++++++++++++-- ...pack-protocol.txt => gitprotocol-pack.txt} | 24 +++++++++++++--- .../protocol-v2.txt => gitprotocol-v2.txt} | 25 +++++++++++++---- Documentation/technical/api-simple-ipc.txt | 2 +- Documentation/technical/http-protocol.txt | 6 ++-- .../long-running-process-protocol.txt | 2 +- Documentation/technical/packfile-uri.txt | 2 +- Documentation/technical/partial-clone.txt | 2 +- command-list.txt | 5 +++- refspec.h | 2 +- t/t5551-http-fetch-smart.sh | 4 +-- 17 files changed, 106 insertions(+), 38 deletions(-) rename Documentation/{technical/protocol-capabilities.txt => gitprotocol-capabilities.txt} (96%) rename Documentation/{technical/protocol-common.txt => gitprotocol-common.txt} (89%) rename Documentation/{technical/pack-protocol.txt => gitprotocol-pack.txt} (98%) rename Documentation/{technical/protocol-v2.txt => gitprotocol-v2.txt} (98%) diff --git a/Documentation/Makefile b/Documentation/Makefile index e7bd72bb84e..b53f3c12843 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -30,6 +30,10 @@ MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt MAN5_TXT += gitmailmap.txt MAN5_TXT += gitmodules.txt +MAN5_TXT += gitprotocol-capabilities.txt +MAN5_TXT += gitprotocol-common.txt +MAN5_TXT += gitprotocol-pack.txt +MAN5_TXT += gitprotocol-v2.txt MAN5_TXT += gitrepository-layout.txt MAN5_TXT += gitweb.conf.txt @@ -105,12 +109,8 @@ TECH_DOCS += technical/long-running-process-protocol TECH_DOCS += technical/multi-pack-index TECH_DOCS += technical/pack-format TECH_DOCS += technical/pack-heuristics -TECH_DOCS += technical/pack-protocol TECH_DOCS += technical/parallel-checkout TECH_DOCS += technical/partial-clone -TECH_DOCS += technical/protocol-capabilities -TECH_DOCS += technical/protocol-common -TECH_DOCS += technical/protocol-v2 TECH_DOCS += technical/racy-git TECH_DOCS += technical/reftable TECH_DOCS += technical/send-pack-pipeline diff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.txt index adeda0f24d3..3d88fb0badb 100644 --- a/Documentation/config/lsrefs.txt +++ b/Documentation/config/lsrefs.txt @@ -1,7 +1,7 @@ lsrefs.unborn:: May be "advertise" (the default), "allow", or "ignore". If "advertise", the server will respond to the client sending "unborn" (as described in - protocol-v2.txt) and will advertise support for this feature during the + linkgit:gitprotocol-v2[5]) and will advertise support for this feature during the protocol v2 capability advertisement. "allow" is the same as "advertise" except that the server will not advertise support for this feature; this is useful for load-balanced servers that cannot be diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt index 756591d77b0..57603818514 100644 --- a/Documentation/config/protocol.txt +++ b/Documentation/config/protocol.txt @@ -58,6 +58,6 @@ protocol.version:: * `1` - the original wire protocol with the addition of a version string in the initial response from the server. -* `2` - link:technical/protocol-v2.html[wire protocol version 2]. +* `2` - Wire protocol version 2, see linkgit:gitprotocol-v2[5]. -- diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 8f87b23ea86..3409e0d36d1 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -40,9 +40,8 @@ OPTIONS Used by linkgit:git-http-backend[1] to serve up `$GIT_URL/info/refs?service=git-upload-pack` requests. See "Smart Clients" in link:technical/http-protocol.html[the HTTP - transfer protocols] documentation and "HTTP Transport" in - link:technical/protocol-v2.html[the Git Wire Protocol, Version - 2] documentation. Also understood by + transfer protocols] documentation and "HTTP Transport" in the + linkgit:gitprotocol-v2[5] documentation. Also understood by linkgit:git-receive-pack[1]. :: diff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.txt index 6a9d9e5bf6f..00e0a20e657 100644 --- a/Documentation/gitformat-bundle.txt +++ b/Documentation/gitformat-bundle.txt @@ -27,7 +27,7 @@ FORMAT ------ We will use ABNF notation to define the Git bundle format. See -link:technical/protocol-common.html for the details. +linkgit:gitprotocol-common[5] for the details. A v2 bundle looks like this: diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/gitprotocol-capabilities.txt similarity index 96% rename from Documentation/technical/protocol-capabilities.txt rename to Documentation/gitprotocol-capabilities.txt index 9dfade930da..c6dcc7d565d 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/gitprotocol-capabilities.txt @@ -1,8 +1,20 @@ -Git Protocol Capabilities -========================= +gitprotocol-capabilities(5) +=========================== + +NAME +---- +gitprotocol-capabilities - Protocol v0 and v1 capabilities + +SYNOPSIS +-------- +[verse] + + +DESCRIPTION +----------- NOTE: this document describes capabilities for versions 0 and 1 of the pack -protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2] +protocol. For version 2, please refer to the linkgit:gitprotocol-v2[5] doc. Servers SHOULD support all capabilities defined in this document. @@ -77,7 +89,7 @@ interleaved with S-R-Q. multi_ack_detailed ------------------ This is an extension of multi_ack that permits client to better -understand the server's in-memory state. See pack-protocol.txt, +understand the server's in-memory state. See linkgit:gitprotocol-pack[5], section "Packfile Negotiation" for more information. no-done @@ -281,7 +293,7 @@ a packfile upload and reference update. If the pushing client requests this capability, after unpacking and updating references the server will respond with whether the packfile unpacked successfully and if each reference was updated successfully. If any of those were not -successful, it will send back an error message. See pack-protocol.txt +successful, it will send back an error message. See linkgit:gitprotocol-pack[5] for example messages. report-status-v2 @@ -292,7 +304,7 @@ adding new "option" directives in order to support reference rewritten by the "proc-receive" hook. The "proc-receive" hook may handle a command for a pseudo-reference which may create or update a reference with different name, new-oid, and old-oid. While the capability -'report-status' cannot report for such case. See pack-protocol.txt +'report-status' cannot report for such case. See linkgit:gitprotocol-pack[5] for details. delete-refs @@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The current implementation uses trace2 session IDs (see link:api-trace2.html[api-trace2] for details), but this may change and users of the session ID should not rely on this fact. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/protocol-common.txt b/Documentation/gitprotocol-common.txt similarity index 89% rename from Documentation/technical/protocol-common.txt rename to Documentation/gitprotocol-common.txt index ecedb34bba5..1486651bd10 100644 --- a/Documentation/technical/protocol-common.txt +++ b/Documentation/gitprotocol-common.txt @@ -1,5 +1,20 @@ -Documentation Common to Pack and Http Protocols -=============================================== +gitprotocol-common(5) +===================== + +NAME +---- +gitprotocol-common - Things common to various protocols + +SYNOPSIS +-------- +[verse] + + +DESCRIPTION +----------- + +This document sets defines things common to various over-the-wire +protocols and file formats used in Git. ABNF Notation ------------- @@ -97,3 +112,7 @@ Examples (as C-style strings): "000bfoobar\n" "foobar\n" "0004" "" ---- + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitprotocol-pack.txt similarity index 98% rename from Documentation/technical/pack-protocol.txt rename to Documentation/gitprotocol-pack.txt index e13a2c064d1..8a4de6decd0 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/gitprotocol-pack.txt @@ -1,5 +1,17 @@ -Packfile transfer protocols -=========================== +gitprotocol-pack(5) +=================== + +NAME +---- +gitprotocol-pack - How packs are transferred over-the-wire + +SYNOPSIS +-------- +[verse] + + +DESCRIPTION +----------- Git supports transferring data in packfiles over the ssh://, git://, http:// and file:// transports. There exist two sets of protocols, one for pushing @@ -18,7 +30,7 @@ pkt-line Format --------------- The descriptions below build on the pkt-line format described in -protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless +linkgit:gitprotocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless otherwise noted the usual pkt-line LF rules apply: the sender SHOULD include a LF, but the receiver MUST NOT complain if it is not present. @@ -60,7 +72,7 @@ Each Extra Parameter takes the form of `=` or ``. Servers that receive any such Extra Parameters MUST ignore all unrecognized keys. Currently, the only Extra Parameter recognized is -"version" with a value of '1' or '2'. See protocol-v2.txt for more +"version" with a value of '1' or '2'. See linkgit:gitprotocol-v2[5] for more information on protocol version 2. Git Transport @@ -707,3 +719,7 @@ An example client/server communication might look like this: S: 0018ok refs/heads/debug\n S: 002ang refs/heads/master non-fast-forward\n ---- + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/gitprotocol-v2.txt similarity index 98% rename from Documentation/technical/protocol-v2.txt rename to Documentation/gitprotocol-v2.txt index 8a877d27e23..d6105e07408 100644 --- a/Documentation/technical/protocol-v2.txt +++ b/Documentation/gitprotocol-v2.txt @@ -1,5 +1,17 @@ -Git Wire Protocol, Version 2 -============================ +gitprotocol-v2(5) +================= + +NAME +---- +gitprotocol-v2 - Git Wire Protocol, Version 2 + +SYNOPSIS +-------- +[verse] + + +DESCRIPTION +----------- This document presents a specification for a version 2 of Git's wire protocol. Protocol v2 will improve upon v1 in the following ways: @@ -26,8 +38,7 @@ Packet-Line Framing ------------------- All communication is done using packet-line framing, just as in v1. See -`Documentation/technical/pack-protocol.txt` and -`Documentation/technical/protocol-common.txt` for more information. +linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-common[5] for more information. In protocol v2 these special packets will have the following semantics: @@ -42,7 +53,7 @@ Initial Client Request In general a client can request to speak protocol v2 by sending `version=2` through the respective side-channel for the transport being used which inevitably sets `GIT_PROTOCOL`. More information can be -found in `pack-protocol.txt` and `http-protocol.txt`, as well as the +found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the `GIT_PROTOCOL` definition in `git.txt`. In all cases the response from the server is the capability advertisement. @@ -566,3 +577,7 @@ and associated requested information, each separated by a single space. attr = "size" obj-info = obj-id SP obj-size + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt index d79ad323e67..d44ada98e7d 100644 --- a/Documentation/technical/api-simple-ipc.txt +++ b/Documentation/technical/api-simple-ipc.txt @@ -78,7 +78,7 @@ client and an optional response message from the server. Both the client and server messages are unlimited in length and are terminated with a flush packet. -The pkt-line routines (Documentation/technical/protocol-common.txt) +The pkt-line routines (linkgit:gitprotocol-common[5]) are used to simplify buffer management during message generation, transmission, and reception. A flush packet is used to mark the end of the message. This allows the sender to incrementally generate and diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt index cc5126cfeda..8bd672d55bb 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/technical/http-protocol.txt @@ -222,7 +222,7 @@ smart server reply: S: 0000 The client may send Extra Parameters (see -Documentation/technical/pack-protocol.txt) as a colon-separated string +linkgit:gitprotocol-pack[5]) as a colon-separated string in the Git-Protocol HTTP header. Uses the `--http-backend-info-refs` option to @@ -518,5 +518,5 @@ References http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)] http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1] -link:technical/pack-protocol.html -link:technical/protocol-capabilities.html +linkgit:gitprotocol-pack[5] +linkgit:gitprotocol-capabilities[5] diff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt index aa0aa9af1c2..6f33654b428 100644 --- a/Documentation/technical/long-running-process-protocol.txt +++ b/Documentation/technical/long-running-process-protocol.txt @@ -3,7 +3,7 @@ Long-running process protocol This protocol is used when Git needs to communicate with an external process throughout the entire life of a single Git command. All -communication is in pkt-line format (see technical/protocol-common.txt) +communication is in pkt-line format (see linkgit:gitprotocol-common[5]) over standard input and standard output. Handshake diff --git a/Documentation/technical/packfile-uri.txt b/Documentation/technical/packfile-uri.txt index 1eb525fe760..9d453d47651 100644 --- a/Documentation/technical/packfile-uri.txt +++ b/Documentation/technical/packfile-uri.txt @@ -18,7 +18,7 @@ a `packfile-uris` argument, the server MAY send a `packfile-uris` section directly before the `packfile` section (right after `wanted-refs` if it is sent) containing URIs of any of the given protocols. The URIs point to packfiles that use only features that the client has declared that it supports -(e.g. ofs-delta and thin-pack). See protocol-v2.txt for the documentation of +(e.g. ofs-delta and thin-pack). See linkgit:gitprotocol-v2[5] for the documentation of this section. Clients should then download and index all the given URIs (in addition to diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt index 99f0eb30406..92fcee2bfff 100644 --- a/Documentation/technical/partial-clone.txt +++ b/Documentation/technical/partial-clone.txt @@ -79,7 +79,7 @@ Design Details upload-pack negotiation. + This uses the existing capability discovery mechanism. -See "filter" in Documentation/technical/pack-protocol.txt. +See "filter" in linkgit:gitprotocol-pack[5]. - Clients pass a "filter-spec" to clone and fetch which is passed to the server to request filtering during packfile construction. diff --git a/command-list.txt b/command-list.txt index 44e244a76f6..ed859fdd798 100644 --- a/command-list.txt +++ b/command-list.txt @@ -210,7 +210,6 @@ gitdiffcore guide giteveryday guide gitfaq guide gitformat-bundle developerinterfaces -gitformat-bundle developerinterfaces gitformat-commit-graph developerinterfaces gitglossary guide githooks userinterfaces @@ -219,6 +218,10 @@ gitk mainporcelain gitmailmap userinterfaces gitmodules userinterfaces gitnamespaces guide +gitprotocol-capabilities developerinterfaces +gitprotocol-common developerinterfaces +gitprotocol-pack developerinterfaces +gitprotocol-v2 developerinterfaces gitremote-helpers guide gitrepository-layout userinterfaces gitrevisions userinterfaces diff --git a/refspec.h b/refspec.h index 8b79891d321..8c0c4469933 100644 --- a/refspec.h +++ b/refspec.h @@ -69,7 +69,7 @@ int valid_remote_name(const char *name); struct strvec; /* * Determine what values to pass to the peer in ref-prefix lines - * (see Documentation/technical/protocol-v2.txt). + * (see linkgit:gitprotocol-v2[5]). */ void refspec_ref_prefixes(const struct refspec *rs, struct strvec *ref_prefixes); diff --git a/t/t5551-http-fetch-smart.sh b/t/t5551-http-fetch-smart.sh index 245532df881..6a38294a476 100755 --- a/t/t5551-http-fetch-smart.sh +++ b/t/t5551-http-fetch-smart.sh @@ -181,8 +181,8 @@ test_expect_success 'no-op half-auth fetch does not require a password' ' # This is not possible with protocol v2, since both objects and refs # are obtained from the "git-upload-pack" path. A solution to this is # to teach the server and client to be able to inline ls-refs requests - # as an Extra Parameter (see pack-protocol.txt), so that "info/refs" - # can serve refs, just like it does in protocol v0. + # as an Extra Parameter (see "git help gitformat-pack-protocol"), so that + # "info/refs" can serve refs, just like it does in protocol v0. GIT_TEST_PROTOCOL_VERSION=0 git --git-dir=half-auth fetch && expect_askpass none ' From patchwork Tue Aug 2 12:56:57 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: 12934639 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 B4BEFC00140 for ; Tue, 2 Aug 2022 12:58:38 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S237100AbiHBM6g (ORCPT ); Tue, 2 Aug 2022 08:58:36 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41892 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232503AbiHBM6L (ORCPT ); Tue, 2 Aug 2022 08:58:11 -0400 Received: from mail-wr1-x436.google.com (mail-wr1-x436.google.com [IPv6:2a00:1450:4864:20::436]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C10F5167C9 for ; Tue, 2 Aug 2022 05:58:09 -0700 (PDT) Received: by mail-wr1-x436.google.com with SMTP id p10so13600002wru.8 for ; Tue, 02 Aug 2022 05:58:09 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc; bh=qAE3GgdgSVK/h0NHYhjwyohvZj6J+6zw80ONnQeKIeY=; b=RP5d8ZU1zAyyF02sv4qvwQXgGNVqyPmUYj8GnLfjI2Sg5QyNicDsDe6hX1Czgm+IcQ UG1zJr5WlLqv3v0V8f/eowQ8jiA4KK2RDTxQTN3EoqB6nwX3svp2usNEFZrakhxXmoB7 Lo612vv+chN0dJFfvyhROUkt0Imo8ZCgeKQhtJg50GWfQ7kARyKVx9Z38zOUBCQIMgH7 4rHYQWswGtfOqa4ZPLq4AUBtqvh2G7gPGzltIZRlDzOeJ3X9WnAjcSxQXVg8hFuMeVeu Ht8DYHEeEmdLFWdxBmbUiubnM96KqZ/vDUQ9G2G7n4yrs2USK4fsmUR5UZ6qxhzoOPCI dm8Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc; bh=qAE3GgdgSVK/h0NHYhjwyohvZj6J+6zw80ONnQeKIeY=; b=C+b2MHAm0Hok8S1i1uRqwKe3MH7q4VsaRIb7CA1j0yscrD30xKBdzi1ZhhmZxtAK1b 1FZ0DkGV0ApL8PAbxdVAk8Lzf9QOC1GeqkeJCEM5vHbIZ2kwU1MJKK+jiaJbjsnbJUUu TlJ7IAWwFWCT8YjwcmOzN00Aiyczrid5eXsjjggZOg8cBCDoljixkuNRUJeZdwrQjkLu 5p7FHIS0VIxUs4fhE+/RGW9Gl1bKMij4X/zs8aNB57d7Qkgs2ROpEFuxsdbIlVx6znc8 nz3h7Y3npFSdOVPcXvru48mmj8SeDrCWUAmON/NsrK28/lsYhHRj8pmWW7onuZIqDzce vbrQ== X-Gm-Message-State: ACgBeo3hVcVI+lWVoNU/tQjd8wtWqzHp4yWuEyWt0KvrUZ/Aguu34jbx CbHHWanPVKcWZYCVAmJkf+x6GTP1AdZ1Iw== X-Google-Smtp-Source: AA6agR6X2S6iQav/LQiFy6uJuZPhjZUdjVJ9LWoY+sTP7QGYm3hG34JX7Fvjz+mEgDaBTamXUk0bwg== X-Received: by 2002:a05:6000:cf:b0:21e:f6e2:e90e with SMTP id q15-20020a05600000cf00b0021ef6e2e90emr13356780wrx.404.1659445087490; Tue, 02 Aug 2022 05:58:07 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id t4-20020adfeb84000000b0021e45afa7b0sm15056145wrn.109.2022.08.02.05.58.06 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Aug 2022 05:58:06 -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 v7 08/10] docs: move pack format docs to man section 5 Date: Tue, 2 Aug 2022 14:56:57 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1232.gc0cde427aa7 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} | 25 +++++++++++--- Documentation/gitformat-commit-graph.txt | 2 +- .../index-format.txt => gitformat-index.txt} | 22 ++++++++++-- ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++++-- .../pack-format.txt => gitformat-pack.txt} | 34 +++++++++++++++++-- ...ure-format.txt => gitformat-signature.txt} | 21 ++++++++++-- Documentation/gitprotocol-pack.txt | 2 +- .../howto/recover-corrupted-object-harder.txt | 2 +- .../technical/hash-function-transition.txt | 2 +- Documentation/user-manual.txt | 2 +- cache.h | 3 +- command-list.txt | 5 +++ pack-revindex.h | 2 +- 17 files changed, 131 insertions(+), 31 deletions(-) rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (91%) 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 b53f3c12843..cd09ccd8c13 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -25,7 +25,12 @@ 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.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 f0b1282b918..6da61722431 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 91% rename from Documentation/technical/chunk-format.txt rename to Documentation/gitformat-chunk.txt index f36ce42f37c..57202ede273 100644 --- a/Documentation/technical/chunk-format.txt +++ b/Documentation/gitformat-chunk.txt @@ -1,11 +1,24 @@ -Chunk-based file formats -======================== +gitformat-chunk(5) +================== + +NAME +---- +gitformat-chunk - Chunk-based file formats + +SYNOPSIS +-------- + +Used by linkgit:gitformat-commit-graph[5] and the "MIDX" format (see +the pack format documentation in linkgit:gitformat-pack[5]). + +DESCRIPTION +----------- Some file formats in Git use a common concept of "chunks" to describe sections of the file. This allows structured access to a large file by scanning a small "table of contents" for the remaining data. This common format is used by the `commit-graph` and `multi-pack-index` files. See -link:technical/pack-format.html[the `multi-pack-index` format] and +the `multi-pack-index` format in linkgit:gitformat-pack[5] and the `commit-graph` format in linkgit:gitformat-commit-graph[5] for how they use the chunks to describe structured data. @@ -113,4 +126,8 @@ for future formats: * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()` in `midx.c` for how the chunk-format API is used to write and parse the multi-pack-index file format documented in - link:technical/pack-format.html[the multi-pack-index file format]. + the multi-pack-index file format section of linkgit:gitformat-pack[5]. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt index 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 f691c20ab0a..015cb21bdc0 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 @@ -125,7 +139,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. @@ -402,3 +416,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/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..546c99f8871 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/gitformat-pack.txt @@ -1,5 +1,29 @@ -Git pack format -=============== +gitformat-pack(5) +================= + +NAME +---- +gitformat-pack - Git pack format + + +SYNOPSIS +-------- +[verse] +$GIT_DIR/objects/pack/pack-*.{pack,idx} +$GIT_DIR/objects/pack/pack-*.rev +$GIT_DIR/objects/pack/multi-pack-index + +DESCRIPTION +----------- + +The Git pack format is now Git stores most of its primary repository +data. Over the lietime af a repository loose objects (if any) and +smaller packs are consolidated into larger pack(s). See +linkgit:git-gc[1] and linkgit:git-pack-objects[1]. + +The pack format is also used over-the-wire, see +e.g. linkgit:gitprotocol-v2[5], as well as being a part of +other container formats in the case of linkgit:gitformat-bundle[5]. == Checksums and object IDs @@ -356,7 +380,7 @@ CHUNK LOOKUP: using the next chunk position if necessary.) The CHUNK LOOKUP matches the table of contents from - link:technical/chunk-format.html[the chunk-based file format]. + the chunk-based file format, see linkgit:gitformat-chunk[5]. The remaining data in the body is described one chunk at a time, and these chunks may be given in any order. Chunks are required unless @@ -482,3 +506,7 @@ packs arranged in MIDX order (with the preferred pack coming first). The MIDX's reverse index is stored in the optional 'RIDX' chunk within the MIDX itself. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/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/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.txt index 8a4de6decd0..93b30b88450 100644 --- a/Documentation/gitprotocol-pack.txt +++ b/Documentation/gitprotocol-pack.txt @@ -467,7 +467,7 @@ Now that the client and server have finished negotiation about what the minimal amount of data that needs to be sent to the client is, the server will construct and send the required data in packfile format. -See pack-format.txt for what the packfile itself actually looks like. +See linkgit:gitformat-pack[5] for what the packfile itself actually looks like. If 'side-band' or 'side-band-64k' capabilities have been specified by the client, the server will send the packfile data multiplexed. diff --git a/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.txt index 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 ed859fdd798..4f30a6c30c8 100644 --- a/command-list.txt +++ b/command-list.txt @@ -210,7 +210,12 @@ gitdiffcore guide giteveryday guide gitfaq guide gitformat-bundle developerinterfaces +gitformat-chunk developerinterfaces gitformat-commit-graph developerinterfaces +gitformat-index developerinterfaces +gitformat-pack developerinterfaces +gitformat-pack-cruft developerinterfaces +gitformat-signature developerinterfaces gitglossary guide githooks userinterfaces gitignore userinterfaces 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 Tue Aug 2 12:56:58 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: 12934638 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 52392C00140 for ; Tue, 2 Aug 2022 12:58:36 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S236629AbiHBM6e (ORCPT ); Tue, 2 Aug 2022 08:58:34 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41872 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236965AbiHBM6K (ORCPT ); Tue, 2 Aug 2022 08:58:10 -0400 Received: from mail-wr1-x431.google.com (mail-wr1-x431.google.com [IPv6:2a00:1450:4864:20::431]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 2481015FDD for ; Tue, 2 Aug 2022 05:58:09 -0700 (PDT) Received: by mail-wr1-x431.google.com with SMTP id j7so17795434wrh.3 for ; Tue, 02 Aug 2022 05:58:09 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc; bh=jCsyOOHrYnEKxSChNErtZWAAF/kehc5nyFHToXCb/bA=; b=E008ZRcMd9wrrJsTDLcfmZvezCU+BnhC3Z83KluvXR3B+0sGmrN9pXdNU6mjrHtbZc vyVIZfF6ptdVBsHUvaFTng6legCtBup6odhxBPTIetNdXDM3hC+SO4Xeb5fUzUblswP7 aFhI/zJ82IZKRXTDLYTOYUDQAAzKZKEY8EU25nPwAe01TInapdlCnsHhxyk+5iUwmr8o Ii+a7ikg5qe0v/JNz9GziToOMNJ6jv1zcxjr86nmLhb+G89VJeCL9969jdDw/0tYNErg kOmkC7Bgd3yBRvX0BLpABiubu9R9rx6jg1eoGLuakv9HB9syU5XcRvBzub2DPbJd+Pej rh5g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc; bh=jCsyOOHrYnEKxSChNErtZWAAF/kehc5nyFHToXCb/bA=; b=pAGXar9Arj4wjFbIhsS2qfo35CYKR2ddHlJIzhKZ/YJf6uQ2HR77VRkqilZmEvzCCV 1rGaRH0eEAuWUOV4VlVP+YPjE0VzH+A99bP/2YqZSEfuivi0e2aW0qK81UkNYPFb+oN+ l0cTSJqxgqlHNVV6LPnP5Jf2bNu2xYa3xCAp/0VFm+zHhCQeSm2M+gBGdY8dtKOVgKAX 6xdJAM/AK5k4gzMOZiZqv/B4RJBq6JrVBNDgt2/fpuKTKbcqtJgtJCgSAH/OhtgC0aoO jfM3mmH/QaXrCcVIlwLau/nnjRIKgkKE4+hcBf/p2D2RtX+y6w+jrSdpISkXboPLnnDL 6R1A== X-Gm-Message-State: ACgBeo1mfMyCbycr/W24BtoA5o9JtlcVLcgpT6TiRMIsLz9t24RcFDqf /U8TM4tGZegYm1kkUvWe5xVi2lMwMDxu0g== X-Google-Smtp-Source: AA6agR6SxnvPmhhQcwOSSrQ2+mcUN9BB8wCCdFfYdScHEok3TZq8jlV1xzjgkjGsYXcAsq57Cy0OfA== X-Received: by 2002:a5d:5a99:0:b0:220:68c4:d7cb with SMTP id bp25-20020a5d5a99000000b0022068c4d7cbmr4443509wrb.565.1659445088340; Tue, 02 Aug 2022 05:58:08 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id t4-20020adfeb84000000b0021e45afa7b0sm15056145wrn.109.2022.08.02.05.58.07 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Aug 2022 05:58:07 -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 v7 09/10] docs: move http-protocol docs to man section 5 Date: Tue, 2 Aug 2022 14:56:58 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1232.gc0cde427aa7 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 ++-- ...http-protocol.txt => gitprotocol-http.txt} | 29 ++++++++++++++++--- Documentation/gitprotocol-pack.txt | 2 +- Documentation/gitprotocol-v2.txt | 4 +-- command-list.txt | 1 + 6 files changed, 33 insertions(+), 11 deletions(-) rename Documentation/{technical/http-protocol.txt => gitprotocol-http.txt} (98%) diff --git a/Documentation/Makefile b/Documentation/Makefile index cd09ccd8c13..6efac142e3e 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -37,6 +37,7 @@ MAN5_TXT += gitmailmap.txt MAN5_TXT += gitmodules.txt MAN5_TXT += gitprotocol-capabilities.txt MAN5_TXT += gitprotocol-common.txt +MAN5_TXT += gitprotocol-http.txt MAN5_TXT += gitprotocol-pack.txt MAN5_TXT += gitprotocol-v2.txt MAN5_TXT += gitrepository-layout.txt @@ -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 3409e0d36d1..3f89d640772 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -39,9 +39,9 @@ OPTIONS --http-backend-info-refs:: Used by linkgit:git-http-backend[1] to serve up `$GIT_URL/info/refs?service=git-upload-pack` requests. See - "Smart Clients" in link:technical/http-protocol.html[the HTTP - transfer protocols] documentation and "HTTP Transport" in the - linkgit:gitprotocol-v2[5] documentation. Also understood by + "Smart Clients" in linkgit:gitprotocol-http[5] and "HTTP + Transport" in in the linkgit:gitprotocol-v2[5] + documentation. Also understood by linkgit:git-receive-pack[1]. :: diff --git a/Documentation/technical/http-protocol.txt b/Documentation/gitprotocol-http.txt similarity index 98% rename from Documentation/technical/http-protocol.txt rename to Documentation/gitprotocol-http.txt index 8bd672d55bb..ccc13f0a407 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/gitprotocol-http.txt @@ -1,5 +1,19 @@ -HTTP transfer protocols -======================= +gitprotocol-http(5) +=================== + +NAME +---- +gitprotocol-http - Git HTTP-based protocols + + +SYNOPSIS +-------- +[verse] + + + +DESCRIPTION +----------- Git supports two HTTP based transfer protocols. A "dumb" protocol which requires only a standard HTTP server on the server end of the @@ -512,11 +526,18 @@ the id obtained through ref discovery as old_id. TODO: Document this further. - -References +REFERENCES ---------- http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)] http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1] + +SEE ALSO +-------- + linkgit:gitprotocol-pack[5] linkgit:gitprotocol-capabilities[5] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.txt index 93b30b88450..dd4108b7a3b 100644 --- a/Documentation/gitprotocol-pack.txt +++ b/Documentation/gitprotocol-pack.txt @@ -17,7 +17,7 @@ Git supports transferring data in packfiles over the ssh://, git://, http:// and file:// transports. There exist two sets of protocols, one for pushing data from a client to a server and another for fetching data from a server to a client. The three transports (ssh, git, file) use the same -protocol to transfer data. http is documented in http-protocol.txt. +protocol to transfer data. http is documented in linkgit:gitprotocol-http[5]. The processes invoked in the canonical Git implementation are 'upload-pack' on the server side and 'fetch-pack' on the client side for fetching data; diff --git a/Documentation/gitprotocol-v2.txt b/Documentation/gitprotocol-v2.txt index d6105e07408..c9c0f9160b2 100644 --- a/Documentation/gitprotocol-v2.txt +++ b/Documentation/gitprotocol-v2.txt @@ -53,7 +53,7 @@ Initial Client Request In general a client can request to speak protocol v2 by sending `version=2` through the respective side-channel for the transport being used which inevitably sets `GIT_PROTOCOL`. More information can be -found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the +found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the `GIT_PROTOCOL` definition in `git.txt`. In all cases the response from the server is the capability advertisement. @@ -77,7 +77,7 @@ HTTP Transport ~~~~~~~~~~~~~~ When using the http:// or https:// transport a client makes a "smart" -info/refs request as described in `http-protocol.txt` and requests that +info/refs request as described in linkgit:gitprotocol-http[5] and requests that v2 be used by supplying "version=2" in the `Git-Protocol` header. C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0 diff --git a/command-list.txt b/command-list.txt index 4f30a6c30c8..2d5d6d17fb1 100644 --- a/command-list.txt +++ b/command-list.txt @@ -225,6 +225,7 @@ gitmodules userinterfaces gitnamespaces guide gitprotocol-capabilities developerinterfaces gitprotocol-common developerinterfaces +gitprotocol-http developerinterfaces gitprotocol-pack developerinterfaces gitprotocol-v2 developerinterfaces gitremote-helpers guide From patchwork Tue Aug 2 12:56:59 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: 12934640 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 3A834C19F2C for ; Tue, 2 Aug 2022 12:58:40 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S236827AbiHBM6j (ORCPT ); Tue, 2 Aug 2022 08:58:39 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41894 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236975AbiHBM6N (ORCPT ); Tue, 2 Aug 2022 08:58:13 -0400 Received: from mail-wr1-x432.google.com (mail-wr1-x432.google.com [IPv6:2a00:1450:4864:20::432]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 20BE118370 for ; Tue, 2 Aug 2022 05:58:11 -0700 (PDT) Received: by mail-wr1-x432.google.com with SMTP id j1so9426334wrw.1 for ; Tue, 02 Aug 2022 05:58:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc; bh=su0qHYYV+jN+Mx34di3lfJjrnDTzMx7vx2OsHRrxIUg=; b=CeWy+hszSCqoebBKVE7aFN/NPgNMZxUkajVMpxuyMBcummk6uwC74/TU4+VqA14U3I 0mWrlR4QAMsrRD4dVoCENoxKQWagrUEKeUzbbq3WIIytStkYjmQoKgYpRabTcKQg7oBD A9zwJWD/PMHGQ77SOO3Y6DIjNbC1wwc/51Oj8snEVAweFEwDYui85TJKb0RIpLUja69n KhBuXz8c6ee1+QbFnu+n25Vx0Wh2WfJpXR0B2YF2UTK+p2Gi+it53wHwtJ3Nd8ck3g4c iXe/2iODom0fBsN/99Cb/Yo25RP14B8wLJJMfGPberfHEw5pX8nKZTqh6mASgFi3WQHA OwoQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc; bh=su0qHYYV+jN+Mx34di3lfJjrnDTzMx7vx2OsHRrxIUg=; b=RV3bWT+jsacqeiOW8SlRDqUzGNZvWOCMuIgwqa/OuxlREWXasLHXe0kp1Hz6MBPnyl Kcl4in2nPr+IlkaXUr0nO/jcH3D/Ict7c6m+DkhPimtGOuR95ZVG1V8M1PBgSXmqsS+i ch6jn6fR/ilgeiWlFKT5kRgAHRh31MY9wwfqb2aorNplp7G5h1/5GPGXSU/7L0m4OI// iBx35CuIp8nJ3RUJsqMmsbnPLxUKv/eAlFqJxkVZi3nw8Wa3RiSWN+UiN4wNPp7L7mx7 IFMeOzD6hyrj1HDBrm+a9GrryNdzkp9KYGWcUblOMphT7M3HYVwM85QnOcu0hK4DlowU 7zHA== X-Gm-Message-State: ACgBeo0sEXMCmRBTZVVyo0tGSlL0jtkSHvba1QDry5kC2b2eXCUha2UM ucIgHLKeFKNu9F347MPv2puVCgWPUuecIQ== X-Google-Smtp-Source: AA6agR5qM7nSfX5t240orpHvRDCcZ2/UumbiACXMPVGO8m3EO/FI01V8qkCYCnqYJ4ghaDZHoFpnhw== X-Received: by 2002:adf:fb0b:0:b0:21e:f717:714a with SMTP id c11-20020adffb0b000000b0021ef717714amr13062404wrr.47.1659445089333; Tue, 02 Aug 2022 05:58:09 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id t4-20020adfeb84000000b0021e45afa7b0sm15056145wrn.109.2022.08.02.05.58.08 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Aug 2022 05:58:08 -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 v7 10/10] docs: move multi-pack-index docs to man section 5 Date: Tue, 2 Aug 2022 14:56:59 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1232.gc0cde427aa7 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 | 4 ++-- ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++++++++++++-- Documentation/gitformat-pack.txt | 5 +++++ command-list.txt | 1 + 5 files changed, 27 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 6efac142e3e..522d6011e7a 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.txt MAN5_TXT += gitformat-signature.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..0ffa8b852cd 100644 --- a/Documentation/git-multi-pack-index.txt +++ b/Documentation/git-multi-pack-index.txt @@ -127,8 +127,8 @@ $ 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 546c99f8871..68328bada6b 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 2d5d6d17fb1..65b3e739be4 100644 --- a/command-list.txt +++ b/command-list.txt @@ -213,6 +213,7 @@ gitformat-bundle developerinterfaces gitformat-chunk developerinterfaces gitformat-commit-graph developerinterfaces gitformat-index developerinterfaces +gitformat-multi-pack-index developerinterfaces gitformat-pack developerinterfaces gitformat-pack-cruft developerinterfaces gitformat-signature developerinterfaces