From patchwork Thu Jul 21 16:13: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: 12925548 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 816D9C43334 for ; Thu, 21 Jul 2022 16:15:15 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233683AbiGUQPO (ORCPT ); Thu, 21 Jul 2022 12:15:14 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42428 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233674AbiGUQPA (ORCPT ); Thu, 21 Jul 2022 12:15:00 -0400 Received: from mail-wm1-x331.google.com (mail-wm1-x331.google.com [IPv6:2a00:1450:4864:20::331]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E9BC189A88 for ; Thu, 21 Jul 2022 09:14:39 -0700 (PDT) Received: by mail-wm1-x331.google.com with SMTP id v5so1339571wmj.0 for ; Thu, 21 Jul 2022 09:14:39 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=3CBsBgItHwq3I8+M1jkjtGUyICpqh8trbIVanepaBUo=; b=fdgZFh2sD30NcPJG38ofSXSf+P2pAq6dsZ8nlEf4OtiujZZFVHn75XWDnkoKXCguSF 4nUiZBu3a/avpBPfZ5uVRtzW/h5zITNOZaZ1IHCTxMu93NTiSdBXY9YQI9Bws4gSsl6C xd8LC3JWmJInDR7Re2IUO/S7baOSqQWpwFs153u/wNIiK/7aIymRnAw3b2cJ6vky457V lGJuSzMKam+MWkneBzyZYFntFqSnu3OLIGtXVLolGDzZJneW+ouSF7s7h4OiYi0HEQSu 1tmPh+qE8Mxk3l8+GEbMOQpzTlTZu9wPqoX2VDGKC84BYI5BrsczyETKbc1FhP7PTlHg BK3Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=3CBsBgItHwq3I8+M1jkjtGUyICpqh8trbIVanepaBUo=; b=yTnxYjJZVpRlm12sAFivR8mKajthSiU9gH7yZlpFqfg425KWv2RF2c9Ff0ySauPhrw jhZi9jBVPpJQBGRxTugvlHHFOeooNnXtOMoEaPxvduS8ZeVs0fTwCDK3E5fjG07+CuST 1cPeNZQvNIyGv6EKE3cmjSefkOfi/fFOhIhue/pdmeO+omceBGQohVr0A++0uChxIubh 2M8DowFT2RHs9hq4fVZivDjr6nPuV4VqZKKIS3epgkcaNJ8c8hSgFs3uZ9soPL191Hdg inIiJ0Jp4r/H/8E+xiNSeOMX1HxTmqj8Z6cLpECeSeqS4N3ahJWAbDbkBuxfW/WKyw1O vbwA== X-Gm-Message-State: AJIora8Y+nKLExv3smI7AXgNgMIeL7iEk/kc5wzN3Sg3N0WNNUjBZ9Rk JbrQQflxihSVUGkvTF2IVPVW2G5C51pLlg== X-Google-Smtp-Source: AGRyM1t/Yavimj0FsIExu2CFoWIHCqwHHjZgx3A2eU+24ixc+1gJ9C2uz/815V4q+1n7So4T2M8vMQ== X-Received: by 2002:a7b:ce13:0:b0:3a3:102c:23d3 with SMTP id m19-20020a7bce13000000b003a3102c23d3mr8795282wmc.67.1658420054694; Thu, 21 Jul 2022 09:14:14 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id n21-20020a05600c4f9500b003a2f2bb72d5sm8498608wmq.45.2022.07.21.09.14.13 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Jul 2022 09:14:13 -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 v5 1/9] help.c: BUG() out if "help --guides" can't remove "git" prefixes Date: Thu, 21 Jul 2022 18:13:50 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1095.g64a1e8362fd In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Adjust code added in 929d9192828 (git docs: split "User-facing file formats" off from "Guides", 2021-06-04) to be more strict about the prefix trimming of the "guides" category. There are no guides in the command-list.txt that don't start with "git", and we're unlikely to ever add any, if we do we can remove this BUG() invocation, but in the meantime this makes the intent more clear. While we're at it remove a stray newline that had been added after the "return name;" statement. Signed-off-by: Ævar Arnfjörð Bjarmason --- help.c | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/help.c b/help.c index 41c41c2aa11..80d516abb0b 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; 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"; + if (!skip_prefix(name, prefix, &new_name)) + BUG("'%s' in category #%d should have '%s' prefix", + name, category, prefix); return new_name; + } return name; - } static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask) From patchwork Thu Jul 21 16:13: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: 12925550 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 4A43EC43334 for ; Thu, 21 Jul 2022 16:15:19 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233763AbiGUQPS (ORCPT ); Thu, 21 Jul 2022 12:15:18 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:43202 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233884AbiGUQPC (ORCPT ); Thu, 21 Jul 2022 12:15:02 -0400 Received: from mail-wm1-x334.google.com (mail-wm1-x334.google.com [IPv6:2a00:1450:4864:20::334]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 78C758AB06 for ; Thu, 21 Jul 2022 09:14:41 -0700 (PDT) Received: by mail-wm1-x334.google.com with SMTP id u14-20020a05600c00ce00b003a323062569so1087262wmm.4 for ; Thu, 21 Jul 2022 09:14:41 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=vm3YP1KeoHropkb/SkT28z+ueMp6Lg3iPedit4zoEic=; b=RKnDcO86Rvh48szkY3vGyw5/NmtnfA4bHtPrJ/bDrTZG8z4DMPvH77YkMVrLd7ZBXL HB+gJzxKKKJPQZm3gLhyqkqHcxZWURAE5qQ1XZYj+YuekjPYqROaojxQBCTjMD+Cawf2 Kqgo9qw9rtx4IAnwPpUpgWJ1Y0ENR4MeYNtxGdn+nVT9i1BQbtA07kxIaaJwya0FdfwD ioBT078jaDreSi8NLfmr4fdq5CTqU1ONJfjEvJ8JjavhYXFXwWk0EilHQBjxKdjU2jtt 73+Awp8PDh15MpNkzmEu+A61mFDlPBuUghXrJIpcidbTtP7hm8GmdJAFIcU0iT/HfH1M cuTg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=vm3YP1KeoHropkb/SkT28z+ueMp6Lg3iPedit4zoEic=; b=J8Yq6CmOiC3JQS2NdJ6OKq8y7CiOUvbaCOZuQfje9SWbQVGnIveWNxDtf4F7EIYQQV vNtYtHtM2k5XfkJcbxYze4HXPXDFz6uEdjSfqkCGJ/bs22v533oQFafIzH3vm5J5oVV/ UTxogFIayIqOHze9M/mPMkKfMvM9xT0DTWBYI4/I0Afay44hgKZ1GDRI6IbQKjjhjChE Y2+IqOGAKD4UZdLTbeqbjFD1Q6MAG/vsqWNIo556r/kMU/Oj+ryZiSrocZbIu9q990Qr EV23ySoRwOgSECkhIRaCYroLVN/LrXzSObEmBNjkJEv6N8M8iTac2l2VW+lwrXNJr8fJ D/7A== X-Gm-Message-State: AJIora/hsizwTS5/j8HQLlKprok95aNoxfVDf1DkIxMJUVnRU9Li4r5r wluZQTeQGQACmy7rsSj7raBhU7h++60hGQ== X-Google-Smtp-Source: AGRyM1sLuZBorPZ4wTqvv780Lypf/8F/cpSayS6ZeZ7k1z0O+kIq6mE1zQYwENylW9G+x3rb0znAUQ== X-Received: by 2002:a05:600c:4ece:b0:3a3:1ce4:1e05 with SMTP id g14-20020a05600c4ece00b003a31ce41e05mr8871277wmq.25.1658420056934; Thu, 21 Jul 2022 09:14:16 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id n21-20020a05600c4f9500b003a2f2bb72d5sm8498608wmq.45.2022.07.21.09.14.14 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Jul 2022 09:14:15 -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 v5 2/9] git help doc: use "" instead of "" Date: Thu, 21 Jul 2022 18:13:51 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1095.g64a1e8362fd 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 Thu Jul 21 16:13: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: 12925551 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 A74CCCCA488 for ; Thu, 21 Jul 2022 16:15:20 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233758AbiGUQPU (ORCPT ); Thu, 21 Jul 2022 12:15:20 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:43212 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233891AbiGUQPE (ORCPT ); Thu, 21 Jul 2022 12:15:04 -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 9F6168AB12 for ; Thu, 21 Jul 2022 09:14:44 -0700 (PDT) Received: by mail-wr1-x436.google.com with SMTP id bu1so2954040wrb.9 for ; Thu, 21 Jul 2022 09:14:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=GjHsGtdJoyfYlLV1WnR+cBorLVr8y92+qKiqouXNzbw=; b=ofrTsX8V2eAsQiW37RckYmekLk6F4uwZoIh9uN0wgMa1rmSEpSDFLaXSLcWfa7E8hZ grlU4Qs/4eDiocPKzb+HZsXeeAHfk3xJiIcYMiFC3qMVMAy3lfeKMx66LacOkhWqpir9 mWejjXMJbZT2c6V5DP3ovv7oVLQ0wZxrRe/GfNp4jizHlpwefPtUpjzQ19nvC1586tuf w5IKLppnOBbBfexTFqT0j8IMScpS0CYtgcOLNSCWxpenDcjSMmQ/sL/Lspe8y+hU4ByZ 2linbWLFhGeBd1cBUSNO6W3RgpiJjy8gvLBoihBjnl8UuBjZEM95+jhgthiJyb3MtmsW 2njg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=GjHsGtdJoyfYlLV1WnR+cBorLVr8y92+qKiqouXNzbw=; b=eUaAmcoagpVBn13zqrlusxGi2B5asB6zEPOXV2RM6vqJ//kO+OzoHpX3y3TUFsbrUt c1NspYhb5g8/aBCbuqWb2SvhBPY/BMhm8gfk6P/8ZmjfN13Zl3izZ93mNf6TC/9TY3mY In5VGDiea89J0dlkdCvF07X0gNMMVKuZlpikYwbVSdgPu1sbkfcqZmle5zxu2mgakN7/ pHzgVBtuMiaNEhIgq8nwm8wjg6bD2Jfl6Z5du3t1F3lqNQ+SXjfCC6P6uBX7BGqFyDtI 8TkjbpOFyK4HPH7VD/oV1wvaPV7R56hzUOlQmiMeix2e+nunw1PL3x+DfBs8Swei+f5Y 2NnQ== X-Gm-Message-State: AJIora/P2Jq71YOQsyKslZfAWb5H2HUAOgCGVAp3Xpw1nPVB1LAsfvjO R9Hr0aiOdbIoHj7kPlFp/5auqAXOewUuMQ== X-Google-Smtp-Source: AGRyM1v+NNxZQ9cgFK0HfRc8mB7sm42DIr0rFlOImYWtkiCgq8b6InNkaotTP4QD2PsFHy6TsVZxjg== X-Received: by 2002:a5d:4f8f:0:b0:21e:4f09:9e15 with SMTP id d15-20020a5d4f8f000000b0021e4f099e15mr5841917wru.55.1658420058649; Thu, 21 Jul 2022 09:14:18 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id n21-20020a05600c4f9500b003a2f2bb72d5sm8498608wmq.45.2022.07.21.09.14.17 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Jul 2022 09:14:17 -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 v5 3/9] git docs: add a category for user-facing file, repo and command UX Date: Thu, 21 Jul 2022 18:13:52 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1095.g64a1e8362fd 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 302607a4967..f69d32e1e79 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 80d516abb0b..a2ceda1723d 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 } }; @@ -50,6 +51,7 @@ static const char *drop_prefix(const char *name, uint32_t category) return new_name; switch (category) { case CAT_guide: + case CAT_userinterfaces: prefix = "git"; if (!skip_prefix(name, prefix, &new_name)) BUG("'%s' in category #%d should have '%s' prefix", @@ -432,6 +434,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 Thu Jul 21 16:13: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: 12925552 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 243BEC43334 for ; Thu, 21 Jul 2022 16:15:37 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233775AbiGUQPg (ORCPT ); Thu, 21 Jul 2022 12:15:36 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:43312 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232853AbiGUQPG (ORCPT ); Thu, 21 Jul 2022 12:15: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 544978AB23 for ; Thu, 21 Jul 2022 09:14:48 -0700 (PDT) Received: by mail-wm1-x32c.google.com with SMTP id v67-20020a1cac46000000b003a1888b9d36so3663942wme.0 for ; Thu, 21 Jul 2022 09:14:48 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=b2W9p3mPrLJZuSbR6DQ1sI21a5s4grW8y45OFH2QynA=; b=bBo9bwuXWZZsHpIOLkUs/daiVmsmFPr6xFjlVtDDYBoPevUFUIhlbr4hfPgcOhVFea 1AqKbZGKYuYK15YLJTZaqUsfdTW1Hq+OpNYjuMZxVhYM1AP2GWhuJpj8Xgd5qKV6xylb Bqs+Xrg4FHPkkZK0tC38/OP4CI5dDRwzBN7WwBcnHjTM/wg2KTre/nNZqB5tmky55rBn EcsOWdNgmrfkRDz6No6QNLkHKC60fS1tJEBcgJVIwAygMyUGfb+/R+seLNTCchHa327C SVWrrSoUXhS0czL44+SzJBVWWj/RKTqL/Ty5UYzc3+b0OwLR9HHSM5MIZWqqP2O9dmA8 9TuA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=b2W9p3mPrLJZuSbR6DQ1sI21a5s4grW8y45OFH2QynA=; b=0PRw+5mJ4FzBeTteglpS+BOHqgN45fuxqJemB8vai4BzisUewYxoIl77nBZ5vbtHS1 Pp5m67sAuLLP/J0j01rzqegvV1VvHWBzH5KMauVhAaZzUAYY3UOjlDa9u79uwGAoH8A4 tqRNPZ6zOA9UyLICjFlSF1vC/U3PV1RIc5SWSO3360uU8+QHqAeQmaw316hL8xc+GHpY MNs8THNttjxbF3U701Z27B5uVTNjmuqrDLkf72rQIIAgpizOEPOVkg+L7PSHaD3H3Sog k93lh4vkdnUd7/J9EZKu5CRagcx9lowutlWdb/Zs9C1hxcS7wreFGiNqydoiI8zJ4W6C 6dAg== X-Gm-Message-State: AJIora9fWfBDREcEv3VTrhQwdCxK3GztAUBUxNPSRHrX30u/is5eaM0p 9geB5mmuTw7qci6A3HXLoGjXv9LMFhwA+A== X-Google-Smtp-Source: AGRyM1vi+MJL6Fi6/KaFtS8G6vH46DIaBcnv+l2vD3z+OFvR0a6KvWrsvu/44nZYkDd0BOIPaxSG/w== X-Received: by 2002:a05:600c:3593:b0:3a3:3a49:41a3 with SMTP id p19-20020a05600c359300b003a33a4941a3mr769323wmq.166.1658420060866; Thu, 21 Jul 2022 09:14:20 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id n21-20020a05600c4f9500b003a2f2bb72d5sm8498608wmq.45.2022.07.21.09.14.18 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Jul 2022 09:14:19 -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 v5 4/9] git docs: add a category for file formats, protocols and interfaces Date: Thu, 21 Jul 2022 18:13:53 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1095.g64a1e8362fd 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 compliments 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 f69d32e1e79..f064951b5c4 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 a2ceda1723d..71f1c905d1c 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 } }; @@ -52,6 +53,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"; if (!skip_prefix(name, prefix, &new_name)) BUG("'%s' in category #%d should have '%s' prefix", @@ -444,6 +446,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 Thu Jul 21 16:13: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: 12925553 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 E9D70C433EF for ; Thu, 21 Jul 2022 16:15:41 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233592AbiGUQPl (ORCPT ); Thu, 21 Jul 2022 12:15:41 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42608 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233525AbiGUQPJ (ORCPT ); Thu, 21 Jul 2022 12:15:09 -0400 Received: from mail-wr1-x434.google.com (mail-wr1-x434.google.com [IPv6:2a00:1450:4864:20::434]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A81A688F38 for ; Thu, 21 Jul 2022 09:14:49 -0700 (PDT) Received: by mail-wr1-x434.google.com with SMTP id a5so2945973wrx.12 for ; Thu, 21 Jul 2022 09:14:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=x3Tybc+u5CDrEBMLWmELwtj5Q3BC/HQwfuEwP2eXQm0=; b=b0wZlkNuyEIkScYOdfJmjKuWgNZjzC1sayvPKCZZZXYnZZfnTi9uIOXidZudwWvGqn CMCj5VntrJWVOESWd1vw7SmalZk0pNro0Xpbe89o+/gjh6yXtbTa55qt822gfrIDz4pi P8f2vw4FubyaXWkH37sJXWLS5E7L4zAQoTbqXKHA2Jofub2vhHQjcSHPj6uZqaGAqiCp 1ROXbnmQSXYsKXOO/bJ6mmNIRPmz/FQqCraEg+hlwG6NcvVLHgv+OclUMpJAex2awTAG QdJUa2R5uuFFWAu3FggAcG3rfqdvB9wiCI3VBzbIrfCsCxVP7dXfbbGRHSJfhtrwVHI7 b5Wg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=x3Tybc+u5CDrEBMLWmELwtj5Q3BC/HQwfuEwP2eXQm0=; b=fc3CV1ac/Gh04jmwvQFUOTMadyoQ61vTl8X5Md1YCbjlBZrCCiUBu3enrluBFfknp+ qn11zR1EXDH+PwzvWB2kh48JWn3XoO+8WPkex+bpdWdWVXcY9HTMy5D+A+/QauwFOqeN JoUiORMmNvSEip6WFmCEngHkmhnRJmsowqcExq3Tn5CoCXn5hssDeSIyMFHrJuBnirhG L8TVW8owsO1x8WKdagoOuU8F1QXCBL7sZMfD6kslWRyEC0JzUeYylcj8vwYXC6oWyN+Z mHHl3x3j7pQUtnRq6sluODV5YMTIkWgUbIFcnrjnniif8fPPSwHnc9uSZo/sKMKtq7Ee fbWA== X-Gm-Message-State: AJIora/GWn6gobq15x1pA2h/iHrEObrAI99nETfCoZTObj9UL/GQ5Lb/ tdcQNLvGPOCjlBuo5M4ibB3Q3nE0d0EHKg== X-Google-Smtp-Source: AGRyM1s2+UM5TPlzPKbBpNu7HpUb/396pdYJfxWO/XkOf2DOROAakeqn5y+TztwsNWkOj9jyPbQIeQ== X-Received: by 2002:a05:6000:15c8:b0:21d:babe:e75c with SMTP id y8-20020a05600015c800b0021dbabee75cmr37279766wry.32.1658420062844; Thu, 21 Jul 2022 09:14:22 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id n21-20020a05600c4f9500b003a2f2bb72d5sm8498608wmq.45.2022.07.21.09.14.20 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Jul 2022 09:14:21 -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 v5 5/9] docs: move commit-graph format docs to man section 5 Date: Thu, 21 Jul 2022 18:13:54 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1095.g64a1e8362fd 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 Thu Jul 21 16:13: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: 12925554 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 99EE9C433EF for ; Thu, 21 Jul 2022 16:15:44 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233897AbiGUQPm (ORCPT ); Thu, 21 Jul 2022 12:15:42 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:43088 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233610AbiGUQPJ (ORCPT ); Thu, 21 Jul 2022 12:15:09 -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 52D0D8AB29 for ; Thu, 21 Jul 2022 09:14:50 -0700 (PDT) Received: by mail-wr1-x436.google.com with SMTP id d8so2973633wrp.6 for ; Thu, 21 Jul 2022 09:14:50 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=UxIh58CZMaR5EUHJFdAhT4UKzOrRqCdf9o/mUSomPXg=; b=MLRXGapE5x9icbyVofTn9zZBfzFaqAGaoN9YlIk14RW0SFnpegIgDoyjQVf1EarG5E xN4v9XeKp2XerTQDwHOrVx9kSBcr62EnpIYp5u37Ex77DKuOVQJ/MrySa555oJdm/ogk x/HDiHLNpX0knzTgBDLOxvssdgUGZj0m/pVFqiOP38MxEFJ296gHP3IQrQbdnDUYFOKf sjR71xATdW71HcrHiSPVMzYeyDjoyzIDmGfRfz9P2gzR/JbLx1TovBKEdlyOu84XK8r3 Ey6gp8EYTzo2BIzPRcSOZ84PtJe0VOVLLM/K6oA163Gh0Stxtm+qJ+E53cQSDkAWcBtS LaOg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=UxIh58CZMaR5EUHJFdAhT4UKzOrRqCdf9o/mUSomPXg=; b=U5L1KthtcSjVvi+zfzFUb8Agul5xQQRngigJA7RoWG9LxnEkQNlVln0MXJ7UAarrc7 fuZSlRcDHUyQkX3O4WIpoIhaUuZEMBEZmaOmeY1DC1TP9GXWi5Dplse2CNPQK6U3SFR0 ZJ5kVHia1/asBpbj2r4oQwL23MzCh+psJ4p0M19fFaAH/yeVM42a/zkgycrZSf6xueen gI/NLks9JhEN3UqNdni7vQQ6x/Fl1Zw3Y1Le6FrK3ho4KhHsTM72a7WdyDKhjSKJuCVT fCPsIvuHLalvMOP3n641Dtz0K655UCu0c+4tVQwLqr7F8z+CG/qynHD06j8yOPyJKL04 J5mA== X-Gm-Message-State: AJIora/oCadrxyDbUf9j7lx862yRz+ed/A2iziU1sOlMGHiMJ2mAtdHx RA4XhJpFWhV5RWJHSJQfAP359tpgaQoQMg== X-Google-Smtp-Source: AGRyM1tSCkeLFQ2QvtfqMUigmPS4+qkk07PF9AIG21f4Qny4eORwp1D3zEd/i/xIWl85zP6kUHyikg== X-Received: by 2002:a05:6000:144f:b0:21d:a3cc:a6fa with SMTP id v15-20020a056000144f00b0021da3cca6famr35207769wrx.191.1658420064841; Thu, 21 Jul 2022 09:14:24 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id n21-20020a05600c4f9500b003a2f2bb72d5sm8498608wmq.45.2022.07.21.09.14.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Jul 2022 09:14:23 -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 v5 6/9] docs: move protocol-related docs to man section 5 Date: Thu, 21 Jul 2022 18:13:55 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1095.g64a1e8362fd 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 Thu Jul 21 16:13: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: 12925555 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 07695C43334 for ; Thu, 21 Jul 2022 16:15:46 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230238AbiGUQPp (ORCPT ); Thu, 21 Jul 2022 12:15:45 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:43098 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233603AbiGUQPJ (ORCPT ); Thu, 21 Jul 2022 12:15:09 -0400 Received: from mail-wr1-x42e.google.com (mail-wr1-x42e.google.com [IPv6:2a00:1450:4864:20::42e]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 65E118AB2C for ; Thu, 21 Jul 2022 09:14:50 -0700 (PDT) Received: by mail-wr1-x42e.google.com with SMTP id k11so2514235wrx.5 for ; Thu, 21 Jul 2022 09:14:50 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=rJygiHxuNsJuJlr1lKQUaaSphSy8EUARwpi8d0bhees=; b=LOiQCa3QMWtla/eyXRBG0AbUvR0uw+HyedVrvemFNYPlsWw8+st2eTgvcRfQvwZtP8 1zrvBYPK5TuaK8Gs0POD6Nm37/xBzoMR1yzgVpmPgjFV6NpDnW4I0vA2f1MoINpLrIYy 0+6nAJ7/OnEZt7TN26elcV1eY8avHqoj1JidAPvpuU93SxPvqVxynge2y0hcGmPWC2yM KUptrpx2bta1/xk1oMCGV2NrFNbZSX2yPEPGCnChDT8QGc8h0LPMP61YCbZDwbKWbfSA xQ/xxouqfbZGhT1KXXItNryXe+GUTAwA5HGn78xIgcOaQhxZX1AgzuvHsh5fvBfqDQTM gU9w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=rJygiHxuNsJuJlr1lKQUaaSphSy8EUARwpi8d0bhees=; b=yJE8bm/STb6t+c3UAn6TulAAxLzAjbzda3JlEW84pLICg5WAmRoMXznP21JM6++MJC HzsN7ecW06wRhkmg2cC8KBgtwquVF8gTwkvpwv0Ooc4lW+n9Qb7b4gt3PsqNG0WkKzcw NG0jLPhbIQxJJ8Z1l0kqwTP56hbMmvxEE6jqj35uYr0AXmpA5oz5AzIT/0gY0IRzw+hT ncuc3CxjXu8NprLXaRoGJN3SkSGxCQ0lz6gmLoJZJunrKHnsmmlCCxB6yiRTJbqw4oUH tKnmuj2KQWjblliLErVsn8FeHgeW4o7vgBsH3rXWeUT5/ZeZ3lRQj6Z/H36uvqTZu3B8 g0OQ== X-Gm-Message-State: AJIora/ALQ3oKoNmgAD6Dco+qYqvjYtSAzhAH1IwQIv5Qdx+duXIc3pH i+W6Ohu8r+jfEqSZflcMYfcjdbaJROMXdQ== X-Google-Smtp-Source: AGRyM1v/CUH7W8N2+YGrILfLLfIUtSuf7B1Wmz9KqweY9et8QIBYQQkCUHOw1UtV6O4zvYCQjtjpPQ== X-Received: by 2002:a5d:5985:0:b0:21d:b6b6:4434 with SMTP id n5-20020a5d5985000000b0021db6b64434mr34523359wri.111.1658420066767; Thu, 21 Jul 2022 09:14:26 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id n21-20020a05600c4f9500b003a2f2bb72d5sm8498608wmq.45.2022.07.21.09.14.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Jul 2022 09:14:25 -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 v5 7/9] docs: move pack format docs to man section 5 Date: Thu, 21 Jul 2022 18:13:56 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1095.g64a1e8362fd 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 65da0daaa56..5f3ed10d2db 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/gitformat-index.txt @@ -1,5 +1,19 @@ +gitformat-index(5) +================== + +NAME +---- +gitformat-index - Git index format + +SYNOPSIS +-------- +[verse] +$GIT_DIR/index + +DESCRIPTION +----------- + Git index format -================ == The Git index file has the following format @@ -127,7 +141,7 @@ Git index format entry is encoded as if the path name for the previous entry is an empty string). At the beginning of an entry, an integer N in the variable width encoding (the same encoding as the offset is encoded - for OFS_DELTA pack entries; see pack-format.txt) is stored, followed + for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed by a NUL-terminated string S. Removing N bytes from the end of the path name for the previous entry, and replacing it with the string S yields the path name for this entry. @@ -404,3 +418,7 @@ The remaining data of each directory block is grouped by type: with signature { 's', 'd', 'i', 'r' }. Like the split-index extension, tools should avoid interacting with a sparse index unless they understand this extension. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/cruft-packs.txt b/Documentation/gitformat-pack-cruft.txt similarity index 96% rename from Documentation/technical/cruft-packs.txt rename to Documentation/gitformat-pack-cruft.txt index d81f3a8982f..908f752bd84 100644 --- a/Documentation/technical/cruft-packs.txt +++ b/Documentation/gitformat-pack-cruft.txt @@ -1,4 +1,17 @@ -= Cruft packs +gitformat-pack-cruft(5) +======================= + +NAME +---- +gitformat-pack-cruft - The cruft pack file format + +SYNOPSIS +-------- +[verse] +$GIT_DIR/objects/pack/pack-*.mtimes + +DESCRIPTION +----------- The cruft packs feature offer an alternative to Git's traditional mechanism of removing unreachable objects. This document provides an overview of Git's @@ -10,10 +23,11 @@ same. To remove unreachable objects from your repository, Git offers `git repack -Ad` (see linkgit:git-repack[1]). Quoting from the documentation: -[quote] +---- [...] unreachable objects in a previous pack become loose, unpacked objects, instead of being left in the old pack. [...] loose unreachable objects will be pruned according to normal expiry rules with the next 'git gc' invocation. +---- Unreachable objects aren't removed immediately, since doing so could race with an incoming push which may reference an object which is about to be deleted. @@ -121,3 +135,7 @@ which aren't already stored in an earlier cruft pack) is significantly more complicated to construct, and so aren't pursued here. The obvious drawback to the current implementation is that the entire cruft pack must be re-written from scratch. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/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 Thu Jul 21 16:13: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: 12925556 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 A609AC43334 for ; Thu, 21 Jul 2022 16:16:07 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232109AbiGUQQF (ORCPT ); Thu, 21 Jul 2022 12:16:05 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:43216 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233865AbiGUQPQ (ORCPT ); Thu, 21 Jul 2022 12:15:16 -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 B2EEE89A9C for ; Thu, 21 Jul 2022 09:14:54 -0700 (PDT) Received: by mail-wr1-x431.google.com with SMTP id d8so2973856wrp.6 for ; Thu, 21 Jul 2022 09:14:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=5sYHUrvd4MfXcyiiIa55wbrWHJ17C85AkaCrY0SdD4E=; b=ZiboUseQuI51HDr4bTq76e7UqsN+P7DZ86SvX2Ir52fZAMQU3jGnmP8oIxmQjhChmE GTLtAxyaWjtafGfemp/2XF4StUOsnGAdKW2cxiSB96kycBnKPMlK3J7Bd4rOR/ebA0wG Q/2dlBdmFZnYTS0jNFmkGPyYNaJBiBO9LeFrbakxgXEhybJ76Jrd83i6LtaeqOzUSRwr Vv/iSVIPSQvQSKIgRcaj4HxeKq5Y1loa/Cr+y1tzbs4g2ZwChXplpDUpoZQ6VSXHCqUe ovvT5V3WvA+aOjfSETWIPZm3WB8MpEk/NWUFJpzRSPuEPvjUa7ozQXOfGxpAb7O3JwEg j8gw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=5sYHUrvd4MfXcyiiIa55wbrWHJ17C85AkaCrY0SdD4E=; b=lqUjJDH2HREU4eQK/NHNxZc8XKXK4+JMWuBsx7Nb9f63bi4IQ5g5aRWfdq00GO3hid cGanSUfwRmajstJq0QmVAa0mHz88VfJurXJ4A1JMjDwHMWGVwpRWbk34eRh/Us9GDHnF CmpYxo2btF34nB6PNkXdKAAu1Mu1xTOdRhNcL6Hc3sD350UfT24cuVKUCZd5OUOxCn10 hntX7Fn9N5AZSrLc+LCqnx8w/Ad/cIlmg4hFN3c48CaeeEnJveLXO18kNlfBZ2hQC38U XDuYADztibchQAIMwAhKOQNPGrxqKjZInduvyhgG/VAHAL4O5MYqMnVR8uDUjB6L6fmu dlRw== X-Gm-Message-State: AJIora+ng4CG2yjcOoTy1QwMhsG9c635AU+Zcbn4lUB7nBgz1pjk9llM xIfi+H4EVullJW4qpeTspI4129UBg8T+mg== X-Google-Smtp-Source: AGRyM1vAb6SfqZRuTrG0aC2AO11TjhPJGh1Moik/lvxbD2k5eDd57s4MeBZTrOIFhyeFIdJgssOKLQ== X-Received: by 2002:adf:ef0b:0:b0:21e:489f:a258 with SMTP id e11-20020adfef0b000000b0021e489fa258mr7213832wro.19.1658420068742; Thu, 21 Jul 2022 09:14:28 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id n21-20020a05600c4f9500b003a2f2bb72d5sm8498608wmq.45.2022.07.21.09.14.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Jul 2022 09:14:27 -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 v5 8/9] docs: move http-protocol docs to man section 5 Date: Thu, 21 Jul 2022 18:13:57 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1095.g64a1e8362fd 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..e3a5d417792 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 Thu Jul 21 16:13: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: 12925557 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 606F3C43334 for ; Thu, 21 Jul 2022 16:16:17 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233872AbiGUQQQ (ORCPT ); Thu, 21 Jul 2022 12:16:16 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42028 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233892AbiGUQPg (ORCPT ); Thu, 21 Jul 2022 12:15:36 -0400 Received: from mail-wr1-x434.google.com (mail-wr1-x434.google.com [IPv6:2a00:1450:4864:20::434]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 5E4BA8875B for ; Thu, 21 Jul 2022 09:15:03 -0700 (PDT) Received: by mail-wr1-x434.google.com with SMTP id h9so3015502wrm.0 for ; Thu, 21 Jul 2022 09:15:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=VGZgbRJXVVS7kjQjlDffbZsCmWs5Aa/G8caZ6wN4zv0=; b=EUJxntsSgf8uDnrejFq/s5Gz0XklH2eUdY26DrHq97DK2LNEEnsdCqnL4jTzU/xscF z01I3jqBFil4Y0Fc8Ty1xNHRMuEb+42k6Roi6soAxSM6Gba8qiNIzdS0Fy5CHe7az8s9 BAAUOYsAxyLB0+RfXtjnj/aOlTLw8Lc6mIcp3RzcxwcrP7WHoOTcfQ75CvFFnlB8dh7X mNA7KLrMJfsHnnBx0SKupJU2ZtP2q6Shf22B9EHF/b267IgBgLQogZAjKePQf/uMdWUw qIVbhNeCktNBpeE5CChQNifDPlHwo45OZf+/tvBpVnlmsXcpK2/FlLSt78PMQeZfJ/xd Af9w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=VGZgbRJXVVS7kjQjlDffbZsCmWs5Aa/G8caZ6wN4zv0=; b=BYPzucFXyK0SNjiVshubwcSWzEETGy8sipKYSETjfUp+uM2eHGrbXkXVIc3Q+YBKAu D2CCbwvyq+M8Xa0JljK8OHy0GqEaFCcU3xam8exsfYZ+SrZAEEl0Z79Il8lmHtqwuNtx 4/xeI5Rdbgnx8VGtDtg6k2pVR1FAALvCGoOsqQsdjI/D3rCnon0yZZNwOqp6/8N2vtL4 Z20+Mag7k8PvnL2RgnF/J21D2Es/OhMeC5fB141gaAT9PdZXGRe7EgaP/or7cbg8pPCs s0Osxu/EhxIkXxHKdWzb66Z1xFkd1P3m45sPlOlBR8ZLmAi4kBuW/ezX8p87FzB7H0Iq et0A== X-Gm-Message-State: AJIora8VOa0Y1ZVSljWVrxMGtKO0GeKOj94cfvFUUaz1vU34OAdGUHZ4 MUfKAvvB4jfB3dEE1cJOa41tQxKIHajPRg== X-Google-Smtp-Source: AGRyM1uo5YUeqNe/vI54RfCMsUpE+lhsgRjdtIbyVruk077LJvpWlxCo6Q6ZDTGtNzKkWjI56IkIew== X-Received: by 2002:a05:6000:1f0b:b0:21d:6dae:7d04 with SMTP id bv11-20020a0560001f0b00b0021d6dae7d04mr35570234wrb.414.1658420071045; Thu, 21 Jul 2022 09:14:31 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id n21-20020a05600c4f9500b003a2f2bb72d5sm8498608wmq.45.2022.07.21.09.14.28 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Jul 2022 09:14:29 -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 v5 9/9] docs: move multi-pack-index docs to man section 5 Date: Thu, 21 Jul 2022 18:13:58 +0200 Message-Id: X-Mailer: git-send-email 2.37.1.1095.g64a1e8362fd 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 e3a5d417792..1215250c9ae 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