git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
* [PATCH 0/2] git(1) doc + "git help": split-out user & git format docs
@ 2021-10-15  2:05 Ævar Arnfjörð Bjarmason
  2021-10-15  2:05 ` [PATCH 1/2] git(1) docs: split "User-facing file formats" off from "Guides" Ævar Arnfjörð Bjarmason
                   ` (2 more replies)
  0 siblings, 3 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-10-15  2:05 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Philippe Blain, Todd Zullinger, Eric Wong,
	Jeff King, Ævar Arnfjörð Bjarmason

This series goes on top of tz/doc-link-to-bundle-format-fix (and my
newly-landed ab/help-config-vars) and creates new "User-facing file
formats" and "Git file and wire formats" sections in the main git
manual page.

My main motivation here was to make the Documentation/technical/* docs
more discoverable and accessible.

2/2 moves over the "bundle-format.txt" into a new gitformat-bundle(5)
manual page, allowing git-bundle(1) to link to it as another man page
(no more links from man pages to generated HTML!).

I've got pending patches to migrate all of the rest of the relevant
"format" documentation in Documentation/technical/*, but setting up
the infrastructure for that first should be easier for reviewers to
consider.

Ævar Arnfjörð Bjarmason (2):
  git(1) docs: split "User-facing file formats" off from "Guides"
  git(1) docs: create a "Git file and wire formats" section

 Documentation/Makefile                        |  4 +-
 Documentation/git-bundle.txt                  | 12 +++--
 Documentation/git-help.txt                    | 11 +++--
 Documentation/git.txt                         | 15 +++++++
 ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++---
 Documentation/lint-man-section-order.perl     |  3 ++
 Makefile                                      |  1 +
 builtin/help.c                                | 16 +++++++
 command-list.txt                              | 21 ++++++---
 help.c                                        | 22 ++++++++++
 help.h                                        |  2 +
 t/t0012-help.sh                               | 16 ++++++-
 12 files changed, 145 insertions(+), 22 deletions(-)
 rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (78%)

-- 
2.33.1.1338.g20da966911a


^ permalink raw reply	[flat|nested] 112+ messages in thread

* [PATCH 1/2] git(1) docs: split "User-facing file formats" off from "Guides"
  2021-10-15  2:05 [PATCH 0/2] git(1) doc + "git help": split-out user & git format docs Ævar Arnfjörð Bjarmason
@ 2021-10-15  2:05 ` Ævar Arnfjörð Bjarmason
  2021-10-15  2:05 ` [PATCH 2/2] git(1) docs: create a "Git file and wire formats" section Ævar Arnfjörð Bjarmason
  2021-12-12 19:49 ` [PATCH v2 0/5] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
  2 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-10-15  2:05 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Philippe Blain, Todd Zullinger, Eric Wong,
	Jeff King, Ævar Arnfjörð Bjarmason

Create a new "User-facing file formats" section in the main "git(1)"
manual page. The "Guides" section was added to the manual page in
f442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense
to list all that documentation.

But placing e.g. "gitignore(5)" in it is stretching the meaning of
what a "guide" is, ideally that section should list things similar to
"giteveryday(7)" and "gitcore-tutorial(7)".

We take a wide view of what's considered a "user format", it's not
just a file format, but e.g. githooks(5) also belongs, since the
layout of the ".git/hooks/" and the placement of hooks in it is
something the user might be expected to interact with.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile     |  1 +
 Documentation/git-help.txt | 11 ++++++++---
 Documentation/git.txt      |  7 +++++++
 Makefile                   |  1 +
 builtin/help.c             |  8 ++++++++
 command-list.txt           | 16 ++++++++++------
 help.c                     | 11 +++++++++++
 help.h                     |  1 +
 t/t0012-help.sh            | 16 +++++++++++++++-
 9 files changed, 62 insertions(+), 10 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 2021568cd5a..8efed2e23e1 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -311,6 +311,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
 	cmds-synchingrepositories.txt \
 	cmds-synchelpers.txt \
 	cmds-guide.txt \
+	cmds-userformats.txt \
 	cmds-purehelpers.txt \
 	cmds-foreignscminterface.txt
 
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index 96d5f598b4b..d47feca0d29 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -12,11 +12,12 @@ SYNOPSIS
 	   [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE]
 'git help' [-g|--guides]
 'git help' [-c|--config]
+'git help' [--user-formats]
 
 DESCRIPTION
 -----------
 
-With no options and no COMMAND or GUIDE given, the synopsis of the 'git'
+With no options and no COMMAND or DOC given, the synopsis of the 'git'
 command and a list of the most commonly used Git commands are printed
 on the standard output.
 
@@ -26,8 +27,8 @@ printed on the standard output.
 If the option `--guides` or `-g` is given, a list of the
 Git concept guides is also printed on the standard output.
 
-If a command, or a guide, is given, a manual page for that command or
-guide is brought up. The 'man' program is used by default for this
+If a command or other documentation is given, the relevant manual page
+will be brought up. The 'man' program is used by default for this
 purpose, but this can be overridden by other options or configuration
 variables.
 
@@ -62,6 +63,10 @@ OPTIONS
 --guides::
 	Prints a list of the Git concept guides on the standard output.
 
+--user-formats::
+	Prints a list of the Git user-facing format documentation on
+	the standard output.
+
 -i::
 --info::
 	Display manual page for the command in the 'info' format. The
diff --git a/Documentation/git.txt b/Documentation/git.txt
index d63c65e67d8..823977595c5 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -337,6 +337,13 @@ The following documentation pages are guides about Git concepts.
 
 include::cmds-guide.txt[]
 
+User-facing file formats
+------------------------
+
+This documentation discusses file formats that users are expected to
+edit. These can also be listed with 'git help --user-formats'.
+
+include::cmds-userformats.txt[]
 
 Configuration Mechanism
 -----------------------
diff --git a/Makefile b/Makefile
index 060a8c46475..3956ed4b291 100644
--- a/Makefile
+++ b/Makefile
@@ -3312,6 +3312,7 @@ check-docs::
 		sed -e '1,/^### command list/d' \
 		    -e '/^#/d' \
 		    -e '/guide$$/d' \
+		    -e '/formats$$/d' \
 		    -e 's/[ 	].*//' \
 		    -e 's/^/listed /' command-list.txt; \
 		$(MAKE) -C Documentation print-man1 | \
diff --git a/builtin/help.c b/builtin/help.c
index 75cd2fb407f..5e842ea5a26 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -43,6 +43,7 @@ static enum help_action {
 	HELP_ACTION_ALL = 1,
 	HELP_ACTION_GUIDES,
 	HELP_ACTION_CONFIG,
+	HELP_ACTION_USER_FORMATS,
 	HELP_ACTION_CONFIG_FOR_COMPLETION,
 	HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
 } cmd_mode;
@@ -64,6 +65,8 @@ static struct option builtin_help_options[] = {
 
 	OPT_CMDMODE('g', "guides", &cmd_mode, N_("print list of useful guides"),
 		    HELP_ACTION_GUIDES),
+	OPT_CMDMODE(0, "user-formats", &cmd_mode, N_("print list of user-facing file formats"),
+		    HELP_ACTION_USER_FORMATS),
 	OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
 		    HELP_ACTION_CONFIG),
 	OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
@@ -79,6 +82,7 @@ static const char * const builtin_help_usage[] = {
 	   "         [[-i|--info] [-m|--man] [-w|--web]] [<command>]"),
 	N_("git help [-g|--guides]"),
 	N_("git help [-c|--config]"),
+	N_("git help [--user-formats]"),
 	NULL
 };
 
@@ -613,6 +617,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		no_extra_argc(argc);
 		list_config_help(SHOW_CONFIG_VARS);
 		return 0;
+	case HELP_ACTION_USER_FORMATS:
+		no_extra_argc(argc);
+		list_user_formats_help();
+		return 0;
 	case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
 		no_extra_argc(argc);
 		list_config_help(SHOW_CONFIG_SECTIONS);
diff --git a/command-list.txt b/command-list.txt
index a289f09ed6f..5732ea437a8 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -43,6 +43,10 @@
 # specified here, which can only have "guide" attribute and nothing
 # else.
 #
+# User-facing file formats such as documentation for the .gitmodules,
+# .mailmap etc. files lives in man section 5. These entries can only
+# have the "userformats" attribute and nothing else.
+#
 ### command list (do not change this line, also do not change alignment)
 # command name                          category [category] [category]
 git-add                                 mainporcelain           worktree
@@ -193,7 +197,7 @@ gitweb                                  ancillaryinterrogators
 git-whatchanged                         ancillaryinterrogators          complete
 git-worktree                            mainporcelain
 git-write-tree                          plumbingmanipulators
-gitattributes                           guide
+gitattributes                           userformats
 gitcli                                  guide
 gitcore-tutorial                        guide
 gitcredentials                          guide
@@ -202,13 +206,13 @@ gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
 gitglossary                             guide
-githooks                                guide
-gitignore                               guide
-gitmailmap                              guide
-gitmodules                              guide
+githooks                                userformats
+gitignore                               userformats
+gitmailmap                              userformats
+gitmodules                              userformats
 gitnamespaces                           guide
 gitremote-helpers                       guide
-gitrepository-layout                    guide
+gitrepository-layout                    userformats
 gitrevisions                            guide
 gitsubmodules                           guide
 gittutorial-2                           guide
diff --git a/help.c b/help.c
index 973e47cdc30..a7b5c909056 100644
--- a/help.c
+++ b/help.c
@@ -37,6 +37,7 @@ static struct category_description main_categories[] = {
 	{ CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") },
 	{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
 	{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
+	{ CAT_userformats, N_("User-facing file formats") },
 	{ 0, NULL }
 };
 
@@ -422,6 +423,16 @@ void list_guides_help(void)
 	putchar('\n');
 }
 
+void list_user_formats_help(void)
+{
+	struct category_description catdesc[] = {
+		{ CAT_userformats, N_("The user-facing file formats are:") },
+		{ 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 9d383f1a0b2..d01908078dc 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(void);
 void list_guides_help(void);
+void list_user_formats_help(void);
 
 void list_all_main_cmds(struct string_list *list);
 void list_all_other_cmds(struct string_list *list);
diff --git a/t/t0012-help.sh b/t/t0012-help.sh
index 91b68c74a15..6a20a7303f8 100755
--- a/t/t0012-help.sh
+++ b/t/t0012-help.sh
@@ -41,6 +41,8 @@ test_expect_success 'invalid usage' '
 	test_expect_code 129 git help -g add &&
 	test_expect_code 129 git help -a -g &&
 
+	test_expect_code 129 git help --user-formats add &&
+
 	test_expect_code 129 git help -g -c &&
 	test_expect_code 129 git help --config-for-completion add &&
 	test_expect_code 129 git help --config-sections-for-completion add
@@ -78,9 +80,15 @@ test_expect_success 'git help' '
 	test_i18ngrep "^   commit " help.output &&
 	test_i18ngrep "^   fetch  " help.output
 '
+
+test_expect_success 'git help -a' '
+	git help -a >help.output &&
+	grep "^Main Porcelain Commands" help.output &&
+	grep "^User-facing file formats" 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
 '
@@ -101,6 +109,12 @@ test_expect_success 'git help succeeds without git.html' '
 	test_cmp expect test-browser.log
 '
 
+test_expect_success 'git help --formats' '
+	git help --user-formats >help.output &&
+	grep "^   gitattributes   " help.output &&
+	grep "^   gitmailmap   " help.output
+'
+
 test_expect_success 'git help -c' '
 	git help -c >help.output &&
 	cat >expect <<-\EOF &&
-- 
2.33.1.1338.g20da966911a


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH 2/2] git(1) docs: create a "Git file and wire formats" section
  2021-10-15  2:05 [PATCH 0/2] git(1) doc + "git help": split-out user & git format docs Ævar Arnfjörð Bjarmason
  2021-10-15  2:05 ` [PATCH 1/2] git(1) docs: split "User-facing file formats" off from "Guides" Ævar Arnfjörð Bjarmason
@ 2021-10-15  2:05 ` Ævar Arnfjörð Bjarmason
  2021-12-12 19:49 ` [PATCH v2 0/5] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
  2 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-10-15  2:05 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Philippe Blain, Todd Zullinger, Eric Wong,
	Jeff King, Ævar Arnfjörð Bjarmason

Create a new "Git file and wire formats" section in the main "git(1)"
manual page and start moving the documentation that now lives in
"Documentation/technical/*.git" over to it. This compliments the newly
added and adjacent "User-facing file formats" section.

This makes the technical documentation more accessible and
discoverable. Before this we wouldn't install it by default, and had
no ability to build man page versions of them. The links to them from
our existing documentation link to the generated HTML version of these
docs.

So let's start moving those over, starting with just the
"bundle-format.txt" documentation added in 7378ec90e1c (doc: describe
Git bundle format, 2020-02-07). We'll now have a new
gitformat-bundle(5) man page.

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 <avarab@gmail.com>
---
 Documentation/Makefile                        |  3 +-
 Documentation/git-bundle.txt                  | 12 +++--
 Documentation/git.txt                         |  8 ++++
 ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++---
 Documentation/lint-man-section-order.perl     |  3 ++
 builtin/help.c                                |  8 ++++
 command-list.txt                              |  5 +++
 help.c                                        | 11 +++++
 help.h                                        |  1 +
 9 files changed, 83 insertions(+), 12 deletions(-)
 rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (78%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 8efed2e23e1..cc4761df82e 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -21,6 +21,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
@@ -90,7 +91,6 @@ SP_ARTICLES += $(API_DOCS)
 TECH_DOCS += MyFirstContribution
 TECH_DOCS += MyFirstObjectWalk
 TECH_DOCS += SubmittingPatches
-TECH_DOCS += technical/bundle-format
 TECH_DOCS += technical/hash-function-transition
 TECH_DOCS += technical/http-protocol
 TECH_DOCS += technical/index-format
@@ -312,6 +312,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
 	cmds-synchelpers.txt \
 	cmds-guide.txt \
 	cmds-userformats.txt \
+	cmds-gitformats.txt \
 	cmds-purehelpers.txt \
 	cmds-foreignscminterface.txt
 
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 71b5ecabd1f..cc3c32f5c0d 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
 -------
@@ -334,6 +333,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.txt b/Documentation/git.txt
index 823977595c5..0c77475d7a0 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -345,6 +345,14 @@ edit. These can also be listed with 'git help --user-formats'.
 
 include::cmds-userformats.txt[]
 
+Git file and wire formats
+-------------------------
+
+This documentation discusses the file and wire formats that git itself
+uses. These can also be listed with 'git help --git-formats'.
+
+include::cmds-gitformats.txt[]
+
 Configuration Mechanism
 -----------------------
 
diff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt
similarity index 78%
rename from Documentation/technical/bundle-format.txt
rename to Documentation/gitformat-bundle.txt
index bac558d049a..3aa2242eb9d 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,15 +86,21 @@ 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.  The only known capability is `object-format`, which specifies
 the hash algorithm in use, and can take the same values as the
 `extensions.objectFormat` configuration value.
+
+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 b05f9156dd9..81f04b6f3a2 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 5e842ea5a26..54ff30a0d37 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -44,6 +44,7 @@ static enum help_action {
 	HELP_ACTION_GUIDES,
 	HELP_ACTION_CONFIG,
 	HELP_ACTION_USER_FORMATS,
+	HELP_ACTION_GIT_FORMATS,
 	HELP_ACTION_CONFIG_FOR_COMPLETION,
 	HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
 } cmd_mode;
@@ -67,6 +68,8 @@ static struct option builtin_help_options[] = {
 		    HELP_ACTION_GUIDES),
 	OPT_CMDMODE(0, "user-formats", &cmd_mode, N_("print list of user-facing file formats"),
 		    HELP_ACTION_USER_FORMATS),
+	OPT_CMDMODE(0, "git-formats", &cmd_mode, N_("print list of Git's own file and network formats"),
+		    HELP_ACTION_GIT_FORMATS),
 	OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
 		    HELP_ACTION_CONFIG),
 	OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
@@ -83,6 +86,7 @@ static const char * const builtin_help_usage[] = {
 	N_("git help [-g|--guides]"),
 	N_("git help [-c|--config]"),
 	N_("git help [--user-formats]"),
+	N_("git help [--git-formats]"),
 	NULL
 };
 
@@ -621,6 +625,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		no_extra_argc(argc);
 		list_user_formats_help();
 		return 0;
+	case HELP_ACTION_GIT_FORMATS:
+		no_extra_argc(argc);
+		list_git_formats_help();
+		return 0;
 	case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
 		no_extra_argc(argc);
 		list_config_help(SHOW_CONFIG_SECTIONS);
diff --git a/command-list.txt b/command-list.txt
index 5732ea437a8..3cf09b9d9eb 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -47,6 +47,10 @@
 # .mailmap etc. files lives in man section 5. These entries can only
 # have the "userformats" attribute and nothing else.
 #
+# Git's own file and network formats such as documentation for the
+# *.bundle format lives in mn section 5. These entries can only have
+# the "gitformats" attribute and nothing else.
+#
 ### command list (do not change this line, also do not change alignment)
 # command name                          category [category] [category]
 git-add                                 mainporcelain           worktree
@@ -210,6 +214,7 @@ githooks                                userformats
 gitignore                               userformats
 gitmailmap                              userformats
 gitmodules                              userformats
+gitformat-bundle                        gitformats
 gitnamespaces                           guide
 gitremote-helpers                       guide
 gitrepository-layout                    userformats
diff --git a/help.c b/help.c
index a7b5c909056..7b97867cb96 100644
--- a/help.c
+++ b/help.c
@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {
 	{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
 	{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
 	{ CAT_userformats, N_("User-facing file formats") },
+	{ CAT_gitformats, N_("Internal file- and wire formats formats") },
 	{ 0, NULL }
 };
 
@@ -433,6 +434,16 @@ void list_user_formats_help(void)
 	putchar('\n');
 }
 
+void list_git_formats_help(void)
+{
+	struct category_description catdesc[] = {
+		{ CAT_gitformats, N_("Git's internal file and network formats are:") },
+		{ 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 d01908078dc..1075235f367 100644
--- a/help.h
+++ b/help.h
@@ -23,6 +23,7 @@ void list_common_cmds_help(void);
 void list_all_cmds_help(void);
 void list_guides_help(void);
 void list_user_formats_help(void);
+void list_git_formats_help(void);
 
 void list_all_main_cmds(struct string_list *list);
 void list_all_other_cmds(struct string_list *list);
-- 
2.33.1.1338.g20da966911a


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v2 0/5] git doc + "git help": move "format" docs from technical/*
  2021-10-15  2:05 [PATCH 0/2] git(1) doc + "git help": split-out user & git format docs Ævar Arnfjörð Bjarmason
  2021-10-15  2:05 ` [PATCH 1/2] git(1) docs: split "User-facing file formats" off from "Guides" Ævar Arnfjörð Bjarmason
  2021-10-15  2:05 ` [PATCH 2/2] git(1) docs: create a "Git file and wire formats" section Ævar Arnfjörð Bjarmason
@ 2021-12-12 19:49 ` Ævar Arnfjörð Bjarmason
  2021-12-12 19:49   ` [PATCH v2 1/5] git docs: split "User-facing file formats" off from "Guides" Ævar Arnfjörð Bjarmason
                     ` (5 more replies)
  2 siblings, 6 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-12-12 19:49 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Philippe Blain, Todd Zullinger, Eric Wong,
	Jeff King, Teng Long, Derrick Stolee, Taylor Blau,
	Ævar Arnfjörð Bjarmason

[This is a more meaty re-roll of [1]. It previously conflicted with
topics that have now landed. There is a trivial conflict here with
tb/cruft-packs, but that one's easily solved (they both edit adjacent
but otherwise unrelated lines in Documentation/Makefile)]

Most of git is documented in its manual pages, but we have various
"technical" and "howto" docs that aren't built as manpages, only as
HTML documentation.

In many cases that's sensible, e.g. we've got one-off mailing list
posts in there, but in the case of documenting git's core file formats
I think these belong in the main documentation space, especially as
many existing manual pages refer to these, but need to do so by
linking from "man" pages to "*.html" files the user may or may not
have locally.

This series starts out by creating a "userformats" category in our
documentation. The documentation for ".gitignore", ".gitattributes",
".mailmap" etc. is currently in the "guides" space. We now have a
"userformats" space with file formats users are expected to interact
with:
    
    $ git help --user-formats
    
    The user-facing file formats are:
       gitattributes          Defining attributes per path
       githooks               Hooks used by Git
       gitignore              Specifies intentionally untracked files to ignore
       gitmailmap             Map author/committer names and/or E-Mail addresses
       gitmodules             Defining submodule properties
       gitrepository-layout   Git Repository Layout

We then have (the main meat of this series) a move of relevant
"internal" and "protocol" formats over to the main documentation
space:

    $ git help --git-formats
    
    Git's internal file and network formats are:
       gitformat-bitmap                  The bitmap file format
       gitformat-bundle                  The bundle file format
       gitformat-chunk                   Chunk-based file formats
       gitformat-commit-graph            Git commit graph format
       gitformat-index                   Git index format
       gitformat-pack-protocol           How packs are transferred over-the-wire
       gitformat-protocol-capabilities   Protocol v0 and v1 capabilities
       gitformat-protocol-common         Things common to various protocols
       gitformat-protocol-v2             Git Wire Protocol, Version 2
       gitformat-signature               Git cryptographic signature formats

This isn't all of them, there's some in-flight conflicts with other
(trivial) changes to those files, so I've skipped them for now. Taylor
also has an in-flight series to add a new Documentation/technical/*
series. I'm planning on an eventual follow-up series (and have most of
the changes already) to move those over.

This also doesn't move over the part of the api-trace2.txt that deals
with the format users interact with, i.e. the JSON schema. I'm
submitting other changes in that are currently, and will eventually
loop around to moving that part over to this new "gitformats" space.

1. https://lore.kernel.org/git/cover-0.2-00000000000-20211015T020351Z-avarab@gmail.com/

Ævar Arnfjörð Bjarmason (5):
  git docs: split "User-facing file formats" off from "Guides"
  git docs: create a "Git file and wire formats" section
  docs: move commit-graph format docs to man section 5
  docs: move protocol-related docs to man section 5
  docs: move {index,signature,bitmap,chunk}-format docs to man section 5

 Documentation/Makefile                        | 19 ++++---
 Documentation/config/lsrefs.txt               |  2 +-
 Documentation/config/protocol.txt             |  2 +-
 Documentation/git-bundle.txt                  | 12 +++--
 Documentation/git-commit-graph.txt            |  5 ++
 Documentation/git-help.txt                    | 13 +++--
 Documentation/git-upload-pack.txt             |  5 +-
 Documentation/git.txt                         | 15 ++++++
 ...bitmap-format.txt => gitformat-bitmap.txt} | 38 +++++++++++---
 ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++---
 .../chunk-format.txt => gitformat-chunk.txt}  | 25 ++++++++--
 ...-format.txt => gitformat-commit-graph.txt} | 49 +++++++++++++------
 .../index-format.txt => gitformat-index.txt}  | 20 +++++++-
 ...otocol.txt => gitformat-pack-protocol.txt} | 22 +++++++--
 ...xt => gitformat-protocol-capabilities.txt} | 28 ++++++++---
 ...mmon.txt => gitformat-protocol-common.txt} | 23 ++++++++-
 ...tocol-v2.txt => gitformat-protocol-v2.txt} | 24 +++++++--
 ...ure-format.txt => gitformat-signature.txt} | 21 ++++++--
 Documentation/lint-man-section-order.perl     |  3 ++
 Documentation/technical/api-simple-ipc.txt    |  2 +-
 Documentation/technical/http-protocol.txt     |  6 +--
 .../long-running-process-protocol.txt         |  2 +-
 Documentation/technical/pack-format.txt       |  2 +-
 Documentation/technical/partial-clone.txt     |  2 +-
 Makefile                                      |  1 +
 builtin/help.c                                | 16 ++++++
 command-list.txt                              | 30 +++++++++---
 help.c                                        | 22 +++++++++
 help.h                                        |  2 +
 t/t0012-help.sh                               | 16 +++++-
 t/t5551-http-fetch-smart.sh                   |  4 +-
 31 files changed, 386 insertions(+), 89 deletions(-)
 rename Documentation/{technical/bitmap-format.txt => gitformat-bitmap.txt} (91%)
 rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (78%)
 rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (91%)
 rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (86%)
 rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)
 rename Documentation/{technical/pack-protocol.txt => gitformat-pack-protocol.txt} (98%)
 rename Documentation/{technical/protocol-capabilities.txt => gitformat-protocol-capabilities.txt} (96%)
 rename Documentation/{technical/protocol-common.txt => gitformat-protocol-common.txt} (88%)
 rename Documentation/{technical/protocol-v2.txt => gitformat-protocol-v2.txt} (98%)
 rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)

Range-diff against v1:
1:  19a8be1fc73 ! 1:  960574b7f05 git(1) docs: split "User-facing file formats" off from "Guides"
    @@ Metadata
     Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
      ## Commit message ##
    -    git(1) docs: split "User-facing file formats" off from "Guides"
    +    git docs: split "User-facing file formats" off from "Guides"
     
    -    Create a new "User-facing file formats" section in the main "git(1)"
    -    manual page. The "Guides" section was added to the manual page in
    +    Create a new "User-facing file formats" section in the main "git help
    +    git" manual page. The "Guides" section was added to the manual page in
         f442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense
         to list all that documentation.
     
    @@ Documentation/Makefile: cmds_txt = cmds-ancillaryinterrogators.txt \
     
      ## Documentation/git-help.txt ##
     @@ Documentation/git-help.txt: SYNOPSIS
    - 	   [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE]
    + --------
    + [verse]
    + 'git help' [-a|--all [--[no-]verbose]]
    +-	   [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]
    ++	   [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>|<doc>]
      'git help' [-g|--guides]
      'git help' [-c|--config]
     +'git help' [--user-formats]
    @@ Documentation/git-help.txt: SYNOPSIS
      DESCRIPTION
      -----------
      
    --With no options and no COMMAND or GUIDE given, the synopsis of the 'git'
    -+With no options and no COMMAND or DOC given, the synopsis of the 'git'
    +-With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
    ++With no options and no '<command>', '<guide>' or '<doc>' given, the synopsis of the 'git'
      command and a list of the most commonly used Git commands are printed
      on the standard output.
      
    @@ command-list.txt
     +# .mailmap etc. files lives in man section 5. These entries can only
     +# have the "userformats" attribute and nothing else.
     +#
    - ### command list (do not change this line, also do not change alignment)
    + ### command list (do not change this line)
      # command name                          category [category] [category]
      git-add                                 mainporcelain           worktree
    -@@ command-list.txt: gitweb                                  ancillaryinterrogators
    +@@ command-list.txt: git-verify-tag                          ancillaryinterrogators
      git-whatchanged                         ancillaryinterrogators          complete
      git-worktree                            mainporcelain
      git-write-tree                          plumbingmanipulators
    @@ command-list.txt: gitdiffcore                             guide
      gitglossary                             guide
     -githooks                                guide
     -gitignore                               guide
    --gitmailmap                              guide
    --gitmodules                              guide
     +githooks                                userformats
     +gitignore                               userformats
    + gitk                                    mainporcelain
    +-gitmailmap                              guide
    +-gitmodules                              guide
     +gitmailmap                              userformats
     +gitmodules                              userformats
      gitnamespaces                           guide
    @@ command-list.txt: gitdiffcore                             guide
     +gitrepository-layout                    userformats
      gitrevisions                            guide
      gitsubmodules                           guide
    - gittutorial-2                           guide
    + gittutorial                             guide
     
      ## help.c ##
     @@ help.c: static struct category_description main_categories[] = {
2:  5e80ee09523 ! 2:  b2d73f8c9da git(1) docs: create a "Git file and wire formats" section
    @@ Metadata
     Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
      ## Commit message ##
    -    git(1) docs: create a "Git file and wire formats" section
    +    git docs: create a "Git file and wire formats" section
     
    -    Create a new "Git file and wire formats" section in the main "git(1)"
    -    manual page and start moving the documentation that now lives in
    +    Create a new "Git file and wire formats" section in the main "git help
    +    git" manual page and start moving the documentation that now lives in
         "Documentation/technical/*.git" over to it. This compliments the newly
         added and adjacent "User-facing file formats" section.
     
    @@ Commit message
         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.
    +    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/Makefile: cmds_txt = cmds-ancillaryinterrogators.txt \
      
     
      ## Documentation/git-bundle.txt ##
    -@@ Documentation/git-bundle.txt: using "thin packs" bundles created using exclusions are smaller in
    +@@ Documentation/git-bundle.txt: 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
    + 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
    @@ command-list.txt
     +# *.bundle format lives in mn section 5. These entries can only have
     +# the "gitformats" attribute and nothing else.
     +#
    - ### command list (do not change this line, also do not change alignment)
    + ### command list (do not change this line)
      # command name                          category [category] [category]
      git-add                                 mainporcelain           worktree
    -@@ command-list.txt: githooks                                userformats
    - gitignore                               userformats
    - gitmailmap                              userformats
    - gitmodules                              userformats
    +@@ command-list.txt: gitcvs-migration                        guide
    + gitdiffcore                             guide
    + giteveryday                             guide
    + gitfaq                                  guide
     +gitformat-bundle                        gitformats
    - gitnamespaces                           guide
    - gitremote-helpers                       guide
    - gitrepository-layout                    userformats
    + gitglossary                             guide
    + githooks                                userformats
    + gitignore                               userformats
     
      ## help.c ##
     @@ help.c: static struct category_description main_categories[] = {
-:  ----------- > 3:  5abd59b807f docs: move commit-graph format docs to man section 5
-:  ----------- > 4:  fb91009c18f docs: move protocol-related docs to man section 5
-:  ----------- > 5:  5cb41bb0dcb docs: move {index,signature,bitmap,chunk}-format docs to man section 5
-- 
2.34.1.929.ge922d848c7a


^ permalink raw reply	[flat|nested] 112+ messages in thread

* [PATCH v2 1/5] git docs: split "User-facing file formats" off from "Guides"
  2021-12-12 19:49 ` [PATCH v2 0/5] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
@ 2021-12-12 19:49   ` Ævar Arnfjörð Bjarmason
  2021-12-12 19:49   ` [PATCH v2 2/5] git docs: create a "Git file and wire formats" section Ævar Arnfjörð Bjarmason
                     ` (4 subsequent siblings)
  5 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-12-12 19:49 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Philippe Blain, Todd Zullinger, Eric Wong,
	Jeff King, Teng Long, Derrick Stolee, Taylor Blau,
	Ævar Arnfjörð Bjarmason

Create a new "User-facing file formats" section in the main "git help
git" manual page. The "Guides" section was added to the manual page in
f442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense
to list all that documentation.

But placing e.g. "gitignore(5)" in it is stretching the meaning of
what a "guide" is, ideally that section should list things similar to
"giteveryday(7)" and "gitcore-tutorial(7)".

We take a wide view of what's considered a "user format", it's not
just a file format, but e.g. githooks(5) also belongs, since the
layout of the ".git/hooks/" and the placement of hooks in it is
something the user might be expected to interact with.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile     |  1 +
 Documentation/git-help.txt | 13 +++++++++----
 Documentation/git.txt      |  7 +++++++
 Makefile                   |  1 +
 builtin/help.c             |  8 ++++++++
 command-list.txt           | 16 ++++++++++------
 help.c                     | 11 +++++++++++
 help.h                     |  1 +
 t/t0012-help.sh            | 16 +++++++++++++++-
 9 files changed, 63 insertions(+), 11 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index ed656db2ae9..e973be97162 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -316,6 +316,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
 	cmds-synchingrepositories.txt \
 	cmds-synchelpers.txt \
 	cmds-guide.txt \
+	cmds-userformats.txt \
 	cmds-purehelpers.txt \
 	cmds-foreignscminterface.txt
 
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index 44ea63cc6d3..32081f3030d 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -9,14 +9,15 @@ SYNOPSIS
 --------
 [verse]
 'git help' [-a|--all [--[no-]verbose]]
-	   [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]
+	   [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>|<doc>]
 'git help' [-g|--guides]
 'git help' [-c|--config]
+'git help' [--user-formats]
 
 DESCRIPTION
 -----------
 
-With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
+With no options and no '<command>', '<guide>' or '<doc>' given, the synopsis of the 'git'
 command and a list of the most commonly used Git commands are printed
 on the standard output.
 
@@ -26,8 +27,8 @@ printed on the standard output.
 If the option `--guides` or `-g` is given, a list of the
 Git concept guides is also printed on the standard output.
 
-If a command, or a guide, is given, a manual page for that command or
-guide is brought up. The 'man' program is used by default for this
+If a command or other documentation is given, the relevant manual page
+will be brought up. The 'man' program is used by default for this
 purpose, but this can be overridden by other options or configuration
 variables.
 
@@ -62,6 +63,10 @@ OPTIONS
 --guides::
 	Prints a list of the Git concept guides on the standard output.
 
+--user-formats::
+	Prints a list of the Git user-facing format documentation on
+	the standard output.
+
 -i::
 --info::
 	Display manual page for the command in the 'info' format. The
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 13f83a2a3a1..7a8be2991df 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -337,6 +337,13 @@ The following documentation pages are guides about Git concepts.
 
 include::cmds-guide.txt[]
 
+User-facing file formats
+------------------------
+
+This documentation discusses file formats that users are expected to
+edit. These can also be listed with 'git help --user-formats'.
+
+include::cmds-userformats.txt[]
 
 Configuration Mechanism
 -----------------------
diff --git a/Makefile b/Makefile
index ed75ed422b5..c59fd6c2be9 100644
--- a/Makefile
+++ b/Makefile
@@ -3304,6 +3304,7 @@ check-docs::
 		sed -e '1,/^### command list/d' \
 		    -e '/^#/d' \
 		    -e '/guide$$/d' \
+		    -e '/formats$$/d' \
 		    -e 's/[ 	].*//' \
 		    -e 's/^/listed /' command-list.txt; \
 		$(MAKE) -C Documentation print-man1 | \
diff --git a/builtin/help.c b/builtin/help.c
index 75cd2fb407f..5e842ea5a26 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -43,6 +43,7 @@ static enum help_action {
 	HELP_ACTION_ALL = 1,
 	HELP_ACTION_GUIDES,
 	HELP_ACTION_CONFIG,
+	HELP_ACTION_USER_FORMATS,
 	HELP_ACTION_CONFIG_FOR_COMPLETION,
 	HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
 } cmd_mode;
@@ -64,6 +65,8 @@ static struct option builtin_help_options[] = {
 
 	OPT_CMDMODE('g', "guides", &cmd_mode, N_("print list of useful guides"),
 		    HELP_ACTION_GUIDES),
+	OPT_CMDMODE(0, "user-formats", &cmd_mode, N_("print list of user-facing file formats"),
+		    HELP_ACTION_USER_FORMATS),
 	OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
 		    HELP_ACTION_CONFIG),
 	OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
@@ -79,6 +82,7 @@ static const char * const builtin_help_usage[] = {
 	   "         [[-i|--info] [-m|--man] [-w|--web]] [<command>]"),
 	N_("git help [-g|--guides]"),
 	N_("git help [-c|--config]"),
+	N_("git help [--user-formats]"),
 	NULL
 };
 
@@ -613,6 +617,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		no_extra_argc(argc);
 		list_config_help(SHOW_CONFIG_VARS);
 		return 0;
+	case HELP_ACTION_USER_FORMATS:
+		no_extra_argc(argc);
+		list_user_formats_help();
+		return 0;
 	case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
 		no_extra_argc(argc);
 		list_config_help(SHOW_CONFIG_SECTIONS);
diff --git a/command-list.txt b/command-list.txt
index 675c28f0bd0..e4118533e93 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -43,6 +43,10 @@
 # specified here, which can only have "guide" attribute and nothing
 # else.
 #
+# User-facing file formats such as documentation for the .gitmodules,
+# .mailmap etc. files lives in man section 5. These entries can only
+# have the "userformats" attribute and nothing else.
+#
 ### command list (do not change this line)
 # command name                          category [category] [category]
 git-add                                 mainporcelain           worktree
@@ -191,7 +195,7 @@ git-verify-tag                          ancillaryinterrogators
 git-whatchanged                         ancillaryinterrogators          complete
 git-worktree                            mainporcelain
 git-write-tree                          plumbingmanipulators
-gitattributes                           guide
+gitattributes                           userformats
 gitcli                                  guide
 gitcore-tutorial                        guide
 gitcredentials                          guide
@@ -200,14 +204,14 @@ gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
 gitglossary                             guide
-githooks                                guide
-gitignore                               guide
+githooks                                userformats
+gitignore                               userformats
 gitk                                    mainporcelain
-gitmailmap                              guide
-gitmodules                              guide
+gitmailmap                              userformats
+gitmodules                              userformats
 gitnamespaces                           guide
 gitremote-helpers                       guide
-gitrepository-layout                    guide
+gitrepository-layout                    userformats
 gitrevisions                            guide
 gitsubmodules                           guide
 gittutorial                             guide
diff --git a/help.c b/help.c
index 973e47cdc30..a7b5c909056 100644
--- a/help.c
+++ b/help.c
@@ -37,6 +37,7 @@ static struct category_description main_categories[] = {
 	{ CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") },
 	{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
 	{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
+	{ CAT_userformats, N_("User-facing file formats") },
 	{ 0, NULL }
 };
 
@@ -422,6 +423,16 @@ void list_guides_help(void)
 	putchar('\n');
 }
 
+void list_user_formats_help(void)
+{
+	struct category_description catdesc[] = {
+		{ CAT_userformats, N_("The user-facing file formats are:") },
+		{ 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 9d383f1a0b2..d01908078dc 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(void);
 void list_guides_help(void);
+void list_user_formats_help(void);
 
 void list_all_main_cmds(struct string_list *list);
 void list_all_other_cmds(struct string_list *list);
diff --git a/t/t0012-help.sh b/t/t0012-help.sh
index 91b68c74a15..6a20a7303f8 100755
--- a/t/t0012-help.sh
+++ b/t/t0012-help.sh
@@ -41,6 +41,8 @@ test_expect_success 'invalid usage' '
 	test_expect_code 129 git help -g add &&
 	test_expect_code 129 git help -a -g &&
 
+	test_expect_code 129 git help --user-formats add &&
+
 	test_expect_code 129 git help -g -c &&
 	test_expect_code 129 git help --config-for-completion add &&
 	test_expect_code 129 git help --config-sections-for-completion add
@@ -78,9 +80,15 @@ test_expect_success 'git help' '
 	test_i18ngrep "^   commit " help.output &&
 	test_i18ngrep "^   fetch  " help.output
 '
+
+test_expect_success 'git help -a' '
+	git help -a >help.output &&
+	grep "^Main Porcelain Commands" help.output &&
+	grep "^User-facing file formats" 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
 '
@@ -101,6 +109,12 @@ test_expect_success 'git help succeeds without git.html' '
 	test_cmp expect test-browser.log
 '
 
+test_expect_success 'git help --formats' '
+	git help --user-formats >help.output &&
+	grep "^   gitattributes   " help.output &&
+	grep "^   gitmailmap   " help.output
+'
+
 test_expect_success 'git help -c' '
 	git help -c >help.output &&
 	cat >expect <<-\EOF &&
-- 
2.34.1.929.ge922d848c7a


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v2 2/5] git docs: create a "Git file and wire formats" section
  2021-12-12 19:49 ` [PATCH v2 0/5] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
  2021-12-12 19:49   ` [PATCH v2 1/5] git docs: split "User-facing file formats" off from "Guides" Ævar Arnfjörð Bjarmason
@ 2021-12-12 19:49   ` Ævar Arnfjörð Bjarmason
  2021-12-12 22:30     ` Eric Sunshine
  2021-12-12 19:49   ` [PATCH v2 3/5] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
                     ` (3 subsequent siblings)
  5 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-12-12 19:49 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Philippe Blain, Todd Zullinger, Eric Wong,
	Jeff King, Teng Long, Derrick Stolee, Taylor Blau,
	Ævar Arnfjörð Bjarmason

Create a new "Git file and wire formats" section in the main "git help
git" manual page and start moving the documentation that now lives in
"Documentation/technical/*.git" over to it. This compliments the newly
added and adjacent "User-facing file formats" section.

This makes the technical documentation more accessible and
discoverable. Before this we wouldn't install it by default, and had
no ability to build man page versions of them. The links to them from
our existing documentation link to the generated HTML version of these
docs.

So let's start moving those over, starting with just the
"bundle-format.txt" documentation added in 7378ec90e1c (doc: describe
Git bundle format, 2020-02-07). We'll now have a new
gitformat-bundle(5) man page. Subsequent commits will move more git
internal format documentation over.

Unfortunately the syntax of the current Documentation/technical/*.txt
is not the same (when it comes to section headings etc.) as our
Documentation/*.txt documentation, so change the relevant bits of
syntax as we're moving this over.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile                        |  3 +-
 Documentation/git-bundle.txt                  | 12 +++--
 Documentation/git.txt                         |  8 ++++
 ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++---
 Documentation/lint-man-section-order.perl     |  3 ++
 builtin/help.c                                |  8 ++++
 command-list.txt                              |  5 +++
 help.c                                        | 11 +++++
 help.h                                        |  1 +
 9 files changed, 83 insertions(+), 12 deletions(-)
 rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (78%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index e973be97162..fe8e1c56c7d 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -21,6 +21,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
@@ -90,7 +91,6 @@ SP_ARTICLES += $(API_DOCS)
 TECH_DOCS += MyFirstContribution
 TECH_DOCS += MyFirstObjectWalk
 TECH_DOCS += SubmittingPatches
-TECH_DOCS += technical/bundle-format
 TECH_DOCS += technical/hash-function-transition
 TECH_DOCS += technical/http-protocol
 TECH_DOCS += technical/index-format
@@ -317,6 +317,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
 	cmds-synchelpers.txt \
 	cmds-guide.txt \
 	cmds-userformats.txt \
+	cmds-gitformats.txt \
 	cmds-purehelpers.txt \
 	cmds-foreignscminterface.txt
 
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 72ab8139052..0ebf3301a0a 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
 -------
@@ -334,6 +333,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.txt b/Documentation/git.txt
index 7a8be2991df..75cce82915d 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -345,6 +345,14 @@ edit. These can also be listed with 'git help --user-formats'.
 
 include::cmds-userformats.txt[]
 
+Git file and wire formats
+-------------------------
+
+This documentation discusses the file and wire formats that git itself
+uses. These can also be listed with 'git help --git-formats'.
+
+include::cmds-gitformats.txt[]
+
 Configuration Mechanism
 -----------------------
 
diff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt
similarity index 78%
rename from Documentation/technical/bundle-format.txt
rename to Documentation/gitformat-bundle.txt
index bac558d049a..3aa2242eb9d 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,15 +86,21 @@ 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.  The only known capability is `object-format`, which specifies
 the hash algorithm in use, and can take the same values as the
 `extensions.objectFormat` configuration value.
+
+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 5e842ea5a26..54ff30a0d37 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -44,6 +44,7 @@ static enum help_action {
 	HELP_ACTION_GUIDES,
 	HELP_ACTION_CONFIG,
 	HELP_ACTION_USER_FORMATS,
+	HELP_ACTION_GIT_FORMATS,
 	HELP_ACTION_CONFIG_FOR_COMPLETION,
 	HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
 } cmd_mode;
@@ -67,6 +68,8 @@ static struct option builtin_help_options[] = {
 		    HELP_ACTION_GUIDES),
 	OPT_CMDMODE(0, "user-formats", &cmd_mode, N_("print list of user-facing file formats"),
 		    HELP_ACTION_USER_FORMATS),
+	OPT_CMDMODE(0, "git-formats", &cmd_mode, N_("print list of Git's own file and network formats"),
+		    HELP_ACTION_GIT_FORMATS),
 	OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
 		    HELP_ACTION_CONFIG),
 	OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
@@ -83,6 +86,7 @@ static const char * const builtin_help_usage[] = {
 	N_("git help [-g|--guides]"),
 	N_("git help [-c|--config]"),
 	N_("git help [--user-formats]"),
+	N_("git help [--git-formats]"),
 	NULL
 };
 
@@ -621,6 +625,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		no_extra_argc(argc);
 		list_user_formats_help();
 		return 0;
+	case HELP_ACTION_GIT_FORMATS:
+		no_extra_argc(argc);
+		list_git_formats_help();
+		return 0;
 	case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
 		no_extra_argc(argc);
 		list_config_help(SHOW_CONFIG_SECTIONS);
diff --git a/command-list.txt b/command-list.txt
index e4118533e93..40d27371228 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -47,6 +47,10 @@
 # .mailmap etc. files lives in man section 5. These entries can only
 # have the "userformats" attribute and nothing else.
 #
+# Git's own file and network formats such as documentation for the
+# *.bundle format lives in mn section 5. These entries can only have
+# the "gitformats" attribute and nothing else.
+#
 ### command list (do not change this line)
 # command name                          category [category] [category]
 git-add                                 mainporcelain           worktree
@@ -203,6 +207,7 @@ gitcvs-migration                        guide
 gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
+gitformat-bundle                        gitformats
 gitglossary                             guide
 githooks                                userformats
 gitignore                               userformats
diff --git a/help.c b/help.c
index a7b5c909056..7b97867cb96 100644
--- a/help.c
+++ b/help.c
@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {
 	{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
 	{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
 	{ CAT_userformats, N_("User-facing file formats") },
+	{ CAT_gitformats, N_("Internal file- and wire formats formats") },
 	{ 0, NULL }
 };
 
@@ -433,6 +434,16 @@ void list_user_formats_help(void)
 	putchar('\n');
 }
 
+void list_git_formats_help(void)
+{
+	struct category_description catdesc[] = {
+		{ CAT_gitformats, N_("Git's internal file and network formats are:") },
+		{ 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 d01908078dc..1075235f367 100644
--- a/help.h
+++ b/help.h
@@ -23,6 +23,7 @@ void list_common_cmds_help(void);
 void list_all_cmds_help(void);
 void list_guides_help(void);
 void list_user_formats_help(void);
+void list_git_formats_help(void);
 
 void list_all_main_cmds(struct string_list *list);
 void list_all_other_cmds(struct string_list *list);
-- 
2.34.1.929.ge922d848c7a


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v2 3/5] docs: move commit-graph format docs to man section 5
  2021-12-12 19:49 ` [PATCH v2 0/5] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
  2021-12-12 19:49   ` [PATCH v2 1/5] git docs: split "User-facing file formats" off from "Guides" Ævar Arnfjörð Bjarmason
  2021-12-12 19:49   ` [PATCH v2 2/5] git docs: create a "Git file and wire formats" section Ævar Arnfjörð Bjarmason
@ 2021-12-12 19:49   ` Ævar Arnfjörð Bjarmason
  2021-12-12 19:49   ` [PATCH v2 4/5] docs: move protocol-related " Ævar Arnfjörð Bjarmason
                     ` (2 subsequent siblings)
  5 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-12-12 19:49 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Philippe Blain, Todd Zullinger, Eric Wong,
	Jeff King, Teng Long, Derrick Stolee, Taylor Blau,
	Ævar Arnfjörð Bjarmason

Continue the move of existing Documentation/technical/* protocol and
file-format documentation into our main documentation space.

By moving the documentation for the commit-graph format into man
section 5 and the new "gitformats" category. This change is split from
subsequent commits due to the relatively large amount of ASCIIDOC
formatting changes that are required.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile                        |  1 +
 Documentation/git-commit-graph.txt            |  5 ++
 ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------
 Documentation/technical/chunk-format.txt      |  4 +-
 command-list.txt                              |  1 +
 5 files changed, 41 insertions(+), 17 deletions(-)
 rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (87%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index fe8e1c56c7d..9483bde3420 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -22,6 +22,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 87%
rename from Documentation/technical/commit-graph-format.txt
rename to Documentation/gitformat-commit-graph.txt
index 87971c27dd7..25eb131dcd2 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', 'T' }) (N * 4 bytes) [Optional]
+==== Generation Data (ID: {'G', 'D', 'A', 'T' }) (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', 'V' }) [Optional]
+==== Generation Data Overflow (ID: {'G', 'D', 'O', 'V' }) [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,12 +160,16 @@ 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.
+
+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 40d27371228..f7dcc795e1e 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -208,6 +208,7 @@ gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
 gitformat-bundle                        gitformats
+gitformat-commit-graph                  gitformats
 gitglossary                             guide
 githooks                                userformats
 gitignore                               userformats
-- 
2.34.1.929.ge922d848c7a


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v2 4/5] docs: move protocol-related docs to man section 5
  2021-12-12 19:49 ` [PATCH v2 0/5] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
                     ` (2 preceding siblings ...)
  2021-12-12 19:49   ` [PATCH v2 3/5] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
@ 2021-12-12 19:49   ` Ævar Arnfjörð Bjarmason
  2021-12-12 19:49   ` [PATCH v2 5/5] docs: move {index,signature,bitmap,chunk}-format " Ævar Arnfjörð Bjarmason
  2022-07-12 20:06   ` [PATCH v3 0/7] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
  5 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-12-12 19:49 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Philippe Blain, Todd Zullinger, Eric Wong,
	Jeff King, Teng Long, Derrick Stolee, Taylor Blau,
	Ævar Arnfjörð Bjarmason

Continue the move of existing Documentation/technical/* protocol and
file-format documentation into our main documentation space. By moving
the things that discuss the protocol we can properly link from
e.g. lsrefs.unborn and protocol.version documentation to a manpage we
build by default.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile                        |  8 +++---
 Documentation/config/lsrefs.txt               |  2 +-
 Documentation/config/protocol.txt             |  2 +-
 Documentation/git-upload-pack.txt             |  5 ++--
 Documentation/gitformat-bundle.txt            |  2 +-
 ...otocol.txt => gitformat-pack-protocol.txt} | 22 +++++++++++++--
 ...xt => gitformat-protocol-capabilities.txt} | 28 +++++++++++++++----
 ...mmon.txt => gitformat-protocol-common.txt} | 23 +++++++++++++--
 ...tocol-v2.txt => gitformat-protocol-v2.txt} | 24 +++++++++++++---
 Documentation/technical/api-simple-ipc.txt    |  2 +-
 Documentation/technical/http-protocol.txt     |  6 ++--
 .../long-running-process-protocol.txt         |  2 +-
 Documentation/technical/partial-clone.txt     |  2 +-
 command-list.txt                              |  4 +++
 t/t5551-http-fetch-smart.sh                   |  4 +--
 15 files changed, 103 insertions(+), 33 deletions(-)
 rename Documentation/{technical/pack-protocol.txt => gitformat-pack-protocol.txt} (98%)
 rename Documentation/{technical/protocol-capabilities.txt => gitformat-protocol-capabilities.txt} (96%)
 rename Documentation/{technical/protocol-common.txt => gitformat-protocol-common.txt} (88%)
 rename Documentation/{technical/protocol-v2.txt => gitformat-protocol-v2.txt} (98%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 9483bde3420..ba587b75a51 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -23,6 +23,10 @@ MAN1_TXT += gitweb.txt
 MAN5_TXT += gitattributes.txt
 MAN5_TXT += gitformat-bundle.txt
 MAN5_TXT += gitformat-commit-graph.txt
+MAN5_TXT += gitformat-pack-protocol.txt
+MAN5_TXT += gitformat-protocol-capabilities.txt
+MAN5_TXT += gitformat-protocol-common.txt
+MAN5_TXT += gitformat-protocol-v2.txt
 MAN5_TXT += githooks.txt
 MAN5_TXT += gitignore.txt
 MAN5_TXT += gitmailmap.txt
@@ -99,12 +103,8 @@ TECH_DOCS += technical/long-running-process-protocol
 TECH_DOCS += technical/multi-pack-index
 TECH_DOCS += technical/pack-format
 TECH_DOCS += technical/pack-heuristics
-TECH_DOCS += technical/pack-protocol
 TECH_DOCS += technical/parallel-checkout
 TECH_DOCS += technical/partial-clone
-TECH_DOCS += technical/protocol-capabilities
-TECH_DOCS += technical/protocol-common
-TECH_DOCS += technical/protocol-v2
 TECH_DOCS += technical/racy-git
 TECH_DOCS += technical/reftable
 TECH_DOCS += technical/send-pack-pipeline
diff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.txt
index adeda0f24d3..e9efe498c01 100644
--- a/Documentation/config/lsrefs.txt
+++ b/Documentation/config/lsrefs.txt
@@ -1,7 +1,7 @@
 lsrefs.unborn::
 	May be "advertise" (the default), "allow", or "ignore". If "advertise",
 	the server will respond to the client sending "unborn" (as described in
-	protocol-v2.txt) and will advertise support for this feature during the
+	linkgit:gitformat-protocol-v2[5]) and will advertise support for this feature during the
 	protocol v2 capability advertisement. "allow" is the same as
 	"advertise" except that the server will not advertise support for this
 	feature; this is useful for load-balanced servers that cannot be
diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt
index 756591d77b0..bf18a70a924 100644
--- a/Documentation/config/protocol.txt
+++ b/Documentation/config/protocol.txt
@@ -58,6 +58,6 @@ protocol.version::
 * `1` - the original wire protocol with the addition of a version string
   in the initial response from the server.
 
-* `2` - link:technical/protocol-v2.html[wire protocol version 2].
+* `2` - Wire protocol version 2, see linkgit:gitformat-protocol-v2[5].
 
 --
diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt
index 8f87b23ea86..754619222f6 100644
--- a/Documentation/git-upload-pack.txt
+++ b/Documentation/git-upload-pack.txt
@@ -40,9 +40,8 @@ OPTIONS
 	Used by linkgit:git-http-backend[1] to serve up
 	`$GIT_URL/info/refs?service=git-upload-pack` requests. See
 	"Smart Clients" in link:technical/http-protocol.html[the HTTP
-	transfer protocols] documentation and "HTTP Transport" in
-	link:technical/protocol-v2.html[the Git Wire Protocol, Version
-	2] documentation. Also understood by
+	transfer protocols] documentation and "HTTP Transport" in the
+	linkgit:gitformat-protocol-v2[5] documentation. Also understood by
 	linkgit:git-receive-pack[1].
 
 <directory>::
diff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.txt
index 3aa2242eb9d..614d51362c9 100644
--- a/Documentation/gitformat-bundle.txt
+++ b/Documentation/gitformat-bundle.txt
@@ -27,7 +27,7 @@ FORMAT
 ------
 
 We will use ABNF notation to define the Git bundle format. See
-link:technical/protocol-common.html for the details.
+linkgit:gitformat-protocol-common[5] for the details.
 
 A v2 bundle looks like this:
 
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt
similarity index 98%
rename from Documentation/technical/pack-protocol.txt
rename to Documentation/gitformat-pack-protocol.txt
index e13a2c064d1..b665af5b690 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/gitformat-pack-protocol.txt
@@ -1,5 +1,17 @@
-Packfile transfer protocols
-===========================
+gitformat-pack-protocol(5)
+==========================
+
+NAME
+----
+gitformat-pack-protocol - How packs are transferred over-the-wire
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
 
 Git supports transferring data in packfiles over the ssh://, git://, http:// and
 file:// transports.  There exist two sets of protocols, one for pushing
@@ -18,7 +30,7 @@ pkt-line Format
 ---------------
 
 The descriptions below build on the pkt-line format described in
-protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless
+linkgit:gitformat-protocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless
 otherwise noted the usual pkt-line LF rules apply: the sender SHOULD
 include a LF, but the receiver MUST NOT complain if it is not present.
 
@@ -707,3 +719,7 @@ An example client/server communication might look like this:
    S: 0018ok refs/heads/debug\n
    S: 002ang refs/heads/master non-fast-forward\n
 ----
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/gitformat-protocol-capabilities.txt
similarity index 96%
rename from Documentation/technical/protocol-capabilities.txt
rename to Documentation/gitformat-protocol-capabilities.txt
index 9dfade930da..2e89f40ddb1 100644
--- a/Documentation/technical/protocol-capabilities.txt
+++ b/Documentation/gitformat-protocol-capabilities.txt
@@ -1,8 +1,20 @@
-Git Protocol Capabilities
-=========================
+gitformat-protocol-capabilities(5)
+==================================
+
+NAME
+----
+gitformat-protocol-capabilities - Protocol v0 and v1 capabilities
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
 
 NOTE: this document describes capabilities for versions 0 and 1 of the pack
-protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]
+protocol. For version 2, please refer to the linkgit:gitformat-protocol-v2[5]
 doc.
 
 Servers SHOULD support all capabilities defined in this document.
@@ -77,7 +89,7 @@ interleaved with S-R-Q.
 multi_ack_detailed
 ------------------
 This is an extension of multi_ack that permits client to better
-understand the server's in-memory state. See pack-protocol.txt,
+understand the server's in-memory state. See linkgit:gitformat-pack-protocol[5],
 section "Packfile Negotiation" for more information.
 
 no-done
@@ -281,7 +293,7 @@ a packfile upload and reference update.  If the pushing client requests
 this capability, after unpacking and updating references the server
 will respond with whether the packfile unpacked successfully and if
 each reference was updated successfully.  If any of those were not
-successful, it will send back an error message.  See pack-protocol.txt
+successful, it will send back an error message.  See linkgit:gitformat-pack-protocol[5]
 for example messages.
 
 report-status-v2
@@ -292,7 +304,7 @@ adding new "option" directives in order to support reference rewritten by
 the "proc-receive" hook.  The "proc-receive" hook may handle a command
 for a pseudo-reference which may create or update a reference with
 different name, new-oid, and old-oid.  While the capability
-'report-status' cannot report for such case.  See pack-protocol.txt
+'report-status' cannot report for such case.  See linkgit:gitformat-pack-protocol[5]
 for details.
 
 delete-refs
@@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The
 current implementation uses trace2 session IDs (see
 link:api-trace2.html[api-trace2] for details), but this may change and users of
 the session ID should not rely on this fact.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/protocol-common.txt b/Documentation/gitformat-protocol-common.txt
similarity index 88%
rename from Documentation/technical/protocol-common.txt
rename to Documentation/gitformat-protocol-common.txt
index ecedb34bba5..6e1e1624e2d 100644
--- a/Documentation/technical/protocol-common.txt
+++ b/Documentation/gitformat-protocol-common.txt
@@ -1,5 +1,20 @@
-Documentation Common to Pack and Http Protocols
-===============================================
+gitformat-protocol-common(5)
+============================
+
+NAME
+----
+gitformat-protocol-common - Things common to various protocols
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
+
+This document sets defines things common to various over-the-wire
+protocols and file formats used in Git.
 
 ABNF Notation
 -------------
@@ -97,3 +112,7 @@ Examples (as C-style strings):
   "000bfoobar\n"    "foobar\n"
   "0004"            ""
 ----
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/gitformat-protocol-v2.txt
similarity index 98%
rename from Documentation/technical/protocol-v2.txt
rename to Documentation/gitformat-protocol-v2.txt
index 8a877d27e23..ae4fcc84e37 100644
--- a/Documentation/technical/protocol-v2.txt
+++ b/Documentation/gitformat-protocol-v2.txt
@@ -1,5 +1,17 @@
-Git Wire Protocol, Version 2
-============================
+gitformat-protocol-v2(5)
+========================
+
+NAME
+----
+gitformat-protocol-v2 - Git Wire Protocol, Version 2
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
 
 This document presents a specification for a version 2 of Git's wire
 protocol.  Protocol v2 will improve upon v1 in the following ways:
@@ -26,7 +38,7 @@ Packet-Line Framing
 -------------------
 
 All communication is done using packet-line framing, just as in v1.  See
-`Documentation/technical/pack-protocol.txt` and
+linkgit:gitformat-pack-protocol[5] and
 `Documentation/technical/protocol-common.txt` for more information.
 
 In protocol v2 these special packets will have the following semantics:
@@ -42,7 +54,7 @@ Initial Client Request
 In general a client can request to speak protocol v2 by sending
 `version=2` through the respective side-channel for the transport being
 used which inevitably sets `GIT_PROTOCOL`.  More information can be
-found in `pack-protocol.txt` and `http-protocol.txt`, as well as the
+found in linkgit:gitformat-pack-protocol[5] and `http-protocol.txt`, as well as the
 `GIT_PROTOCOL` definition in `git.txt`. In all cases the
 response from the server is the capability advertisement.
 
@@ -566,3 +578,7 @@ and associated requested information, each separated by a single space.
 	attr = "size"
 
 	obj-info = obj-id SP obj-size
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt
index d79ad323e67..945c21bbc38 100644
--- a/Documentation/technical/api-simple-ipc.txt
+++ b/Documentation/technical/api-simple-ipc.txt
@@ -78,7 +78,7 @@ client and an optional response message from the server.  Both the
 client and server messages are unlimited in length and are terminated
 with a flush packet.
 
-The pkt-line routines (Documentation/technical/protocol-common.txt)
+The pkt-line routines (linkgit:gitformat-protocol-common[5])
 are used to simplify buffer management during message generation,
 transmission, and reception.  A flush packet is used to mark the end
 of the message.  This allows the sender to incrementally generate and
diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
index cc5126cfeda..9d9c7acd512 100644
--- a/Documentation/technical/http-protocol.txt
+++ b/Documentation/technical/http-protocol.txt
@@ -222,7 +222,7 @@ smart server reply:
    S: 0000
 
 The client may send Extra Parameters (see
-Documentation/technical/pack-protocol.txt) as a colon-separated string
+linkgit:gitformat-pack-protocol[5]) as a colon-separated string
 in the Git-Protocol HTTP header.
 
 Uses the `--http-backend-info-refs` option to
@@ -518,5 +518,5 @@ References
 
 http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
 http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
-link:technical/pack-protocol.html
-link:technical/protocol-capabilities.html
+linkgit:gitformat-pack-protocol[5]
+linkgit:gitformat-protocol-capabilities[5]
diff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt
index aa0aa9af1c2..c6922ce6ccc 100644
--- a/Documentation/technical/long-running-process-protocol.txt
+++ b/Documentation/technical/long-running-process-protocol.txt
@@ -3,7 +3,7 @@ Long-running process protocol
 
 This protocol is used when Git needs to communicate with an external
 process throughout the entire life of a single Git command. All
-communication is in pkt-line format (see technical/protocol-common.txt)
+communication is in pkt-line format (see linkgit:gitformat-protocol-common[5])
 over standard input and standard output.
 
 Handshake
diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt
index a0dd7c66f24..957d6dfe375 100644
--- a/Documentation/technical/partial-clone.txt
+++ b/Documentation/technical/partial-clone.txt
@@ -79,7 +79,7 @@ Design Details
   upload-pack negotiation.
 +
 This uses the existing capability discovery mechanism.
-See "filter" in Documentation/technical/pack-protocol.txt.
+See "filter" in linkgit:gitformat-pack-protocol[5].
 
 - Clients pass a "filter-spec" to clone and fetch which is passed to the
   server to request filtering during packfile construction.
diff --git a/command-list.txt b/command-list.txt
index f7dcc795e1e..f4d1f9c31b1 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -209,6 +209,10 @@ giteveryday                             guide
 gitfaq                                  guide
 gitformat-bundle                        gitformats
 gitformat-commit-graph                  gitformats
+gitformat-pack-protocol                 gitformats
+gitformat-protocol-capabilities         gitformats
+gitformat-protocol-common               gitformats
+gitformat-protocol-v2                   gitformats
 gitglossary                             guide
 githooks                                userformats
 gitignore                               userformats
diff --git a/t/t5551-http-fetch-smart.sh b/t/t5551-http-fetch-smart.sh
index f92c79c1326..a5ece8a33cc 100755
--- a/t/t5551-http-fetch-smart.sh
+++ b/t/t5551-http-fetch-smart.sh
@@ -175,8 +175,8 @@ test_expect_success 'no-op half-auth fetch does not require a password' '
 	# This is not possible with protocol v2, since both objects and refs
 	# are obtained from the "git-upload-pack" path. A solution to this is
 	# to teach the server and client to be able to inline ls-refs requests
-	# as an Extra Parameter (see pack-protocol.txt), so that "info/refs"
-	# can serve refs, just like it does in protocol v0.
+	# as an Extra Parameter (see "git help gitformat-pack-protocol"), so that
+	# "info/refs" can serve refs, just like it does in protocol v0.
 	GIT_TEST_PROTOCOL_VERSION=0 git --git-dir=half-auth fetch &&
 	expect_askpass none
 '
-- 
2.34.1.929.ge922d848c7a


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v2 5/5] docs: move {index,signature,bitmap,chunk}-format docs to man section 5
  2021-12-12 19:49 ` [PATCH v2 0/5] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
                     ` (3 preceding siblings ...)
  2021-12-12 19:49   ` [PATCH v2 4/5] docs: move protocol-related " Ævar Arnfjörð Bjarmason
@ 2021-12-12 19:49   ` Ævar Arnfjörð Bjarmason
  2022-07-12 20:06   ` [PATCH v3 0/7] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
  5 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-12-12 19:49 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Philippe Blain, Todd Zullinger, Eric Wong,
	Jeff King, Teng Long, Derrick Stolee, Taylor Blau,
	Ævar Arnfjörð Bjarmason

Continue the move of existing Documentation/technical/* protocol and
file-format documentation into our main documentation space.

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. Let's also move the rest over for consistency.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile                        |  6 ++-
 ...bitmap-format.txt => gitformat-bitmap.txt} | 38 +++++++++++++++----
 .../chunk-format.txt => gitformat-chunk.txt}  | 21 +++++++++-
 Documentation/gitformat-commit-graph.txt      |  2 +-
 .../index-format.txt => gitformat-index.txt}  | 20 +++++++++-
 ...ure-format.txt => gitformat-signature.txt} | 21 ++++++++--
 Documentation/technical/pack-format.txt       |  2 +-
 command-list.txt                              |  4 ++
 8 files changed, 97 insertions(+), 17 deletions(-)
 rename Documentation/{technical/bitmap-format.txt => gitformat-bitmap.txt} (91%)
 rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (94%)
 rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)
 rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index ba587b75a51..f8a84173667 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -21,12 +21,16 @@ MAN1_TXT += gitweb.txt
 
 # man5 / man7 guides (note: new guides should also be added to command-list.txt)
 MAN5_TXT += gitattributes.txt
+MAN5_TXT += gitformat-bitmap.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-protocol.txt
 MAN5_TXT += gitformat-protocol-capabilities.txt
 MAN5_TXT += gitformat-protocol-common.txt
 MAN5_TXT += gitformat-protocol-v2.txt
+MAN5_TXT += gitformat-signature.txt
 MAN5_TXT += githooks.txt
 MAN5_TXT += gitignore.txt
 MAN5_TXT += gitmailmap.txt
@@ -98,7 +102,6 @@ TECH_DOCS += MyFirstObjectWalk
 TECH_DOCS += SubmittingPatches
 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
@@ -109,7 +112,6 @@ TECH_DOCS += technical/racy-git
 TECH_DOCS += technical/reftable
 TECH_DOCS += technical/send-pack-pipeline
 TECH_DOCS += technical/shallow
-TECH_DOCS += technical/signature-format
 TECH_DOCS += technical/trivial-merge
 SP_ARTICLES += $(TECH_DOCS)
 SP_ARTICLES += technical/api-index
diff --git a/Documentation/technical/bitmap-format.txt b/Documentation/gitformat-bitmap.txt
similarity index 91%
rename from Documentation/technical/bitmap-format.txt
rename to Documentation/gitformat-bitmap.txt
index 04b3ec21785..b239dc5cbe1 100644
--- a/Documentation/technical/bitmap-format.txt
+++ b/Documentation/gitformat-bitmap.txt
@@ -1,7 +1,25 @@
-GIT bitmap v1 format
-====================
+gitformat-bitmap(5)
+===================
 
-== Pack and multi-pack bitmaps
+NAME
+----
+gitformat-bitmap - The bitmap file format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/pack/*.bitmap
+
+DESCRIPTION
+-----------
+
+Bitmaps are a file format associated with .pack files. See
+link:technical/pack-format.html[the pack format documentation] and
+linkgit:git-pack-objects[1].
+
+== GIT bitmap v1 format
+
+=== Pack and multi-pack bitmaps
 
 Bitmaps store reachability information about the set of objects in a packfile,
 or a multi-pack index (MIDX). The former is defined obviously, and the latter is
@@ -37,7 +55,7 @@ Certain bitmap extensions are supported (see: Appendix B). No extensions are
 required for bitmaps corresponding to packfiles. For bitmaps that correspond to
 MIDXs, both the bit-cache and rev-cache extensions are required.
 
-== On-disk format
+=== On-disk format
 
 	- A header appears at the beginning:
 
@@ -131,7 +149,8 @@ MIDXs, both the bit-cache and rev-cache extensions are required.
 
 		- The compressed bitmap itself, see Appendix A.
 
-== Appendix A: Serialization format for an EWAH bitmap
+Appendix A - Serialization format for an EWAH bitmap
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Ewah bitmaps are serialized in the same protocol as the JAVAEWAH
 library, making them backwards compatible with the JGit
@@ -179,13 +198,14 @@ chunk.  For efficient appending to the bitstream, the EWAH stores a
 pointer to the last RLW in the stream.
 
 
-== Appendix B: Optional Bitmap Sections
+Appendix B - Optional Bitmap Sections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These sections may or may not be present in the `.bitmap` file; their
 presence is indicated by the header flags section described above.
 
 Name-hash cache
----------------
+~~~~~~~~~~~~~~~
 
 If the BITMAP_OPT_HASH_CACHE flag is set, the end of the bitmap contains
 a cache of 32-bit values, one per object in the pack/MIDX. The value at
@@ -205,3 +225,7 @@ Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag.
 If implementations want to choose a different hashing scheme, they are
 free to do so, but MUST allocate a new header flag (because comparing
 hashes made under two different schemes would be pointless).
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt
similarity index 94%
rename from Documentation/technical/chunk-format.txt
rename to Documentation/gitformat-chunk.txt
index f36ce42f37c..8ddf21e3277 100644
--- a/Documentation/technical/chunk-format.txt
+++ b/Documentation/gitformat-chunk.txt
@@ -1,5 +1,18 @@
-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
+link:technical/pack-format.html[the pack format documentation]).
+
+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
@@ -114,3 +127,7 @@ for future formats:
   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].
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt
index 25eb131dcd2..5f839eda058 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..41491d2a075 100644
--- a/Documentation/technical/index-format.txt
+++ b/Documentation/gitformat-index.txt
@@ -1,5 +1,19 @@
+gitformat-index(5)
+==================
+
+NAME
+----
+gitformat-index - Git index format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/index
+
+DESCRIPTION
+-----------
+
 Git index format
-================
 
 == The Git index file has the following format
 
@@ -404,3 +418,7 @@ The remaining data of each directory block is grouped by type:
   with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,
   tools should avoid interacting with a sparse index unless they understand
   this extension.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/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)>
+<over-the-wire protocol>
+
+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/technical/pack-format.txt b/Documentation/technical/pack-format.txt
index 8d2f42f29e5..79cc83aead0 100644
--- a/Documentation/technical/pack-format.txt
+++ b/Documentation/technical/pack-format.txt
@@ -337,7 +337,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
diff --git a/command-list.txt b/command-list.txt
index f4d1f9c31b1..42093fd5a07 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -207,12 +207,16 @@ gitcvs-migration                        guide
 gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
+gitformat-bitmap                        gitformats
 gitformat-bundle                        gitformats
+gitformat-chunk                         gitformats
 gitformat-commit-graph                  gitformats
+gitformat-index                         gitformats
 gitformat-pack-protocol                 gitformats
 gitformat-protocol-capabilities         gitformats
 gitformat-protocol-common               gitformats
 gitformat-protocol-v2                   gitformats
+gitformat-signature                     gitformats
 gitglossary                             guide
 githooks                                userformats
 gitignore                               userformats
-- 
2.34.1.929.ge922d848c7a


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* Re: [PATCH v2 2/5] git docs: create a "Git file and wire formats" section
  2021-12-12 19:49   ` [PATCH v2 2/5] git docs: create a "Git file and wire formats" section Ævar Arnfjörð Bjarmason
@ 2021-12-12 22:30     ` Eric Sunshine
  2021-12-13  9:33       ` Ævar Arnfjörð Bjarmason
  0 siblings, 1 reply; 112+ messages in thread
From: Eric Sunshine @ 2021-12-12 22:30 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: Git List, Junio C Hamano, Philippe Blain, Todd Zullinger,
	Eric Wong, Jeff King, Teng Long, Derrick Stolee, Taylor Blau

On Sun, Dec 12, 2021 at 4:23 PM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
> diff --git a/help.c b/help.c
> @@ -38,6 +38,7 @@ static struct category_description main_categories[] = {
> +       { CAT_gitformats, N_("Internal file- and wire formats formats") },

Should this be: s/file-/file/ ?

^ permalink raw reply	[flat|nested] 112+ messages in thread

* Re: [PATCH v2 2/5] git docs: create a "Git file and wire formats" section
  2021-12-12 22:30     ` Eric Sunshine
@ 2021-12-13  9:33       ` Ævar Arnfjörð Bjarmason
  0 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-12-13  9:33 UTC (permalink / raw)
  To: Eric Sunshine
  Cc: Git List, Junio C Hamano, Philippe Blain, Todd Zullinger,
	Eric Wong, Jeff King, Teng Long, Derrick Stolee, Taylor Blau


On Sun, Dec 12 2021, Eric Sunshine wrote:

> On Sun, Dec 12, 2021 at 4:23 PM Ævar Arnfjörð Bjarmason
> <avarab@gmail.com> wrote:
>> diff --git a/help.c b/help.c
>> @@ -38,6 +38,7 @@ static struct category_description main_categories[] = {
>> +       { CAT_gitformats, N_("Internal file- and wire formats formats") },
>
> Should this be: s/file-/file/ ?

I meant to write it like that, i.e. as a shorthand for "Internal file
formats and wire formats", but I see I included "formats" twice, which I
didn't intend to :)

Anyway, it's probably best to just drop the "-" there, and of course get
rid of the "formats formats" for just "formats".

^ permalink raw reply	[flat|nested] 112+ messages in thread

* [PATCH v3 0/7] git doc + "git help": move "format" docs from technical/*
  2021-12-12 19:49 ` [PATCH v2 0/5] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
                     ` (4 preceding siblings ...)
  2021-12-12 19:49   ` [PATCH v2 5/5] docs: move {index,signature,bitmap,chunk}-format " Ævar Arnfjörð Bjarmason
@ 2022-07-12 20:06   ` Ævar Arnfjörð Bjarmason
  2022-07-12 20:06     ` [PATCH v3 1/7] git docs: split "User-facing file formats" off from "Guides" Ævar Arnfjörð Bjarmason
                       ` (7 more replies)
  5 siblings, 8 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-12 20:06 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

This series improves the accessability of our documentation by moving
much of the documentation about user and developer-facing "formats" to
our main documentation namespace.

I.e. they'll be installed as part of "make install-doc" etc, most of
our docs avoid referring to these, and when they do they refer to the
html versions. Now the manual pages will be self-contained, without
any need to visit these in a browser.

A "user format" is defined broadly as a file format (or similar) that
a user might need to interact with or edit. This contains some manual
pages that are now in --guides:

	$ git help --user-formats
	Git user-facing file formats:
	   attributes          Defining attributes per path
	   hooks               Hooks used by Git
	   ignore              Specifies intentionally untracked files to ignore
	   mailmap             Map author/committer names and/or E-Mail addresses
	   modules             Defining submodule properties
	   repository-layout   Git Repository Layout

All of that exists already, it's just in its own category now,
i.e. not with the likes of "tutorial" etc.

But this is new, all of these docs were previously languishing in
Documentation/techical/, but are now built as manual pages:

	$ git help --git-formats
	Internal file formats and protocols:
	   format-bundle                  The bundle file format
	   format-chunk                   Chunk-based file formats
	   format-commit-graph            Git commit graph format
	   format-index                   Git index format
	   format-multi-pack-index        The multi-pack-index file format
	   format-pack                    Git pack format
	   format-pack-bitmap             The bitmap file format
	   format-pack-cruft              The cruft pack file format
	   format-pack-protocol           How packs are transferred over-the-wire
	   format-protocol-capabilities   Protocol v0 and v1 capabilities
	   format-protocol-common         Things common to various protocols
	   format-protocol-http           Git HTTP-based protocols
	   format-protocol-v2             Git Wire Protocol, Version 2
	   format-signature               Git cryptographic signature formats

See [1] for the v2. This series took a while to re-roll because there
have been various painful conflicts in-flight work in
Documentation/techical/ in the interim. There's a minor conflict here
with ac/bitmap-lookup-table, see below:

Changes since v2:

 * Fix SYNOPSIS, usage etc.
 * The --user-formats and --git-formats now skip the "git" prefix,
   like --guides did.
 * Updated the help descriptions / title sections (see range-diff)
 * The cruft pack format is now included, as well as this being
   re-rolled for other changes in Documentation/techical/
 * Moved all the pack formats under gitformat-pack-*
 * Fixed some more cross-links to the now-moved
   Documentation/techical/ docs.
 * Move more docs to --git-formats (which previously conflicted)

1. https://lore.kernel.org/git/cover-v2-0.5-00000000000-20211212T194047Z-avarab@gmail.com/

For Junio: There's a conflict here with ac/bitmap-lookup-table in
"seen", which can be solved thusly (remerge-diff output):
	
	diff --git a/Documentation/gitformat-pack-bitmap.txt b/Documentation/gitformat-pack-bitmap.txt
	remerge CONFLICT (content): Merge conflict in Documentation/gitformat-pack-bitmap.txt
	index b01a3a202e8..136fd0c1b71 100644
	--- a/Documentation/gitformat-pack-bitmap.txt
	+++ b/Documentation/gitformat-pack-bitmap.txt
	@@ -248,13 +248,8 @@ If implementations want to choose a different hashing scheme, they are
	 free to do so, but MUST allocate a new header flag (because comparing
	 hashes made under two different schemes would be pointless).
	 
	-<<<<<<< aabdc4a4151 (docs: move multi-pack-index docs to man section 5):Documentation/gitformat-pack-bitmap.txt
	-GIT
	----
	-Part of the linkgit:git[1] suite
	-=======
	 Commit lookup table
	--------------------
	+~~~~~~~~~~~~~~~~~~~
	 
	 If the BITMAP_OPT_LOOKUP_TABLE flag is set, the last `N * (4 + 8 + 4)`
	 bytes (preceding the name-hash cache and trailing hash) of the `.bitmap`
	@@ -280,4 +275,7 @@ triplet is -
	 	xor_row (4 byte integer, network byte order): ::
	 	The position of the triplet whose bitmap is used to compress
	 	this one, or `0xffffffff` if no such bitmap exists.
	->>>>>>> 135e1ec09aa (Merge branch 'sa/cat-file-mailmap' into seen):Documentation/technical/bitmap-format.txt
	+
	+GIT
	+---
	+Part of the linkgit:git[1] suite

I.e. the new "GIT" section needs to come last (as check-docs will
report), but otherwise it's a union of the two, *except* that the
"Commit lookup table" needs to use "~" for the section, not "-".
	

Ævar Arnfjörð Bjarmason (7):
  git docs: split "User-facing file formats" off from "Guides"
  git docs: create a "Git file formats and protocols" section
  docs: move commit-graph format docs to man section 5
  docs: move protocol-related docs to man section 5
  docs: move pack format docs to man section 5
  docs: move http-protocol docs to man section 5
  docs: move multi-pack-index docs to man section 5

 Documentation/Makefile                        | 28 ++++++-----
 Documentation/config/lsrefs.txt               |  2 +-
 Documentation/config/pack.txt                 |  2 +-
 Documentation/config/protocol.txt             |  2 +-
 Documentation/git-bundle.txt                  | 11 +++--
 Documentation/git-commit-graph.txt            |  5 ++
 Documentation/git-help.txt                    | 14 ++++--
 Documentation/git-multi-pack-index.txt        |  7 +--
 Documentation/git-upload-pack.txt             |  7 ++-
 Documentation/git.txt                         | 15 ++++++
 ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++---
 .../chunk-format.txt => gitformat-chunk.txt}  | 27 ++++++++--
 ...-format.txt => gitformat-commit-graph.txt} | 49 +++++++++++++------
 .../index-format.txt => gitformat-index.txt}  | 22 ++++++++-
 ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++-
 ...p-format.txt => gitformat-pack-bitmap.txt} | 38 +++++++++++---
 ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++-
 ...otocol.txt => gitformat-pack-protocol.txt} | 26 ++++++++--
 .../pack-format.txt => gitformat-pack.txt}    | 39 +++++++++++++--
 ...xt => gitformat-protocol-capabilities.txt} | 28 ++++++++---
 ...mmon.txt => gitformat-protocol-common.txt} | 23 ++++++++-
 ...otocol.txt => gitformat-protocol-http.txt} | 35 ++++++++++---
 ...tocol-v2.txt => gitformat-protocol-v2.txt} | 26 ++++++++--
 ...ure-format.txt => gitformat-signature.txt} | 21 ++++++--
 .../howto/recover-corrupted-object-harder.txt |  2 +-
 Documentation/lint-man-section-order.perl     |  3 ++
 Documentation/technical/api-simple-ipc.txt    |  2 +-
 .../technical/hash-function-transition.txt    |  2 +-
 .../long-running-process-protocol.txt         |  2 +-
 Documentation/technical/partial-clone.txt     |  2 +-
 Documentation/user-manual.txt                 |  2 +-
 Makefile                                      |  1 +
 builtin/help.c                                | 18 ++++++-
 cache.h                                       |  3 +-
 command-list.txt                              | 34 ++++++++++---
 help.c                                        | 29 ++++++++++-
 help.h                                        |  2 +
 pack-revindex.h                               |  2 +-
 t/t0012-help.sh                               | 14 +++++-
 t/t5551-http-fetch-smart.sh                   |  4 +-
 40 files changed, 513 insertions(+), 122 deletions(-)
 rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)
 rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (90%)
 rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (87%)
 rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)
 rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)
 rename Documentation/{technical/bitmap-format.txt => gitformat-pack-bitmap.txt} (91%)
 rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%)
 rename Documentation/{technical/pack-protocol.txt => gitformat-pack-protocol.txt} (98%)
 rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)
 rename Documentation/{technical/protocol-capabilities.txt => gitformat-protocol-capabilities.txt} (96%)
 rename Documentation/{technical/protocol-common.txt => gitformat-protocol-common.txt} (88%)
 rename Documentation/{technical/http-protocol.txt => gitformat-protocol-http.txt} (97%)
 rename Documentation/{technical/protocol-v2.txt => gitformat-protocol-v2.txt} (97%)
 rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)

Range-diff against v2:
1:  960574b7f05 ! 1:  929d9192828 git docs: split "User-facing file formats" off from "Guides"
    @@ Documentation/git-help.txt
     @@ Documentation/git-help.txt: SYNOPSIS
      --------
      [verse]
    - 'git help' [-a|--all [--[no-]verbose]]
    --	   [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]
    -+	   [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>|<doc>]
    + 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]
    +-'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]
    ++'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>|<doc>]
      'git help' [-g|--guides]
      'git help' [-c|--config]
     +'git help' [--user-formats]
    @@ builtin/help.c: static struct option builtin_help_options[] = {
      	OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
      		    HELP_ACTION_CONFIG),
      	OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
    -@@ builtin/help.c: static const char * const builtin_help_usage[] = {
    - 	   "         [[-i|--info] [-m|--man] [-w|--web]] [<command>]"),
    - 	N_("git help [-g|--guides]"),
    - 	N_("git help [-c|--config]"),
    -+	N_("git help [--user-formats]"),
    +@@ builtin/help.c: 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]] [<command>]"),
    ++	N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
    + 	"git help [-g|--guides]",
    + 	"git help [-c|--config]",
    ++	"git help [--user-formats]",
      	NULL
      };
      
     @@ builtin/help.c: int cmd_help(int argc, const char **argv, const char *prefix)
    - 		no_extra_argc(argc);
    + 		opt_mode_usage(argc, "--config-for-completion", help_format);
      		list_config_help(SHOW_CONFIG_VARS);
      		return 0;
     +	case HELP_ACTION_USER_FORMATS:
    -+		no_extra_argc(argc);
    ++		opt_mode_usage(argc, "--user-formats", help_format);
     +		list_user_formats_help();
     +		return 0;
      	case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
    - 		no_extra_argc(argc);
    - 		list_config_help(SHOW_CONFIG_SECTIONS);
    + 		opt_mode_usage(argc, "--config-sections-for-completion",
    + 			       help_format);
     
      ## command-list.txt ##
     @@
    @@ help.c: static struct category_description main_categories[] = {
      	{ CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") },
      	{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
      	{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
    -+	{ CAT_userformats, N_("User-facing file formats") },
    ++	{ CAT_userformats, N_("Git user-facing file formats") },
      	{ 0, NULL }
      };
      
    +@@ help.c: static const char *drop_prefix(const char *name, uint32_t category)
    + 
    + 	if (skip_prefix(name, "git-", &new_name))
    + 		return new_name;
    +-	if (category == CAT_guide && skip_prefix(name, "git", &new_name))
    ++	switch (category) {
    ++	case CAT_guide:
    ++	case CAT_userformats:
    ++		skip_prefix(name, "git", &new_name);
    + 		return new_name;
    ++	}
    + 	return name;
    + 
    + }
     @@ help.c: void list_guides_help(void)
      	putchar('\n');
      }
    @@ help.c: void list_guides_help(void)
     +void list_user_formats_help(void)
     +{
     +	struct category_description catdesc[] = {
    -+		{ CAT_userformats, N_("The user-facing file formats are:") },
    ++		{ CAT_userformats, N_("Git user-facing file formats:") },
     +		{ 0, NULL }
     +	};
     +	print_cmd_by_category(catdesc, NULL);
    @@ help.c: void list_guides_help(void)
      ## help.h ##
     @@ help.h: static inline void mput_char(char c, unsigned int num)
      void list_common_cmds_help(void);
    - void list_all_cmds_help(void);
    + void list_all_cmds_help(int show_external_commands, int show_aliases);
      void list_guides_help(void);
     +void list_user_formats_help(void);
      
    @@ t/t0012-help.sh: test_expect_success 'git help' '
      	test_i18ngrep "^   commit " help.output &&
      	test_i18ngrep "^   fetch  " help.output
      '
    -+
    -+test_expect_success 'git help -a' '
    -+	git help -a >help.output &&
    -+	grep "^Main Porcelain Commands" help.output &&
    -+	grep "^User-facing file formats" help.output
    -+'
     +
      test_expect_success 'git help -g' '
      	git help -g >help.output &&
    @@ t/t0012-help.sh: test_expect_success 'git help succeeds without git.html' '
      	test_cmp expect test-browser.log
      '
      
    -+test_expect_success 'git help --formats' '
    ++test_expect_success 'git help --user-formats' '
     +	git help --user-formats >help.output &&
    -+	grep "^   gitattributes   " help.output &&
    -+	grep "^   gitmailmap   " help.output
    ++	grep "^   attributes   " help.output &&
    ++	grep "^   mailmap   " help.output
     +'
     +
      test_expect_success 'git help -c' '
      	git help -c >help.output &&
      	cat >expect <<-\EOF &&
    +@@ t/t0012-help.sh: test_expect_success "'git help -a' section spacing" '
    + 	Low-level Commands / Syncing Repositories
    + 
    + 	Low-level Commands / Internal Helpers
    ++
    ++	Git user-facing file formats
    + 	EOF
    + 	test_cmp expect actual
    + '
2:  b2d73f8c9da ! 2:  1fd57d5caf4 git docs: create a "Git file and wire formats" section
    @@ Metadata
     Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
      ## Commit message ##
    -    git docs: create a "Git file and wire formats" section
    +    git docs: create a "Git file formats and protocols" section
     
    -    Create a new "Git file and wire formats" section in the main "git help
    +    Create a new "Git file formats and protocols" section in the main "git help
         git" manual page and start moving the documentation that now lives in
         "Documentation/technical/*.git" over to it. This compliments the newly
         added and adjacent "User-facing file formats" section.
    @@ Documentation/Makefile: MAN1_TXT += gitweb.txt
      MAN5_TXT += githooks.txt
      MAN5_TXT += gitignore.txt
      MAN5_TXT += gitmailmap.txt
    -@@ Documentation/Makefile: SP_ARTICLES += $(API_DOCS)
    - TECH_DOCS += MyFirstContribution
    - TECH_DOCS += MyFirstObjectWalk
    +@@ Documentation/Makefile: 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
    - TECH_DOCS += technical/index-format
     @@ Documentation/Makefile: cmds_txt = cmds-ancillaryinterrogators.txt \
      	cmds-synchelpers.txt \
      	cmds-guide.txt \
    @@ Documentation/git-bundle.txt: You can also see what references it offers:
      ---
      Part of the linkgit:git[1] suite
     
    + ## Documentation/git-help.txt ##
    +@@ Documentation/git-help.txt: SYNOPSIS
    + 'git help' [-g|--guides]
    + 'git help' [-c|--config]
    + 'git help' [--user-formats]
    ++'git help' [--git-formats]
    + 
    + DESCRIPTION
    + -----------
    +
      ## Documentation/git.txt ##
     @@ Documentation/git.txt: edit. These can also be listed with 'git help --user-formats'.
      
      include::cmds-userformats.txt[]
      
    -+Git file and wire formats
    -+-------------------------
    ++Git file formats and protocols
    ++------------------------------
     +
    -+This documentation discusses the file and wire formats that git itself
    -+uses. These can also be listed with 'git help --git-formats'.
    ++This documentation discusses the file formats and protocols that git
    ++itself uses. These can also be listed with 'git help --git-formats'.
     +
     +include::cmds-gitformats.txt[]
     +
    @@ Documentation/gitformat-bundle.txt: In the bundle format, there can be a comment
     +------------
      
      Because there is no opportunity for negotiation, unknown capabilities cause 'git
    - bundle' to abort.  The only known capability is `object-format`, which specifies
    - the hash algorithm in use, and can take the same values as the
    - `extensions.objectFormat` configuration value.
    + bundle' to abort.
    +@@ Documentation/gitformat-bundle.txt: 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
     +---
    @@ builtin/help.c: static struct option builtin_help_options[] = {
      		    HELP_ACTION_GUIDES),
      	OPT_CMDMODE(0, "user-formats", &cmd_mode, N_("print list of user-facing file formats"),
      		    HELP_ACTION_USER_FORMATS),
    -+	OPT_CMDMODE(0, "git-formats", &cmd_mode, N_("print list of Git's own file and network formats"),
    ++	OPT_CMDMODE(0, "git-formats", &cmd_mode, N_("print list of internal file formats and network protocols"),
     +		    HELP_ACTION_GIT_FORMATS),
      	OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
      		    HELP_ACTION_CONFIG),
      	OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
     @@ builtin/help.c: static const char * const builtin_help_usage[] = {
    - 	N_("git help [-g|--guides]"),
    - 	N_("git help [-c|--config]"),
    - 	N_("git help [--user-formats]"),
    -+	N_("git help [--git-formats]"),
    + 	"git help [-g|--guides]",
    + 	"git help [-c|--config]",
    + 	"git help [--user-formats]",
    ++	"git help [--git-formats]",
      	NULL
      };
      
     @@ builtin/help.c: int cmd_help(int argc, const char **argv, const char *prefix)
    - 		no_extra_argc(argc);
    + 		opt_mode_usage(argc, "--user-formats", help_format);
      		list_user_formats_help();
      		return 0;
     +	case HELP_ACTION_GIT_FORMATS:
    -+		no_extra_argc(argc);
    ++		opt_mode_usage(argc, "--git-formats", help_format);
     +		list_git_formats_help();
     +		return 0;
      	case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
    - 		no_extra_argc(argc);
    - 		list_config_help(SHOW_CONFIG_SECTIONS);
    + 		opt_mode_usage(argc, "--config-sections-for-completion",
    + 			       help_format);
     
      ## command-list.txt ##
     @@
      # .mailmap etc. files lives in man section 5. These entries can only
      # have the "userformats" attribute and nothing else.
      #
    -+# Git's own file and network formats such as documentation for the
    -+# *.bundle format lives in mn section 5. These entries can only have
    ++# Git internal file formats and protocols, such as documentation for the
    ++# *.bundle format lives in man section 5. These entries can only have
     +# the "gitformats" attribute and nothing else.
     +#
      ### command list (do not change this line)
    @@ help.c
     @@ help.c: static struct category_description main_categories[] = {
      	{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
      	{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
    - 	{ CAT_userformats, N_("User-facing file formats") },
    -+	{ CAT_gitformats, N_("Internal file- and wire formats formats") },
    + 	{ CAT_userformats, N_("Git user-facing file formats") },
    ++	{ CAT_gitformats, N_("Git internal file formats and protocols") },
      	{ 0, NULL }
      };
      
    +@@ help.c: static const char *drop_prefix(const char *name, uint32_t category)
    + 	switch (category) {
    + 	case CAT_guide:
    + 	case CAT_userformats:
    ++	case CAT_gitformats:
    + 		skip_prefix(name, "git", &new_name);
    + 		return new_name;
    + 	}
     @@ help.c: void list_user_formats_help(void)
      	putchar('\n');
      }
    @@ help.c: void list_user_formats_help(void)
     +void list_git_formats_help(void)
     +{
     +	struct category_description catdesc[] = {
    -+		{ CAT_gitformats, N_("Git's internal file and network formats are:") },
    ++		{ CAT_gitformats, N_("Internal file formats and protocols:") },
     +		{ 0, NULL }
     +	};
     +	print_cmd_by_category(catdesc, NULL);
    @@ help.c: void list_user_formats_help(void)
     
      ## help.h ##
     @@ help.h: void list_common_cmds_help(void);
    - void list_all_cmds_help(void);
    + void list_all_cmds_help(int show_external_commands, int show_aliases);
      void list_guides_help(void);
      void list_user_formats_help(void);
     +void list_git_formats_help(void);
      
      void list_all_main_cmds(struct string_list *list);
      void list_all_other_cmds(struct string_list *list);
    +
    + ## t/t0012-help.sh ##
    +@@ t/t0012-help.sh: test_expect_success "'git help -a' section spacing" '
    + 	Low-level Commands / Internal Helpers
    + 
    + 	Git user-facing file formats
    ++
    ++	Git internal file formats and protocols
    + 	EOF
    + 	test_cmp expect actual
    + '
3:  5abd59b807f ! 3:  d548c6aaba7 docs: move commit-graph format docs to man section 5
    @@ Documentation/gitformat-commit-graph.txt: CHUNK DATA:
            2 bits of the lowest byte, storing the 33rd and 34th bit of the
            commit time.
      
    --  Generation Data (ID: {'G', 'D', 'A', 'T' }) (N * 4 bytes) [Optional]
    -+==== Generation Data (ID: {'G', 'D', 'A', 'T' }) (N * 4 bytes) [Optional]
    +-  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,
    @@ Documentation/gitformat-commit-graph.txt: 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', 'V' }) [Optional]
    -+==== Generation Data Overflow (ID: {'G', 'D', 'O', 'V' }) [Optional]
    +-  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.
    @@ Documentation/gitformat-commit-graph.txt: CHUNK DATA:
     +=== TRAILER:
      
      	H-byte HASH-checksum of all of the above.
    + 
    +@@ Documentation/gitformat-commit-graph.txt: 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
     +---
4:  fb91009c18f = 4:  f404987f94d docs: move protocol-related docs to man section 5
5:  5cb41bb0dcb ! 5:  6c46b4dccea docs: move {index,signature,bitmap,chunk}-format docs to man section 5
    @@ Metadata
     Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
      ## Commit message ##
    -    docs: move {index,signature,bitmap,chunk}-format docs to man section 5
    +    docs: move pack format docs to man section 5
     
         Continue the move of existing Documentation/technical/* protocol and
    -    file-format documentation into our main documentation space.
    +    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. Let's also move the rest over for consistency.
    +    by default.
     
         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
      ## Documentation/Makefile ##
     @@ Documentation/Makefile: 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-bitmap.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-bitmap.txt
    ++MAN5_TXT += gitformat-pack-cruft.txt
      MAN5_TXT += gitformat-pack-protocol.txt
    ++MAN5_TXT += gitformat-pack.txt
      MAN5_TXT += gitformat-protocol-capabilities.txt
      MAN5_TXT += gitformat-protocol-common.txt
      MAN5_TXT += gitformat-protocol-v2.txt
    @@ Documentation/Makefile: MAN1_TXT += gitweb.txt
      MAN5_TXT += githooks.txt
      MAN5_TXT += gitignore.txt
      MAN5_TXT += gitmailmap.txt
    -@@ Documentation/Makefile: TECH_DOCS += MyFirstObjectWalk
    +@@ Documentation/Makefile: TECH_DOCS += MyFirstContribution
    + 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-format
    + TECH_DOCS += technical/pack-heuristics
    + TECH_DOCS += technical/parallel-checkout
    + TECH_DOCS += technical/partial-clone
     @@ Documentation/Makefile: TECH_DOCS += technical/racy-git
      TECH_DOCS += technical/reftable
      TECH_DOCS += technical/send-pack-pipeline
    @@ Documentation/Makefile: TECH_DOCS += technical/racy-git
      SP_ARTICLES += $(TECH_DOCS)
      SP_ARTICLES += technical/api-index
     
    - ## Documentation/technical/bitmap-format.txt => Documentation/gitformat-bitmap.txt ##
    + ## Documentation/config/pack.txt ##
    +@@ Documentation/config/pack.txt: 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.
    +
    + ## Documentation/git-bundle.txt ##
    +@@ Documentation/git-bundle.txt: 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
    + -------
    +
    + ## Documentation/git-multi-pack-index.txt ##
    +@@ Documentation/git-multi-pack-index.txt: $ 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
    +
    + ## Documentation/technical/chunk-format.txt => Documentation/gitformat-chunk.txt ##
    +@@
    +-Chunk-based file formats
    +-========================
    ++gitformat-chunk(5)
    ++==================
    ++
    ++NAME
    ++----
    ++gitformat-chunk - Chunk-based file formats
    ++
    ++SYNOPSIS
    ++--------
    ++
    ++Used by linkgit:gitformat-commit-graph[5] and the "MIDX" format (see
    ++the pack format documentation in linkgit:gitformat-pack[5]).
    ++
    ++DESCRIPTION
    ++-----------
    + 
    + Some file formats in Git use a common concept of "chunks" to describe
    + sections of the file. This allows structured access to a large file by
    + scanning a small "table of contents" for the remaining data. This common
    + format is used by the `commit-graph` and `multi-pack-index` files. See
    +-link:technical/pack-format.html[the `multi-pack-index` format] and
    +-the `commit-graph` format in linkgit:gitformat-commit-graph[5] for
    ++the `multi-pack-index` format in linkgit:gitformat-pack[5] and
    ++link:technical/commit-graph-format.html[the `commit-graph` format] for
    + how they use the chunks to describe structured data.
    + 
    + A chunk-based file format begins with some header information custom to
    +@@ Documentation/gitformat-chunk.txt: 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
    +
    + ## Documentation/gitformat-commit-graph.txt ##
    +@@ Documentation/gitformat-commit-graph.txt: 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
    +
    + ## Documentation/technical/index-format.txt => Documentation/gitformat-index.txt ##
    +@@
    ++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
    + 
    +@@ Documentation/gitformat-index.txt: 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.
    +@@ Documentation/gitformat-index.txt: 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
    +
    + ## Documentation/technical/bitmap-format.txt => Documentation/gitformat-pack-bitmap.txt ##
     @@
     -GIT bitmap v1 format
     -====================
    -+gitformat-bitmap(5)
    -+===================
    ++gitformat-pack-bitmap(5)
    ++========================
      
     -== Pack and multi-pack bitmaps
     +NAME
     +----
    -+gitformat-bitmap - The bitmap file format
    ++gitformat-pack-bitmap - The bitmap file format
     +
     +SYNOPSIS
     +--------
     +[verse]
    -+$GIT_DIR/objects/pack/*.bitmap
    ++$GIT_DIR/objects/pack/pack-*.bitmap
     +
     +DESCRIPTION
     +-----------
     +
     +Bitmaps are a file format associated with .pack files. See
    -+link:technical/pack-format.html[the pack format documentation] and
    ++the pack format documentation in linkgit:gitformat-pack[5] and
     +linkgit:git-pack-objects[1].
     +
     +== GIT bitmap v1 format
    @@ Documentation/technical/bitmap-format.txt => Documentation/gitformat-bitmap.txt
      
      Bitmaps store reachability information about the set of objects in a packfile,
      or a multi-pack index (MIDX). The former is defined obviously, and the latter is
    -@@ Documentation/gitformat-bitmap.txt: Certain bitmap extensions are supported (see: Appendix B). No extensions are
    +@@ Documentation/gitformat-pack-bitmap.txt: Certain bitmap extensions are supported (see: Appendix B). No extensions are
      required for bitmaps corresponding to packfiles. For bitmaps that correspond to
      MIDXs, both the bit-cache and rev-cache extensions are required.
      
     -== On-disk format
     +=== On-disk format
      
    - 	- A header appears at the beginning:
    - 
    -@@ Documentation/gitformat-bitmap.txt: MIDXs, both the bit-cache and rev-cache extensions are required.
    +     * A header appears at the beginning:
      
    - 		- The compressed bitmap itself, see Appendix A.
    +@@ Documentation/gitformat-pack-bitmap.txt: in the index.
    + 	TRAILER: ::
    + 		Trailing checksum of the preceding contents.
      
     -== Appendix A: Serialization format for an EWAH bitmap
     +Appendix A - Serialization format for an EWAH bitmap
    @@ Documentation/gitformat-bitmap.txt: MIDXs, both the bit-cache and rev-cache exte
      
      Ewah bitmaps are serialized in the same protocol as the JAVAEWAH
      library, making them backwards compatible with the JGit
    -@@ Documentation/gitformat-bitmap.txt: chunk.  For efficient appending to the bitstream, the EWAH stores a
    +@@ Documentation/gitformat-pack-bitmap.txt: chunk.  For efficient appending to the bitstream, the EWAH stores a
      pointer to the last RLW in the stream.
      
      
    @@ Documentation/gitformat-bitmap.txt: chunk.  For efficient appending to the bitst
      
      If the BITMAP_OPT_HASH_CACHE flag is set, the end of the bitmap contains
      a cache of 32-bit values, one per object in the pack/MIDX. The value at
    -@@ Documentation/gitformat-bitmap.txt: Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag.
    +@@ Documentation/gitformat-pack-bitmap.txt: Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag.
      If implementations want to choose a different hashing scheme, they are
      free to do so, but MUST allocate a new header flag (because comparing
      hashes made under two different schemes would be pointless).
    @@ Documentation/gitformat-bitmap.txt: Note that this hashing scheme is tied to the
     +---
     +Part of the linkgit:git[1] suite
     
    - ## Documentation/technical/chunk-format.txt => Documentation/gitformat-chunk.txt ##
    + ## Documentation/technical/cruft-packs.txt => Documentation/gitformat-pack-cruft.txt ##
     @@
    --Chunk-based file formats
    --========================
    -+gitformat-chunk(5)
    -+==================
    +-= Cruft packs
    ++gitformat-pack-cruft(5)
    ++=======================
     +
     +NAME
     +----
    -+gitformat-chunk - Chunk-based file formats
    ++gitformat-pack-cruft - The cruft pack file format
     +
     +SYNOPSIS
     +--------
    -+
    -+Used by linkgit:gitformat-commit-graph[5] and the "MIDX" format (see
    -+link:technical/pack-format.html[the pack format documentation]).
    ++[verse]
    ++$GIT_DIR/objects/pack/pack-*.mtimes
     +
     +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
    -@@ Documentation/gitformat-chunk.txt: for future formats:
    -   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 cruft packs feature offer an alternative to Git's traditional mechanism of
    + removing unreachable objects. This document provides an overview of Git's
    +@@ Documentation/gitformat-pack-cruft.txt: 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.
    +@@ Documentation/gitformat-pack-cruft.txt: 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
     
    - ## Documentation/gitformat-commit-graph.txt ##
    -@@ Documentation/gitformat-commit-graph.txt: All multi-byte numbers are in network byte order.
    -       ID appears at most once.
    + ## Documentation/gitformat-pack-protocol.txt ##
    +@@ Documentation/gitformat-pack-protocol.txt: 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.
      
    -   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]
    +-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.
      
    -   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
    + If 'side-band' or 'side-band-64k' capabilities have been specified by
    + the client, the server will send the packfile data multiplexed.
     
    - ## Documentation/technical/index-format.txt => Documentation/gitformat-index.txt ##
    + ## Documentation/technical/pack-format.txt => Documentation/gitformat-pack.txt ##
     @@
    -+gitformat-index(5)
    -+==================
    +-Git pack format
    +-===============
    ++gitformat-pack(5)
    ++=================
     +
     +NAME
     +----
    -+gitformat-index - Git index format
    ++gitformat-pack - Git pack format
    ++
     +
     +SYNOPSIS
     +--------
     +[verse]
    -+$GIT_DIR/index
    ++$GIT_DIR/objects/pack/pack-*.{pack,idx}
    ++$GIT_DIR/objects/pack/pack-*.rev
    ++$GIT_DIR/objects/pack/multi-pack-index
     +
     +DESCRIPTION
     +-----------
     +
    - Git index format
    --================
    ++The Git pack format is now Git stores most of its primary repository
    ++data. Over the lietime af a repository loose objects (if any) and
    ++smaller packs are consolidated into larger pack(s). See
    ++linkgit:git-gc[1] and linkgit:git-pack-objects[1].
    ++
    ++The pack format is also used over-the-wire, see
    ++e.g. linkgit:gitformat-protocol-v2[5], as well as being a part of
    ++other container formats in the case of linkgit:gitformat-bundle[5].
      
    - == The Git index file has the following format
    + == Checksums and object IDs
      
    -@@ Documentation/gitformat-index.txt: 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.
    +@@ Documentation/gitformat-pack.txt: 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
    +@@ Documentation/gitformat-pack.txt: 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
     +---
    @@ Documentation/gitformat-signature.txt: Date:   Wed Jun 15 09:13:29 2016 +0000
     +---
     +Part of the linkgit:git[1] suite
     
    - ## Documentation/technical/pack-format.txt ##
    -@@ Documentation/technical/pack-format.txt: CHUNK LOOKUP:
    - 	    using the next chunk position if necessary.)
    + ## Documentation/howto/recover-corrupted-object-harder.txt ##
    +@@ Documentation/howto/recover-corrupted-object-harder.txt: 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:
      
    - 	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].
    +
    + ## Documentation/technical/hash-function-transition.txt ##
    +@@ Documentation/technical/hash-function-transition.txt: 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.
    + 
    +
    + ## Documentation/user-manual.txt ##
    +@@ Documentation/user-manual.txt: 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:
      
    - 	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
    +
    + ## cache.h ##
    +@@ cache.h: 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,
     
      ## command-list.txt ##
    -@@ command-list.txt: gitcvs-migration                        guide
    - gitdiffcore                             guide
    +@@ command-list.txt: gitdiffcore                             guide
      giteveryday                             guide
      gitfaq                                  guide
    -+gitformat-bitmap                        gitformats
      gitformat-bundle                        gitformats
     +gitformat-chunk                         gitformats
      gitformat-commit-graph                  gitformats
     +gitformat-index                         gitformats
    ++gitformat-pack                          gitformats
    ++gitformat-pack-bitmap                   gitformats
    ++gitformat-pack-cruft                    gitformats
      gitformat-pack-protocol                 gitformats
      gitformat-protocol-capabilities         gitformats
      gitformat-protocol-common               gitformats
    @@ command-list.txt: gitcvs-migration                        guide
      gitglossary                             guide
      githooks                                userformats
      gitignore                               userformats
    +
    + ## pack-revindex.h ##
    +@@
    +  *
    +  *   - 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
-:  ----------- > 6:  5cf8b526bff docs: move http-protocol docs to man section 5
-:  ----------- > 7:  aabdc4a4151 docs: move multi-pack-index docs to man section 5
-- 
2.37.0.932.g7b7031e73bc


^ permalink raw reply	[flat|nested] 112+ messages in thread

* [PATCH v3 1/7] git docs: split "User-facing file formats" off from "Guides"
  2022-07-12 20:06   ` [PATCH v3 0/7] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
@ 2022-07-12 20:06     ` Ævar Arnfjörð Bjarmason
  2022-07-13  1:09       ` Ævar Arnfjörð Bjarmason
  2022-07-12 20:06     ` [PATCH v3 2/7] git docs: create a "Git file formats and protocols" section Ævar Arnfjörð Bjarmason
                       ` (6 subsequent siblings)
  7 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-12 20:06 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

Create a new "User-facing file formats" section in the main "git help
git" manual page. The "Guides" section was added to the manual page in
f442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense
to list all that documentation.

But placing e.g. "gitignore(5)" in it is stretching the meaning of
what a "guide" is, ideally that section should list things similar to
"giteveryday(7)" and "gitcore-tutorial(7)".

We take a wide view of what's considered a "user format", it's not
just a file format, but e.g. githooks(5) also belongs, since the
layout of the ".git/hooks/" and the placement of hooks in it is
something the user might be expected to interact with.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile     |  1 +
 Documentation/git-help.txt | 13 +++++++++----
 Documentation/git.txt      |  7 +++++++
 Makefile                   |  1 +
 builtin/help.c             | 10 +++++++++-
 command-list.txt           | 16 ++++++++++------
 help.c                     | 17 ++++++++++++++++-
 help.h                     |  1 +
 t/t0012-help.sh            | 12 +++++++++++-
 9 files changed, 65 insertions(+), 13 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 4f801f4e4c9..08b896a3c4c 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
 	cmds-synchingrepositories.txt \
 	cmds-synchelpers.txt \
 	cmds-guide.txt \
+	cmds-userformats.txt \
 	cmds-purehelpers.txt \
 	cmds-foreignscminterface.txt
 
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index 239c68db457..6c285709040 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -9,14 +9,15 @@ SYNOPSIS
 --------
 [verse]
 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]
-'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]
+'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>|<doc>]
 'git help' [-g|--guides]
 'git help' [-c|--config]
+'git help' [--user-formats]
 
 DESCRIPTION
 -----------
 
-With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
+With no options and no '<command>', '<guide>' or '<doc>' given, the synopsis of the 'git'
 command and a list of the most commonly used Git commands are printed
 on the standard output.
 
@@ -26,8 +27,8 @@ printed on the standard output.
 If the option `--guides` or `-g` is given, a list of the
 Git concept guides is also printed on the standard output.
 
-If a command, or a guide, is given, a manual page for that command or
-guide is brought up. The 'man' program is used by default for this
+If a command or other documentation is given, the relevant manual page
+will be brought up. The 'man' program is used by default for this
 purpose, but this can be overridden by other options or configuration
 variables.
 
@@ -69,6 +70,10 @@ OPTIONS
 --guides::
 	Prints a list of the Git concept guides on the standard output.
 
+--user-formats::
+	Prints a list of the Git user-facing format documentation on
+	the standard output.
+
 -i::
 --info::
 	Display manual page for the command in the 'info' format. The
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 302607a4967..9b03bbc3851 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -339,6 +339,13 @@ The following documentation pages are guides about Git concepts.
 
 include::cmds-guide.txt[]
 
+User-facing file formats
+------------------------
+
+This documentation discusses file formats that users are expected to
+edit. These can also be listed with 'git help --user-formats'.
+
+include::cmds-userformats.txt[]
 
 Configuration Mechanism
 -----------------------
diff --git a/Makefile b/Makefile
index 04d0fd1fe60..e24db1d52e2 100644
--- a/Makefile
+++ b/Makefile
@@ -3489,6 +3489,7 @@ check-docs::
 		sed -e '1,/^### command list/d' \
 		    -e '/^#/d' \
 		    -e '/guide$$/d' \
+		    -e '/formats$$/d' \
 		    -e 's/[ 	].*//' \
 		    -e 's/^/listed /' command-list.txt; \
 		$(MAKE) -C Documentation print-man1 | \
diff --git a/builtin/help.c b/builtin/help.c
index 222f994f863..b0164b774c2 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -43,6 +43,7 @@ static enum help_action {
 	HELP_ACTION_ALL = 1,
 	HELP_ACTION_GUIDES,
 	HELP_ACTION_CONFIG,
+	HELP_ACTION_USER_FORMATS,
 	HELP_ACTION_CONFIG_FOR_COMPLETION,
 	HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
 } cmd_mode;
@@ -69,6 +70,8 @@ static struct option builtin_help_options[] = {
 
 	OPT_CMDMODE('g', "guides", &cmd_mode, N_("print list of useful guides"),
 		    HELP_ACTION_GUIDES),
+	OPT_CMDMODE(0, "user-formats", &cmd_mode, N_("print list of user-facing file formats"),
+		    HELP_ACTION_USER_FORMATS),
 	OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
 		    HELP_ACTION_CONFIG),
 	OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
@@ -81,9 +84,10 @@ static struct option builtin_help_options[] = {
 
 static const char * const builtin_help_usage[] = {
 	"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]",
-	N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>]"),
+	N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
 	"git help [-g|--guides]",
 	"git help [-c|--config]",
+	"git help [--user-formats]",
 	NULL
 };
 
@@ -654,6 +658,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		opt_mode_usage(argc, "--config-for-completion", help_format);
 		list_config_help(SHOW_CONFIG_VARS);
 		return 0;
+	case HELP_ACTION_USER_FORMATS:
+		opt_mode_usage(argc, "--user-formats", help_format);
+		list_user_formats_help();
+		return 0;
 	case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
 		opt_mode_usage(argc, "--config-sections-for-completion",
 			       help_format);
diff --git a/command-list.txt b/command-list.txt
index 9bd6f3c48f4..c1eace8f7ad 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -43,6 +43,10 @@
 # specified here, which can only have "guide" attribute and nothing
 # else.
 #
+# User-facing file formats such as documentation for the .gitmodules,
+# .mailmap etc. files lives in man section 5. These entries can only
+# have the "userformats" attribute and nothing else.
+#
 ### command list (do not change this line)
 # command name                          category [category] [category]
 git-add                                 mainporcelain           worktree
@@ -192,7 +196,7 @@ git-verify-tag                          ancillaryinterrogators
 git-whatchanged                         ancillaryinterrogators          complete
 git-worktree                            mainporcelain
 git-write-tree                          plumbingmanipulators
-gitattributes                           guide
+gitattributes                           userformats
 gitcli                                  guide
 gitcore-tutorial                        guide
 gitcredentials                          guide
@@ -201,14 +205,14 @@ gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
 gitglossary                             guide
-githooks                                guide
-gitignore                               guide
+githooks                                userformats
+gitignore                               userformats
 gitk                                    mainporcelain
-gitmailmap                              guide
-gitmodules                              guide
+gitmailmap                              userformats
+gitmodules                              userformats
 gitnamespaces                           guide
 gitremote-helpers                       guide
-gitrepository-layout                    guide
+gitrepository-layout                    userformats
 gitrevisions                            guide
 gitsubmodules                           guide
 gittutorial                             guide
diff --git a/help.c b/help.c
index 41c41c2aa11..51bfc28661c 100644
--- a/help.c
+++ b/help.c
@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {
 	{ CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") },
 	{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
 	{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
+	{ CAT_userformats, N_("Git user-facing file formats") },
 	{ 0, NULL }
 };
 
@@ -47,8 +48,12 @@ static const char *drop_prefix(const char *name, uint32_t category)
 
 	if (skip_prefix(name, "git-", &new_name))
 		return new_name;
-	if (category == CAT_guide && skip_prefix(name, "git", &new_name))
+	switch (category) {
+	case CAT_guide:
+	case CAT_userformats:
+		skip_prefix(name, "git", &new_name);
 		return new_name;
+	}
 	return name;
 
 }
@@ -426,6 +431,16 @@ void list_guides_help(void)
 	putchar('\n');
 }
 
+void list_user_formats_help(void)
+{
+	struct category_description catdesc[] = {
+		{ CAT_userformats, N_("Git user-facing file formats:") },
+		{ 0, NULL }
+	};
+	print_cmd_by_category(catdesc, NULL);
+	putchar('\n');
+}
+
 static int get_alias(const char *var, const char *value, void *data)
 {
 	struct string_list *list = data;
diff --git a/help.h b/help.h
index 971a3ad855a..d8b744178ec 100644
--- a/help.h
+++ b/help.h
@@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num)
 void list_common_cmds_help(void);
 void list_all_cmds_help(int show_external_commands, int show_aliases);
 void list_guides_help(void);
+void list_user_formats_help(void);
 
 void list_all_main_cmds(struct string_list *list);
 void list_all_other_cmds(struct string_list *list);
diff --git a/t/t0012-help.sh b/t/t0012-help.sh
index 6c33a436901..91b5318aa32 100755
--- a/t/t0012-help.sh
+++ b/t/t0012-help.sh
@@ -44,6 +44,8 @@ test_expect_success 'invalid usage' '
 	test_expect_code 129 git help -g add &&
 	test_expect_code 129 git help -a -g &&
 
+	test_expect_code 129 git help --user-formats add &&
+
 	test_expect_code 129 git help -g -c &&
 	test_expect_code 129 git help --config-for-completion add &&
 	test_expect_code 129 git help --config-sections-for-completion add
@@ -104,9 +106,9 @@ test_expect_success 'git help' '
 	test_i18ngrep "^   commit " help.output &&
 	test_i18ngrep "^   fetch  " help.output
 '
+
 test_expect_success 'git help -g' '
 	git help -g >help.output &&
-	test_i18ngrep "^   attributes " help.output &&
 	test_i18ngrep "^   everyday   " help.output &&
 	test_i18ngrep "^   tutorial   " help.output
 '
@@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' '
 	test_cmp expect test-browser.log
 '
 
+test_expect_success 'git help --user-formats' '
+	git help --user-formats >help.output &&
+	grep "^   attributes   " help.output &&
+	grep "^   mailmap   " help.output
+'
+
 test_expect_success 'git help -c' '
 	git help -c >help.output &&
 	cat >expect <<-\EOF &&
@@ -220,6 +228,8 @@ test_expect_success "'git help -a' section spacing" '
 	Low-level Commands / Syncing Repositories
 
 	Low-level Commands / Internal Helpers
+
+	Git user-facing file formats
 	EOF
 	test_cmp expect actual
 '
-- 
2.37.0.932.g7b7031e73bc


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v3 2/7] git docs: create a "Git file formats and protocols" section
  2022-07-12 20:06   ` [PATCH v3 0/7] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
  2022-07-12 20:06     ` [PATCH v3 1/7] git docs: split "User-facing file formats" off from "Guides" Ævar Arnfjörð Bjarmason
@ 2022-07-12 20:06     ` Ævar Arnfjörð Bjarmason
  2022-07-12 20:06     ` [PATCH v3 3/7] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
                       ` (5 subsequent siblings)
  7 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-12 20:06 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

Create a new "Git file formats and protocols" section in the main "git help
git" manual page and start moving the documentation that now lives in
"Documentation/technical/*.git" over to it. This compliments the newly
added and adjacent "User-facing file formats" section.

This makes the technical documentation more accessible and
discoverable. Before this we wouldn't install it by default, and had
no ability to build man page versions of them. The links to them from
our existing documentation link to the generated HTML version of these
docs.

So let's start moving those over, starting with just the
"bundle-format.txt" documentation added in 7378ec90e1c (doc: describe
Git bundle format, 2020-02-07). We'll now have a new
gitformat-bundle(5) man page. Subsequent commits will move more git
internal format documentation over.

Unfortunately the syntax of the current Documentation/technical/*.txt
is not the same (when it comes to section headings etc.) as our
Documentation/*.txt documentation, so change the relevant bits of
syntax as we're moving this over.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile                        |  3 +-
 Documentation/git-bundle.txt                  | 12 +++--
 Documentation/git-help.txt                    |  1 +
 Documentation/git.txt                         |  8 ++++
 ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++---
 Documentation/lint-man-section-order.perl     |  3 ++
 builtin/help.c                                |  8 ++++
 command-list.txt                              |  5 +++
 help.c                                        | 12 +++++
 help.h                                        |  1 +
 t/t0012-help.sh                               |  2 +
 11 files changed, 87 insertions(+), 12 deletions(-)
 rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 08b896a3c4c..404139274e7 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -24,6 +24,7 @@ MAN1_TXT += gitweb.txt
 
 # man5 / man7 guides (note: new guides should also be added to command-list.txt)
 MAN5_TXT += gitattributes.txt
+MAN5_TXT += gitformat-bundle.txt
 MAN5_TXT += githooks.txt
 MAN5_TXT += gitignore.txt
 MAN5_TXT += gitmailmap.txt
@@ -95,7 +96,6 @@ TECH_DOCS += MyFirstObjectWalk
 TECH_DOCS += SubmittingPatches
 TECH_DOCS += ToolsForGit
 TECH_DOCS += technical/bitmap-format
-TECH_DOCS += technical/bundle-format
 TECH_DOCS += technical/cruft-packs
 TECH_DOCS += technical/hash-function-transition
 TECH_DOCS += technical/http-protocol
@@ -291,6 +291,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
 	cmds-synchelpers.txt \
 	cmds-guide.txt \
 	cmds-userformats.txt \
+	cmds-gitformats.txt \
 	cmds-purehelpers.txt \
 	cmds-foreignscminterface.txt
 
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 7685b570455..1aeae09f082 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -56,10 +56,9 @@ using "thin packs", bundles created using exclusions are smaller in
 size. That they're "thin" under the hood is merely noted here as a
 curiosity, and as a reference to other documentation.
 
-See link:technical/bundle-format.html[the `bundle-format`
-documentation] for more details and the discussion of "thin pack" in
-link:technical/pack-format.html[the pack format documentation] for
-further details.
+See linkgit:gitformat-bundle[5] for more details and the discussion of
+"thin pack" in link:technical/pack-format.html[the pack format
+documentation] for further details.
 
 OPTIONS
 -------
@@ -337,6 +336,11 @@ You can also see what references it offers:
 $ git ls-remote mybundle
 ----------------
 
+FILE FORMAT
+-----------
+
+See linkgit:gitformat-bundle[5].
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index 6c285709040..a91126ba802 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -13,6 +13,7 @@ SYNOPSIS
 'git help' [-g|--guides]
 'git help' [-c|--config]
 'git help' [--user-formats]
+'git help' [--git-formats]
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 9b03bbc3851..1980a0e29cd 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -347,6 +347,14 @@ edit. These can also be listed with 'git help --user-formats'.
 
 include::cmds-userformats.txt[]
 
+Git file formats and protocols
+------------------------------
+
+This documentation discusses the file formats and protocols that git
+itself uses. These can also be listed with 'git help --git-formats'.
+
+include::cmds-gitformats.txt[]
+
 Configuration Mechanism
 -----------------------
 
diff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt
similarity index 79%
rename from Documentation/technical/bundle-format.txt
rename to Documentation/gitformat-bundle.txt
index b9be8644cf5..6a9d9e5bf6f 100644
--- a/Documentation/technical/bundle-format.txt
+++ b/Documentation/gitformat-bundle.txt
@@ -1,11 +1,33 @@
-= Git bundle v2 format
+gitformat-bundle(5)
+===================
 
-The Git bundle format is a format that represents both refs and Git objects.
+NAME
+----
+gitformat-bundle - The bundle file format
+
+
+SYNOPSIS
+--------
+[verse]
+*.bundle
+*.bdl
+
+DESCRIPTION
+-----------
+
+The Git bundle format is a format that represents both refs and Git
+objects. A bundle is a header in a format similar to
+linkgit:git-show-ref[1] followed by a pack in *.pack format.
 
-== Format
+The format is created and read by the linkgit:git-bundle[1] command,
+and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1].
+
+
+FORMAT
+------
 
 We will use ABNF notation to define the Git bundle format. See
-protocol-common.txt for the details.
+link:technical/protocol-common.html for the details.
 
 A v2 bundle looks like this:
 
@@ -36,7 +58,9 @@ value        = *(%01-09 / %0b-FF)
 pack         = ... ; packfile
 ----
 
-== Semantics
+
+SEMANTICS
+---------
 
 A Git bundle consists of several parts.
 
@@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id.
 This is a comment and it has no specific meaning. The writer of the bundle MAY
 put any string here. The reader of the bundle MUST ignore the comment.
 
-=== Note on the shallow clone and a Git bundle
+Note on the shallow clone and a Git bundle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Note that the prerequisites does not represent a shallow-clone boundary. The
 semantics of the prerequisites and the shallow-clone boundaries are different,
 and the Git bundle v2 format cannot represent a shallow clone repository.
 
-== Capabilities
+CAPABILITIES
+------------
 
 Because there is no opportunity for negotiation, unknown capabilities cause 'git
 bundle' to abort.
@@ -79,3 +105,7 @@ bundle' to abort.
 * `filter` specifies an object filter as in the `--filter` option in
   linkgit:git-rev-list[1]. The resulting pack-file must be marked as a
   `.promisor` pack-file after it is unbundled.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
index 425377dfeb7..02408a0062f 100755
--- a/Documentation/lint-man-section-order.perl
+++ b/Documentation/lint-man-section-order.perl
@@ -32,6 +32,9 @@
 		'SEE ALSO' => {
 			order => $order++,
 		},
+		'FILE FORMAT' => {
+			order => $order++,
+		},
 		'GIT' => {
 			required => 1,
 			order => $order++,
diff --git a/builtin/help.c b/builtin/help.c
index b0164b774c2..3ff2c5d17a7 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -44,6 +44,7 @@ static enum help_action {
 	HELP_ACTION_GUIDES,
 	HELP_ACTION_CONFIG,
 	HELP_ACTION_USER_FORMATS,
+	HELP_ACTION_GIT_FORMATS,
 	HELP_ACTION_CONFIG_FOR_COMPLETION,
 	HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
 } cmd_mode;
@@ -72,6 +73,8 @@ static struct option builtin_help_options[] = {
 		    HELP_ACTION_GUIDES),
 	OPT_CMDMODE(0, "user-formats", &cmd_mode, N_("print list of user-facing file formats"),
 		    HELP_ACTION_USER_FORMATS),
+	OPT_CMDMODE(0, "git-formats", &cmd_mode, N_("print list of internal file formats and network protocols"),
+		    HELP_ACTION_GIT_FORMATS),
 	OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
 		    HELP_ACTION_CONFIG),
 	OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
@@ -88,6 +91,7 @@ static const char * const builtin_help_usage[] = {
 	"git help [-g|--guides]",
 	"git help [-c|--config]",
 	"git help [--user-formats]",
+	"git help [--git-formats]",
 	NULL
 };
 
@@ -662,6 +666,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		opt_mode_usage(argc, "--user-formats", help_format);
 		list_user_formats_help();
 		return 0;
+	case HELP_ACTION_GIT_FORMATS:
+		opt_mode_usage(argc, "--git-formats", help_format);
+		list_git_formats_help();
+		return 0;
 	case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
 		opt_mode_usage(argc, "--config-sections-for-completion",
 			       help_format);
diff --git a/command-list.txt b/command-list.txt
index c1eace8f7ad..1794a7279bc 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -47,6 +47,10 @@
 # .mailmap etc. files lives in man section 5. These entries can only
 # have the "userformats" attribute and nothing else.
 #
+# Git internal file formats and protocols, such as documentation for the
+# *.bundle format lives in man section 5. These entries can only have
+# the "gitformats" attribute and nothing else.
+#
 ### command list (do not change this line)
 # command name                          category [category] [category]
 git-add                                 mainporcelain           worktree
@@ -204,6 +208,7 @@ gitcvs-migration                        guide
 gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
+gitformat-bundle                        gitformats
 gitglossary                             guide
 githooks                                userformats
 gitignore                               userformats
diff --git a/help.c b/help.c
index 51bfc28661c..cce4dbb3f71 100644
--- a/help.c
+++ b/help.c
@@ -39,6 +39,7 @@ static struct category_description main_categories[] = {
 	{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
 	{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
 	{ CAT_userformats, N_("Git user-facing file formats") },
+	{ CAT_gitformats, N_("Git internal file formats and protocols") },
 	{ 0, NULL }
 };
 
@@ -51,6 +52,7 @@ static const char *drop_prefix(const char *name, uint32_t category)
 	switch (category) {
 	case CAT_guide:
 	case CAT_userformats:
+	case CAT_gitformats:
 		skip_prefix(name, "git", &new_name);
 		return new_name;
 	}
@@ -441,6 +443,16 @@ void list_user_formats_help(void)
 	putchar('\n');
 }
 
+void list_git_formats_help(void)
+{
+	struct category_description catdesc[] = {
+		{ CAT_gitformats, N_("Internal file formats and protocols:") },
+		{ 0, NULL }
+	};
+	print_cmd_by_category(catdesc, NULL);
+	putchar('\n');
+}
+
 static int get_alias(const char *var, const char *value, void *data)
 {
 	struct string_list *list = data;
diff --git a/help.h b/help.h
index d8b744178ec..173bd890ce3 100644
--- a/help.h
+++ b/help.h
@@ -23,6 +23,7 @@ void list_common_cmds_help(void);
 void list_all_cmds_help(int show_external_commands, int show_aliases);
 void list_guides_help(void);
 void list_user_formats_help(void);
+void list_git_formats_help(void);
 
 void list_all_main_cmds(struct string_list *list);
 void list_all_other_cmds(struct string_list *list);
diff --git a/t/t0012-help.sh b/t/t0012-help.sh
index 91b5318aa32..0e291cb91e8 100755
--- a/t/t0012-help.sh
+++ b/t/t0012-help.sh
@@ -230,6 +230,8 @@ test_expect_success "'git help -a' section spacing" '
 	Low-level Commands / Internal Helpers
 
 	Git user-facing file formats
+
+	Git internal file formats and protocols
 	EOF
 	test_cmp expect actual
 '
-- 
2.37.0.932.g7b7031e73bc


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v3 3/7] docs: move commit-graph format docs to man section 5
  2022-07-12 20:06   ` [PATCH v3 0/7] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
  2022-07-12 20:06     ` [PATCH v3 1/7] git docs: split "User-facing file formats" off from "Guides" Ævar Arnfjörð Bjarmason
  2022-07-12 20:06     ` [PATCH v3 2/7] git docs: create a "Git file formats and protocols" section Ævar Arnfjörð Bjarmason
@ 2022-07-12 20:06     ` Ævar Arnfjörð Bjarmason
  2022-07-12 20:06     ` [PATCH v3 4/7] docs: move protocol-related " Ævar Arnfjörð Bjarmason
                       ` (4 subsequent siblings)
  7 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-12 20:06 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

Continue the move of existing Documentation/technical/* protocol and
file-format documentation into our main documentation space.

By moving the documentation for the commit-graph format into man
section 5 and the new "gitformats" category. This change is split from
subsequent commits due to the relatively large amount of ASCIIDOC
formatting changes that are required.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile                        |  1 +
 Documentation/git-commit-graph.txt            |  5 ++
 ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------
 Documentation/technical/chunk-format.txt      |  4 +-
 command-list.txt                              |  1 +
 5 files changed, 41 insertions(+), 17 deletions(-)
 rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (88%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 404139274e7..cc6870cce41 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -25,6 +25,7 @@ MAN1_TXT += gitweb.txt
 # man5 / man7 guides (note: new guides should also be added to command-list.txt)
 MAN5_TXT += gitattributes.txt
 MAN5_TXT += gitformat-bundle.txt
+MAN5_TXT += gitformat-commit-graph.txt
 MAN5_TXT += githooks.txt
 MAN5_TXT += gitignore.txt
 MAN5_TXT += gitmailmap.txt
diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
index e1f48c95b3c..047decdb65b 100644
--- a/Documentation/git-commit-graph.txt
+++ b/Documentation/git-commit-graph.txt
@@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append
 ------------------------------------------------
 
 
+FILE FORMAT
+-----------
+
+see linkgit:gitformat-commit-graph[5].
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt
similarity index 88%
rename from Documentation/technical/commit-graph-format.txt
rename to Documentation/gitformat-commit-graph.txt
index 484b185ba98..108dc2295c0 100644
--- a/Documentation/technical/commit-graph-format.txt
+++ b/Documentation/gitformat-commit-graph.txt
@@ -1,5 +1,18 @@
-Git commit graph format
-=======================
+gitformat-commit-graph(5)
+=========================
+
+NAME
+----
+gitformat-commit-graph - Git commit graph format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/info/commit-graph
+$GIT_DIR/objects/info/commit-graphs/*
+
+DESCRIPTION
+-----------
 
 The Git commit graph stores a list of commit OIDs and some associated
 metadata, including:
@@ -30,7 +43,7 @@ and hash type.
 
 All multi-byte numbers are in network byte order.
 
-HEADER:
+=== HEADER:
 
   4-byte signature:
       The signature is: {'C', 'G', 'P', 'H'}
@@ -52,7 +65,7 @@ HEADER:
       We infer the length (H*B) of the Base Graphs chunk
       from this value.
 
-CHUNK LOOKUP:
+=== CHUNK LOOKUP:
 
   (C + 1) * 12 bytes listing the table of contents for the chunks:
       First 4 bytes describe the chunk id. Value 0 is a terminating label.
@@ -68,17 +81,17 @@ CHUNK LOOKUP:
   these chunks may be given in any order. Chunks are required unless
   otherwise specified.
 
-CHUNK DATA:
+=== CHUNK DATA:
 
-  OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)
+==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)
       The ith entry, F[i], stores the number of OIDs with first
       byte at most i. Thus F[255] stores the total
       number of commits (N).
 
-  OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)
+====  OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)
       The OIDs for all commits in the graph, sorted in ascending order.
 
-  Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)
+====  Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)
     * The first H bytes are for the OID of the root tree.
     * The next 8 bytes are for the positions of the first two parents
       of the ith commit. Stores value 0x70000000 if no parent in that
@@ -93,7 +106,7 @@ CHUNK DATA:
       2 bits of the lowest byte, storing the 33rd and 34th bit of the
       commit time.
 
-  Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]
+==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]
     * This list of 4-byte values store corrected commit date offsets for the
       commits, arranged in the same order as commit data chunk.
     * If the corrected commit date offset cannot be stored within 31 bits,
@@ -104,7 +117,7 @@ CHUNK DATA:
       by compatible versions of Git and in case of split commit-graph chains,
       the topmost layer also has Generation Data chunk.
 
-  Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]
+==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]
     * This list of 8-byte values stores the corrected commit date offsets
       for commits with corrected commit date offsets that cannot be
       stored within 31 bits.
@@ -112,7 +125,7 @@ CHUNK DATA:
       chunk is present and atleast one corrected commit date offset cannot
       be stored within 31 bits.
 
-  Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]
+==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]
       This list of 4-byte values store the second through nth parents for
       all octopus merges. The second parent value in the commit data stores
       an array position within this list along with the most-significant bit
@@ -120,14 +133,14 @@ CHUNK DATA:
       positions for the parents until reaching a value with the most-significant
       bit on. The other bits correspond to the position of the last parent.
 
-  Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]
+==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]
     * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters
       from commit 0 to commit i (inclusive) in lexicographic order. The Bloom
       filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header
       length), where BIDX[-1] is 0.
     * The BIDX chunk is ignored if the BDAT chunk is not present.
 
-  Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]
+==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]
     * It starts with header consisting of three unsigned 32-bit integers:
       - Version of the hash algorithm being used. We currently only support
 	value 1 which corresponds to the 32-bit version of the murmur3 hash
@@ -147,13 +160,13 @@ CHUNK DATA:
       of length one, with either all bits set to zero or one respectively.
     * The BDAT chunk is present if and only if BIDX is present.
 
-  Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]
+==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]
       This list of H-byte hashes describe a set of B commit-graph files that
       form a commit-graph chain. The graph position for the ith commit in this
       file's OID Lookup chunk is equal to i plus the number of commits in all
       base graphs.  If B is non-zero, this chunk must exist.
 
-TRAILER:
+=== TRAILER:
 
 	H-byte HASH-checksum of all of the above.
 
@@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote
 possibly erroneous data in these chunks with the IDs "GDAT" and "GDOV". By
 changing the IDs, newer versions of Git will silently ignore those older
 chunks and write the new information without trusting the incorrect data.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/chunk-format.txt b/Documentation/technical/chunk-format.txt
index 593614fceda..f36ce42f37c 100644
--- a/Documentation/technical/chunk-format.txt
+++ b/Documentation/technical/chunk-format.txt
@@ -6,7 +6,7 @@ sections of the file. This allows structured access to a large file by
 scanning a small "table of contents" for the remaining data. This common
 format is used by the `commit-graph` and `multi-pack-index` files. See
 link:technical/pack-format.html[the `multi-pack-index` format] and
-link:technical/commit-graph-format.html[the `commit-graph` format] for
+the `commit-graph` format in linkgit:gitformat-commit-graph[5] for
 how they use the chunks to describe structured data.
 
 A chunk-based file format begins with some header information custom to
@@ -108,7 +108,7 @@ for future formats:
 * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()`
   in `commit-graph.c` for how the chunk-format API is used to write and
   parse the commit-graph file format documented in
-  link:technical/commit-graph-format.html[the commit-graph file format].
+  the commit-graph file format in linkgit:gitformat-commit-graph[5].
 
 * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`
   in `midx.c` for how the chunk-format API is used to write and
diff --git a/command-list.txt b/command-list.txt
index 1794a7279bc..66e6a0ba217 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -209,6 +209,7 @@ gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
 gitformat-bundle                        gitformats
+gitformat-commit-graph                  gitformats
 gitglossary                             guide
 githooks                                userformats
 gitignore                               userformats
-- 
2.37.0.932.g7b7031e73bc


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v3 4/7] docs: move protocol-related docs to man section 5
  2022-07-12 20:06   ` [PATCH v3 0/7] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
                       ` (2 preceding siblings ...)
  2022-07-12 20:06     ` [PATCH v3 3/7] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
@ 2022-07-12 20:06     ` Ævar Arnfjörð Bjarmason
  2022-07-12 20:07     ` [PATCH v3 5/7] docs: move pack format " Ævar Arnfjörð Bjarmason
                       ` (3 subsequent siblings)
  7 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-12 20:06 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

Continue the move of existing Documentation/technical/* protocol and
file-format documentation into our main documentation space. By moving
the things that discuss the protocol we can properly link from
e.g. lsrefs.unborn and protocol.version documentation to a manpage we
build by default.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile                        |  8 +++---
 Documentation/config/lsrefs.txt               |  2 +-
 Documentation/config/protocol.txt             |  2 +-
 Documentation/git-upload-pack.txt             |  5 ++--
 Documentation/gitformat-bundle.txt            |  2 +-
 ...otocol.txt => gitformat-pack-protocol.txt} | 22 +++++++++++++--
 ...xt => gitformat-protocol-capabilities.txt} | 28 +++++++++++++++----
 ...mmon.txt => gitformat-protocol-common.txt} | 23 +++++++++++++--
 ...tocol-v2.txt => gitformat-protocol-v2.txt} | 24 +++++++++++++---
 Documentation/technical/api-simple-ipc.txt    |  2 +-
 Documentation/technical/http-protocol.txt     |  6 ++--
 .../long-running-process-protocol.txt         |  2 +-
 Documentation/technical/partial-clone.txt     |  2 +-
 command-list.txt                              |  4 +++
 t/t5551-http-fetch-smart.sh                   |  4 +--
 15 files changed, 103 insertions(+), 33 deletions(-)
 rename Documentation/{technical/pack-protocol.txt => gitformat-pack-protocol.txt} (98%)
 rename Documentation/{technical/protocol-capabilities.txt => gitformat-protocol-capabilities.txt} (96%)
 rename Documentation/{technical/protocol-common.txt => gitformat-protocol-common.txt} (88%)
 rename Documentation/{technical/protocol-v2.txt => gitformat-protocol-v2.txt} (98%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index cc6870cce41..adc1404d380 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -26,6 +26,10 @@ MAN1_TXT += gitweb.txt
 MAN5_TXT += gitattributes.txt
 MAN5_TXT += gitformat-bundle.txt
 MAN5_TXT += gitformat-commit-graph.txt
+MAN5_TXT += gitformat-pack-protocol.txt
+MAN5_TXT += gitformat-protocol-capabilities.txt
+MAN5_TXT += gitformat-protocol-common.txt
+MAN5_TXT += gitformat-protocol-v2.txt
 MAN5_TXT += githooks.txt
 MAN5_TXT += gitignore.txt
 MAN5_TXT += gitmailmap.txt
@@ -105,12 +109,8 @@ TECH_DOCS += technical/long-running-process-protocol
 TECH_DOCS += technical/multi-pack-index
 TECH_DOCS += technical/pack-format
 TECH_DOCS += technical/pack-heuristics
-TECH_DOCS += technical/pack-protocol
 TECH_DOCS += technical/parallel-checkout
 TECH_DOCS += technical/partial-clone
-TECH_DOCS += technical/protocol-capabilities
-TECH_DOCS += technical/protocol-common
-TECH_DOCS += technical/protocol-v2
 TECH_DOCS += technical/racy-git
 TECH_DOCS += technical/reftable
 TECH_DOCS += technical/send-pack-pipeline
diff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.txt
index adeda0f24d3..e9efe498c01 100644
--- a/Documentation/config/lsrefs.txt
+++ b/Documentation/config/lsrefs.txt
@@ -1,7 +1,7 @@
 lsrefs.unborn::
 	May be "advertise" (the default), "allow", or "ignore". If "advertise",
 	the server will respond to the client sending "unborn" (as described in
-	protocol-v2.txt) and will advertise support for this feature during the
+	linkgit:gitformat-protocol-v2[5]) and will advertise support for this feature during the
 	protocol v2 capability advertisement. "allow" is the same as
 	"advertise" except that the server will not advertise support for this
 	feature; this is useful for load-balanced servers that cannot be
diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt
index 756591d77b0..bf18a70a924 100644
--- a/Documentation/config/protocol.txt
+++ b/Documentation/config/protocol.txt
@@ -58,6 +58,6 @@ protocol.version::
 * `1` - the original wire protocol with the addition of a version string
   in the initial response from the server.
 
-* `2` - link:technical/protocol-v2.html[wire protocol version 2].
+* `2` - Wire protocol version 2, see linkgit:gitformat-protocol-v2[5].
 
 --
diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt
index 8f87b23ea86..754619222f6 100644
--- a/Documentation/git-upload-pack.txt
+++ b/Documentation/git-upload-pack.txt
@@ -40,9 +40,8 @@ OPTIONS
 	Used by linkgit:git-http-backend[1] to serve up
 	`$GIT_URL/info/refs?service=git-upload-pack` requests. See
 	"Smart Clients" in link:technical/http-protocol.html[the HTTP
-	transfer protocols] documentation and "HTTP Transport" in
-	link:technical/protocol-v2.html[the Git Wire Protocol, Version
-	2] documentation. Also understood by
+	transfer protocols] documentation and "HTTP Transport" in the
+	linkgit:gitformat-protocol-v2[5] documentation. Also understood by
 	linkgit:git-receive-pack[1].
 
 <directory>::
diff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.txt
index 6a9d9e5bf6f..3d60d9067e4 100644
--- a/Documentation/gitformat-bundle.txt
+++ b/Documentation/gitformat-bundle.txt
@@ -27,7 +27,7 @@ FORMAT
 ------
 
 We will use ABNF notation to define the Git bundle format. See
-link:technical/protocol-common.html for the details.
+linkgit:gitformat-protocol-common[5] for the details.
 
 A v2 bundle looks like this:
 
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt
similarity index 98%
rename from Documentation/technical/pack-protocol.txt
rename to Documentation/gitformat-pack-protocol.txt
index e13a2c064d1..b665af5b690 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/gitformat-pack-protocol.txt
@@ -1,5 +1,17 @@
-Packfile transfer protocols
-===========================
+gitformat-pack-protocol(5)
+==========================
+
+NAME
+----
+gitformat-pack-protocol - How packs are transferred over-the-wire
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
 
 Git supports transferring data in packfiles over the ssh://, git://, http:// and
 file:// transports.  There exist two sets of protocols, one for pushing
@@ -18,7 +30,7 @@ pkt-line Format
 ---------------
 
 The descriptions below build on the pkt-line format described in
-protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless
+linkgit:gitformat-protocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless
 otherwise noted the usual pkt-line LF rules apply: the sender SHOULD
 include a LF, but the receiver MUST NOT complain if it is not present.
 
@@ -707,3 +719,7 @@ An example client/server communication might look like this:
    S: 0018ok refs/heads/debug\n
    S: 002ang refs/heads/master non-fast-forward\n
 ----
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/gitformat-protocol-capabilities.txt
similarity index 96%
rename from Documentation/technical/protocol-capabilities.txt
rename to Documentation/gitformat-protocol-capabilities.txt
index 9dfade930da..2e89f40ddb1 100644
--- a/Documentation/technical/protocol-capabilities.txt
+++ b/Documentation/gitformat-protocol-capabilities.txt
@@ -1,8 +1,20 @@
-Git Protocol Capabilities
-=========================
+gitformat-protocol-capabilities(5)
+==================================
+
+NAME
+----
+gitformat-protocol-capabilities - Protocol v0 and v1 capabilities
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
 
 NOTE: this document describes capabilities for versions 0 and 1 of the pack
-protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]
+protocol. For version 2, please refer to the linkgit:gitformat-protocol-v2[5]
 doc.
 
 Servers SHOULD support all capabilities defined in this document.
@@ -77,7 +89,7 @@ interleaved with S-R-Q.
 multi_ack_detailed
 ------------------
 This is an extension of multi_ack that permits client to better
-understand the server's in-memory state. See pack-protocol.txt,
+understand the server's in-memory state. See linkgit:gitformat-pack-protocol[5],
 section "Packfile Negotiation" for more information.
 
 no-done
@@ -281,7 +293,7 @@ a packfile upload and reference update.  If the pushing client requests
 this capability, after unpacking and updating references the server
 will respond with whether the packfile unpacked successfully and if
 each reference was updated successfully.  If any of those were not
-successful, it will send back an error message.  See pack-protocol.txt
+successful, it will send back an error message.  See linkgit:gitformat-pack-protocol[5]
 for example messages.
 
 report-status-v2
@@ -292,7 +304,7 @@ adding new "option" directives in order to support reference rewritten by
 the "proc-receive" hook.  The "proc-receive" hook may handle a command
 for a pseudo-reference which may create or update a reference with
 different name, new-oid, and old-oid.  While the capability
-'report-status' cannot report for such case.  See pack-protocol.txt
+'report-status' cannot report for such case.  See linkgit:gitformat-pack-protocol[5]
 for details.
 
 delete-refs
@@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The
 current implementation uses trace2 session IDs (see
 link:api-trace2.html[api-trace2] for details), but this may change and users of
 the session ID should not rely on this fact.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/protocol-common.txt b/Documentation/gitformat-protocol-common.txt
similarity index 88%
rename from Documentation/technical/protocol-common.txt
rename to Documentation/gitformat-protocol-common.txt
index ecedb34bba5..6e1e1624e2d 100644
--- a/Documentation/technical/protocol-common.txt
+++ b/Documentation/gitformat-protocol-common.txt
@@ -1,5 +1,20 @@
-Documentation Common to Pack and Http Protocols
-===============================================
+gitformat-protocol-common(5)
+============================
+
+NAME
+----
+gitformat-protocol-common - Things common to various protocols
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
+
+This document sets defines things common to various over-the-wire
+protocols and file formats used in Git.
 
 ABNF Notation
 -------------
@@ -97,3 +112,7 @@ Examples (as C-style strings):
   "000bfoobar\n"    "foobar\n"
   "0004"            ""
 ----
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/gitformat-protocol-v2.txt
similarity index 98%
rename from Documentation/technical/protocol-v2.txt
rename to Documentation/gitformat-protocol-v2.txt
index 8a877d27e23..ae4fcc84e37 100644
--- a/Documentation/technical/protocol-v2.txt
+++ b/Documentation/gitformat-protocol-v2.txt
@@ -1,5 +1,17 @@
-Git Wire Protocol, Version 2
-============================
+gitformat-protocol-v2(5)
+========================
+
+NAME
+----
+gitformat-protocol-v2 - Git Wire Protocol, Version 2
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
 
 This document presents a specification for a version 2 of Git's wire
 protocol.  Protocol v2 will improve upon v1 in the following ways:
@@ -26,7 +38,7 @@ Packet-Line Framing
 -------------------
 
 All communication is done using packet-line framing, just as in v1.  See
-`Documentation/technical/pack-protocol.txt` and
+linkgit:gitformat-pack-protocol[5] and
 `Documentation/technical/protocol-common.txt` for more information.
 
 In protocol v2 these special packets will have the following semantics:
@@ -42,7 +54,7 @@ Initial Client Request
 In general a client can request to speak protocol v2 by sending
 `version=2` through the respective side-channel for the transport being
 used which inevitably sets `GIT_PROTOCOL`.  More information can be
-found in `pack-protocol.txt` and `http-protocol.txt`, as well as the
+found in linkgit:gitformat-pack-protocol[5] and `http-protocol.txt`, as well as the
 `GIT_PROTOCOL` definition in `git.txt`. In all cases the
 response from the server is the capability advertisement.
 
@@ -566,3 +578,7 @@ and associated requested information, each separated by a single space.
 	attr = "size"
 
 	obj-info = obj-id SP obj-size
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt
index d79ad323e67..945c21bbc38 100644
--- a/Documentation/technical/api-simple-ipc.txt
+++ b/Documentation/technical/api-simple-ipc.txt
@@ -78,7 +78,7 @@ client and an optional response message from the server.  Both the
 client and server messages are unlimited in length and are terminated
 with a flush packet.
 
-The pkt-line routines (Documentation/technical/protocol-common.txt)
+The pkt-line routines (linkgit:gitformat-protocol-common[5])
 are used to simplify buffer management during message generation,
 transmission, and reception.  A flush packet is used to mark the end
 of the message.  This allows the sender to incrementally generate and
diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
index cc5126cfeda..9d9c7acd512 100644
--- a/Documentation/technical/http-protocol.txt
+++ b/Documentation/technical/http-protocol.txt
@@ -222,7 +222,7 @@ smart server reply:
    S: 0000
 
 The client may send Extra Parameters (see
-Documentation/technical/pack-protocol.txt) as a colon-separated string
+linkgit:gitformat-pack-protocol[5]) as a colon-separated string
 in the Git-Protocol HTTP header.
 
 Uses the `--http-backend-info-refs` option to
@@ -518,5 +518,5 @@ References
 
 http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
 http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
-link:technical/pack-protocol.html
-link:technical/protocol-capabilities.html
+linkgit:gitformat-pack-protocol[5]
+linkgit:gitformat-protocol-capabilities[5]
diff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt
index aa0aa9af1c2..c6922ce6ccc 100644
--- a/Documentation/technical/long-running-process-protocol.txt
+++ b/Documentation/technical/long-running-process-protocol.txt
@@ -3,7 +3,7 @@ Long-running process protocol
 
 This protocol is used when Git needs to communicate with an external
 process throughout the entire life of a single Git command. All
-communication is in pkt-line format (see technical/protocol-common.txt)
+communication is in pkt-line format (see linkgit:gitformat-protocol-common[5])
 over standard input and standard output.
 
 Handshake
diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt
index 99f0eb30406..9d5199d5c6c 100644
--- a/Documentation/technical/partial-clone.txt
+++ b/Documentation/technical/partial-clone.txt
@@ -79,7 +79,7 @@ Design Details
   upload-pack negotiation.
 +
 This uses the existing capability discovery mechanism.
-See "filter" in Documentation/technical/pack-protocol.txt.
+See "filter" in linkgit:gitformat-pack-protocol[5].
 
 - Clients pass a "filter-spec" to clone and fetch which is passed to the
   server to request filtering during packfile construction.
diff --git a/command-list.txt b/command-list.txt
index 66e6a0ba217..bec0fa690aa 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -210,6 +210,10 @@ giteveryday                             guide
 gitfaq                                  guide
 gitformat-bundle                        gitformats
 gitformat-commit-graph                  gitformats
+gitformat-pack-protocol                 gitformats
+gitformat-protocol-capabilities         gitformats
+gitformat-protocol-common               gitformats
+gitformat-protocol-v2                   gitformats
 gitglossary                             guide
 githooks                                userformats
 gitignore                               userformats
diff --git a/t/t5551-http-fetch-smart.sh b/t/t5551-http-fetch-smart.sh
index b9351a732f6..d17f77dda6f 100755
--- a/t/t5551-http-fetch-smart.sh
+++ b/t/t5551-http-fetch-smart.sh
@@ -175,8 +175,8 @@ test_expect_success 'no-op half-auth fetch does not require a password' '
 	# This is not possible with protocol v2, since both objects and refs
 	# are obtained from the "git-upload-pack" path. A solution to this is
 	# to teach the server and client to be able to inline ls-refs requests
-	# as an Extra Parameter (see pack-protocol.txt), so that "info/refs"
-	# can serve refs, just like it does in protocol v0.
+	# as an Extra Parameter (see "git help gitformat-pack-protocol"), so that
+	# "info/refs" can serve refs, just like it does in protocol v0.
 	GIT_TEST_PROTOCOL_VERSION=0 git --git-dir=half-auth fetch &&
 	expect_askpass none
 '
-- 
2.37.0.932.g7b7031e73bc


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v3 5/7] docs: move pack format docs to man section 5
  2022-07-12 20:06   ` [PATCH v3 0/7] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
                       ` (3 preceding siblings ...)
  2022-07-12 20:06     ` [PATCH v3 4/7] docs: move protocol-related " Ævar Arnfjörð Bjarmason
@ 2022-07-12 20:07     ` Ævar Arnfjörð Bjarmason
  2022-07-12 20:07     ` [PATCH v3 6/7] docs: move http-protocol " Ævar Arnfjörð Bjarmason
                       ` (2 subsequent siblings)
  7 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-12 20:07 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile                        | 11 +++---
 Documentation/config/pack.txt                 |  2 +-
 Documentation/git-bundle.txt                  |  3 +-
 Documentation/git-multi-pack-index.txt        |  4 +-
 .../chunk-format.txt => gitformat-chunk.txt}  | 27 ++++++++++---
 Documentation/gitformat-commit-graph.txt      |  2 +-
 .../index-format.txt => gitformat-index.txt}  | 22 ++++++++++-
 ...p-format.txt => gitformat-pack-bitmap.txt} | 38 +++++++++++++++----
 ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++++-
 Documentation/gitformat-pack-protocol.txt     |  2 +-
 .../pack-format.txt => gitformat-pack.txt}    | 34 +++++++++++++++--
 ...ure-format.txt => gitformat-signature.txt} | 21 ++++++++--
 .../howto/recover-corrupted-object-harder.txt |  2 +-
 .../technical/hash-function-transition.txt    |  2 +-
 Documentation/user-manual.txt                 |  2 +-
 cache.h                                       |  3 +-
 command-list.txt                              |  6 +++
 pack-revindex.h                               |  2 +-
 18 files changed, 165 insertions(+), 40 deletions(-)
 rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (90%)
 rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)
 rename Documentation/{technical/bitmap-format.txt => gitformat-pack-bitmap.txt} (91%)
 rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%)
 rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)
 rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index adc1404d380..64be37526c1 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -25,11 +25,17 @@ 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-bitmap.txt
+MAN5_TXT += gitformat-pack-cruft.txt
 MAN5_TXT += gitformat-pack-protocol.txt
+MAN5_TXT += gitformat-pack.txt
 MAN5_TXT += gitformat-protocol-capabilities.txt
 MAN5_TXT += gitformat-protocol-common.txt
 MAN5_TXT += gitformat-protocol-v2.txt
+MAN5_TXT += gitformat-signature.txt
 MAN5_TXT += githooks.txt
 MAN5_TXT += gitignore.txt
 MAN5_TXT += gitmailmap.txt
@@ -100,14 +106,10 @@ TECH_DOCS += MyFirstContribution
 TECH_DOCS += MyFirstObjectWalk
 TECH_DOCS += SubmittingPatches
 TECH_DOCS += ToolsForGit
-TECH_DOCS += technical/bitmap-format
-TECH_DOCS += technical/cruft-packs
 TECH_DOCS += technical/hash-function-transition
 TECH_DOCS += technical/http-protocol
-TECH_DOCS += technical/index-format
 TECH_DOCS += technical/long-running-process-protocol
 TECH_DOCS += technical/multi-pack-index
-TECH_DOCS += technical/pack-format
 TECH_DOCS += technical/pack-heuristics
 TECH_DOCS += technical/parallel-checkout
 TECH_DOCS += technical/partial-clone
@@ -115,7 +117,6 @@ TECH_DOCS += technical/racy-git
 TECH_DOCS += technical/reftable
 TECH_DOCS += technical/send-pack-pipeline
 TECH_DOCS += technical/shallow
-TECH_DOCS += technical/signature-format
 TECH_DOCS += technical/trivial-merge
 SP_ARTICLES += $(TECH_DOCS)
 SP_ARTICLES += technical/api-index
diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt
index ad7f73a1ead..3e581eab84a 100644
--- a/Documentation/config/pack.txt
+++ b/Documentation/config/pack.txt
@@ -166,7 +166,7 @@ permuted into their appropriate location when writing a new bitmap.
 
 pack.writeReverseIndex::
 	When true, git will write a corresponding .rev file (see:
-	link:../technical/pack-format.html[Documentation/technical/pack-format.txt])
+	linkgit:gitformat-pack[5])
 	for each new packfile that it writes in all places except for
 	linkgit:git-fast-import[1] and in the bulk checkin mechanism.
 	Defaults to false.
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 1aeae09f082..4c6c41e1a09 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -57,8 +57,7 @@ size. That they're "thin" under the hood is merely noted here as a
 curiosity, and as a reference to other documentation.
 
 See linkgit:gitformat-bundle[5] for more details and the discussion of
-"thin pack" in link:technical/pack-format.html[the pack format
-documentation] for further details.
+"thin pack" in linkgit:gitformat-pack[5] for further details.
 
 OPTIONS
 -------
diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt
index c588fb91af1..a48c3d5ea63 100644
--- a/Documentation/git-multi-pack-index.txt
+++ b/Documentation/git-multi-pack-index.txt
@@ -128,8 +128,8 @@ $ git multi-pack-index verify
 SEE ALSO
 --------
 See link:technical/multi-pack-index.html[The Multi-Pack-Index Design
-Document] and link:technical/pack-format.html[The Multi-Pack-Index
-Format] for more information on the multi-pack-index feature.
+Document] and linkgit:gitformat-pack[5] for more information on the
+multi-pack-index feature and its file format.
 
 
 GIT
diff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt
similarity index 90%
rename from Documentation/technical/chunk-format.txt
rename to Documentation/gitformat-chunk.txt
index f36ce42f37c..784c5d987de 100644
--- a/Documentation/technical/chunk-format.txt
+++ b/Documentation/gitformat-chunk.txt
@@ -1,12 +1,25 @@
-Chunk-based file formats
-========================
+gitformat-chunk(5)
+==================
+
+NAME
+----
+gitformat-chunk - Chunk-based file formats
+
+SYNOPSIS
+--------
+
+Used by linkgit:gitformat-commit-graph[5] and the "MIDX" format (see
+the pack format documentation in linkgit:gitformat-pack[5]).
+
+DESCRIPTION
+-----------
 
 Some file formats in Git use a common concept of "chunks" to describe
 sections of the file. This allows structured access to a large file by
 scanning a small "table of contents" for the remaining data. This common
 format is used by the `commit-graph` and `multi-pack-index` files. See
-link:technical/pack-format.html[the `multi-pack-index` format] and
-the `commit-graph` format in linkgit:gitformat-commit-graph[5] for
+the `multi-pack-index` format in linkgit:gitformat-pack[5] and
+link:technical/commit-graph-format.html[the `commit-graph` format] for
 how they use the chunks to describe structured data.
 
 A chunk-based file format begins with some header information custom to
@@ -113,4 +126,8 @@ for future formats:
 * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`
   in `midx.c` for how the chunk-format API is used to write and
   parse the multi-pack-index file format documented in
-  link:technical/pack-format.html[the multi-pack-index file format].
+  the multi-pack-index file format section of linkgit:gitformat-pack[5].
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt
index 108dc2295c0..7324665716d 100644
--- a/Documentation/gitformat-commit-graph.txt
+++ b/Documentation/gitformat-commit-graph.txt
@@ -75,7 +75,7 @@ All multi-byte numbers are in network byte order.
       ID appears at most once.
 
   The CHUNK LOOKUP matches the table of contents from
-  link:technical/chunk-format.html[the chunk-based file format].
+  the chunk-based file format, see linkgit:gitformat-chunk[5]
 
   The remaining data in the body is described one chunk at a time, and
   these chunks may be given in any order. Chunks are required unless
diff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt
similarity index 98%
rename from Documentation/technical/index-format.txt
rename to Documentation/gitformat-index.txt
index 65da0daaa56..5f3ed10d2db 100644
--- a/Documentation/technical/index-format.txt
+++ b/Documentation/gitformat-index.txt
@@ -1,5 +1,19 @@
+gitformat-index(5)
+==================
+
+NAME
+----
+gitformat-index - Git index format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/index
+
+DESCRIPTION
+-----------
+
 Git index format
-================
 
 == The Git index file has the following format
 
@@ -127,7 +141,7 @@ Git index format
     entry is encoded as if the path name for the previous entry is an
     empty string).  At the beginning of an entry, an integer N in the
     variable width encoding (the same encoding as the offset is encoded
-    for OFS_DELTA pack entries; see pack-format.txt) is stored, followed
+    for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed
     by a NUL-terminated string S.  Removing N bytes from the end of the
     path name for the previous entry, and replacing it with the string S
     yields the path name for this entry.
@@ -404,3 +418,7 @@ The remaining data of each directory block is grouped by type:
   with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,
   tools should avoid interacting with a sparse index unless they understand
   this extension.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/bitmap-format.txt b/Documentation/gitformat-pack-bitmap.txt
similarity index 91%
rename from Documentation/technical/bitmap-format.txt
rename to Documentation/gitformat-pack-bitmap.txt
index a85f58f5153..942bdd020ca 100644
--- a/Documentation/technical/bitmap-format.txt
+++ b/Documentation/gitformat-pack-bitmap.txt
@@ -1,7 +1,25 @@
-GIT bitmap v1 format
-====================
+gitformat-pack-bitmap(5)
+========================
 
-== Pack and multi-pack bitmaps
+NAME
+----
+gitformat-pack-bitmap - The bitmap file format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/pack/pack-*.bitmap
+
+DESCRIPTION
+-----------
+
+Bitmaps are a file format associated with .pack files. See
+the pack format documentation in linkgit:gitformat-pack[5] and
+linkgit:git-pack-objects[1].
+
+== GIT bitmap v1 format
+
+=== Pack and multi-pack bitmaps
 
 Bitmaps store reachability information about the set of objects in a packfile,
 or a multi-pack index (MIDX). The former is defined obviously, and the latter is
@@ -37,7 +55,7 @@ Certain bitmap extensions are supported (see: Appendix B). No extensions are
 required for bitmaps corresponding to packfiles. For bitmaps that correspond to
 MIDXs, both the bit-cache and rev-cache extensions are required.
 
-== On-disk format
+=== On-disk format
 
     * A header appears at the beginning:
 
@@ -142,7 +160,8 @@ in the index.
 	TRAILER: ::
 		Trailing checksum of the preceding contents.
 
-== Appendix A: Serialization format for an EWAH bitmap
+Appendix A - Serialization format for an EWAH bitmap
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Ewah bitmaps are serialized in the same protocol as the JAVAEWAH
 library, making them backwards compatible with the JGit
@@ -190,13 +209,14 @@ chunk.  For efficient appending to the bitstream, the EWAH stores a
 pointer to the last RLW in the stream.
 
 
-== Appendix B: Optional Bitmap Sections
+Appendix B - Optional Bitmap Sections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These sections may or may not be present in the `.bitmap` file; their
 presence is indicated by the header flags section described above.
 
 Name-hash cache
----------------
+~~~~~~~~~~~~~~~
 
 If the BITMAP_OPT_HASH_CACHE flag is set, the end of the bitmap contains
 a cache of 32-bit values, one per object in the pack/MIDX. The value at
@@ -216,3 +236,7 @@ Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag.
 If implementations want to choose a different hashing scheme, they are
 free to do so, but MUST allocate a new header flag (because comparing
 hashes made under two different schemes would be pointless).
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/cruft-packs.txt b/Documentation/gitformat-pack-cruft.txt
similarity index 96%
rename from Documentation/technical/cruft-packs.txt
rename to Documentation/gitformat-pack-cruft.txt
index d81f3a8982f..908f752bd84 100644
--- a/Documentation/technical/cruft-packs.txt
+++ b/Documentation/gitformat-pack-cruft.txt
@@ -1,4 +1,17 @@
-= Cruft packs
+gitformat-pack-cruft(5)
+=======================
+
+NAME
+----
+gitformat-pack-cruft - The cruft pack file format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/pack/pack-*.mtimes
+
+DESCRIPTION
+-----------
 
 The cruft packs feature offer an alternative to Git's traditional mechanism of
 removing unreachable objects. This document provides an overview of Git's
@@ -10,10 +23,11 @@ same.
 To remove unreachable objects from your repository, Git offers `git repack -Ad`
 (see linkgit:git-repack[1]). Quoting from the documentation:
 
-[quote]
+----
 [...] unreachable objects in a previous pack become loose, unpacked objects,
 instead of being left in the old pack. [...] loose unreachable objects will be
 pruned according to normal expiry rules with the next 'git gc' invocation.
+----
 
 Unreachable objects aren't removed immediately, since doing so could race with
 an incoming push which may reference an object which is about to be deleted.
@@ -121,3 +135,7 @@ which aren't already stored in an earlier cruft pack) is significantly more
 complicated to construct, and so aren't pursued here. The obvious drawback to
 the current implementation is that the entire cruft pack must be re-written from
 scratch.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitformat-pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt
index b665af5b690..f1bfd6705d9 100644
--- a/Documentation/gitformat-pack-protocol.txt
+++ b/Documentation/gitformat-pack-protocol.txt
@@ -467,7 +467,7 @@ Now that the client and server have finished negotiation about what
 the minimal amount of data that needs to be sent to the client is, the server
 will construct and send the required data in packfile format.
 
-See pack-format.txt for what the packfile itself actually looks like.
+See linkgit:gitformat-pack[5] for what the packfile itself actually looks like.
 
 If 'side-band' or 'side-band-64k' capabilities have been specified by
 the client, the server will send the packfile data multiplexed.
diff --git a/Documentation/technical/pack-format.txt b/Documentation/gitformat-pack.txt
similarity index 95%
rename from Documentation/technical/pack-format.txt
rename to Documentation/gitformat-pack.txt
index b520aa9c45b..5b21d0f2521 100644
--- a/Documentation/technical/pack-format.txt
+++ b/Documentation/gitformat-pack.txt
@@ -1,5 +1,29 @@
-Git pack format
-===============
+gitformat-pack(5)
+=================
+
+NAME
+----
+gitformat-pack - Git pack format
+
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/pack/pack-*.{pack,idx}
+$GIT_DIR/objects/pack/pack-*.rev
+$GIT_DIR/objects/pack/multi-pack-index
+
+DESCRIPTION
+-----------
+
+The Git pack format is now Git stores most of its primary repository
+data. Over the lietime af a repository loose objects (if any) and
+smaller packs are consolidated into larger pack(s). See
+linkgit:git-gc[1] and linkgit:git-pack-objects[1].
+
+The pack format is also used over-the-wire, see
+e.g. linkgit:gitformat-protocol-v2[5], as well as being a part of
+other container formats in the case of linkgit:gitformat-bundle[5].
 
 == Checksums and object IDs
 
@@ -356,7 +380,7 @@ CHUNK LOOKUP:
 	    using the next chunk position if necessary.)
 
 	The CHUNK LOOKUP matches the table of contents from
-	link:technical/chunk-format.html[the chunk-based file format].
+	the chunk-based file format, see linkgit:gitformat-chunk[5].
 
 	The remaining data in the body is described one chunk at a time, and
 	these chunks may be given in any order. Chunks are required unless
@@ -482,3 +506,7 @@ packs arranged in MIDX order (with the preferred pack coming first).
 
 The MIDX's reverse index is stored in the optional 'RIDX' chunk within
 the MIDX itself.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt
similarity index 96%
rename from Documentation/technical/signature-format.txt
rename to Documentation/gitformat-signature.txt
index 166721be6f6..a249869fafa 100644
--- a/Documentation/technical/signature-format.txt
+++ b/Documentation/gitformat-signature.txt
@@ -1,7 +1,18 @@
-Git signature format
-====================
+gitformat-signature(5)
+======================
 
-== Overview
+NAME
+----
+gitformat-signature - Git cryptographic signature formats
+
+SYNOPSIS
+--------
+[verse]
+<[tag|commit] object header(s)>
+<over-the-wire protocol>
+
+DESCRIPTION
+-----------
 
 Git uses cryptographic signatures in various places, currently objects (tags,
 commits, mergetags) and transactions (pushes). In every case, the command which
@@ -200,3 +211,7 @@ Date:   Wed Jun 15 09:13:29 2016 +0000
     # gpg:          There is no indication that the signature belongs to the owner.
     # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
 ----
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.txt
index 8994e2559ea..5efb4fe81ff 100644
--- a/Documentation/howto/recover-corrupted-object-harder.txt
+++ b/Documentation/howto/recover-corrupted-object-harder.txt
@@ -68,7 +68,7 @@ Note that the "object" file isn't fit for feeding straight to zlib; it
 has the git packed object header, which is variable-length. We want to
 strip that off so we can start playing with the zlib data directly. You
 can either work your way through it manually (the format is described in
-link:../technical/pack-format.html[Documentation/technical/pack-format.txt]),
+linkgit:gitformat-pack[5]),
 or you can walk through it in a debugger. I did the latter, creating a
 valid pack like:
 
diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt
index 260224b0331..e2ac36dd210 100644
--- a/Documentation/technical/hash-function-transition.txt
+++ b/Documentation/technical/hash-function-transition.txt
@@ -205,7 +205,7 @@ SHA-1 content.
 Object storage
 ~~~~~~~~~~~~~~
 Loose objects use zlib compression and packed objects use the packed
-format described in Documentation/technical/pack-format.txt, just like
+format described in linkgit:gitformat-pack[5], just like
 today. The content that is compressed and stored uses SHA-256 content
 instead of SHA-1 content.
 
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 865074bed4e..ca9decdd952 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3133,7 +3133,7 @@ those "loose" objects.
 You can save space and make Git faster by moving these loose objects in
 to a "pack file", which stores a group of objects in an efficient
 compressed format; the details of how pack files are formatted can be
-found in link:technical/pack-format.html[pack format].
+found in link:gitformat-pack[5].
 
 To put the loose objects into a pack, just run git repack:
 
diff --git a/cache.h b/cache.h
index ac5ab4ef9d3..82755c7c0aa 100644
--- a/cache.h
+++ b/cache.h
@@ -475,8 +475,7 @@ extern struct index_state the_index;
 
 /*
  * Values in this enum (except those outside the 3 bit range) are part
- * of pack file format. See Documentation/technical/pack-format.txt
- * for more information.
+ * of pack file format. See gitformat-pack(5) for more information.
  */
 enum object_type {
 	OBJ_BAD = -1,
diff --git a/command-list.txt b/command-list.txt
index bec0fa690aa..8cd64c34a7c 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -209,11 +209,17 @@ gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
 gitformat-bundle                        gitformats
+gitformat-chunk                         gitformats
 gitformat-commit-graph                  gitformats
+gitformat-index                         gitformats
+gitformat-pack                          gitformats
+gitformat-pack-bitmap                   gitformats
+gitformat-pack-cruft                    gitformats
 gitformat-pack-protocol                 gitformats
 gitformat-protocol-capabilities         gitformats
 gitformat-protocol-common               gitformats
 gitformat-protocol-v2                   gitformats
+gitformat-signature                     gitformats
 gitglossary                             guide
 githooks                                userformats
 gitignore                               userformats
diff --git a/pack-revindex.h b/pack-revindex.h
index 74f4eae668d..4974e75eb4d 100644
--- a/pack-revindex.h
+++ b/pack-revindex.h
@@ -22,7 +22,7 @@
  *
  *   - pack position refers to an object's position within a non-existent pack
  *     described by the MIDX. The pack structure is described in
- *     Documentation/technical/pack-format.txt.
+ *     gitformat-pack(5).
  *
  *     It is effectively a concatanation of all packs in the MIDX (ordered by
  *     their numeric ID within the MIDX) in their original order within each
-- 
2.37.0.932.g7b7031e73bc


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v3 6/7] docs: move http-protocol docs to man section 5
  2022-07-12 20:06   ` [PATCH v3 0/7] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
                       ` (4 preceding siblings ...)
  2022-07-12 20:07     ` [PATCH v3 5/7] docs: move pack format " Ævar Arnfjörð Bjarmason
@ 2022-07-12 20:07     ` Ævar Arnfjörð Bjarmason
  2022-07-12 20:07     ` [PATCH v3 7/7] docs: move multi-pack-index " Ævar Arnfjörð Bjarmason
  2022-07-18 13:29     ` [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
  7 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-12 20:07 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 Documentation/Makefile                        |  2 +-
 Documentation/git-upload-pack.txt             |  6 ++--
 Documentation/gitformat-pack-protocol.txt     |  2 +-
 ...otocol.txt => gitformat-protocol-http.txt} | 29 ++++++++++++++++---
 Documentation/gitformat-protocol-v2.txt       |  4 +--
 command-list.txt                              |  1 +
 6 files changed, 33 insertions(+), 11 deletions(-)
 rename Documentation/{technical/http-protocol.txt => gitformat-protocol-http.txt} (98%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 64be37526c1..0e87d5151df 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -34,6 +34,7 @@ MAN5_TXT += gitformat-pack-protocol.txt
 MAN5_TXT += gitformat-pack.txt
 MAN5_TXT += gitformat-protocol-capabilities.txt
 MAN5_TXT += gitformat-protocol-common.txt
+MAN5_TXT += gitformat-protocol-http.txt
 MAN5_TXT += gitformat-protocol-v2.txt
 MAN5_TXT += gitformat-signature.txt
 MAN5_TXT += githooks.txt
@@ -107,7 +108,6 @@ TECH_DOCS += MyFirstObjectWalk
 TECH_DOCS += SubmittingPatches
 TECH_DOCS += ToolsForGit
 TECH_DOCS += technical/hash-function-transition
-TECH_DOCS += technical/http-protocol
 TECH_DOCS += technical/long-running-process-protocol
 TECH_DOCS += technical/multi-pack-index
 TECH_DOCS += technical/pack-heuristics
diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt
index 754619222f6..720697df3a0 100644
--- a/Documentation/git-upload-pack.txt
+++ b/Documentation/git-upload-pack.txt
@@ -39,9 +39,9 @@ OPTIONS
 --http-backend-info-refs::
 	Used by linkgit:git-http-backend[1] to serve up
 	`$GIT_URL/info/refs?service=git-upload-pack` requests. See
-	"Smart Clients" in link:technical/http-protocol.html[the HTTP
-	transfer protocols] documentation and "HTTP Transport" in the
-	linkgit:gitformat-protocol-v2[5] documentation. Also understood by
+	"Smart Clients" in linkgit:gitformat-protocol-http[5] and
+	"HTTP Transport" in link:technical/protocol-v2.html[the Git
+	Wire Protocol, Version 2] documentation. Also understood by
 	linkgit:git-receive-pack[1].
 
 <directory>::
diff --git a/Documentation/gitformat-pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt
index f1bfd6705d9..c82b926e661 100644
--- a/Documentation/gitformat-pack-protocol.txt
+++ b/Documentation/gitformat-pack-protocol.txt
@@ -17,7 +17,7 @@ Git supports transferring data in packfiles over the ssh://, git://, http:// and
 file:// transports.  There exist two sets of protocols, one for pushing
 data from a client to a server and another for fetching data from a
 server to a client.  The three transports (ssh, git, file) use the same
-protocol to transfer data. http is documented in http-protocol.txt.
+protocol to transfer data. http is documented in linkgit:gitformat-protocol-http[5].
 
 The processes invoked in the canonical Git implementation are 'upload-pack'
 on the server side and 'fetch-pack' on the client side for fetching data;
diff --git a/Documentation/technical/http-protocol.txt b/Documentation/gitformat-protocol-http.txt
similarity index 98%
rename from Documentation/technical/http-protocol.txt
rename to Documentation/gitformat-protocol-http.txt
index 9d9c7acd512..b85fc86abf6 100644
--- a/Documentation/technical/http-protocol.txt
+++ b/Documentation/gitformat-protocol-http.txt
@@ -1,5 +1,19 @@
-HTTP transfer protocols
-=======================
+gitformat-protocol-http(5)
+==========================
+
+NAME
+----
+gitformat-protocol-http - Git HTTP-based protocols
+
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+
+DESCRIPTION
+-----------
 
 Git supports two HTTP based transfer protocols.  A "dumb" protocol
 which requires only a standard HTTP server on the server end of the
@@ -512,11 +526,18 @@ the id obtained through ref discovery as old_id.
 
 TODO: Document this further.
 
-
-References
+REFERENCES
 ----------
 
 http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
 http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
+
+SEE ALSO
+--------
+
 linkgit:gitformat-pack-protocol[5]
 linkgit:gitformat-protocol-capabilities[5]
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitformat-protocol-v2.txt b/Documentation/gitformat-protocol-v2.txt
index ae4fcc84e37..e29bc4b6a68 100644
--- a/Documentation/gitformat-protocol-v2.txt
+++ b/Documentation/gitformat-protocol-v2.txt
@@ -54,7 +54,7 @@ Initial Client Request
 In general a client can request to speak protocol v2 by sending
 `version=2` through the respective side-channel for the transport being
 used which inevitably sets `GIT_PROTOCOL`.  More information can be
-found in linkgit:gitformat-pack-protocol[5] and `http-protocol.txt`, as well as the
+found in linkgit:gitformat-pack-protocol[5] and linkgit:gitformat-protocol-http[5], as well as the
 `GIT_PROTOCOL` definition in `git.txt`. In all cases the
 response from the server is the capability advertisement.
 
@@ -78,7 +78,7 @@ HTTP Transport
 ~~~~~~~~~~~~~~
 
 When using the http:// or https:// transport a client makes a "smart"
-info/refs request as described in `http-protocol.txt` and requests that
+info/refs request as described in linkgit:gitformat-protocol-http[5] and requests that
 v2 be used by supplying "version=2" in the `Git-Protocol` header.
 
    C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
diff --git a/command-list.txt b/command-list.txt
index 8cd64c34a7c..fad553784d9 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -218,6 +218,7 @@ gitformat-pack-cruft                    gitformats
 gitformat-pack-protocol                 gitformats
 gitformat-protocol-capabilities         gitformats
 gitformat-protocol-common               gitformats
+gitformat-protocol-http                 gitformats
 gitformat-protocol-v2                   gitformats
 gitformat-signature                     gitformats
 gitglossary                             guide
-- 
2.37.0.932.g7b7031e73bc


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v3 7/7] docs: move multi-pack-index docs to man section 5
  2022-07-12 20:06   ` [PATCH v3 0/7] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
                       ` (5 preceding siblings ...)
  2022-07-12 20:07     ` [PATCH v3 6/7] docs: move http-protocol " Ævar Arnfjörð Bjarmason
@ 2022-07-12 20:07     ` Ævar Arnfjörð Bjarmason
  2022-07-18 13:29     ` [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
  7 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-12 20:07 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 Documentation/Makefile                        |  2 +-
 Documentation/git-multi-pack-index.txt        |  5 +++--
 ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++++++++++++--
 Documentation/gitformat-pack.txt              |  5 +++++
 command-list.txt                              |  1 +
 5 files changed, 28 insertions(+), 5 deletions(-)
 rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 0e87d5151df..51c3e3a489a 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-bitmap.txt
 MAN5_TXT += gitformat-pack-cruft.txt
 MAN5_TXT += gitformat-pack-protocol.txt
@@ -109,7 +110,6 @@ TECH_DOCS += SubmittingPatches
 TECH_DOCS += ToolsForGit
 TECH_DOCS += technical/hash-function-transition
 TECH_DOCS += technical/long-running-process-protocol
-TECH_DOCS += technical/multi-pack-index
 TECH_DOCS += technical/pack-heuristics
 TECH_DOCS += technical/parallel-checkout
 TECH_DOCS += technical/partial-clone
diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt
index a48c3d5ea63..a147e047c91 100644
--- a/Documentation/git-multi-pack-index.txt
+++ b/Documentation/git-multi-pack-index.txt
@@ -127,8 +127,9 @@ $ git multi-pack-index verify
 
 SEE ALSO
 --------
-See link:technical/multi-pack-index.html[The Multi-Pack-Index Design
-Document] and linkgit:gitformat-pack[5] for more information on the
+
+See linkgit:git-multi-pack-index[1] and
+linkgit:gitformat-multi-pack-index[5] for more information on the
 multi-pack-index feature and its file format.
 
 
diff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/gitformat-multi-pack-index.txt
similarity index 94%
rename from Documentation/technical/multi-pack-index.txt
rename to Documentation/gitformat-multi-pack-index.txt
index f2221d2b441..3bca1e7b10d 100644
--- a/Documentation/technical/multi-pack-index.txt
+++ b/Documentation/gitformat-multi-pack-index.txt
@@ -1,5 +1,17 @@
-Multi-Pack-Index (MIDX) Design Notes
-====================================
+gitformat-multi-pack-index(5)
+=============================
+
+NAME
+----
+gitformat-multi-pack-index - The multi-pack-index file format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/pack/multi-pack-index
+
+DESCRIPTION
+-----------
 
 The Git object directory contains a 'pack' directory containing
 packfiles (with suffix ".pack") and pack-indexes (with suffix
@@ -98,3 +110,7 @@ Related Links
 
 [2] https://lore.kernel.org/git/alpine.DEB.2.20.1803091557510.23109@alexmv-linux/
     Git Merge 2018 Contributor's summit notes (includes discussion of MIDX)
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt
index 5b21d0f2521..06b469c6944 100644
--- a/Documentation/gitformat-pack.txt
+++ b/Documentation/gitformat-pack.txt
@@ -507,6 +507,11 @@ packs arranged in MIDX order (with the preferred pack coming first).
 The MIDX's reverse index is stored in the optional 'RIDX' chunk within
 the MIDX itself.
 
+SEE ALSO
+--------
+
+linkgit:gitformat-multi-pack-index[5]
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/command-list.txt b/command-list.txt
index fad553784d9..685ce8077d3 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -212,6 +212,7 @@ gitformat-bundle                        gitformats
 gitformat-chunk                         gitformats
 gitformat-commit-graph                  gitformats
 gitformat-index                         gitformats
+gitformat-multi-pack-index              gitformats
 gitformat-pack                          gitformats
 gitformat-pack-bitmap                   gitformats
 gitformat-pack-cruft                    gitformats
-- 
2.37.0.932.g7b7031e73bc


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* Re: [PATCH v3 1/7] git docs: split "User-facing file formats" off from "Guides"
  2022-07-12 20:06     ` [PATCH v3 1/7] git docs: split "User-facing file formats" off from "Guides" Ævar Arnfjörð Bjarmason
@ 2022-07-13  1:09       ` Ævar Arnfjörð Bjarmason
  0 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-13  1:09 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason


On Tue, Jul 12 2022, Ævar Arnfjörð Bjarmason wrote:

> @@ -47,8 +48,12 @@ static const char *drop_prefix(const char *name, uint32_t category)
>  
>  	if (skip_prefix(name, "git-", &new_name))
>  		return new_name;
> -	if (category == CAT_guide && skip_prefix(name, "git", &new_name))
> +	switch (category) {
> +	case CAT_guide:
> +	case CAT_userformats:
> +		skip_prefix(name, "git", &new_name);
>  		return new_name;
> +	}
>  	return name;
>  
>  }

I noticed after submission that -fanalyzer complaints about this, since
according to it (and probably also coverity etc.) we could return a NULL
"new_name" there, i.e. if the "skip_prefix" doesn't succeed.

I'll guard this in the inevitable re-roll, but FWIW this isn't a logic
error now, it's just that the compiler can't see that.

All of these categories (and the one added in 2/7) have strings that
start with "git", so we'll never have a NULL "new_name" here, we always
skip that prefix.

Of course that depends on the relevant categories in command-list.txt
having git* names, but we know that's the case, and that'll probably
never change. So I'll just have this BUG() out if the constraint is
violated.

^ permalink raw reply	[flat|nested] 112+ messages in thread

* [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/*
  2022-07-12 20:06   ` [PATCH v3 0/7] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
                       ` (6 preceding siblings ...)
  2022-07-12 20:07     ` [PATCH v3 7/7] docs: move multi-pack-index " Ævar Arnfjörð Bjarmason
@ 2022-07-18 13:29     ` Ævar Arnfjörð Bjarmason
  2022-07-18 13:29       ` [PATCH v4 1/8] help.c: BUG() out if "help --guides" can't remove "git" prefixes Ævar Arnfjörð Bjarmason
                         ` (9 more replies)
  7 siblings, 10 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-18 13:29 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

This series improves the discoverability of the technical/*
documentation covering those "formats" where we interact with users
(e.g. "gitattributes") by moving them to its own "git help" category.

It then moves various technical documentation from technical/* to our
main documentation namespace, allowing us to cross-link e.g. from
"git-bundle(1)" to a new "gitformat-bundle(5)".

See the v3 CL[1] for more details.

Changes since v3:

 * Made a condition that never happened but which -fanalyzer
   complained about a BUG() (required knowing about the nature of
   command-list.txt).

 * Ejected the conflict with ac/bitmap-lookup-table by punting on
   gitformat-pack-bitmap(5). We can migrate that later, but this way
   there's no conflicts with "seen".

1. https://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/

Ævar Arnfjörð Bjarmason (8):
  help.c: BUG() out if "help --guides" can't remove "git" prefixes
  git docs: split "User-facing file formats" off from "Guides"
  git docs: create a "Git file formats and protocols" section
  docs: move commit-graph format docs to man section 5
  docs: move protocol-related docs to man section 5
  docs: move pack format docs to man section 5
  docs: move http-protocol docs to man section 5
  docs: move multi-pack-index docs to man section 5

 Documentation/Makefile                        | 26 +++++-----
 Documentation/config/lsrefs.txt               |  2 +-
 Documentation/config/pack.txt                 |  2 +-
 Documentation/config/protocol.txt             |  2 +-
 Documentation/git-bundle.txt                  | 11 +++--
 Documentation/git-commit-graph.txt            |  5 ++
 Documentation/git-help.txt                    | 14 ++++--
 Documentation/git-multi-pack-index.txt        |  7 +--
 Documentation/git-upload-pack.txt             |  7 ++-
 Documentation/git.txt                         | 15 ++++++
 ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++---
 .../chunk-format.txt => gitformat-chunk.txt}  | 27 ++++++++--
 ...-format.txt => gitformat-commit-graph.txt} | 49 +++++++++++++------
 .../index-format.txt => gitformat-index.txt}  | 22 ++++++++-
 ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++-
 ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++-
 ...otocol.txt => gitformat-pack-protocol.txt} | 26 ++++++++--
 .../pack-format.txt => gitformat-pack.txt}    | 39 +++++++++++++--
 ...xt => gitformat-protocol-capabilities.txt} | 28 ++++++++---
 ...mmon.txt => gitformat-protocol-common.txt} | 23 ++++++++-
 ...otocol.txt => gitformat-protocol-http.txt} | 35 ++++++++++---
 ...tocol-v2.txt => gitformat-protocol-v2.txt} | 26 ++++++++--
 ...ure-format.txt => gitformat-signature.txt} | 21 ++++++--
 .../howto/recover-corrupted-object-harder.txt |  2 +-
 Documentation/lint-man-section-order.perl     |  3 ++
 Documentation/technical/api-simple-ipc.txt    |  2 +-
 .../technical/hash-function-transition.txt    |  2 +-
 .../long-running-process-protocol.txt         |  2 +-
 Documentation/technical/partial-clone.txt     |  2 +-
 Documentation/user-manual.txt                 |  2 +-
 Makefile                                      |  1 +
 builtin/help.c                                | 18 ++++++-
 cache.h                                       |  3 +-
 command-list.txt                              | 33 ++++++++++---
 help.c                                        | 32 +++++++++++-
 help.h                                        |  2 +
 pack-revindex.h                               |  2 +-
 t/t0012-help.sh                               | 14 +++++-
 t/t5551-http-fetch-smart.sh                   |  4 +-
 39 files changed, 482 insertions(+), 115 deletions(-)
 rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)
 rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (90%)
 rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (87%)
 rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)
 rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)
 rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%)
 rename Documentation/{technical/pack-protocol.txt => gitformat-pack-protocol.txt} (98%)
 rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)
 rename Documentation/{technical/protocol-capabilities.txt => gitformat-protocol-capabilities.txt} (96%)
 rename Documentation/{technical/protocol-common.txt => gitformat-protocol-common.txt} (88%)
 rename Documentation/{technical/http-protocol.txt => gitformat-protocol-http.txt} (97%)
 rename Documentation/{technical/protocol-v2.txt => gitformat-protocol-v2.txt} (97%)
 rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)

Range-diff against v3:
-:  ----------- > 1:  4428f0a6fb1 help.c: BUG() out if "help --guides" can't remove "git" prefixes
1:  929d9192828 ! 2:  883c483d4e7 git docs: split "User-facing file formats" off from "Guides"
    @@ help.c: static struct category_description main_categories[] = {
      };
      
     @@ help.c: static const char *drop_prefix(const char *name, uint32_t category)
    - 
    - 	if (skip_prefix(name, "git-", &new_name))
    - 		return new_name;
    --	if (category == CAT_guide && skip_prefix(name, "git", &new_name))
    -+	switch (category) {
    -+	case CAT_guide:
    + 	switch (category)
    + 	{
    + 	case CAT_guide:
     +	case CAT_userformats:
    -+		skip_prefix(name, "git", &new_name);
    + 		if (!skip_prefix(name, "git", &new_name))
    + 			BUG("category #%d but no 'git' prefix?", category);
      		return new_name;
    -+	}
    - 	return name;
    - 
    - }
     @@ help.c: void list_guides_help(void)
      	putchar('\n');
      }
2:  1fd57d5caf4 ! 3:  d196bcd1db0 git docs: create a "Git file formats and protocols" section
    @@ help.c: static struct category_description main_categories[] = {
      };
      
     @@ help.c: static const char *drop_prefix(const char *name, uint32_t category)
    - 	switch (category) {
    + 	{
      	case CAT_guide:
      	case CAT_userformats:
     +	case CAT_gitformats:
    - 		skip_prefix(name, "git", &new_name);
    + 		if (!skip_prefix(name, "git", &new_name))
    + 			BUG("category #%d but no 'git' prefix?", category);
      		return new_name;
    - 	}
     @@ help.c: void list_user_formats_help(void)
      	putchar('\n');
      }
3:  d548c6aaba7 = 4:  b59e001a4ca docs: move commit-graph format docs to man section 5
4:  f404987f94d = 5:  968aa977b67 docs: move protocol-related docs to man section 5
5:  6c46b4dccea ! 6:  858ce9c6999 docs: move pack format docs to man section 5
    @@ Commit message
         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 <avarab@gmail.com>
     
      ## Documentation/Makefile ##
    @@ Documentation/Makefile: MAN1_TXT += gitweb.txt
     +MAN5_TXT += gitformat-chunk.txt
      MAN5_TXT += gitformat-commit-graph.txt
     +MAN5_TXT += gitformat-index.txt
    -+MAN5_TXT += gitformat-pack-bitmap.txt
     +MAN5_TXT += gitformat-pack-cruft.txt
      MAN5_TXT += gitformat-pack-protocol.txt
     +MAN5_TXT += gitformat-pack.txt
    @@ Documentation/Makefile: MAN1_TXT += gitweb.txt
      MAN5_TXT += githooks.txt
      MAN5_TXT += gitignore.txt
      MAN5_TXT += gitmailmap.txt
    -@@ Documentation/Makefile: TECH_DOCS += MyFirstContribution
    - TECH_DOCS += MyFirstObjectWalk
    +@@ Documentation/Makefile: TECH_DOCS += MyFirstObjectWalk
      TECH_DOCS += SubmittingPatches
      TECH_DOCS += ToolsForGit
    --TECH_DOCS += technical/bitmap-format
    + TECH_DOCS += technical/bitmap-format
     -TECH_DOCS += technical/cruft-packs
      TECH_DOCS += technical/hash-function-transition
      TECH_DOCS += technical/http-protocol
    @@ Documentation/gitformat-index.txt: The remaining data of each directory block is
     +
     +GIT
     +---
    -+Part of the linkgit:git[1] suite
    -
    - ## Documentation/technical/bitmap-format.txt => Documentation/gitformat-pack-bitmap.txt ##
    -@@
    --GIT bitmap v1 format
    --====================
    -+gitformat-pack-bitmap(5)
    -+========================
    - 
    --== Pack and multi-pack bitmaps
    -+NAME
    -+----
    -+gitformat-pack-bitmap - The bitmap file format
    -+
    -+SYNOPSIS
    -+--------
    -+[verse]
    -+$GIT_DIR/objects/pack/pack-*.bitmap
    -+
    -+DESCRIPTION
    -+-----------
    -+
    -+Bitmaps are a file format associated with .pack files. See
    -+the pack format documentation in linkgit:gitformat-pack[5] and
    -+linkgit:git-pack-objects[1].
    -+
    -+== GIT bitmap v1 format
    -+
    -+=== Pack and multi-pack bitmaps
    - 
    - Bitmaps store reachability information about the set of objects in a packfile,
    - or a multi-pack index (MIDX). The former is defined obviously, and the latter is
    -@@ Documentation/gitformat-pack-bitmap.txt: Certain bitmap extensions are supported (see: Appendix B). No extensions are
    - required for bitmaps corresponding to packfiles. For bitmaps that correspond to
    - MIDXs, both the bit-cache and rev-cache extensions are required.
    - 
    --== On-disk format
    -+=== On-disk format
    - 
    -     * A header appears at the beginning:
    - 
    -@@ Documentation/gitformat-pack-bitmap.txt: in the index.
    - 	TRAILER: ::
    - 		Trailing checksum of the preceding contents.
    - 
    --== Appendix A: Serialization format for an EWAH bitmap
    -+Appendix A - Serialization format for an EWAH bitmap
    -+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    - 
    - Ewah bitmaps are serialized in the same protocol as the JAVAEWAH
    - library, making them backwards compatible with the JGit
    -@@ Documentation/gitformat-pack-bitmap.txt: chunk.  For efficient appending to the bitstream, the EWAH stores a
    - pointer to the last RLW in the stream.
    - 
    - 
    --== Appendix B: Optional Bitmap Sections
    -+Appendix B - Optional Bitmap Sections
    -+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    - 
    - These sections may or may not be present in the `.bitmap` file; their
    - presence is indicated by the header flags section described above.
    - 
    - Name-hash cache
    -----------------
    -+~~~~~~~~~~~~~~~
    - 
    - If the BITMAP_OPT_HASH_CACHE flag is set, the end of the bitmap contains
    - a cache of 32-bit values, one per object in the pack/MIDX. The value at
    -@@ Documentation/gitformat-pack-bitmap.txt: Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag.
    - If implementations want to choose a different hashing scheme, they are
    - free to do so, but MUST allocate a new header flag (because comparing
    - hashes made under two different schemes would be pointless).
    -+
    -+GIT
    -+---
     +Part of the linkgit:git[1] suite
     
      ## Documentation/technical/cruft-packs.txt => Documentation/gitformat-pack-cruft.txt ##
    @@ command-list.txt: gitdiffcore                             guide
      gitformat-commit-graph                  gitformats
     +gitformat-index                         gitformats
     +gitformat-pack                          gitformats
    -+gitformat-pack-bitmap                   gitformats
     +gitformat-pack-cruft                    gitformats
      gitformat-pack-protocol                 gitformats
      gitformat-protocol-capabilities         gitformats
6:  5cf8b526bff ! 7:  499ee582644 docs: move http-protocol docs to man section 5
    @@ Documentation/Makefile: MAN5_TXT += gitformat-pack-protocol.txt
      MAN5_TXT += gitformat-protocol-v2.txt
      MAN5_TXT += gitformat-signature.txt
      MAN5_TXT += githooks.txt
    -@@ Documentation/Makefile: TECH_DOCS += MyFirstObjectWalk
    - TECH_DOCS += SubmittingPatches
    +@@ Documentation/Makefile: 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
7:  aabdc4a4151 ! 8:  f186950e673 docs: move multi-pack-index docs to man section 5
    @@ Documentation/Makefile: MAN5_TXT += gitformat-bundle.txt
      MAN5_TXT += gitformat-commit-graph.txt
      MAN5_TXT += gitformat-index.txt
     +MAN5_TXT += gitformat-multi-pack-index.txt
    - MAN5_TXT += gitformat-pack-bitmap.txt
      MAN5_TXT += gitformat-pack-cruft.txt
      MAN5_TXT += gitformat-pack-protocol.txt
    -@@ Documentation/Makefile: TECH_DOCS += SubmittingPatches
    - TECH_DOCS += ToolsForGit
    + MAN5_TXT += gitformat-pack.txt
    +@@ Documentation/Makefile: 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
    @@ command-list.txt: gitformat-bundle                        gitformats
      gitformat-index                         gitformats
     +gitformat-multi-pack-index              gitformats
      gitformat-pack                          gitformats
    - gitformat-pack-bitmap                   gitformats
      gitformat-pack-cruft                    gitformats
    + gitformat-pack-protocol                 gitformats
-- 
2.37.1.1032.gb00b5447790


^ permalink raw reply	[flat|nested] 112+ messages in thread

* [PATCH v4 1/8] help.c: BUG() out if "help --guides" can't remove "git" prefixes
  2022-07-18 13:29     ` [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
@ 2022-07-18 13:29       ` Ævar Arnfjörð Bjarmason
  2022-07-18 17:03         ` Junio C Hamano
  2022-07-18 13:29       ` [PATCH v4 2/8] git docs: split "User-facing file formats" off from "Guides" Ævar Arnfjörð Bjarmason
                         ` (8 subsequent siblings)
  9 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-18 13:29 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 help.c | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/help.c b/help.c
index 41c41c2aa11..24ac50f62fe 100644
--- a/help.c
+++ b/help.c
@@ -47,10 +47,14 @@ static const char *drop_prefix(const char *name, uint32_t category)
 
 	if (skip_prefix(name, "git-", &new_name))
 		return new_name;
-	if (category == CAT_guide && skip_prefix(name, "git", &new_name))
+	switch (category)
+	{
+	case CAT_guide:
+		if (!skip_prefix(name, "git", &new_name))
+			BUG("category #%d but no 'git' prefix?", category);
 		return new_name;
+	}
 	return name;
-
 }
 
 static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask)
-- 
2.37.1.1032.gb00b5447790


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v4 2/8] git docs: split "User-facing file formats" off from "Guides"
  2022-07-18 13:29     ` [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
  2022-07-18 13:29       ` [PATCH v4 1/8] help.c: BUG() out if "help --guides" can't remove "git" prefixes Ævar Arnfjörð Bjarmason
@ 2022-07-18 13:29       ` Ævar Arnfjörð Bjarmason
  2022-07-18 17:17         ` Junio C Hamano
  2022-07-18 13:29       ` [PATCH v4 3/8] git docs: create a "Git file formats and protocols" section Ævar Arnfjörð Bjarmason
                         ` (7 subsequent siblings)
  9 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-18 13:29 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

Create a new "User-facing file formats" section in the main "git help
git" manual page. The "Guides" section was added to the manual page in
f442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense
to list all that documentation.

But placing e.g. "gitignore(5)" in it is stretching the meaning of
what a "guide" is, ideally that section should list things similar to
"giteveryday(7)" and "gitcore-tutorial(7)".

We take a wide view of what's considered a "user format", it's not
just a file format, but e.g. githooks(5) also belongs, since the
layout of the ".git/hooks/" and the placement of hooks in it is
something the user might be expected to interact with.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile     |  1 +
 Documentation/git-help.txt | 13 +++++++++----
 Documentation/git.txt      |  7 +++++++
 Makefile                   |  1 +
 builtin/help.c             | 10 +++++++++-
 command-list.txt           | 16 ++++++++++------
 help.c                     | 12 ++++++++++++
 help.h                     |  1 +
 t/t0012-help.sh            | 12 +++++++++++-
 9 files changed, 61 insertions(+), 12 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 4f801f4e4c9..08b896a3c4c 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
 	cmds-synchingrepositories.txt \
 	cmds-synchelpers.txt \
 	cmds-guide.txt \
+	cmds-userformats.txt \
 	cmds-purehelpers.txt \
 	cmds-foreignscminterface.txt
 
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index 239c68db457..6c285709040 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -9,14 +9,15 @@ SYNOPSIS
 --------
 [verse]
 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]
-'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]
+'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>|<doc>]
 'git help' [-g|--guides]
 'git help' [-c|--config]
+'git help' [--user-formats]
 
 DESCRIPTION
 -----------
 
-With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
+With no options and no '<command>', '<guide>' or '<doc>' given, the synopsis of the 'git'
 command and a list of the most commonly used Git commands are printed
 on the standard output.
 
@@ -26,8 +27,8 @@ printed on the standard output.
 If the option `--guides` or `-g` is given, a list of the
 Git concept guides is also printed on the standard output.
 
-If a command, or a guide, is given, a manual page for that command or
-guide is brought up. The 'man' program is used by default for this
+If a command or other documentation is given, the relevant manual page
+will be brought up. The 'man' program is used by default for this
 purpose, but this can be overridden by other options or configuration
 variables.
 
@@ -69,6 +70,10 @@ OPTIONS
 --guides::
 	Prints a list of the Git concept guides on the standard output.
 
+--user-formats::
+	Prints a list of the Git user-facing format documentation on
+	the standard output.
+
 -i::
 --info::
 	Display manual page for the command in the 'info' format. The
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 302607a4967..9b03bbc3851 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -339,6 +339,13 @@ The following documentation pages are guides about Git concepts.
 
 include::cmds-guide.txt[]
 
+User-facing file formats
+------------------------
+
+This documentation discusses file formats that users are expected to
+edit. These can also be listed with 'git help --user-formats'.
+
+include::cmds-userformats.txt[]
 
 Configuration Mechanism
 -----------------------
diff --git a/Makefile b/Makefile
index 04d0fd1fe60..e24db1d52e2 100644
--- a/Makefile
+++ b/Makefile
@@ -3489,6 +3489,7 @@ check-docs::
 		sed -e '1,/^### command list/d' \
 		    -e '/^#/d' \
 		    -e '/guide$$/d' \
+		    -e '/formats$$/d' \
 		    -e 's/[ 	].*//' \
 		    -e 's/^/listed /' command-list.txt; \
 		$(MAKE) -C Documentation print-man1 | \
diff --git a/builtin/help.c b/builtin/help.c
index 222f994f863..b0164b774c2 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -43,6 +43,7 @@ static enum help_action {
 	HELP_ACTION_ALL = 1,
 	HELP_ACTION_GUIDES,
 	HELP_ACTION_CONFIG,
+	HELP_ACTION_USER_FORMATS,
 	HELP_ACTION_CONFIG_FOR_COMPLETION,
 	HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
 } cmd_mode;
@@ -69,6 +70,8 @@ static struct option builtin_help_options[] = {
 
 	OPT_CMDMODE('g', "guides", &cmd_mode, N_("print list of useful guides"),
 		    HELP_ACTION_GUIDES),
+	OPT_CMDMODE(0, "user-formats", &cmd_mode, N_("print list of user-facing file formats"),
+		    HELP_ACTION_USER_FORMATS),
 	OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
 		    HELP_ACTION_CONFIG),
 	OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
@@ -81,9 +84,10 @@ static struct option builtin_help_options[] = {
 
 static const char * const builtin_help_usage[] = {
 	"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]",
-	N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>]"),
+	N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
 	"git help [-g|--guides]",
 	"git help [-c|--config]",
+	"git help [--user-formats]",
 	NULL
 };
 
@@ -654,6 +658,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		opt_mode_usage(argc, "--config-for-completion", help_format);
 		list_config_help(SHOW_CONFIG_VARS);
 		return 0;
+	case HELP_ACTION_USER_FORMATS:
+		opt_mode_usage(argc, "--user-formats", help_format);
+		list_user_formats_help();
+		return 0;
 	case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
 		opt_mode_usage(argc, "--config-sections-for-completion",
 			       help_format);
diff --git a/command-list.txt b/command-list.txt
index 9bd6f3c48f4..c1eace8f7ad 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -43,6 +43,10 @@
 # specified here, which can only have "guide" attribute and nothing
 # else.
 #
+# User-facing file formats such as documentation for the .gitmodules,
+# .mailmap etc. files lives in man section 5. These entries can only
+# have the "userformats" attribute and nothing else.
+#
 ### command list (do not change this line)
 # command name                          category [category] [category]
 git-add                                 mainporcelain           worktree
@@ -192,7 +196,7 @@ git-verify-tag                          ancillaryinterrogators
 git-whatchanged                         ancillaryinterrogators          complete
 git-worktree                            mainporcelain
 git-write-tree                          plumbingmanipulators
-gitattributes                           guide
+gitattributes                           userformats
 gitcli                                  guide
 gitcore-tutorial                        guide
 gitcredentials                          guide
@@ -201,14 +205,14 @@ gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
 gitglossary                             guide
-githooks                                guide
-gitignore                               guide
+githooks                                userformats
+gitignore                               userformats
 gitk                                    mainporcelain
-gitmailmap                              guide
-gitmodules                              guide
+gitmailmap                              userformats
+gitmodules                              userformats
 gitnamespaces                           guide
 gitremote-helpers                       guide
-gitrepository-layout                    guide
+gitrepository-layout                    userformats
 gitrevisions                            guide
 gitsubmodules                           guide
 gittutorial                             guide
diff --git a/help.c b/help.c
index 24ac50f62fe..17ba210cf4e 100644
--- a/help.c
+++ b/help.c
@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {
 	{ CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") },
 	{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
 	{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
+	{ CAT_userformats, N_("Git user-facing file formats") },
 	{ 0, NULL }
 };
 
@@ -50,6 +51,7 @@ static const char *drop_prefix(const char *name, uint32_t category)
 	switch (category)
 	{
 	case CAT_guide:
+	case CAT_userformats:
 		if (!skip_prefix(name, "git", &new_name))
 			BUG("category #%d but no 'git' prefix?", category);
 		return new_name;
@@ -430,6 +432,16 @@ void list_guides_help(void)
 	putchar('\n');
 }
 
+void list_user_formats_help(void)
+{
+	struct category_description catdesc[] = {
+		{ CAT_userformats, N_("Git user-facing file formats:") },
+		{ 0, NULL }
+	};
+	print_cmd_by_category(catdesc, NULL);
+	putchar('\n');
+}
+
 static int get_alias(const char *var, const char *value, void *data)
 {
 	struct string_list *list = data;
diff --git a/help.h b/help.h
index 971a3ad855a..d8b744178ec 100644
--- a/help.h
+++ b/help.h
@@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num)
 void list_common_cmds_help(void);
 void list_all_cmds_help(int show_external_commands, int show_aliases);
 void list_guides_help(void);
+void list_user_formats_help(void);
 
 void list_all_main_cmds(struct string_list *list);
 void list_all_other_cmds(struct string_list *list);
diff --git a/t/t0012-help.sh b/t/t0012-help.sh
index 6c33a436901..91b5318aa32 100755
--- a/t/t0012-help.sh
+++ b/t/t0012-help.sh
@@ -44,6 +44,8 @@ test_expect_success 'invalid usage' '
 	test_expect_code 129 git help -g add &&
 	test_expect_code 129 git help -a -g &&
 
+	test_expect_code 129 git help --user-formats add &&
+
 	test_expect_code 129 git help -g -c &&
 	test_expect_code 129 git help --config-for-completion add &&
 	test_expect_code 129 git help --config-sections-for-completion add
@@ -104,9 +106,9 @@ test_expect_success 'git help' '
 	test_i18ngrep "^   commit " help.output &&
 	test_i18ngrep "^   fetch  " help.output
 '
+
 test_expect_success 'git help -g' '
 	git help -g >help.output &&
-	test_i18ngrep "^   attributes " help.output &&
 	test_i18ngrep "^   everyday   " help.output &&
 	test_i18ngrep "^   tutorial   " help.output
 '
@@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' '
 	test_cmp expect test-browser.log
 '
 
+test_expect_success 'git help --user-formats' '
+	git help --user-formats >help.output &&
+	grep "^   attributes   " help.output &&
+	grep "^   mailmap   " help.output
+'
+
 test_expect_success 'git help -c' '
 	git help -c >help.output &&
 	cat >expect <<-\EOF &&
@@ -220,6 +228,8 @@ test_expect_success "'git help -a' section spacing" '
 	Low-level Commands / Syncing Repositories
 
 	Low-level Commands / Internal Helpers
+
+	Git user-facing file formats
 	EOF
 	test_cmp expect actual
 '
-- 
2.37.1.1032.gb00b5447790


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v4 3/8] git docs: create a "Git file formats and protocols" section
  2022-07-18 13:29     ` [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
  2022-07-18 13:29       ` [PATCH v4 1/8] help.c: BUG() out if "help --guides" can't remove "git" prefixes Ævar Arnfjörð Bjarmason
  2022-07-18 13:29       ` [PATCH v4 2/8] git docs: split "User-facing file formats" off from "Guides" Ævar Arnfjörð Bjarmason
@ 2022-07-18 13:29       ` Ævar Arnfjörð Bjarmason
  2022-07-18 13:29       ` [PATCH v4 4/8] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
                         ` (6 subsequent siblings)
  9 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-18 13:29 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

Create a new "Git file formats and protocols" section in the main "git help
git" manual page and start moving the documentation that now lives in
"Documentation/technical/*.git" over to it. This compliments the newly
added and adjacent "User-facing file formats" section.

This makes the technical documentation more accessible and
discoverable. Before this we wouldn't install it by default, and had
no ability to build man page versions of them. The links to them from
our existing documentation link to the generated HTML version of these
docs.

So let's start moving those over, starting with just the
"bundle-format.txt" documentation added in 7378ec90e1c (doc: describe
Git bundle format, 2020-02-07). We'll now have a new
gitformat-bundle(5) man page. Subsequent commits will move more git
internal format documentation over.

Unfortunately the syntax of the current Documentation/technical/*.txt
is not the same (when it comes to section headings etc.) as our
Documentation/*.txt documentation, so change the relevant bits of
syntax as we're moving this over.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile                        |  3 +-
 Documentation/git-bundle.txt                  | 12 +++--
 Documentation/git-help.txt                    |  1 +
 Documentation/git.txt                         |  8 ++++
 ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++++---
 Documentation/lint-man-section-order.perl     |  3 ++
 builtin/help.c                                |  8 ++++
 command-list.txt                              |  5 +++
 help.c                                        | 12 +++++
 help.h                                        |  1 +
 t/t0012-help.sh                               |  2 +
 11 files changed, 87 insertions(+), 12 deletions(-)
 rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 08b896a3c4c..404139274e7 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -24,6 +24,7 @@ MAN1_TXT += gitweb.txt
 
 # man5 / man7 guides (note: new guides should also be added to command-list.txt)
 MAN5_TXT += gitattributes.txt
+MAN5_TXT += gitformat-bundle.txt
 MAN5_TXT += githooks.txt
 MAN5_TXT += gitignore.txt
 MAN5_TXT += gitmailmap.txt
@@ -95,7 +96,6 @@ TECH_DOCS += MyFirstObjectWalk
 TECH_DOCS += SubmittingPatches
 TECH_DOCS += ToolsForGit
 TECH_DOCS += technical/bitmap-format
-TECH_DOCS += technical/bundle-format
 TECH_DOCS += technical/cruft-packs
 TECH_DOCS += technical/hash-function-transition
 TECH_DOCS += technical/http-protocol
@@ -291,6 +291,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
 	cmds-synchelpers.txt \
 	cmds-guide.txt \
 	cmds-userformats.txt \
+	cmds-gitformats.txt \
 	cmds-purehelpers.txt \
 	cmds-foreignscminterface.txt
 
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 7685b570455..1aeae09f082 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -56,10 +56,9 @@ using "thin packs", bundles created using exclusions are smaller in
 size. That they're "thin" under the hood is merely noted here as a
 curiosity, and as a reference to other documentation.
 
-See link:technical/bundle-format.html[the `bundle-format`
-documentation] for more details and the discussion of "thin pack" in
-link:technical/pack-format.html[the pack format documentation] for
-further details.
+See linkgit:gitformat-bundle[5] for more details and the discussion of
+"thin pack" in link:technical/pack-format.html[the pack format
+documentation] for further details.
 
 OPTIONS
 -------
@@ -337,6 +336,11 @@ You can also see what references it offers:
 $ git ls-remote mybundle
 ----------------
 
+FILE FORMAT
+-----------
+
+See linkgit:gitformat-bundle[5].
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index 6c285709040..a91126ba802 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -13,6 +13,7 @@ SYNOPSIS
 'git help' [-g|--guides]
 'git help' [-c|--config]
 'git help' [--user-formats]
+'git help' [--git-formats]
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 9b03bbc3851..1980a0e29cd 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -347,6 +347,14 @@ edit. These can also be listed with 'git help --user-formats'.
 
 include::cmds-userformats.txt[]
 
+Git file formats and protocols
+------------------------------
+
+This documentation discusses the file formats and protocols that git
+itself uses. These can also be listed with 'git help --git-formats'.
+
+include::cmds-gitformats.txt[]
+
 Configuration Mechanism
 -----------------------
 
diff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt
similarity index 79%
rename from Documentation/technical/bundle-format.txt
rename to Documentation/gitformat-bundle.txt
index b9be8644cf5..6a9d9e5bf6f 100644
--- a/Documentation/technical/bundle-format.txt
+++ b/Documentation/gitformat-bundle.txt
@@ -1,11 +1,33 @@
-= Git bundle v2 format
+gitformat-bundle(5)
+===================
 
-The Git bundle format is a format that represents both refs and Git objects.
+NAME
+----
+gitformat-bundle - The bundle file format
+
+
+SYNOPSIS
+--------
+[verse]
+*.bundle
+*.bdl
+
+DESCRIPTION
+-----------
+
+The Git bundle format is a format that represents both refs and Git
+objects. A bundle is a header in a format similar to
+linkgit:git-show-ref[1] followed by a pack in *.pack format.
 
-== Format
+The format is created and read by the linkgit:git-bundle[1] command,
+and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1].
+
+
+FORMAT
+------
 
 We will use ABNF notation to define the Git bundle format. See
-protocol-common.txt for the details.
+link:technical/protocol-common.html for the details.
 
 A v2 bundle looks like this:
 
@@ -36,7 +58,9 @@ value        = *(%01-09 / %0b-FF)
 pack         = ... ; packfile
 ----
 
-== Semantics
+
+SEMANTICS
+---------
 
 A Git bundle consists of several parts.
 
@@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id.
 This is a comment and it has no specific meaning. The writer of the bundle MAY
 put any string here. The reader of the bundle MUST ignore the comment.
 
-=== Note on the shallow clone and a Git bundle
+Note on the shallow clone and a Git bundle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Note that the prerequisites does not represent a shallow-clone boundary. The
 semantics of the prerequisites and the shallow-clone boundaries are different,
 and the Git bundle v2 format cannot represent a shallow clone repository.
 
-== Capabilities
+CAPABILITIES
+------------
 
 Because there is no opportunity for negotiation, unknown capabilities cause 'git
 bundle' to abort.
@@ -79,3 +105,7 @@ bundle' to abort.
 * `filter` specifies an object filter as in the `--filter` option in
   linkgit:git-rev-list[1]. The resulting pack-file must be marked as a
   `.promisor` pack-file after it is unbundled.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
index 425377dfeb7..02408a0062f 100755
--- a/Documentation/lint-man-section-order.perl
+++ b/Documentation/lint-man-section-order.perl
@@ -32,6 +32,9 @@
 		'SEE ALSO' => {
 			order => $order++,
 		},
+		'FILE FORMAT' => {
+			order => $order++,
+		},
 		'GIT' => {
 			required => 1,
 			order => $order++,
diff --git a/builtin/help.c b/builtin/help.c
index b0164b774c2..3ff2c5d17a7 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -44,6 +44,7 @@ static enum help_action {
 	HELP_ACTION_GUIDES,
 	HELP_ACTION_CONFIG,
 	HELP_ACTION_USER_FORMATS,
+	HELP_ACTION_GIT_FORMATS,
 	HELP_ACTION_CONFIG_FOR_COMPLETION,
 	HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
 } cmd_mode;
@@ -72,6 +73,8 @@ static struct option builtin_help_options[] = {
 		    HELP_ACTION_GUIDES),
 	OPT_CMDMODE(0, "user-formats", &cmd_mode, N_("print list of user-facing file formats"),
 		    HELP_ACTION_USER_FORMATS),
+	OPT_CMDMODE(0, "git-formats", &cmd_mode, N_("print list of internal file formats and network protocols"),
+		    HELP_ACTION_GIT_FORMATS),
 	OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
 		    HELP_ACTION_CONFIG),
 	OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
@@ -88,6 +91,7 @@ static const char * const builtin_help_usage[] = {
 	"git help [-g|--guides]",
 	"git help [-c|--config]",
 	"git help [--user-formats]",
+	"git help [--git-formats]",
 	NULL
 };
 
@@ -662,6 +666,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		opt_mode_usage(argc, "--user-formats", help_format);
 		list_user_formats_help();
 		return 0;
+	case HELP_ACTION_GIT_FORMATS:
+		opt_mode_usage(argc, "--git-formats", help_format);
+		list_git_formats_help();
+		return 0;
 	case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
 		opt_mode_usage(argc, "--config-sections-for-completion",
 			       help_format);
diff --git a/command-list.txt b/command-list.txt
index c1eace8f7ad..1794a7279bc 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -47,6 +47,10 @@
 # .mailmap etc. files lives in man section 5. These entries can only
 # have the "userformats" attribute and nothing else.
 #
+# Git internal file formats and protocols, such as documentation for the
+# *.bundle format lives in man section 5. These entries can only have
+# the "gitformats" attribute and nothing else.
+#
 ### command list (do not change this line)
 # command name                          category [category] [category]
 git-add                                 mainporcelain           worktree
@@ -204,6 +208,7 @@ gitcvs-migration                        guide
 gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
+gitformat-bundle                        gitformats
 gitglossary                             guide
 githooks                                userformats
 gitignore                               userformats
diff --git a/help.c b/help.c
index 17ba210cf4e..68b1dc70aff 100644
--- a/help.c
+++ b/help.c
@@ -39,6 +39,7 @@ static struct category_description main_categories[] = {
 	{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
 	{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
 	{ CAT_userformats, N_("Git user-facing file formats") },
+	{ CAT_gitformats, N_("Git internal file formats and protocols") },
 	{ 0, NULL }
 };
 
@@ -52,6 +53,7 @@ static const char *drop_prefix(const char *name, uint32_t category)
 	{
 	case CAT_guide:
 	case CAT_userformats:
+	case CAT_gitformats:
 		if (!skip_prefix(name, "git", &new_name))
 			BUG("category #%d but no 'git' prefix?", category);
 		return new_name;
@@ -442,6 +444,16 @@ void list_user_formats_help(void)
 	putchar('\n');
 }
 
+void list_git_formats_help(void)
+{
+	struct category_description catdesc[] = {
+		{ CAT_gitformats, N_("Internal file formats and protocols:") },
+		{ 0, NULL }
+	};
+	print_cmd_by_category(catdesc, NULL);
+	putchar('\n');
+}
+
 static int get_alias(const char *var, const char *value, void *data)
 {
 	struct string_list *list = data;
diff --git a/help.h b/help.h
index d8b744178ec..173bd890ce3 100644
--- a/help.h
+++ b/help.h
@@ -23,6 +23,7 @@ void list_common_cmds_help(void);
 void list_all_cmds_help(int show_external_commands, int show_aliases);
 void list_guides_help(void);
 void list_user_formats_help(void);
+void list_git_formats_help(void);
 
 void list_all_main_cmds(struct string_list *list);
 void list_all_other_cmds(struct string_list *list);
diff --git a/t/t0012-help.sh b/t/t0012-help.sh
index 91b5318aa32..0e291cb91e8 100755
--- a/t/t0012-help.sh
+++ b/t/t0012-help.sh
@@ -230,6 +230,8 @@ test_expect_success "'git help -a' section spacing" '
 	Low-level Commands / Internal Helpers
 
 	Git user-facing file formats
+
+	Git internal file formats and protocols
 	EOF
 	test_cmp expect actual
 '
-- 
2.37.1.1032.gb00b5447790


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v4 4/8] docs: move commit-graph format docs to man section 5
  2022-07-18 13:29     ` [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
                         ` (2 preceding siblings ...)
  2022-07-18 13:29       ` [PATCH v4 3/8] git docs: create a "Git file formats and protocols" section Ævar Arnfjörð Bjarmason
@ 2022-07-18 13:29       ` Ævar Arnfjörð Bjarmason
  2022-07-18 13:29       ` [PATCH v4 5/8] docs: move protocol-related " Ævar Arnfjörð Bjarmason
                         ` (5 subsequent siblings)
  9 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-18 13:29 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

Continue the move of existing Documentation/technical/* protocol and
file-format documentation into our main documentation space.

By moving the documentation for the commit-graph format into man
section 5 and the new "gitformats" category. This change is split from
subsequent commits due to the relatively large amount of ASCIIDOC
formatting changes that are required.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile                        |  1 +
 Documentation/git-commit-graph.txt            |  5 ++
 ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------
 Documentation/technical/chunk-format.txt      |  4 +-
 command-list.txt                              |  1 +
 5 files changed, 41 insertions(+), 17 deletions(-)
 rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (88%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 404139274e7..cc6870cce41 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -25,6 +25,7 @@ MAN1_TXT += gitweb.txt
 # man5 / man7 guides (note: new guides should also be added to command-list.txt)
 MAN5_TXT += gitattributes.txt
 MAN5_TXT += gitformat-bundle.txt
+MAN5_TXT += gitformat-commit-graph.txt
 MAN5_TXT += githooks.txt
 MAN5_TXT += gitignore.txt
 MAN5_TXT += gitmailmap.txt
diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
index e1f48c95b3c..047decdb65b 100644
--- a/Documentation/git-commit-graph.txt
+++ b/Documentation/git-commit-graph.txt
@@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append
 ------------------------------------------------
 
 
+FILE FORMAT
+-----------
+
+see linkgit:gitformat-commit-graph[5].
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt
similarity index 88%
rename from Documentation/technical/commit-graph-format.txt
rename to Documentation/gitformat-commit-graph.txt
index 484b185ba98..108dc2295c0 100644
--- a/Documentation/technical/commit-graph-format.txt
+++ b/Documentation/gitformat-commit-graph.txt
@@ -1,5 +1,18 @@
-Git commit graph format
-=======================
+gitformat-commit-graph(5)
+=========================
+
+NAME
+----
+gitformat-commit-graph - Git commit graph format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/info/commit-graph
+$GIT_DIR/objects/info/commit-graphs/*
+
+DESCRIPTION
+-----------
 
 The Git commit graph stores a list of commit OIDs and some associated
 metadata, including:
@@ -30,7 +43,7 @@ and hash type.
 
 All multi-byte numbers are in network byte order.
 
-HEADER:
+=== HEADER:
 
   4-byte signature:
       The signature is: {'C', 'G', 'P', 'H'}
@@ -52,7 +65,7 @@ HEADER:
       We infer the length (H*B) of the Base Graphs chunk
       from this value.
 
-CHUNK LOOKUP:
+=== CHUNK LOOKUP:
 
   (C + 1) * 12 bytes listing the table of contents for the chunks:
       First 4 bytes describe the chunk id. Value 0 is a terminating label.
@@ -68,17 +81,17 @@ CHUNK LOOKUP:
   these chunks may be given in any order. Chunks are required unless
   otherwise specified.
 
-CHUNK DATA:
+=== CHUNK DATA:
 
-  OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)
+==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)
       The ith entry, F[i], stores the number of OIDs with first
       byte at most i. Thus F[255] stores the total
       number of commits (N).
 
-  OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)
+====  OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)
       The OIDs for all commits in the graph, sorted in ascending order.
 
-  Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)
+====  Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)
     * The first H bytes are for the OID of the root tree.
     * The next 8 bytes are for the positions of the first two parents
       of the ith commit. Stores value 0x70000000 if no parent in that
@@ -93,7 +106,7 @@ CHUNK DATA:
       2 bits of the lowest byte, storing the 33rd and 34th bit of the
       commit time.
 
-  Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]
+==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]
     * This list of 4-byte values store corrected commit date offsets for the
       commits, arranged in the same order as commit data chunk.
     * If the corrected commit date offset cannot be stored within 31 bits,
@@ -104,7 +117,7 @@ CHUNK DATA:
       by compatible versions of Git and in case of split commit-graph chains,
       the topmost layer also has Generation Data chunk.
 
-  Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]
+==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]
     * This list of 8-byte values stores the corrected commit date offsets
       for commits with corrected commit date offsets that cannot be
       stored within 31 bits.
@@ -112,7 +125,7 @@ CHUNK DATA:
       chunk is present and atleast one corrected commit date offset cannot
       be stored within 31 bits.
 
-  Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]
+==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]
       This list of 4-byte values store the second through nth parents for
       all octopus merges. The second parent value in the commit data stores
       an array position within this list along with the most-significant bit
@@ -120,14 +133,14 @@ CHUNK DATA:
       positions for the parents until reaching a value with the most-significant
       bit on. The other bits correspond to the position of the last parent.
 
-  Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]
+==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]
     * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters
       from commit 0 to commit i (inclusive) in lexicographic order. The Bloom
       filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header
       length), where BIDX[-1] is 0.
     * The BIDX chunk is ignored if the BDAT chunk is not present.
 
-  Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]
+==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]
     * It starts with header consisting of three unsigned 32-bit integers:
       - Version of the hash algorithm being used. We currently only support
 	value 1 which corresponds to the 32-bit version of the murmur3 hash
@@ -147,13 +160,13 @@ CHUNK DATA:
       of length one, with either all bits set to zero or one respectively.
     * The BDAT chunk is present if and only if BIDX is present.
 
-  Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]
+==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]
       This list of H-byte hashes describe a set of B commit-graph files that
       form a commit-graph chain. The graph position for the ith commit in this
       file's OID Lookup chunk is equal to i plus the number of commits in all
       base graphs.  If B is non-zero, this chunk must exist.
 
-TRAILER:
+=== TRAILER:
 
 	H-byte HASH-checksum of all of the above.
 
@@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote
 possibly erroneous data in these chunks with the IDs "GDAT" and "GDOV". By
 changing the IDs, newer versions of Git will silently ignore those older
 chunks and write the new information without trusting the incorrect data.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/chunk-format.txt b/Documentation/technical/chunk-format.txt
index 593614fceda..f36ce42f37c 100644
--- a/Documentation/technical/chunk-format.txt
+++ b/Documentation/technical/chunk-format.txt
@@ -6,7 +6,7 @@ sections of the file. This allows structured access to a large file by
 scanning a small "table of contents" for the remaining data. This common
 format is used by the `commit-graph` and `multi-pack-index` files. See
 link:technical/pack-format.html[the `multi-pack-index` format] and
-link:technical/commit-graph-format.html[the `commit-graph` format] for
+the `commit-graph` format in linkgit:gitformat-commit-graph[5] for
 how they use the chunks to describe structured data.
 
 A chunk-based file format begins with some header information custom to
@@ -108,7 +108,7 @@ for future formats:
 * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()`
   in `commit-graph.c` for how the chunk-format API is used to write and
   parse the commit-graph file format documented in
-  link:technical/commit-graph-format.html[the commit-graph file format].
+  the commit-graph file format in linkgit:gitformat-commit-graph[5].
 
 * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`
   in `midx.c` for how the chunk-format API is used to write and
diff --git a/command-list.txt b/command-list.txt
index 1794a7279bc..66e6a0ba217 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -209,6 +209,7 @@ gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
 gitformat-bundle                        gitformats
+gitformat-commit-graph                  gitformats
 gitglossary                             guide
 githooks                                userformats
 gitignore                               userformats
-- 
2.37.1.1032.gb00b5447790


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v4 5/8] docs: move protocol-related docs to man section 5
  2022-07-18 13:29     ` [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
                         ` (3 preceding siblings ...)
  2022-07-18 13:29       ` [PATCH v4 4/8] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
@ 2022-07-18 13:29       ` Ævar Arnfjörð Bjarmason
  2022-07-18 13:29       ` [PATCH v4 6/8] docs: move pack format " Ævar Arnfjörð Bjarmason
                         ` (4 subsequent siblings)
  9 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-18 13:29 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

Continue the move of existing Documentation/technical/* protocol and
file-format documentation into our main documentation space. By moving
the things that discuss the protocol we can properly link from
e.g. lsrefs.unborn and protocol.version documentation to a manpage we
build by default.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile                        |  8 +++---
 Documentation/config/lsrefs.txt               |  2 +-
 Documentation/config/protocol.txt             |  2 +-
 Documentation/git-upload-pack.txt             |  5 ++--
 Documentation/gitformat-bundle.txt            |  2 +-
 ...otocol.txt => gitformat-pack-protocol.txt} | 22 +++++++++++++--
 ...xt => gitformat-protocol-capabilities.txt} | 28 +++++++++++++++----
 ...mmon.txt => gitformat-protocol-common.txt} | 23 +++++++++++++--
 ...tocol-v2.txt => gitformat-protocol-v2.txt} | 24 +++++++++++++---
 Documentation/technical/api-simple-ipc.txt    |  2 +-
 Documentation/technical/http-protocol.txt     |  6 ++--
 .../long-running-process-protocol.txt         |  2 +-
 Documentation/technical/partial-clone.txt     |  2 +-
 command-list.txt                              |  4 +++
 t/t5551-http-fetch-smart.sh                   |  4 +--
 15 files changed, 103 insertions(+), 33 deletions(-)
 rename Documentation/{technical/pack-protocol.txt => gitformat-pack-protocol.txt} (98%)
 rename Documentation/{technical/protocol-capabilities.txt => gitformat-protocol-capabilities.txt} (96%)
 rename Documentation/{technical/protocol-common.txt => gitformat-protocol-common.txt} (88%)
 rename Documentation/{technical/protocol-v2.txt => gitformat-protocol-v2.txt} (98%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index cc6870cce41..adc1404d380 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -26,6 +26,10 @@ MAN1_TXT += gitweb.txt
 MAN5_TXT += gitattributes.txt
 MAN5_TXT += gitformat-bundle.txt
 MAN5_TXT += gitformat-commit-graph.txt
+MAN5_TXT += gitformat-pack-protocol.txt
+MAN5_TXT += gitformat-protocol-capabilities.txt
+MAN5_TXT += gitformat-protocol-common.txt
+MAN5_TXT += gitformat-protocol-v2.txt
 MAN5_TXT += githooks.txt
 MAN5_TXT += gitignore.txt
 MAN5_TXT += gitmailmap.txt
@@ -105,12 +109,8 @@ TECH_DOCS += technical/long-running-process-protocol
 TECH_DOCS += technical/multi-pack-index
 TECH_DOCS += technical/pack-format
 TECH_DOCS += technical/pack-heuristics
-TECH_DOCS += technical/pack-protocol
 TECH_DOCS += technical/parallel-checkout
 TECH_DOCS += technical/partial-clone
-TECH_DOCS += technical/protocol-capabilities
-TECH_DOCS += technical/protocol-common
-TECH_DOCS += technical/protocol-v2
 TECH_DOCS += technical/racy-git
 TECH_DOCS += technical/reftable
 TECH_DOCS += technical/send-pack-pipeline
diff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.txt
index adeda0f24d3..e9efe498c01 100644
--- a/Documentation/config/lsrefs.txt
+++ b/Documentation/config/lsrefs.txt
@@ -1,7 +1,7 @@
 lsrefs.unborn::
 	May be "advertise" (the default), "allow", or "ignore". If "advertise",
 	the server will respond to the client sending "unborn" (as described in
-	protocol-v2.txt) and will advertise support for this feature during the
+	linkgit:gitformat-protocol-v2[5]) and will advertise support for this feature during the
 	protocol v2 capability advertisement. "allow" is the same as
 	"advertise" except that the server will not advertise support for this
 	feature; this is useful for load-balanced servers that cannot be
diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt
index 756591d77b0..bf18a70a924 100644
--- a/Documentation/config/protocol.txt
+++ b/Documentation/config/protocol.txt
@@ -58,6 +58,6 @@ protocol.version::
 * `1` - the original wire protocol with the addition of a version string
   in the initial response from the server.
 
-* `2` - link:technical/protocol-v2.html[wire protocol version 2].
+* `2` - Wire protocol version 2, see linkgit:gitformat-protocol-v2[5].
 
 --
diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt
index 8f87b23ea86..754619222f6 100644
--- a/Documentation/git-upload-pack.txt
+++ b/Documentation/git-upload-pack.txt
@@ -40,9 +40,8 @@ OPTIONS
 	Used by linkgit:git-http-backend[1] to serve up
 	`$GIT_URL/info/refs?service=git-upload-pack` requests. See
 	"Smart Clients" in link:technical/http-protocol.html[the HTTP
-	transfer protocols] documentation and "HTTP Transport" in
-	link:technical/protocol-v2.html[the Git Wire Protocol, Version
-	2] documentation. Also understood by
+	transfer protocols] documentation and "HTTP Transport" in the
+	linkgit:gitformat-protocol-v2[5] documentation. Also understood by
 	linkgit:git-receive-pack[1].
 
 <directory>::
diff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.txt
index 6a9d9e5bf6f..3d60d9067e4 100644
--- a/Documentation/gitformat-bundle.txt
+++ b/Documentation/gitformat-bundle.txt
@@ -27,7 +27,7 @@ FORMAT
 ------
 
 We will use ABNF notation to define the Git bundle format. See
-link:technical/protocol-common.html for the details.
+linkgit:gitformat-protocol-common[5] for the details.
 
 A v2 bundle looks like this:
 
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt
similarity index 98%
rename from Documentation/technical/pack-protocol.txt
rename to Documentation/gitformat-pack-protocol.txt
index e13a2c064d1..b665af5b690 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/gitformat-pack-protocol.txt
@@ -1,5 +1,17 @@
-Packfile transfer protocols
-===========================
+gitformat-pack-protocol(5)
+==========================
+
+NAME
+----
+gitformat-pack-protocol - How packs are transferred over-the-wire
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
 
 Git supports transferring data in packfiles over the ssh://, git://, http:// and
 file:// transports.  There exist two sets of protocols, one for pushing
@@ -18,7 +30,7 @@ pkt-line Format
 ---------------
 
 The descriptions below build on the pkt-line format described in
-protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless
+linkgit:gitformat-protocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless
 otherwise noted the usual pkt-line LF rules apply: the sender SHOULD
 include a LF, but the receiver MUST NOT complain if it is not present.
 
@@ -707,3 +719,7 @@ An example client/server communication might look like this:
    S: 0018ok refs/heads/debug\n
    S: 002ang refs/heads/master non-fast-forward\n
 ----
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/gitformat-protocol-capabilities.txt
similarity index 96%
rename from Documentation/technical/protocol-capabilities.txt
rename to Documentation/gitformat-protocol-capabilities.txt
index 9dfade930da..2e89f40ddb1 100644
--- a/Documentation/technical/protocol-capabilities.txt
+++ b/Documentation/gitformat-protocol-capabilities.txt
@@ -1,8 +1,20 @@
-Git Protocol Capabilities
-=========================
+gitformat-protocol-capabilities(5)
+==================================
+
+NAME
+----
+gitformat-protocol-capabilities - Protocol v0 and v1 capabilities
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
 
 NOTE: this document describes capabilities for versions 0 and 1 of the pack
-protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]
+protocol. For version 2, please refer to the linkgit:gitformat-protocol-v2[5]
 doc.
 
 Servers SHOULD support all capabilities defined in this document.
@@ -77,7 +89,7 @@ interleaved with S-R-Q.
 multi_ack_detailed
 ------------------
 This is an extension of multi_ack that permits client to better
-understand the server's in-memory state. See pack-protocol.txt,
+understand the server's in-memory state. See linkgit:gitformat-pack-protocol[5],
 section "Packfile Negotiation" for more information.
 
 no-done
@@ -281,7 +293,7 @@ a packfile upload and reference update.  If the pushing client requests
 this capability, after unpacking and updating references the server
 will respond with whether the packfile unpacked successfully and if
 each reference was updated successfully.  If any of those were not
-successful, it will send back an error message.  See pack-protocol.txt
+successful, it will send back an error message.  See linkgit:gitformat-pack-protocol[5]
 for example messages.
 
 report-status-v2
@@ -292,7 +304,7 @@ adding new "option" directives in order to support reference rewritten by
 the "proc-receive" hook.  The "proc-receive" hook may handle a command
 for a pseudo-reference which may create or update a reference with
 different name, new-oid, and old-oid.  While the capability
-'report-status' cannot report for such case.  See pack-protocol.txt
+'report-status' cannot report for such case.  See linkgit:gitformat-pack-protocol[5]
 for details.
 
 delete-refs
@@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The
 current implementation uses trace2 session IDs (see
 link:api-trace2.html[api-trace2] for details), but this may change and users of
 the session ID should not rely on this fact.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/protocol-common.txt b/Documentation/gitformat-protocol-common.txt
similarity index 88%
rename from Documentation/technical/protocol-common.txt
rename to Documentation/gitformat-protocol-common.txt
index ecedb34bba5..6e1e1624e2d 100644
--- a/Documentation/technical/protocol-common.txt
+++ b/Documentation/gitformat-protocol-common.txt
@@ -1,5 +1,20 @@
-Documentation Common to Pack and Http Protocols
-===============================================
+gitformat-protocol-common(5)
+============================
+
+NAME
+----
+gitformat-protocol-common - Things common to various protocols
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
+
+This document sets defines things common to various over-the-wire
+protocols and file formats used in Git.
 
 ABNF Notation
 -------------
@@ -97,3 +112,7 @@ Examples (as C-style strings):
   "000bfoobar\n"    "foobar\n"
   "0004"            ""
 ----
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/gitformat-protocol-v2.txt
similarity index 98%
rename from Documentation/technical/protocol-v2.txt
rename to Documentation/gitformat-protocol-v2.txt
index 8a877d27e23..ae4fcc84e37 100644
--- a/Documentation/technical/protocol-v2.txt
+++ b/Documentation/gitformat-protocol-v2.txt
@@ -1,5 +1,17 @@
-Git Wire Protocol, Version 2
-============================
+gitformat-protocol-v2(5)
+========================
+
+NAME
+----
+gitformat-protocol-v2 - Git Wire Protocol, Version 2
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
 
 This document presents a specification for a version 2 of Git's wire
 protocol.  Protocol v2 will improve upon v1 in the following ways:
@@ -26,7 +38,7 @@ Packet-Line Framing
 -------------------
 
 All communication is done using packet-line framing, just as in v1.  See
-`Documentation/technical/pack-protocol.txt` and
+linkgit:gitformat-pack-protocol[5] and
 `Documentation/technical/protocol-common.txt` for more information.
 
 In protocol v2 these special packets will have the following semantics:
@@ -42,7 +54,7 @@ Initial Client Request
 In general a client can request to speak protocol v2 by sending
 `version=2` through the respective side-channel for the transport being
 used which inevitably sets `GIT_PROTOCOL`.  More information can be
-found in `pack-protocol.txt` and `http-protocol.txt`, as well as the
+found in linkgit:gitformat-pack-protocol[5] and `http-protocol.txt`, as well as the
 `GIT_PROTOCOL` definition in `git.txt`. In all cases the
 response from the server is the capability advertisement.
 
@@ -566,3 +578,7 @@ and associated requested information, each separated by a single space.
 	attr = "size"
 
 	obj-info = obj-id SP obj-size
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt
index d79ad323e67..945c21bbc38 100644
--- a/Documentation/technical/api-simple-ipc.txt
+++ b/Documentation/technical/api-simple-ipc.txt
@@ -78,7 +78,7 @@ client and an optional response message from the server.  Both the
 client and server messages are unlimited in length and are terminated
 with a flush packet.
 
-The pkt-line routines (Documentation/technical/protocol-common.txt)
+The pkt-line routines (linkgit:gitformat-protocol-common[5])
 are used to simplify buffer management during message generation,
 transmission, and reception.  A flush packet is used to mark the end
 of the message.  This allows the sender to incrementally generate and
diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
index cc5126cfeda..9d9c7acd512 100644
--- a/Documentation/technical/http-protocol.txt
+++ b/Documentation/technical/http-protocol.txt
@@ -222,7 +222,7 @@ smart server reply:
    S: 0000
 
 The client may send Extra Parameters (see
-Documentation/technical/pack-protocol.txt) as a colon-separated string
+linkgit:gitformat-pack-protocol[5]) as a colon-separated string
 in the Git-Protocol HTTP header.
 
 Uses the `--http-backend-info-refs` option to
@@ -518,5 +518,5 @@ References
 
 http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
 http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
-link:technical/pack-protocol.html
-link:technical/protocol-capabilities.html
+linkgit:gitformat-pack-protocol[5]
+linkgit:gitformat-protocol-capabilities[5]
diff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt
index aa0aa9af1c2..c6922ce6ccc 100644
--- a/Documentation/technical/long-running-process-protocol.txt
+++ b/Documentation/technical/long-running-process-protocol.txt
@@ -3,7 +3,7 @@ Long-running process protocol
 
 This protocol is used when Git needs to communicate with an external
 process throughout the entire life of a single Git command. All
-communication is in pkt-line format (see technical/protocol-common.txt)
+communication is in pkt-line format (see linkgit:gitformat-protocol-common[5])
 over standard input and standard output.
 
 Handshake
diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt
index 99f0eb30406..9d5199d5c6c 100644
--- a/Documentation/technical/partial-clone.txt
+++ b/Documentation/technical/partial-clone.txt
@@ -79,7 +79,7 @@ Design Details
   upload-pack negotiation.
 +
 This uses the existing capability discovery mechanism.
-See "filter" in Documentation/technical/pack-protocol.txt.
+See "filter" in linkgit:gitformat-pack-protocol[5].
 
 - Clients pass a "filter-spec" to clone and fetch which is passed to the
   server to request filtering during packfile construction.
diff --git a/command-list.txt b/command-list.txt
index 66e6a0ba217..bec0fa690aa 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -210,6 +210,10 @@ giteveryday                             guide
 gitfaq                                  guide
 gitformat-bundle                        gitformats
 gitformat-commit-graph                  gitformats
+gitformat-pack-protocol                 gitformats
+gitformat-protocol-capabilities         gitformats
+gitformat-protocol-common               gitformats
+gitformat-protocol-v2                   gitformats
 gitglossary                             guide
 githooks                                userformats
 gitignore                               userformats
diff --git a/t/t5551-http-fetch-smart.sh b/t/t5551-http-fetch-smart.sh
index b9351a732f6..d17f77dda6f 100755
--- a/t/t5551-http-fetch-smart.sh
+++ b/t/t5551-http-fetch-smart.sh
@@ -175,8 +175,8 @@ test_expect_success 'no-op half-auth fetch does not require a password' '
 	# This is not possible with protocol v2, since both objects and refs
 	# are obtained from the "git-upload-pack" path. A solution to this is
 	# to teach the server and client to be able to inline ls-refs requests
-	# as an Extra Parameter (see pack-protocol.txt), so that "info/refs"
-	# can serve refs, just like it does in protocol v0.
+	# as an Extra Parameter (see "git help gitformat-pack-protocol"), so that
+	# "info/refs" can serve refs, just like it does in protocol v0.
 	GIT_TEST_PROTOCOL_VERSION=0 git --git-dir=half-auth fetch &&
 	expect_askpass none
 '
-- 
2.37.1.1032.gb00b5447790


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v4 6/8] docs: move pack format docs to man section 5
  2022-07-18 13:29     ` [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
                         ` (4 preceding siblings ...)
  2022-07-18 13:29       ` [PATCH v4 5/8] docs: move protocol-related " Ævar Arnfjörð Bjarmason
@ 2022-07-18 13:29       ` Ævar Arnfjörð Bjarmason
  2022-07-18 13:29       ` [PATCH v4 7/8] docs: move http-protocol " Ævar Arnfjörð Bjarmason
                         ` (3 subsequent siblings)
  9 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-18 13:29 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 Documentation/Makefile                        |  9 ++---
 Documentation/config/pack.txt                 |  2 +-
 Documentation/git-bundle.txt                  |  3 +-
 Documentation/git-multi-pack-index.txt        |  4 +--
 .../chunk-format.txt => gitformat-chunk.txt}  | 27 ++++++++++++---
 Documentation/gitformat-commit-graph.txt      |  2 +-
 .../index-format.txt => gitformat-index.txt}  | 22 ++++++++++--
 ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++++--
 Documentation/gitformat-pack-protocol.txt     |  2 +-
 .../pack-format.txt => gitformat-pack.txt}    | 34 +++++++++++++++++--
 ...ure-format.txt => gitformat-signature.txt} | 21 ++++++++++--
 .../howto/recover-corrupted-object-harder.txt |  2 +-
 .../technical/hash-function-transition.txt    |  2 +-
 Documentation/user-manual.txt                 |  2 +-
 cache.h                                       |  3 +-
 command-list.txt                              |  5 +++
 pack-revindex.h                               |  2 +-
 17 files changed, 132 insertions(+), 32 deletions(-)
 rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (90%)
 rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)
 rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%)
 rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)
 rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index adc1404d380..b4d2361dfc7 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -25,11 +25,16 @@ MAN1_TXT += gitweb.txt
 # man5 / man7 guides (note: new guides should also be added to command-list.txt)
 MAN5_TXT += gitattributes.txt
 MAN5_TXT += gitformat-bundle.txt
+MAN5_TXT += gitformat-chunk.txt
 MAN5_TXT += gitformat-commit-graph.txt
+MAN5_TXT += gitformat-index.txt
+MAN5_TXT += gitformat-pack-cruft.txt
 MAN5_TXT += gitformat-pack-protocol.txt
+MAN5_TXT += gitformat-pack.txt
 MAN5_TXT += gitformat-protocol-capabilities.txt
 MAN5_TXT += gitformat-protocol-common.txt
 MAN5_TXT += gitformat-protocol-v2.txt
+MAN5_TXT += gitformat-signature.txt
 MAN5_TXT += githooks.txt
 MAN5_TXT += gitignore.txt
 MAN5_TXT += gitmailmap.txt
@@ -101,13 +106,10 @@ TECH_DOCS += MyFirstObjectWalk
 TECH_DOCS += SubmittingPatches
 TECH_DOCS += ToolsForGit
 TECH_DOCS += technical/bitmap-format
-TECH_DOCS += technical/cruft-packs
 TECH_DOCS += technical/hash-function-transition
 TECH_DOCS += technical/http-protocol
-TECH_DOCS += technical/index-format
 TECH_DOCS += technical/long-running-process-protocol
 TECH_DOCS += technical/multi-pack-index
-TECH_DOCS += technical/pack-format
 TECH_DOCS += technical/pack-heuristics
 TECH_DOCS += technical/parallel-checkout
 TECH_DOCS += technical/partial-clone
@@ -115,7 +117,6 @@ TECH_DOCS += technical/racy-git
 TECH_DOCS += technical/reftable
 TECH_DOCS += technical/send-pack-pipeline
 TECH_DOCS += technical/shallow
-TECH_DOCS += technical/signature-format
 TECH_DOCS += technical/trivial-merge
 SP_ARTICLES += $(TECH_DOCS)
 SP_ARTICLES += technical/api-index
diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt
index ad7f73a1ead..3e581eab84a 100644
--- a/Documentation/config/pack.txt
+++ b/Documentation/config/pack.txt
@@ -166,7 +166,7 @@ permuted into their appropriate location when writing a new bitmap.
 
 pack.writeReverseIndex::
 	When true, git will write a corresponding .rev file (see:
-	link:../technical/pack-format.html[Documentation/technical/pack-format.txt])
+	linkgit:gitformat-pack[5])
 	for each new packfile that it writes in all places except for
 	linkgit:git-fast-import[1] and in the bulk checkin mechanism.
 	Defaults to false.
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 1aeae09f082..4c6c41e1a09 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -57,8 +57,7 @@ size. That they're "thin" under the hood is merely noted here as a
 curiosity, and as a reference to other documentation.
 
 See linkgit:gitformat-bundle[5] for more details and the discussion of
-"thin pack" in link:technical/pack-format.html[the pack format
-documentation] for further details.
+"thin pack" in linkgit:gitformat-pack[5] for further details.
 
 OPTIONS
 -------
diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt
index c588fb91af1..a48c3d5ea63 100644
--- a/Documentation/git-multi-pack-index.txt
+++ b/Documentation/git-multi-pack-index.txt
@@ -128,8 +128,8 @@ $ git multi-pack-index verify
 SEE ALSO
 --------
 See link:technical/multi-pack-index.html[The Multi-Pack-Index Design
-Document] and link:technical/pack-format.html[The Multi-Pack-Index
-Format] for more information on the multi-pack-index feature.
+Document] and linkgit:gitformat-pack[5] for more information on the
+multi-pack-index feature and its file format.
 
 
 GIT
diff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt
similarity index 90%
rename from Documentation/technical/chunk-format.txt
rename to Documentation/gitformat-chunk.txt
index f36ce42f37c..784c5d987de 100644
--- a/Documentation/technical/chunk-format.txt
+++ b/Documentation/gitformat-chunk.txt
@@ -1,12 +1,25 @@
-Chunk-based file formats
-========================
+gitformat-chunk(5)
+==================
+
+NAME
+----
+gitformat-chunk - Chunk-based file formats
+
+SYNOPSIS
+--------
+
+Used by linkgit:gitformat-commit-graph[5] and the "MIDX" format (see
+the pack format documentation in linkgit:gitformat-pack[5]).
+
+DESCRIPTION
+-----------
 
 Some file formats in Git use a common concept of "chunks" to describe
 sections of the file. This allows structured access to a large file by
 scanning a small "table of contents" for the remaining data. This common
 format is used by the `commit-graph` and `multi-pack-index` files. See
-link:technical/pack-format.html[the `multi-pack-index` format] and
-the `commit-graph` format in linkgit:gitformat-commit-graph[5] for
+the `multi-pack-index` format in linkgit:gitformat-pack[5] and
+link:technical/commit-graph-format.html[the `commit-graph` format] for
 how they use the chunks to describe structured data.
 
 A chunk-based file format begins with some header information custom to
@@ -113,4 +126,8 @@ for future formats:
 * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`
   in `midx.c` for how the chunk-format API is used to write and
   parse the multi-pack-index file format documented in
-  link:technical/pack-format.html[the multi-pack-index file format].
+  the multi-pack-index file format section of linkgit:gitformat-pack[5].
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt
index 108dc2295c0..7324665716d 100644
--- a/Documentation/gitformat-commit-graph.txt
+++ b/Documentation/gitformat-commit-graph.txt
@@ -75,7 +75,7 @@ All multi-byte numbers are in network byte order.
       ID appears at most once.
 
   The CHUNK LOOKUP matches the table of contents from
-  link:technical/chunk-format.html[the chunk-based file format].
+  the chunk-based file format, see linkgit:gitformat-chunk[5]
 
   The remaining data in the body is described one chunk at a time, and
   these chunks may be given in any order. Chunks are required unless
diff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt
similarity index 98%
rename from Documentation/technical/index-format.txt
rename to Documentation/gitformat-index.txt
index 65da0daaa56..5f3ed10d2db 100644
--- a/Documentation/technical/index-format.txt
+++ b/Documentation/gitformat-index.txt
@@ -1,5 +1,19 @@
+gitformat-index(5)
+==================
+
+NAME
+----
+gitformat-index - Git index format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/index
+
+DESCRIPTION
+-----------
+
 Git index format
-================
 
 == The Git index file has the following format
 
@@ -127,7 +141,7 @@ Git index format
     entry is encoded as if the path name for the previous entry is an
     empty string).  At the beginning of an entry, an integer N in the
     variable width encoding (the same encoding as the offset is encoded
-    for OFS_DELTA pack entries; see pack-format.txt) is stored, followed
+    for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed
     by a NUL-terminated string S.  Removing N bytes from the end of the
     path name for the previous entry, and replacing it with the string S
     yields the path name for this entry.
@@ -404,3 +418,7 @@ The remaining data of each directory block is grouped by type:
   with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,
   tools should avoid interacting with a sparse index unless they understand
   this extension.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/cruft-packs.txt b/Documentation/gitformat-pack-cruft.txt
similarity index 96%
rename from Documentation/technical/cruft-packs.txt
rename to Documentation/gitformat-pack-cruft.txt
index d81f3a8982f..908f752bd84 100644
--- a/Documentation/technical/cruft-packs.txt
+++ b/Documentation/gitformat-pack-cruft.txt
@@ -1,4 +1,17 @@
-= Cruft packs
+gitformat-pack-cruft(5)
+=======================
+
+NAME
+----
+gitformat-pack-cruft - The cruft pack file format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/pack/pack-*.mtimes
+
+DESCRIPTION
+-----------
 
 The cruft packs feature offer an alternative to Git's traditional mechanism of
 removing unreachable objects. This document provides an overview of Git's
@@ -10,10 +23,11 @@ same.
 To remove unreachable objects from your repository, Git offers `git repack -Ad`
 (see linkgit:git-repack[1]). Quoting from the documentation:
 
-[quote]
+----
 [...] unreachable objects in a previous pack become loose, unpacked objects,
 instead of being left in the old pack. [...] loose unreachable objects will be
 pruned according to normal expiry rules with the next 'git gc' invocation.
+----
 
 Unreachable objects aren't removed immediately, since doing so could race with
 an incoming push which may reference an object which is about to be deleted.
@@ -121,3 +135,7 @@ which aren't already stored in an earlier cruft pack) is significantly more
 complicated to construct, and so aren't pursued here. The obvious drawback to
 the current implementation is that the entire cruft pack must be re-written from
 scratch.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitformat-pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt
index b665af5b690..f1bfd6705d9 100644
--- a/Documentation/gitformat-pack-protocol.txt
+++ b/Documentation/gitformat-pack-protocol.txt
@@ -467,7 +467,7 @@ Now that the client and server have finished negotiation about what
 the minimal amount of data that needs to be sent to the client is, the server
 will construct and send the required data in packfile format.
 
-See pack-format.txt for what the packfile itself actually looks like.
+See linkgit:gitformat-pack[5] for what the packfile itself actually looks like.
 
 If 'side-band' or 'side-band-64k' capabilities have been specified by
 the client, the server will send the packfile data multiplexed.
diff --git a/Documentation/technical/pack-format.txt b/Documentation/gitformat-pack.txt
similarity index 95%
rename from Documentation/technical/pack-format.txt
rename to Documentation/gitformat-pack.txt
index b520aa9c45b..5b21d0f2521 100644
--- a/Documentation/technical/pack-format.txt
+++ b/Documentation/gitformat-pack.txt
@@ -1,5 +1,29 @@
-Git pack format
-===============
+gitformat-pack(5)
+=================
+
+NAME
+----
+gitformat-pack - Git pack format
+
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/pack/pack-*.{pack,idx}
+$GIT_DIR/objects/pack/pack-*.rev
+$GIT_DIR/objects/pack/multi-pack-index
+
+DESCRIPTION
+-----------
+
+The Git pack format is now Git stores most of its primary repository
+data. Over the lietime af a repository loose objects (if any) and
+smaller packs are consolidated into larger pack(s). See
+linkgit:git-gc[1] and linkgit:git-pack-objects[1].
+
+The pack format is also used over-the-wire, see
+e.g. linkgit:gitformat-protocol-v2[5], as well as being a part of
+other container formats in the case of linkgit:gitformat-bundle[5].
 
 == Checksums and object IDs
 
@@ -356,7 +380,7 @@ CHUNK LOOKUP:
 	    using the next chunk position if necessary.)
 
 	The CHUNK LOOKUP matches the table of contents from
-	link:technical/chunk-format.html[the chunk-based file format].
+	the chunk-based file format, see linkgit:gitformat-chunk[5].
 
 	The remaining data in the body is described one chunk at a time, and
 	these chunks may be given in any order. Chunks are required unless
@@ -482,3 +506,7 @@ packs arranged in MIDX order (with the preferred pack coming first).
 
 The MIDX's reverse index is stored in the optional 'RIDX' chunk within
 the MIDX itself.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt
similarity index 96%
rename from Documentation/technical/signature-format.txt
rename to Documentation/gitformat-signature.txt
index 166721be6f6..a249869fafa 100644
--- a/Documentation/technical/signature-format.txt
+++ b/Documentation/gitformat-signature.txt
@@ -1,7 +1,18 @@
-Git signature format
-====================
+gitformat-signature(5)
+======================
 
-== Overview
+NAME
+----
+gitformat-signature - Git cryptographic signature formats
+
+SYNOPSIS
+--------
+[verse]
+<[tag|commit] object header(s)>
+<over-the-wire protocol>
+
+DESCRIPTION
+-----------
 
 Git uses cryptographic signatures in various places, currently objects (tags,
 commits, mergetags) and transactions (pushes). In every case, the command which
@@ -200,3 +211,7 @@ Date:   Wed Jun 15 09:13:29 2016 +0000
     # gpg:          There is no indication that the signature belongs to the owner.
     # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
 ----
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.txt
index 8994e2559ea..5efb4fe81ff 100644
--- a/Documentation/howto/recover-corrupted-object-harder.txt
+++ b/Documentation/howto/recover-corrupted-object-harder.txt
@@ -68,7 +68,7 @@ Note that the "object" file isn't fit for feeding straight to zlib; it
 has the git packed object header, which is variable-length. We want to
 strip that off so we can start playing with the zlib data directly. You
 can either work your way through it manually (the format is described in
-link:../technical/pack-format.html[Documentation/technical/pack-format.txt]),
+linkgit:gitformat-pack[5]),
 or you can walk through it in a debugger. I did the latter, creating a
 valid pack like:
 
diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt
index 260224b0331..e2ac36dd210 100644
--- a/Documentation/technical/hash-function-transition.txt
+++ b/Documentation/technical/hash-function-transition.txt
@@ -205,7 +205,7 @@ SHA-1 content.
 Object storage
 ~~~~~~~~~~~~~~
 Loose objects use zlib compression and packed objects use the packed
-format described in Documentation/technical/pack-format.txt, just like
+format described in linkgit:gitformat-pack[5], just like
 today. The content that is compressed and stored uses SHA-256 content
 instead of SHA-1 content.
 
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 865074bed4e..ca9decdd952 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3133,7 +3133,7 @@ those "loose" objects.
 You can save space and make Git faster by moving these loose objects in
 to a "pack file", which stores a group of objects in an efficient
 compressed format; the details of how pack files are formatted can be
-found in link:technical/pack-format.html[pack format].
+found in link:gitformat-pack[5].
 
 To put the loose objects into a pack, just run git repack:
 
diff --git a/cache.h b/cache.h
index ac5ab4ef9d3..82755c7c0aa 100644
--- a/cache.h
+++ b/cache.h
@@ -475,8 +475,7 @@ extern struct index_state the_index;
 
 /*
  * Values in this enum (except those outside the 3 bit range) are part
- * of pack file format. See Documentation/technical/pack-format.txt
- * for more information.
+ * of pack file format. See gitformat-pack(5) for more information.
  */
 enum object_type {
 	OBJ_BAD = -1,
diff --git a/command-list.txt b/command-list.txt
index bec0fa690aa..c364557fe09 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -209,11 +209,16 @@ gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
 gitformat-bundle                        gitformats
+gitformat-chunk                         gitformats
 gitformat-commit-graph                  gitformats
+gitformat-index                         gitformats
+gitformat-pack                          gitformats
+gitformat-pack-cruft                    gitformats
 gitformat-pack-protocol                 gitformats
 gitformat-protocol-capabilities         gitformats
 gitformat-protocol-common               gitformats
 gitformat-protocol-v2                   gitformats
+gitformat-signature                     gitformats
 gitglossary                             guide
 githooks                                userformats
 gitignore                               userformats
diff --git a/pack-revindex.h b/pack-revindex.h
index 74f4eae668d..4974e75eb4d 100644
--- a/pack-revindex.h
+++ b/pack-revindex.h
@@ -22,7 +22,7 @@
  *
  *   - pack position refers to an object's position within a non-existent pack
  *     described by the MIDX. The pack structure is described in
- *     Documentation/technical/pack-format.txt.
+ *     gitformat-pack(5).
  *
  *     It is effectively a concatanation of all packs in the MIDX (ordered by
  *     their numeric ID within the MIDX) in their original order within each
-- 
2.37.1.1032.gb00b5447790


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v4 7/8] docs: move http-protocol docs to man section 5
  2022-07-18 13:29     ` [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
                         ` (5 preceding siblings ...)
  2022-07-18 13:29       ` [PATCH v4 6/8] docs: move pack format " Ævar Arnfjörð Bjarmason
@ 2022-07-18 13:29       ` Ævar Arnfjörð Bjarmason
  2022-07-18 13:29       ` [PATCH v4 8/8] docs: move multi-pack-index " Ævar Arnfjörð Bjarmason
                         ` (2 subsequent siblings)
  9 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-18 13:29 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 Documentation/Makefile                        |  2 +-
 Documentation/git-upload-pack.txt             |  6 ++--
 Documentation/gitformat-pack-protocol.txt     |  2 +-
 ...otocol.txt => gitformat-protocol-http.txt} | 29 ++++++++++++++++---
 Documentation/gitformat-protocol-v2.txt       |  4 +--
 command-list.txt                              |  1 +
 6 files changed, 33 insertions(+), 11 deletions(-)
 rename Documentation/{technical/http-protocol.txt => gitformat-protocol-http.txt} (98%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index b4d2361dfc7..44757823e96 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -33,6 +33,7 @@ MAN5_TXT += gitformat-pack-protocol.txt
 MAN5_TXT += gitformat-pack.txt
 MAN5_TXT += gitformat-protocol-capabilities.txt
 MAN5_TXT += gitformat-protocol-common.txt
+MAN5_TXT += gitformat-protocol-http.txt
 MAN5_TXT += gitformat-protocol-v2.txt
 MAN5_TXT += gitformat-signature.txt
 MAN5_TXT += githooks.txt
@@ -107,7 +108,6 @@ TECH_DOCS += SubmittingPatches
 TECH_DOCS += ToolsForGit
 TECH_DOCS += technical/bitmap-format
 TECH_DOCS += technical/hash-function-transition
-TECH_DOCS += technical/http-protocol
 TECH_DOCS += technical/long-running-process-protocol
 TECH_DOCS += technical/multi-pack-index
 TECH_DOCS += technical/pack-heuristics
diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt
index 754619222f6..720697df3a0 100644
--- a/Documentation/git-upload-pack.txt
+++ b/Documentation/git-upload-pack.txt
@@ -39,9 +39,9 @@ OPTIONS
 --http-backend-info-refs::
 	Used by linkgit:git-http-backend[1] to serve up
 	`$GIT_URL/info/refs?service=git-upload-pack` requests. See
-	"Smart Clients" in link:technical/http-protocol.html[the HTTP
-	transfer protocols] documentation and "HTTP Transport" in the
-	linkgit:gitformat-protocol-v2[5] documentation. Also understood by
+	"Smart Clients" in linkgit:gitformat-protocol-http[5] and
+	"HTTP Transport" in link:technical/protocol-v2.html[the Git
+	Wire Protocol, Version 2] documentation. Also understood by
 	linkgit:git-receive-pack[1].
 
 <directory>::
diff --git a/Documentation/gitformat-pack-protocol.txt b/Documentation/gitformat-pack-protocol.txt
index f1bfd6705d9..c82b926e661 100644
--- a/Documentation/gitformat-pack-protocol.txt
+++ b/Documentation/gitformat-pack-protocol.txt
@@ -17,7 +17,7 @@ Git supports transferring data in packfiles over the ssh://, git://, http:// and
 file:// transports.  There exist two sets of protocols, one for pushing
 data from a client to a server and another for fetching data from a
 server to a client.  The three transports (ssh, git, file) use the same
-protocol to transfer data. http is documented in http-protocol.txt.
+protocol to transfer data. http is documented in linkgit:gitformat-protocol-http[5].
 
 The processes invoked in the canonical Git implementation are 'upload-pack'
 on the server side and 'fetch-pack' on the client side for fetching data;
diff --git a/Documentation/technical/http-protocol.txt b/Documentation/gitformat-protocol-http.txt
similarity index 98%
rename from Documentation/technical/http-protocol.txt
rename to Documentation/gitformat-protocol-http.txt
index 9d9c7acd512..b85fc86abf6 100644
--- a/Documentation/technical/http-protocol.txt
+++ b/Documentation/gitformat-protocol-http.txt
@@ -1,5 +1,19 @@
-HTTP transfer protocols
-=======================
+gitformat-protocol-http(5)
+==========================
+
+NAME
+----
+gitformat-protocol-http - Git HTTP-based protocols
+
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+
+DESCRIPTION
+-----------
 
 Git supports two HTTP based transfer protocols.  A "dumb" protocol
 which requires only a standard HTTP server on the server end of the
@@ -512,11 +526,18 @@ the id obtained through ref discovery as old_id.
 
 TODO: Document this further.
 
-
-References
+REFERENCES
 ----------
 
 http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
 http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
+
+SEE ALSO
+--------
+
 linkgit:gitformat-pack-protocol[5]
 linkgit:gitformat-protocol-capabilities[5]
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitformat-protocol-v2.txt b/Documentation/gitformat-protocol-v2.txt
index ae4fcc84e37..e29bc4b6a68 100644
--- a/Documentation/gitformat-protocol-v2.txt
+++ b/Documentation/gitformat-protocol-v2.txt
@@ -54,7 +54,7 @@ Initial Client Request
 In general a client can request to speak protocol v2 by sending
 `version=2` through the respective side-channel for the transport being
 used which inevitably sets `GIT_PROTOCOL`.  More information can be
-found in linkgit:gitformat-pack-protocol[5] and `http-protocol.txt`, as well as the
+found in linkgit:gitformat-pack-protocol[5] and linkgit:gitformat-protocol-http[5], as well as the
 `GIT_PROTOCOL` definition in `git.txt`. In all cases the
 response from the server is the capability advertisement.
 
@@ -78,7 +78,7 @@ HTTP Transport
 ~~~~~~~~~~~~~~
 
 When using the http:// or https:// transport a client makes a "smart"
-info/refs request as described in `http-protocol.txt` and requests that
+info/refs request as described in linkgit:gitformat-protocol-http[5] and requests that
 v2 be used by supplying "version=2" in the `Git-Protocol` header.
 
    C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
diff --git a/command-list.txt b/command-list.txt
index c364557fe09..c87b07e779c 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -217,6 +217,7 @@ gitformat-pack-cruft                    gitformats
 gitformat-pack-protocol                 gitformats
 gitformat-protocol-capabilities         gitformats
 gitformat-protocol-common               gitformats
+gitformat-protocol-http                 gitformats
 gitformat-protocol-v2                   gitformats
 gitformat-signature                     gitformats
 gitglossary                             guide
-- 
2.37.1.1032.gb00b5447790


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v4 8/8] docs: move multi-pack-index docs to man section 5
  2022-07-18 13:29     ` [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
                         ` (6 preceding siblings ...)
  2022-07-18 13:29       ` [PATCH v4 7/8] docs: move http-protocol " Ævar Arnfjörð Bjarmason
@ 2022-07-18 13:29       ` Ævar Arnfjörð Bjarmason
  2022-07-18 16:54       ` [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/* Junio C Hamano
  2022-07-21 16:13       ` [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
  9 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-18 13:29 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 Documentation/Makefile                        |  2 +-
 Documentation/git-multi-pack-index.txt        |  5 +++--
 ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++++++++++++--
 Documentation/gitformat-pack.txt              |  5 +++++
 command-list.txt                              |  1 +
 5 files changed, 28 insertions(+), 5 deletions(-)
 rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 44757823e96..984d86a96d3 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -28,6 +28,7 @@ MAN5_TXT += gitformat-bundle.txt
 MAN5_TXT += gitformat-chunk.txt
 MAN5_TXT += gitformat-commit-graph.txt
 MAN5_TXT += gitformat-index.txt
+MAN5_TXT += gitformat-multi-pack-index.txt
 MAN5_TXT += gitformat-pack-cruft.txt
 MAN5_TXT += gitformat-pack-protocol.txt
 MAN5_TXT += gitformat-pack.txt
@@ -109,7 +110,6 @@ TECH_DOCS += ToolsForGit
 TECH_DOCS += technical/bitmap-format
 TECH_DOCS += technical/hash-function-transition
 TECH_DOCS += technical/long-running-process-protocol
-TECH_DOCS += technical/multi-pack-index
 TECH_DOCS += technical/pack-heuristics
 TECH_DOCS += technical/parallel-checkout
 TECH_DOCS += technical/partial-clone
diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt
index a48c3d5ea63..a147e047c91 100644
--- a/Documentation/git-multi-pack-index.txt
+++ b/Documentation/git-multi-pack-index.txt
@@ -127,8 +127,9 @@ $ git multi-pack-index verify
 
 SEE ALSO
 --------
-See link:technical/multi-pack-index.html[The Multi-Pack-Index Design
-Document] and linkgit:gitformat-pack[5] for more information on the
+
+See linkgit:git-multi-pack-index[1] and
+linkgit:gitformat-multi-pack-index[5] for more information on the
 multi-pack-index feature and its file format.
 
 
diff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/gitformat-multi-pack-index.txt
similarity index 94%
rename from Documentation/technical/multi-pack-index.txt
rename to Documentation/gitformat-multi-pack-index.txt
index f2221d2b441..3bca1e7b10d 100644
--- a/Documentation/technical/multi-pack-index.txt
+++ b/Documentation/gitformat-multi-pack-index.txt
@@ -1,5 +1,17 @@
-Multi-Pack-Index (MIDX) Design Notes
-====================================
+gitformat-multi-pack-index(5)
+=============================
+
+NAME
+----
+gitformat-multi-pack-index - The multi-pack-index file format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/pack/multi-pack-index
+
+DESCRIPTION
+-----------
 
 The Git object directory contains a 'pack' directory containing
 packfiles (with suffix ".pack") and pack-indexes (with suffix
@@ -98,3 +110,7 @@ Related Links
 
 [2] https://lore.kernel.org/git/alpine.DEB.2.20.1803091557510.23109@alexmv-linux/
     Git Merge 2018 Contributor's summit notes (includes discussion of MIDX)
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt
index 5b21d0f2521..06b469c6944 100644
--- a/Documentation/gitformat-pack.txt
+++ b/Documentation/gitformat-pack.txt
@@ -507,6 +507,11 @@ packs arranged in MIDX order (with the preferred pack coming first).
 The MIDX's reverse index is stored in the optional 'RIDX' chunk within
 the MIDX itself.
 
+SEE ALSO
+--------
+
+linkgit:gitformat-multi-pack-index[5]
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/command-list.txt b/command-list.txt
index c87b07e779c..a802f5b3369 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -212,6 +212,7 @@ gitformat-bundle                        gitformats
 gitformat-chunk                         gitformats
 gitformat-commit-graph                  gitformats
 gitformat-index                         gitformats
+gitformat-multi-pack-index              gitformats
 gitformat-pack                          gitformats
 gitformat-pack-cruft                    gitformats
 gitformat-pack-protocol                 gitformats
-- 
2.37.1.1032.gb00b5447790


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* Re: [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/*
  2022-07-18 13:29     ` [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
                         ` (7 preceding siblings ...)
  2022-07-18 13:29       ` [PATCH v4 8/8] docs: move multi-pack-index " Ævar Arnfjörð Bjarmason
@ 2022-07-18 16:54       ` Junio C Hamano
  2022-07-18 17:58         ` Ævar Arnfjörð Bjarmason
  2022-07-21 16:13       ` [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
  9 siblings, 1 reply; 112+ messages in thread
From: Junio C Hamano @ 2022-07-18 16:54 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: git, Eric Sunshine, Philippe Blain, Derrick Stolee, Taylor Blau,
	Jeff King, Teng Long

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

> This series improves the discoverability of the technical/*
> documentation covering those "formats" where we interact with users
> (e.g. "gitattributes") by moving them to its own "git help" category.
>
> It then moves various technical documentation from technical/* to our
> main documentation namespace, allowing us to cross-link e.g. from
> "git-bundle(1)" to a new "gitformat-bundle(5)".

This may be a good direction to go in in the longer term, but there
are already topics in flight that change these documents.  Luckily
none in 'next' yet, but there are two that have been in 'seen' and
need to coordinate with this change.



^ permalink raw reply	[flat|nested] 112+ messages in thread

* Re: [PATCH v4 1/8] help.c: BUG() out if "help --guides" can't remove "git" prefixes
  2022-07-18 13:29       ` [PATCH v4 1/8] help.c: BUG() out if "help --guides" can't remove "git" prefixes Ævar Arnfjörð Bjarmason
@ 2022-07-18 17:03         ` Junio C Hamano
  0 siblings, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-07-18 17:03 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: git, Eric Sunshine, Philippe Blain, Derrick Stolee, Taylor Blau,
	Jeff King, Teng Long

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

> 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.

The observation is good.

>  	if (skip_prefix(name, "git-", &new_name))
>  		return new_name;
> -	if (category == CAT_guide && skip_prefix(name, "git", &new_name))
> +	switch (category)
> +	{
> +	case CAT_guide:
> +		if (!skip_prefix(name, "git", &new_name))
> +			BUG("category #%d but no 'git' prefix?", category);
>  		return new_name;
> +	}
>  	return name;
> -
>  }

If we were to use "switch", can we have the opening brace on the
same line, like all other switch statements?

I suspect that we should avoid losing information, perhaps the most
straight-forward implementation would be without "switch", like so

	if (category == CAT_guide) {
		if (skip_prefix(name, "git", &new_name))
			return new_name;
		BUG("CAT_guide category but no 'git' prefix? '%s'", name);
	}
	return name;

even if we plan to add more categories that would remove the prefix
and we insist the prefix to be there?

>  static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask)

^ permalink raw reply	[flat|nested] 112+ messages in thread

* Re: [PATCH v4 2/8] git docs: split "User-facing file formats" off from "Guides"
  2022-07-18 13:29       ` [PATCH v4 2/8] git docs: split "User-facing file formats" off from "Guides" Ævar Arnfjörð Bjarmason
@ 2022-07-18 17:17         ` Junio C Hamano
  2022-07-18 18:41           ` Ævar Arnfjörð Bjarmason
  0 siblings, 1 reply; 112+ messages in thread
From: Junio C Hamano @ 2022-07-18 17:17 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: git, Eric Sunshine, Philippe Blain, Derrick Stolee, Taylor Blau,
	Jeff King, Teng Long

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

> We take a wide view of what's considered a "user format", it's not
> just a file format, but e.g. githooks(5) also belongs, since the
> layout of the ".git/hooks/" and the placement of hooks in it is
> something the user might be expected to interact with.

I am afraid it is a bit big a stretch.  Other documents that fall
into the user-format category all have "format" the users must
follow while writing the "contents" in the file.  ".gitignore" has
certain format and syntax and the document describes what effect the
file has, based on the contents of the file that follows the syntax.

A hook can be written in any language, even though our UNIX lineage
makes our samples all in written in the shell, so there is no
"format" for the users to follow that we should force upon them.

If we can come up with a word that is more appropriate than
"format", it would be great.  If we do not place too much emphasis
on "format", I agree that both "gitignore" and "githook" fall into
the same category, because they define how the contents written in
these files affect the operation of Git commands.

> -With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
> +With no options and no '<command>', '<guide>' or '<doc>' given, the synopsis of the 'git'

At some point, we will have enough <doc> that it would probably
become meaningless to treat <guide> as a separate class, no?
Guides, user-supplied customization files, and implementation
details of on-disk files that may help reimplementations of Git, all
will become <doc>.

> @@ -26,8 +27,8 @@ printed on the standard output.
>  If the option `--guides` or `-g` is given, a list of the
>  Git concept guides is also printed on the standard output.
>  
> -If a command, or a guide, is given, a manual page for that command or
> -guide is brought up. The 'man' program is used by default for this
> +If a command or other documentation is given, the relevant manual page
> +will be brought up. The 'man' program is used by default for this

Good.

^ permalink raw reply	[flat|nested] 112+ messages in thread

* Re: [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/*
  2022-07-18 16:54       ` [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/* Junio C Hamano
@ 2022-07-18 17:58         ` Ævar Arnfjörð Bjarmason
  2022-07-21  7:12           ` Ævar Arnfjörð Bjarmason
  0 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-18 17:58 UTC (permalink / raw)
  To: Junio C Hamano
  Cc: git, Eric Sunshine, Philippe Blain, Derrick Stolee, Taylor Blau,
	Jeff King, Teng Long


On Mon, Jul 18 2022, Junio C Hamano wrote:

> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>
>> This series improves the discoverability of the technical/*
>> documentation covering those "formats" where we interact with users
>> (e.g. "gitattributes") by moving them to its own "git help" category.
>>
>> It then moves various technical documentation from technical/* to our
>> main documentation namespace, allowing us to cross-link e.g. from
>> "git-bundle(1)" to a new "gitformat-bundle(5)".
>
> This may be a good direction to go in in the longer term, but there
> are already topics in flight that change these documents.  Luckily
> none in 'next' yet, but there are two that have been in 'seen' and
> need to coordinate with this change.

The v4 merges cleanly for me, unless there's a semantic conflict you've
spotted that I've missed.

But I assume you mean a "seen" you haven't pushed out yet, which
includes SZEDER's change here:
https://lore.kernel.org/git/220718.86cze2y22q.gmgdl@evledraar.gmail.com/

I sent out the v3 with a merge resolution for the only conflict at the
time:
https://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/

But as noted in the v4 CL I thought I'd make even that trivial conflict
go away in v4, but it looks like I'll need to roll a v5.

I don't want to make it a hassle for you to carry this topic, and I have
waited a few months to submit this, as there were always various
Documentation/technical/ changes in-flight.

Would you prefer to have this entirely conflict free, or to have me
solve the (small) conflicts locally and note the resolution (per
--remerge-diff) in the CLs?

^ permalink raw reply	[flat|nested] 112+ messages in thread

* Re: [PATCH v4 2/8] git docs: split "User-facing file formats" off from "Guides"
  2022-07-18 17:17         ` Junio C Hamano
@ 2022-07-18 18:41           ` Ævar Arnfjörð Bjarmason
  2022-07-19 23:21             ` Junio C Hamano
  0 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-18 18:41 UTC (permalink / raw)
  To: Junio C Hamano
  Cc: git, Eric Sunshine, Philippe Blain, Derrick Stolee, Taylor Blau,
	Jeff King, Teng Long


On Mon, Jul 18 2022, Junio C Hamano wrote:

> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>
>> We take a wide view of what's considered a "user format", it's not
>> just a file format, but e.g. githooks(5) also belongs, since the
>> layout of the ".git/hooks/" and the placement of hooks in it is
>> something the user might be expected to interact with.
>
> I am afraid it is a bit big a stretch.  Other documents that fall
> into the user-format category all have "format" the users must
> follow while writing the "contents" in the file.  ".gitignore" has
> certain format and syntax and the document describes what effect the
> file has, based on the contents of the file that follows the syntax.
>
> A hook can be written in any language, even though our UNIX lineage
> makes our samples all in written in the shell, so there is no
> "format" for the users to follow that we should force upon them.

The "format" I have in mind is the "shape" of the configuration,
i.e. that a hook goes in .git/hooks/<name>, not the contents of that
<name> itself.

So it's introducing a bit of a neologism, but I couldn't think of a
better one. Suggestions welcome. There is "gitrepository-layout(5)", but
calling this a "layout" seems odd.

I do think that things that users are expected to interact with on a
file-level (gitignore, gitmailmap etc.) and on the FS arrange in such a
way as to interact with git (gitignore) belong together under one hat.

So it's not perfect, but I think it sucks less than calling both
"gitmodules" and "giteverday" a "guide", which is the status quo.

> If we can come up with a word that is more appropriate than
> "format", it would be great.  If we do not place too much emphasis
> on "format", I agree that both "gitignore" and "githook" fall into
> the same category, because they define how the contents written in
> these files affect the operation of Git commands.

*nod*, another word would be most welcome :)

I do think that if we have --user-formats or --user-X it makes sense to
have to have that match the --git-X. I.e. the "format" of say the
commit-graph includes how we arrange those files on disk, just as is the
case with the hoks.

>> -With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
>> +With no options and no '<command>', '<guide>' or '<doc>' given, the synopsis of the 'git'
>
> At some point, we will have enough <doc> that it would probably
> become meaningless to treat <guide> as a separate class, no?
> Guides, user-supplied customization files, and implementation
> details of on-disk files that may help reimplementations of Git, all
> will become <doc>.

Maybe I should just use <name> here?

^ permalink raw reply	[flat|nested] 112+ messages in thread

* Re: [PATCH v4 2/8] git docs: split "User-facing file formats" off from "Guides"
  2022-07-18 18:41           ` Ævar Arnfjörð Bjarmason
@ 2022-07-19 23:21             ` Junio C Hamano
  2022-07-21  7:02               ` Ævar Arnfjörð Bjarmason
  0 siblings, 1 reply; 112+ messages in thread
From: Junio C Hamano @ 2022-07-19 23:21 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: git, Eric Sunshine, Philippe Blain, Derrick Stolee, Taylor Blau,
	Jeff King, Teng Long

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

>> If we can come up with a word that is more appropriate than
>> "format", it would be great.  If we do not place too much emphasis
>> on "format", I agree that both "gitignore" and "githook" fall into
>> the same category, because they define how the contents written in
>> these files affect the operation of Git commands.
>
> *nod*, another word would be most welcome :)

True.  What I am absolutely sure about is that the word is not
"format" X-<.  It is the interface end-users interact with internals
of Git, with need similar to how "plugin" interfaces need to have
documentation for their users.

> I do think that if we have --user-formats or --user-X it makes sense to
> have to have that match the --git-X. I.e. the "format" of say the
> commit-graph includes how we arrange those files on disk, just as is the
> case with the hoks.
>
>>> -With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
>>> +With no options and no '<command>', '<guide>' or '<doc>' given, the synopsis of the 'git'
>>
>> At some point, we will have enough <doc> that it would probably
>> become meaningless to treat <guide> as a separate class, no?
>> Guides, user-supplied customization files, and implementation
>> details of on-disk files that may help reimplementations of Git, all
>> will become <doc>.
>
> Maybe I should just use <name> here?

I think <doc> is very good, much better than <name>, here.

^ permalink raw reply	[flat|nested] 112+ messages in thread

* Re: [PATCH v4 2/8] git docs: split "User-facing file formats" off from "Guides"
  2022-07-19 23:21             ` Junio C Hamano
@ 2022-07-21  7:02               ` Ævar Arnfjörð Bjarmason
  0 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-21  7:02 UTC (permalink / raw)
  To: Junio C Hamano
  Cc: git, Eric Sunshine, Philippe Blain, Derrick Stolee, Taylor Blau,
	Jeff King, Teng Long


On Tue, Jul 19 2022, Junio C Hamano wrote:

> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>>> If we can come up with a word that is more appropriate than
>>> "format", it would be great.  If we do not place too much emphasis
>>> on "format", I agree that both "gitignore" and "githook" fall into
>>> the same category, because they define how the contents written in
>>> these files affect the operation of Git commands.
>>
>> *nod*, another word would be most welcome :)
>
> True.  What I am absolutely sure about is that the word is not
> "format" X-<.  It is the interface end-users interact with internals
> of Git, with need similar to how "plugin" interfaces need to have
> documentation for their users.

My goal here is just to make this part of our documentation more
accessible, so I don't care about the term. But this series also seems
blocked on you not liking the term, so...

A few ways I can think of to go forward:

1. Use "format", but explain that we're using it loosely. Perhaps with
   this on top?
	
	diff --git a/Documentation/git.txt b/Documentation/git.txt
	index 1980a0e29cd..9f8d7a3543e 100644
	--- a/Documentation/git.txt
	+++ b/Documentation/git.txt
	@@ -343,7 +343,10 @@ User-facing file formats
	 ------------------------
	 
	 This documentation discusses file formats that users are expected to
	-edit. These can also be listed with 'git help --user-formats'.
	+edit. "Format" here refers more broadly to files and/or file contents
	+that the user is expected to edit or know about.
	+
	+These can also be listed with 'git help --user-formats'.
	 
	 include::cmds-userformats.txt[]

2. I could submit this without the "git help --user-formats" change for
   now, and just focus on --git-formats:
	
	Internal file formats and protocols:
	   format-bundle                  The bundle file format
	   format-chunk                   Chunk-based file formats
	   format-commit-graph            Git commit graph format
	   format-index                   Git index format
	   format-multi-pack-index        The multi-pack-index file format
	   format-pack                    Git pack format
	   format-pack-cruft              The cruft pack file format
	   format-pack-protocol           How packs are transferred over-the-wire
	   format-protocol-capabilities   Protocol v0 and v1 capabilities
	   format-protocol-common         Things common to various protocols
	   format-protocol-http           Git HTTP-based protocols
	   format-protocol-v2             Git Wire Protocol, Version 2
	   format-signature               Git cryptographic signature formats

   Do you have an objection to any of those being labeled "format"? I
   understood your comments above to not include those, i.e. that you
   took objection to githooks(5) in particular being in that new
   --user-formats category.

3. A re-roll of this series pretty much as-is (sans other fixes), but
   remove "githooks" from this re-categorization.

4. Come up with s/format/<something>/g, but I have no idea what that
   "something" would be. "Protocol?", After all a secret handshake is
   also a protocol....

^ permalink raw reply	[flat|nested] 112+ messages in thread

* Re: [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/*
  2022-07-18 17:58         ` Ævar Arnfjörð Bjarmason
@ 2022-07-21  7:12           ` Ævar Arnfjörð Bjarmason
  0 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-21  7:12 UTC (permalink / raw)
  To: Junio C Hamano
  Cc: git, Eric Sunshine, Philippe Blain, Derrick Stolee, Taylor Blau,
	Jeff King, Teng Long


On Mon, Jul 18 2022, Ævar Arnfjörð Bjarmason wrote:

> On Mon, Jul 18 2022, Junio C Hamano wrote:
>
>> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>>
>>> This series improves the discoverability of the technical/*
>>> documentation covering those "formats" where we interact with users
>>> (e.g. "gitattributes") by moving them to its own "git help" category.
>>>
>>> It then moves various technical documentation from technical/* to our
>>> main documentation namespace, allowing us to cross-link e.g. from
>>> "git-bundle(1)" to a new "gitformat-bundle(5)".
>>
>> This may be a good direction to go in in the longer term, but there
>> are already topics in flight that change these documents.  Luckily
>> none in 'next' yet, but there are two that have been in 'seen' and
>> need to coordinate with this change.
>
> The v4 merges cleanly for me, unless there's a semantic conflict you've
> spotted that I've missed.
>
> But I assume you mean a "seen" you haven't pushed out yet, which
> includes SZEDER's change here:
> https://lore.kernel.org/git/220718.86cze2y22q.gmgdl@evledraar.gmail.com/
>
> I sent out the v3 with a merge resolution for the only conflict at the
> time:
> https://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/
>
> But as noted in the v4 CL I thought I'd make even that trivial conflict
> go away in v4, but it looks like I'll need to roll a v5.
>
> I don't want to make it a hassle for you to carry this topic, and I have
> waited a few months to submit this, as there were always various
> Documentation/technical/ changes in-flight.
>
> Would you prefer to have this entirely conflict free, or to have me
> solve the (small) conflicts locally and note the resolution (per
> --remerge-diff) in the CLs?

FWIW this merges cleanly with "seen" due to the magic of "git merge",
i.e. even with the rename we resolve the conflict with SZEDER's work
smoothly.

But there's other reasons to re-roll, just say'n for when you eventually
(hopefully) pick up such a re-roll ...

^ permalink raw reply	[flat|nested] 112+ messages in thread

* [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories
  2022-07-18 13:29     ` [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/* Ævar Arnfjörð Bjarmason
                         ` (8 preceding siblings ...)
  2022-07-18 16:54       ` [PATCH v4 0/8] git doc + "git help": move "format" docs from technical/* Junio C Hamano
@ 2022-07-21 16:13       ` Ævar Arnfjörð Bjarmason
  2022-07-21 16:13         ` [PATCH v5 1/9] help.c: BUG() out if "help --guides" can't remove "git" prefixes Ævar Arnfjörð Bjarmason
                           ` (10 more replies)
  9 siblings, 11 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-21 16:13 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

See v3[1] for lofty goals. The changes since v4 are mainly to rename
the "user formats" and "developer formats" to "user interfaces" and
"developer interfaces".

Now:

	$ ./git help --user-interfaces
	User-facing repository, command and file interfaces:
	   attributes          Defining attributes per path
	   cli                 Git command-line interface and conventions
	   hooks               Hooks used by Git
	   ignore              Specifies intentionally untracked files to ignore
	   mailmap             Map author/committer names and/or E-Mail addresses
	   modules             Defining submodule properties
	   repository-layout   Git Repository Layout
	   revisions           Specifying revisions and ranges for Git

The addition of "gitcli" and "gitrevisions" is new. I.e. per git-help(1):

	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].

And for "--developer-interfaces" (I wondered about calling this --apis):

	$ ./git help --developer-interfaces
	File formats, protocols and other developer interfaces:
	   format-bundle             The bundle file format
	   format-chunk              Chunk-based file formats
	   format-commit-graph       Git commit graph format
	   format-index              Git index format
	   format-multi-pack-index   The multi-pack-index file format
	   format-pack               Git pack format
	   format-pack-cruft         The cruft pack file format
	   format-signature          Git cryptographic signature formats
	   protocol-capabilities     Protocol v0 and v1 capabilities
	   protocol-common           Things common to various protocols
	   protocol-http             Git HTTP-based protocols
	   protocol-pack             How packs are transferred over-the-wire
	   protocol-v2               Git Wire Protocol, Version 2

I.e.:

 * The name of the new "user" category refers generally to "user
   interfaces", and as the description notes we'll cover user-editable
   files, UX conventions etc. there.

 * Not all the "--developer-interfaces" start with "gitformat"
   anymore, now it's "gitformat" for e.g. the bundle format, but
   "gitprotocol" for things that have to do with the protocol.

   This also solves an ugly wart: Before we had
   "gitformat-pack-protocol" (protocol) and "gitformat-pack" (*.pack
   files).

Other changes:

 * Changed the "<guide> or <doc>" to just say "<doc>, and it's now a
   split-off 2/9.

 * Fixed some links to the new docs, and added missing ones.

 * There was no "--developer-interfaces" section in the git-help(1)
   docs (or "--git-formats") before).

1. https://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/

Ævar Arnfjörð Bjarmason (9):
  help.c: BUG() out if "help --guides" can't remove "git" prefixes
  git help doc: use "<doc>" instead of "<guide>"
  git docs: add a category for user-facing file, repo and command UX
  git docs: add a category for file formats, protocols and interfaces
  docs: move commit-graph format docs to man section 5
  docs: move protocol-related docs to man section 5
  docs: move pack format docs to man section 5
  docs: move http-protocol docs to man section 5
  docs: move multi-pack-index docs to man section 5

 Documentation/Makefile                        | 26 +++++-----
 Documentation/config/lsrefs.txt               |  2 +-
 Documentation/config/pack.txt                 |  2 +-
 Documentation/config/protocol.txt             |  2 +-
 Documentation/git-bundle.txt                  | 13 +++--
 Documentation/git-commit-graph.txt            |  5 ++
 Documentation/git-help.txt                    | 27 ++++++++--
 Documentation/git-multi-pack-index.txt        |  6 +--
 Documentation/git-upload-pack.txt             |  7 ++-
 Documentation/git.txt                         | 17 +++++++
 ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++---
 .../chunk-format.txt => gitformat-chunk.txt}  | 29 ++++++++---
 ...-format.txt => gitformat-commit-graph.txt} | 49 +++++++++++++------
 .../index-format.txt => gitformat-index.txt}  | 22 ++++++++-
 ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++-
 ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++-
 .../pack-format.txt => gitformat-pack.txt}    | 39 +++++++++++++--
 ...ure-format.txt => gitformat-signature.txt} | 21 ++++++--
 ...ities.txt => gitprotocol-capabilities.txt} | 28 ++++++++---
 ...ocol-common.txt => gitprotocol-common.txt} | 23 ++++++++-
 ...http-protocol.txt => gitprotocol-http.txt} | 35 ++++++++++---
 ...pack-protocol.txt => gitprotocol-pack.txt} | 28 ++++++++---
 .../protocol-v2.txt => gitprotocol-v2.txt}    | 27 +++++++---
 .../howto/recover-corrupted-object-harder.txt |  2 +-
 Documentation/lint-man-section-order.perl     |  3 ++
 Documentation/technical/api-simple-ipc.txt    |  2 +-
 .../technical/hash-function-transition.txt    |  2 +-
 .../long-running-process-protocol.txt         |  2 +-
 Documentation/technical/packfile-uri.txt      |  2 +-
 Documentation/technical/partial-clone.txt     |  2 +-
 Documentation/user-manual.txt                 |  2 +-
 Makefile                                      |  1 +
 builtin/help.c                                | 20 +++++++-
 cache.h                                       |  3 +-
 command-list.txt                              | 38 +++++++++++---
 help.c                                        | 34 ++++++++++++-
 help.h                                        |  2 +
 pack-revindex.h                               |  2 +-
 refspec.h                                     |  2 +-
 t/t0012-help.sh                               | 14 +++++-
 t/t5551-http-fetch-smart.sh                   |  4 +-
 41 files changed, 508 insertions(+), 123 deletions(-)
 rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)
 rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (89%)
 rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (87%)
 rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)
 rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)
 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%)
 rename Documentation/{technical/protocol-capabilities.txt => gitprotocol-capabilities.txt} (96%)
 rename Documentation/{technical/protocol-common.txt => gitprotocol-common.txt} (89%)
 rename Documentation/{technical/http-protocol.txt => gitprotocol-http.txt} (97%)
 rename Documentation/{technical/pack-protocol.txt => gitprotocol-pack.txt} (98%)
 rename Documentation/{technical/protocol-v2.txt => gitprotocol-v2.txt} (97%)

Range-diff against v4:
 1:  4428f0a6fb1 !  1:  b0bb29bb131 help.c: BUG() out if "help --guides" can't remove "git" prefixes
    @@ Commit message
         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
      ## help.c ##
    -@@ help.c: static const char *drop_prefix(const char *name, uint32_t category)
    +@@ help.c: 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)
    -+	{
    ++	switch (category) {
     +	case CAT_guide:
    -+		if (!skip_prefix(name, "git", &new_name))
    -+			BUG("category #%d but no 'git' prefix?", category);
    ++		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;
 -:  ----------- >  2:  2ec00f81552 git help doc: use "<doc>" instead of "<guide>"
 2:  883c483d4e7 !  3:  31be7d01c50 git docs: split "User-facing file formats" off from "Guides"
    @@ Metadata
     Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
      ## Commit message ##
    -    git docs: split "User-facing file formats" off from "Guides"
    +    git docs: add a category for user-facing file, repo and command UX
     
    -    Create a new "User-facing file formats" section in the main "git help
    -    git" manual page. The "Guides" section was added to the manual page in
    -    f442f28a81b (git.txt: add list of guides, 2020-08-05), it makes sense
    -    to list all that documentation.
    +    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)".
     
    -    We take a wide view of what's considered a "user format", it's not
    -    just a file format, but e.g. githooks(5) also belongs, since the
    -    layout of the ".git/hooks/" and the placement of hooks in it is
    -    something the user might be expected to interact with.
    +    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 <avarab@gmail.com>
     
    @@ Documentation/Makefile: cmds_txt = cmds-ancillaryinterrogators.txt \
      	cmds-synchingrepositories.txt \
      	cmds-synchelpers.txt \
      	cmds-guide.txt \
    -+	cmds-userformats.txt \
    ++	cmds-userinterfaces.txt \
      	cmds-purehelpers.txt \
      	cmds-foreignscminterface.txt
      
     
      ## Documentation/git-help.txt ##
     @@ Documentation/git-help.txt: SYNOPSIS
    - --------
    - [verse]
    - 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]
    --'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]
    -+'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>|<doc>]
    + 'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]
      'git help' [-g|--guides]
      'git help' [-c|--config]
    -+'git help' [--user-formats]
    ++'git help' [--user-interfaces]
      
      DESCRIPTION
      -----------
    - 
    --With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
    -+With no options and no '<command>', '<guide>' or '<doc>' given, the synopsis of the 'git'
    - command and a list of the most commonly used Git commands are printed
    - on the standard output.
    - 
    -@@ Documentation/git-help.txt: 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.
    - 
     @@ Documentation/git-help.txt: OPTIONS
      --guides::
      	Prints a list of the Git concept guides on the standard output.
      
    -+--user-formats::
    -+	Prints a list of the Git user-facing format documentation on
    -+	the standard output.
    ++--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::
    @@ Documentation/git.txt: The following documentation pages are guides about Git co
      
      include::cmds-guide.txt[]
      
    -+User-facing file formats
    -+------------------------
    ++Repository, command and file interfaces
    ++---------------------------------------
     +
    -+This documentation discusses file formats that users are expected to
    -+edit. These can also be listed with 'git help --user-formats'.
    ++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-userformats.txt[]
    ++include::cmds-userinterfaces.txt[]
      
      Configuration Mechanism
      -----------------------
    @@ Makefile: check-docs::
      		sed -e '1,/^### command list/d' \
      		    -e '/^#/d' \
      		    -e '/guide$$/d' \
    -+		    -e '/formats$$/d' \
    ++		    -e '/interfaces$$/d' \
      		    -e 's/[ 	].*//' \
      		    -e 's/^/listed /' command-list.txt; \
      		$(MAKE) -C Documentation print-man1 | \
    @@ builtin/help.c: static enum help_action {
      	HELP_ACTION_ALL = 1,
      	HELP_ACTION_GUIDES,
      	HELP_ACTION_CONFIG,
    -+	HELP_ACTION_USER_FORMATS,
    ++	HELP_ACTION_USER_INTERFACES,
      	HELP_ACTION_CONFIG_FOR_COMPLETION,
      	HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
      } cmd_mode;
    @@ builtin/help.c: static struct option builtin_help_options[] = {
      
      	OPT_CMDMODE('g', "guides", &cmd_mode, N_("print list of useful guides"),
      		    HELP_ACTION_GUIDES),
    -+	OPT_CMDMODE(0, "user-formats", &cmd_mode, N_("print list of user-facing file formats"),
    -+		    HELP_ACTION_USER_FORMATS),
    ++	OPT_CMDMODE(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, "",
    -@@ builtin/help.c: 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]] [<command>]"),
    -+	N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
    +@@ builtin/help.c: static const char * const builtin_help_usage[] = {
    + 	N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
      	"git help [-g|--guides]",
      	"git help [-c|--config]",
    -+	"git help [--user-formats]",
    ++	"git help [--user-interfaces]",
      	NULL
      };
      
    @@ builtin/help.c: int cmd_help(int argc, const char **argv, const char *prefix)
      		opt_mode_usage(argc, "--config-for-completion", help_format);
      		list_config_help(SHOW_CONFIG_VARS);
      		return 0;
    -+	case HELP_ACTION_USER_FORMATS:
    -+		opt_mode_usage(argc, "--user-formats", help_format);
    -+		list_user_formats_help();
    ++	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",
    @@ command-list.txt
      # specified here, which can only have "guide" attribute and nothing
      # else.
      #
    -+# User-facing file formats such as documentation for the .gitmodules,
    -+# .mailmap etc. files lives in man section 5. These entries can only
    -+# have the "userformats" attribute and nothing else.
    ++# 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]
    @@ command-list.txt: git-verify-tag                          ancillaryinterrogators
      git-worktree                            mainporcelain
      git-write-tree                          plumbingmanipulators
     -gitattributes                           guide
    -+gitattributes                           userformats
    - gitcli                                  guide
    +-gitcli                                  guide
    ++gitattributes                           userinterfaces
    ++gitcli                                  userinterfaces
      gitcore-tutorial                        guide
      gitcredentials                          guide
    + gitcvs-migration                        guide
     @@ command-list.txt: gitdiffcore                             guide
      giteveryday                             guide
      gitfaq                                  guide
      gitglossary                             guide
     -githooks                                guide
     -gitignore                               guide
    -+githooks                                userformats
    -+gitignore                               userformats
    ++githooks                                userinterfaces
    ++gitignore                               userinterfaces
      gitk                                    mainporcelain
     -gitmailmap                              guide
     -gitmodules                              guide
    -+gitmailmap                              userformats
    -+gitmodules                              userformats
    ++gitmailmap                              userinterfaces
    ++gitmodules                              userinterfaces
      gitnamespaces                           guide
      gitremote-helpers                       guide
     -gitrepository-layout                    guide
    -+gitrepository-layout                    userformats
    - gitrevisions                            guide
    +-gitrevisions                            guide
    ++gitrepository-layout                    userinterfaces
    ++gitrevisions                            userinterfaces
      gitsubmodules                           guide
      gittutorial                             guide
    + gittutorial-2                           guide
     
      ## help.c ##
     @@ help.c: static struct category_description main_categories[] = {
      	{ CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") },
      	{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
      	{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
    -+	{ CAT_userformats, N_("Git user-facing file formats") },
    ++	{ CAT_userinterfaces, N_("User-facing repository, command and file interfaces") },
      	{ 0, NULL }
      };
      
     @@ help.c: static const char *drop_prefix(const char *name, uint32_t category)
    - 	switch (category)
    - 	{
    - 	case CAT_guide:
    -+	case CAT_userformats:
    - 		if (!skip_prefix(name, "git", &new_name))
    - 			BUG("category #%d but no 'git' prefix?", category);
      		return new_name;
    + 	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",
     @@ help.c: void list_guides_help(void)
      	putchar('\n');
      }
      
    -+void list_user_formats_help(void)
    ++void list_user_interfaces_help(void)
     +{
     +	struct category_description catdesc[] = {
    -+		{ CAT_userformats, N_("Git user-facing file formats:") },
    ++		{ CAT_userinterfaces, N_("User-facing repository, command and file interfaces:") },
     +		{ 0, NULL }
     +	};
     +	print_cmd_by_category(catdesc, NULL);
    @@ help.h: static inline void mput_char(char c, unsigned int num)
      void list_common_cmds_help(void);
      void list_all_cmds_help(int show_external_commands, int show_aliases);
      void list_guides_help(void);
    -+void list_user_formats_help(void);
    ++void list_user_interfaces_help(void);
      
      void list_all_main_cmds(struct string_list *list);
      void list_all_other_cmds(struct string_list *list);
    @@ t/t0012-help.sh: test_expect_success 'invalid usage' '
      	test_expect_code 129 git help -g add &&
      	test_expect_code 129 git help -a -g &&
      
    -+	test_expect_code 129 git help --user-formats add &&
    ++	test_expect_code 129 git help --user-interfaces add &&
     +
      	test_expect_code 129 git help -g -c &&
      	test_expect_code 129 git help --config-for-completion add &&
    @@ t/t0012-help.sh: test_expect_success 'git help succeeds without git.html' '
      	test_cmp expect test-browser.log
      '
      
    -+test_expect_success 'git help --user-formats' '
    -+	git help --user-formats >help.output &&
    ++test_expect_success 'git help --user-interfaces' '
    ++	git help --user-interfaces >help.output &&
     +	grep "^   attributes   " help.output &&
     +	grep "^   mailmap   " help.output
     +'
    @@ t/t0012-help.sh: test_expect_success "'git help -a' section spacing" '
      
      	Low-level Commands / Internal Helpers
     +
    -+	Git user-facing file formats
    ++	User-facing repository, command and file interfaces
      	EOF
      	test_cmp expect actual
      '
 3:  d196bcd1db0 !  4:  a7310898866 git docs: create a "Git file formats and protocols" section
    @@ Metadata
     Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
      ## Commit message ##
    -    git docs: create a "Git file formats and protocols" section
    +    git docs: add a category for file formats, protocols and interfaces
     
    -    Create a new "Git file formats and protocols" section in the main "git help
    -    git" manual page and start moving the documentation that now lives in
    -    "Documentation/technical/*.git" over to it. This compliments the newly
    -    added and adjacent "User-facing file formats" section.
    +    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
    @@ Documentation/Makefile: TECH_DOCS += MyFirstObjectWalk
      TECH_DOCS += technical/hash-function-transition
      TECH_DOCS += technical/http-protocol
     @@ Documentation/Makefile: cmds_txt = cmds-ancillaryinterrogators.txt \
    + 	cmds-synchingrepositories.txt \
      	cmds-synchelpers.txt \
      	cmds-guide.txt \
    - 	cmds-userformats.txt \
    -+	cmds-gitformats.txt \
    ++	cmds-developerinterfaces.txt \
    + 	cmds-userinterfaces.txt \
      	cmds-purehelpers.txt \
      	cmds-foreignscminterface.txt
    - 
     
      ## Documentation/git-bundle.txt ##
     @@ Documentation/git-bundle.txt: using "thin packs", bundles created using exclusions are smaller in
    @@ Documentation/git-bundle.txt: using "thin packs", bundles created using exclusio
      
      OPTIONS
      -------
    +@@ Documentation/git-bundle.txt: verify <file>::
    + 	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.
    + 
     @@ Documentation/git-bundle.txt: You can also see what references it offers:
      $ git ls-remote mybundle
      ----------------
    @@ Documentation/git-help.txt
     @@ Documentation/git-help.txt: SYNOPSIS
      'git help' [-g|--guides]
      'git help' [-c|--config]
    - 'git help' [--user-formats]
    -+'git help' [--git-formats]
    + 'git help' [--user-interfaces]
    ++'git help' [--developer-interfaces]
      
      DESCRIPTION
      -----------
    +@@ Documentation/git-help.txt: 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
     
      ## Documentation/git.txt ##
    -@@ Documentation/git.txt: edit. These can also be listed with 'git help --user-formats'.
    +@@ Documentation/git.txt: linkgit:git-help[1] for more details on the critera.
      
    - include::cmds-userformats.txt[]
    + include::cmds-userinterfaces.txt[]
      
    -+Git file formats and protocols
    -+------------------------------
    ++File formats, protocols and other developer interfaces
    ++------------------------------------------------------
     +
    -+This documentation discusses the file formats and protocols that git
    -+itself uses. These can also be listed with 'git help --git-formats'.
    ++This documentation discusses file formats, over-the-wire protocols and
    ++other git developer interfaces. See `--developer-interfaces` in
    ++linkgit:git-help[1].
     +
    -+include::cmds-gitformats.txt[]
    ++include::cmds-developerinterfaces.txt[]
     +
      Configuration Mechanism
      -----------------------
    @@ builtin/help.c
     @@ builtin/help.c: static enum help_action {
      	HELP_ACTION_GUIDES,
      	HELP_ACTION_CONFIG,
    - 	HELP_ACTION_USER_FORMATS,
    -+	HELP_ACTION_GIT_FORMATS,
    + 	HELP_ACTION_USER_INTERFACES,
    ++	HELP_ACTION_DEVELOPER_INTERFACES,
      	HELP_ACTION_CONFIG_FOR_COMPLETION,
      	HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
      } cmd_mode;
     @@ builtin/help.c: static struct option builtin_help_options[] = {
    - 		    HELP_ACTION_GUIDES),
    - 	OPT_CMDMODE(0, "user-formats", &cmd_mode, N_("print list of user-facing file formats"),
    - 		    HELP_ACTION_USER_FORMATS),
    -+	OPT_CMDMODE(0, "git-formats", &cmd_mode, N_("print list of internal file formats and network protocols"),
    -+		    HELP_ACTION_GIT_FORMATS),
    + 	OPT_CMDMODE(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, "",
     @@ builtin/help.c: static const char * const builtin_help_usage[] = {
      	"git help [-g|--guides]",
      	"git help [-c|--config]",
    - 	"git help [--user-formats]",
    -+	"git help [--git-formats]",
    + 	"git help [--user-interfaces]",
    ++	"git help [--developer-interfaces]",
      	NULL
      };
      
     @@ builtin/help.c: int cmd_help(int argc, const char **argv, const char *prefix)
    - 		opt_mode_usage(argc, "--user-formats", help_format);
    - 		list_user_formats_help();
    + 		opt_mode_usage(argc, "--user-interfaces", help_format);
    + 		list_user_interfaces_help();
      		return 0;
    -+	case HELP_ACTION_GIT_FORMATS:
    -+		opt_mode_usage(argc, "--git-formats", help_format);
    -+		list_git_formats_help();
    ++	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",
    @@ builtin/help.c: int cmd_help(int argc, const char **argv, const char *prefix)
     
      ## command-list.txt ##
     @@
    - # .mailmap etc. files lives in man section 5. These entries can only
    - # have the "userformats" attribute and nothing else.
    + # sections 5 and 7. These entries can only have the "userinterfaces"
    + # attribute and nothing else.
      #
    -+# Git internal file formats and protocols, such as documentation for the
    ++# Git's file formats and protocols, such as documentation for the
     +# *.bundle format lives in man section 5. These entries can only have
    -+# the "gitformats" attribute and nothing else.
    ++# the "developerinterfaces" attribute and nothing else.
     +#
      ### command list (do not change this line)
      # command name                          category [category] [category]
    @@ command-list.txt: gitcvs-migration                        guide
      gitdiffcore                             guide
      giteveryday                             guide
      gitfaq                                  guide
    -+gitformat-bundle                        gitformats
    ++gitformat-bundle                        developerinterfaces
      gitglossary                             guide
    - githooks                                userformats
    - gitignore                               userformats
    + githooks                                userinterfaces
    + gitignore                               userinterfaces
     
      ## help.c ##
     @@ help.c: static struct category_description main_categories[] = {
      	{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
      	{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
    - 	{ CAT_userformats, N_("Git user-facing file formats") },
    -+	{ CAT_gitformats, N_("Git internal file formats and protocols") },
    + 	{ CAT_userinterfaces, N_("User-facing repository, command and file interfaces") },
    ++	{ CAT_developerinterfaces, N_("Developer-facing file file formats, protocols and interfaces") },
      	{ 0, NULL }
      };
      
     @@ help.c: static const char *drop_prefix(const char *name, uint32_t category)
    - 	{
    + 	switch (category) {
      	case CAT_guide:
    - 	case CAT_userformats:
    -+	case CAT_gitformats:
    - 		if (!skip_prefix(name, "git", &new_name))
    - 			BUG("category #%d but no 'git' prefix?", category);
    - 		return new_name;
    -@@ help.c: void list_user_formats_help(void)
    + 	case CAT_userinterfaces:
    ++	case CAT_developerinterfaces:
    + 		prefix = "git";
    + 		if (!skip_prefix(name, prefix, &new_name))
    + 			BUG("'%s' in category #%d should have '%s' prefix",
    +@@ help.c: void list_user_interfaces_help(void)
      	putchar('\n');
      }
      
    -+void list_git_formats_help(void)
    ++void list_developer_interfaces_help(void)
     +{
     +	struct category_description catdesc[] = {
    -+		{ CAT_gitformats, N_("Internal file formats and protocols:") },
    ++		{ CAT_developerinterfaces, N_("File formats, protocols and other developer interfaces:") },
     +		{ 0, NULL }
     +	};
     +	print_cmd_by_category(catdesc, NULL);
    @@ help.h
     @@ help.h: void list_common_cmds_help(void);
      void list_all_cmds_help(int show_external_commands, int show_aliases);
      void list_guides_help(void);
    - void list_user_formats_help(void);
    -+void list_git_formats_help(void);
    + void list_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);
    @@ t/t0012-help.sh
     @@ t/t0012-help.sh: test_expect_success "'git help -a' section spacing" '
      	Low-level Commands / Internal Helpers
      
    - 	Git user-facing file formats
    + 	User-facing repository, command and file interfaces
     +
    -+	Git internal file formats and protocols
    ++	Developer-facing file file formats, protocols and interfaces
      	EOF
      	test_cmp expect actual
      '
 4:  b59e001a4ca !  5:  62f9020a72d docs: move commit-graph format docs to man section 5
    @@ Commit message
         file-format documentation into our main documentation space.
     
         By moving the documentation for the commit-graph format into man
    -    section 5 and the new "gitformats" category. This change is split from
    -    subsequent commits due to the relatively large amount of ASCIIDOC
    -    formatting changes that are required.
    +    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 <avarab@gmail.com>
     
    @@ command-list.txt
     @@ command-list.txt: gitdiffcore                             guide
      giteveryday                             guide
      gitfaq                                  guide
    - gitformat-bundle                        gitformats
    -+gitformat-commit-graph                  gitformats
    + gitformat-bundle                        developerinterfaces
    ++gitformat-bundle                        developerinterfaces
    ++gitformat-commit-graph                  developerinterfaces
      gitglossary                             guide
    - githooks                                userformats
    - gitignore                               userformats
    + githooks                                userinterfaces
    + gitignore                               userinterfaces
 5:  968aa977b67 !  6:  019ec8cf73c docs: move protocol-related docs to man section 5
    @@ Commit message
         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 <avarab@gmail.com>
     
      ## Documentation/Makefile ##
    -@@ Documentation/Makefile: MAN1_TXT += gitweb.txt
    - MAN5_TXT += gitattributes.txt
    - MAN5_TXT += gitformat-bundle.txt
    - MAN5_TXT += gitformat-commit-graph.txt
    -+MAN5_TXT += gitformat-pack-protocol.txt
    -+MAN5_TXT += gitformat-protocol-capabilities.txt
    -+MAN5_TXT += gitformat-protocol-common.txt
    -+MAN5_TXT += gitformat-protocol-v2.txt
    - MAN5_TXT += githooks.txt
    +@@ Documentation/Makefile: 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
    + 
     @@ Documentation/Makefile: TECH_DOCS += technical/long-running-process-protocol
      TECH_DOCS += technical/multi-pack-index
      TECH_DOCS += technical/pack-format
    @@ Documentation/config/lsrefs.txt
      	May be "advertise" (the default), "allow", or "ignore". If "advertise",
      	the server will respond to the client sending "unborn" (as described in
     -	protocol-v2.txt) and will advertise support for this feature during the
    -+	linkgit:gitformat-protocol-v2[5]) and will advertise support for this feature during the
    ++	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
    @@ Documentation/config/protocol.txt: protocol.version::
        in the initial response from the server.
      
     -* `2` - link:technical/protocol-v2.html[wire protocol version 2].
    -+* `2` - Wire protocol version 2, see linkgit:gitformat-protocol-v2[5].
    ++* `2` - Wire protocol version 2, see linkgit:gitprotocol-v2[5].
      
      --
     
    @@ Documentation/git-upload-pack.txt: OPTIONS
     -	link:technical/protocol-v2.html[the Git Wire Protocol, Version
     -	2] documentation. Also understood by
     +	transfer protocols] documentation and "HTTP Transport" in the
    -+	linkgit:gitformat-protocol-v2[5] documentation. Also understood by
    ++	linkgit:gitprotocol-v2[5] documentation. Also understood by
      	linkgit:git-receive-pack[1].
      
      <directory>::
    @@ Documentation/gitformat-bundle.txt: FORMAT
      
      We will use ABNF notation to define the Git bundle format. See
     -link:technical/protocol-common.html for the details.
    -+linkgit:gitformat-protocol-common[5] for the details.
    ++linkgit:gitprotocol-common[5] for the details.
      
      A v2 bundle looks like this:
      
     
    - ## Documentation/technical/pack-protocol.txt => Documentation/gitformat-pack-protocol.txt ##
    -@@
    --Packfile transfer protocols
    --===========================
    -+gitformat-pack-protocol(5)
    -+==========================
    -+
    -+NAME
    -+----
    -+gitformat-pack-protocol - How packs are transferred over-the-wire
    -+
    -+SYNOPSIS
    -+--------
    -+[verse]
    -+<over-the-wire-protocol>
    -+
    -+DESCRIPTION
    -+-----------
    - 
    - Git supports transferring data in packfiles over the ssh://, git://, http:// and
    - file:// transports.  There exist two sets of protocols, one for pushing
    -@@ Documentation/gitformat-pack-protocol.txt: pkt-line Format
    - ---------------
    - 
    - The descriptions below build on the pkt-line format described in
    --protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless
    -+linkgit:gitformat-protocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless
    - otherwise noted the usual pkt-line LF rules apply: the sender SHOULD
    - include a LF, but the receiver MUST NOT complain if it is not present.
    - 
    -@@ Documentation/gitformat-pack-protocol.txt: 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
    -
    - ## Documentation/technical/protocol-capabilities.txt => Documentation/gitformat-protocol-capabilities.txt ##
    + ## Documentation/technical/protocol-capabilities.txt => Documentation/gitprotocol-capabilities.txt ##
     @@
     -Git Protocol Capabilities
     -=========================
    -+gitformat-protocol-capabilities(5)
    -+==================================
    ++gitprotocol-capabilities(5)
    ++===========================
     +
     +NAME
     +----
    -+gitformat-protocol-capabilities - Protocol v0 and v1 capabilities
    ++gitprotocol-capabilities - Protocol v0 and v1 capabilities
     +
     +SYNOPSIS
     +--------
    @@ Documentation/technical/protocol-capabilities.txt => Documentation/gitformat-pro
      
      NOTE: this document describes capabilities for versions 0 and 1 of the pack
     -protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]
    -+protocol. For version 2, please refer to the linkgit:gitformat-protocol-v2[5]
    ++protocol. For version 2, please refer to the linkgit:gitprotocol-v2[5]
      doc.
      
      Servers SHOULD support all capabilities defined in this document.
    -@@ Documentation/gitformat-protocol-capabilities.txt: interleaved with S-R-Q.
    +@@ Documentation/gitprotocol-capabilities.txt: interleaved with S-R-Q.
      multi_ack_detailed
      ------------------
      This is an extension of multi_ack that permits client to better
     -understand the server's in-memory state. See pack-protocol.txt,
    -+understand the server's in-memory state. See linkgit:gitformat-pack-protocol[5],
    ++understand the server's in-memory state. See linkgit:gitprotocol-pack[5],
      section "Packfile Negotiation" for more information.
      
      no-done
    -@@ Documentation/gitformat-protocol-capabilities.txt: a packfile upload and reference update.  If the pushing client requests
    +@@ Documentation/gitprotocol-capabilities.txt: a packfile upload and reference update.  If the pushing client requests
      this capability, after unpacking and updating references the server
      will respond with whether the packfile unpacked successfully and if
      each reference was updated successfully.  If any of those were not
     -successful, it will send back an error message.  See pack-protocol.txt
    -+successful, it will send back an error message.  See linkgit:gitformat-pack-protocol[5]
    ++successful, it will send back an error message.  See linkgit:gitprotocol-pack[5]
      for example messages.
      
      report-status-v2
    -@@ Documentation/gitformat-protocol-capabilities.txt: adding new "option" directives in order to support reference rewritten by
    +@@ Documentation/gitprotocol-capabilities.txt: adding new "option" directives in order to support reference rewritten by
      the "proc-receive" hook.  The "proc-receive" hook may handle a command
      for a pseudo-reference which may create or update a reference with
      different name, new-oid, and old-oid.  While the capability
     -'report-status' cannot report for such case.  See pack-protocol.txt
    -+'report-status' cannot report for such case.  See linkgit:gitformat-pack-protocol[5]
    ++'report-status' cannot report for such case.  See linkgit:gitprotocol-pack[5]
      for details.
      
      delete-refs
    -@@ Documentation/gitformat-protocol-capabilities.txt: packet-line, and must not contain non-printable or whitespace characters. The
    +@@ Documentation/gitprotocol-capabilities.txt: 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.
    @@ Documentation/gitformat-protocol-capabilities.txt: packet-line, and must not con
     +---
     +Part of the linkgit:git[1] suite
     
    - ## Documentation/technical/protocol-common.txt => Documentation/gitformat-protocol-common.txt ##
    + ## Documentation/technical/protocol-common.txt => Documentation/gitprotocol-common.txt ##
     @@
     -Documentation Common to Pack and Http Protocols
     -===============================================
    -+gitformat-protocol-common(5)
    -+============================
    ++gitprotocol-common(5)
    ++=====================
     +
     +NAME
     +----
    -+gitformat-protocol-common - Things common to various protocols
    ++gitprotocol-common - Things common to various protocols
     +
     +SYNOPSIS
     +--------
    @@ Documentation/technical/protocol-common.txt => Documentation/gitformat-protocol-
      
      ABNF Notation
      -------------
    -@@ Documentation/gitformat-protocol-common.txt: Examples (as C-style strings):
    +@@ Documentation/gitprotocol-common.txt: Examples (as C-style strings):
        "000bfoobar\n"    "foobar\n"
        "0004"            ""
      ----
    @@ Documentation/gitformat-protocol-common.txt: Examples (as C-style strings):
     +---
     +Part of the linkgit:git[1] suite
     
    - ## Documentation/technical/protocol-v2.txt => Documentation/gitformat-protocol-v2.txt ##
    + ## Documentation/technical/pack-protocol.txt => Documentation/gitprotocol-pack.txt ##
    +@@
    +-Packfile transfer protocols
    +-===========================
    ++gitprotocol-pack(5)
    ++===================
    ++
    ++NAME
    ++----
    ++gitprotocol-pack - How packs are transferred over-the-wire
    ++
    ++SYNOPSIS
    ++--------
    ++[verse]
    ++<over-the-wire-protocol>
    ++
    ++DESCRIPTION
    ++-----------
    + 
    + Git supports transferring data in packfiles over the ssh://, git://, http:// and
    + file:// transports.  There exist two sets of protocols, one for pushing
    +@@ Documentation/gitprotocol-pack.txt: 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.
    + 
    +@@ Documentation/gitprotocol-pack.txt: Each Extra Parameter takes the form of `<key>=<value>` or `<key>`.
    + 
    + 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
    +@@ Documentation/gitprotocol-pack.txt: 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
    +
    + ## Documentation/technical/protocol-v2.txt => Documentation/gitprotocol-v2.txt ##
     @@
     -Git Wire Protocol, Version 2
     -============================
    -+gitformat-protocol-v2(5)
    -+========================
    ++gitprotocol-v2(5)
    ++=================
     +
     +NAME
     +----
    -+gitformat-protocol-v2 - Git Wire Protocol, Version 2
    ++gitprotocol-v2 - Git Wire Protocol, Version 2
     +
     +SYNOPSIS
     +--------
    @@ Documentation/technical/protocol-v2.txt => Documentation/gitformat-protocol-v2.t
      
      This document presents a specification for a version 2 of Git's wire
      protocol.  Protocol v2 will improve upon v1 in the following ways:
    -@@ Documentation/gitformat-protocol-v2.txt: Packet-Line Framing
    +@@ Documentation/gitprotocol-v2.txt: Packet-Line Framing
      -------------------
      
      All communication is done using packet-line framing, just as in v1.  See
     -`Documentation/technical/pack-protocol.txt` and
    -+linkgit:gitformat-pack-protocol[5] and
    - `Documentation/technical/protocol-common.txt` for more information.
    +-`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:
    -@@ Documentation/gitformat-protocol-v2.txt: Initial Client Request
    + 
    +@@ Documentation/gitprotocol-v2.txt: Initial Client Request
      In general a client can request to speak protocol v2 by sending
      `version=2` through the respective side-channel for the transport being
      used which inevitably sets `GIT_PROTOCOL`.  More information can be
     -found in `pack-protocol.txt` and `http-protocol.txt`, as well as the
    -+found in linkgit:gitformat-pack-protocol[5] and `http-protocol.txt`, as well as the
    ++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.
      
    -@@ Documentation/gitformat-protocol-v2.txt: and associated requested information, each separated by a single space.
    +@@ Documentation/gitprotocol-v2.txt: and associated requested information, each separated by a single space.
      	attr = "size"
      
      	obj-info = obj-id SP obj-size
    @@ Documentation/technical/api-simple-ipc.txt: client and an optional response mess
      with a flush packet.
      
     -The pkt-line routines (Documentation/technical/protocol-common.txt)
    -+The pkt-line routines (linkgit:gitformat-protocol-common[5])
    ++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
    @@ Documentation/technical/http-protocol.txt: smart server reply:
      
      The client may send Extra Parameters (see
     -Documentation/technical/pack-protocol.txt) as a colon-separated string
    -+linkgit:gitformat-pack-protocol[5]) as a colon-separated string
    ++linkgit:gitprotocol-pack[5]) as a colon-separated string
      in the Git-Protocol HTTP header.
      
      Uses the `--http-backend-info-refs` option to
    @@ Documentation/technical/http-protocol.txt: References
      http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
     -link:technical/pack-protocol.html
     -link:technical/protocol-capabilities.html
    -+linkgit:gitformat-pack-protocol[5]
    -+linkgit:gitformat-protocol-capabilities[5]
    ++linkgit:gitprotocol-pack[5]
    ++linkgit:gitprotocol-capabilities[5]
     
      ## Documentation/technical/long-running-process-protocol.txt ##
     @@ Documentation/technical/long-running-process-protocol.txt: Long-running process protocol
    @@ Documentation/technical/long-running-process-protocol.txt: Long-running process
      This protocol is used when Git needs to communicate with an external
      process throughout the entire life of a single Git command. All
     -communication is in pkt-line format (see technical/protocol-common.txt)
    -+communication is in pkt-line format (see linkgit:gitformat-protocol-common[5])
    ++communication is in pkt-line format (see linkgit:gitprotocol-common[5])
      over standard input and standard output.
      
      Handshake
     
    + ## Documentation/technical/packfile-uri.txt ##
    +@@ Documentation/technical/packfile-uri.txt: 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
    +
      ## Documentation/technical/partial-clone.txt ##
     @@ Documentation/technical/partial-clone.txt: Design Details
        upload-pack negotiation.
      +
      This uses the existing capability discovery mechanism.
     -See "filter" in Documentation/technical/pack-protocol.txt.
    -+See "filter" in linkgit:gitformat-pack-protocol[5].
    ++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.
     
      ## command-list.txt ##
    -@@ command-list.txt: giteveryday                             guide
    +@@ command-list.txt: gitdiffcore                             guide
    + giteveryday                             guide
      gitfaq                                  guide
    - gitformat-bundle                        gitformats
    - gitformat-commit-graph                  gitformats
    -+gitformat-pack-protocol                 gitformats
    -+gitformat-protocol-capabilities         gitformats
    -+gitformat-protocol-common               gitformats
    -+gitformat-protocol-v2                   gitformats
    + gitformat-bundle                        developerinterfaces
    +-gitformat-bundle                        developerinterfaces
    + gitformat-commit-graph                  developerinterfaces
      gitglossary                             guide
    - githooks                                userformats
    - gitignore                               userformats
    + githooks                                userinterfaces
    +@@ command-list.txt: 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
    +
    + ## refspec.h ##
    +@@ refspec.h: int valid_remote_name(const char *name);
    + struct strvec;
    + /*
    +  * Determine what <prefix> 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);
     
      ## t/t5551-http-fetch-smart.sh ##
     @@ t/t5551-http-fetch-smart.sh: test_expect_success 'no-op half-auth fetch does not require a password' '
 6:  858ce9c6999 !  7:  5b081e6637a docs: move pack format docs to man section 5
    @@ Documentation/Makefile: MAN1_TXT += gitweb.txt
      MAN5_TXT += gitformat-commit-graph.txt
     +MAN5_TXT += gitformat-index.txt
     +MAN5_TXT += gitformat-pack-cruft.txt
    - MAN5_TXT += gitformat-pack-protocol.txt
     +MAN5_TXT += gitformat-pack.txt
    - MAN5_TXT += gitformat-protocol-capabilities.txt
    - MAN5_TXT += gitformat-protocol-common.txt
    - MAN5_TXT += gitformat-protocol-v2.txt
     +MAN5_TXT += gitformat-signature.txt
      MAN5_TXT += githooks.txt
      MAN5_TXT += gitignore.txt
    @@ Documentation/technical/chunk-format.txt => Documentation/gitformat-chunk.txt
      scanning a small "table of contents" for the remaining data. This common
      format is used by the `commit-graph` and `multi-pack-index` files. See
     -link:technical/pack-format.html[the `multi-pack-index` format] and
    --the `commit-graph` format in linkgit:gitformat-commit-graph[5] for
     +the `multi-pack-index` format in linkgit:gitformat-pack[5] and
    -+link:technical/commit-graph-format.html[the `commit-graph` format] for
    + 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
     @@ Documentation/gitformat-chunk.txt: 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
    @@ Documentation/gitformat-pack-cruft.txt: which aren't already stored in an earlie
     +---
     +Part of the linkgit:git[1] suite
     
    - ## Documentation/gitformat-pack-protocol.txt ##
    -@@ Documentation/gitformat-pack-protocol.txt: 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.
    -
      ## Documentation/technical/pack-format.txt => Documentation/gitformat-pack.txt ##
     @@
     -Git pack format
    @@ Documentation/technical/pack-format.txt => Documentation/gitformat-pack.txt
     +linkgit:git-gc[1] and linkgit:git-pack-objects[1].
     +
     +The pack format is also used over-the-wire, see
    -+e.g. linkgit:gitformat-protocol-v2[5], as well as being a part of
    ++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
    @@ Documentation/gitformat-signature.txt: Date:   Wed Jun 15 09:13:29 2016 +0000
     +---
     +Part of the linkgit:git[1] suite
     
    + ## Documentation/gitprotocol-pack.txt ##
    +@@ Documentation/gitprotocol-pack.txt: 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.
    +
      ## Documentation/howto/recover-corrupted-object-harder.txt ##
     @@ Documentation/howto/recover-corrupted-object-harder.txt: 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
    @@ command-list.txt
     @@ command-list.txt: gitdiffcore                             guide
      giteveryday                             guide
      gitfaq                                  guide
    - gitformat-bundle                        gitformats
    -+gitformat-chunk                         gitformats
    - gitformat-commit-graph                  gitformats
    -+gitformat-index                         gitformats
    -+gitformat-pack                          gitformats
    -+gitformat-pack-cruft                    gitformats
    - gitformat-pack-protocol                 gitformats
    - gitformat-protocol-capabilities         gitformats
    - gitformat-protocol-common               gitformats
    - gitformat-protocol-v2                   gitformats
    -+gitformat-signature                     gitformats
    + 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                                userformats
    - gitignore                               userformats
    + githooks                                userinterfaces
    + gitignore                               userinterfaces
     
      ## pack-revindex.h ##
     @@
 7:  499ee582644 !  8:  8f8214addfd docs: move http-protocol docs to man section 5
    @@ Commit message
         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
      ## Documentation/Makefile ##
    -@@ Documentation/Makefile: MAN5_TXT += gitformat-pack-protocol.txt
    - MAN5_TXT += gitformat-pack.txt
    - MAN5_TXT += gitformat-protocol-capabilities.txt
    - MAN5_TXT += gitformat-protocol-common.txt
    -+MAN5_TXT += gitformat-protocol-http.txt
    - MAN5_TXT += gitformat-protocol-v2.txt
    - MAN5_TXT += gitformat-signature.txt
    - MAN5_TXT += githooks.txt
    +@@ Documentation/Makefile: 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
     @@ Documentation/Makefile: TECH_DOCS += SubmittingPatches
      TECH_DOCS += ToolsForGit
      TECH_DOCS += technical/bitmap-format
    @@ Documentation/git-upload-pack.txt: OPTIONS
      	`$GIT_URL/info/refs?service=git-upload-pack` requests. See
     -	"Smart Clients" in link:technical/http-protocol.html[the HTTP
     -	transfer protocols] documentation and "HTTP Transport" in the
    --	linkgit:gitformat-protocol-v2[5] documentation. Also understood by
    -+	"Smart Clients" in linkgit:gitformat-protocol-http[5] and
    -+	"HTTP Transport" in link:technical/protocol-v2.html[the Git
    -+	Wire Protocol, Version 2] documentation. Also understood by
    +-	linkgit: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].
      
      <directory>::
     
    - ## Documentation/gitformat-pack-protocol.txt ##
    -@@ Documentation/gitformat-pack-protocol.txt: Git supports transferring data in packfiles over the ssh://, git://, http:// and
    - file:// transports.  There exist two sets of protocols, one for pushing
    - data from a client to a server and another for fetching data from a
    - server to a client.  The three transports (ssh, git, file) use the same
    --protocol to transfer data. http is documented in http-protocol.txt.
    -+protocol to transfer data. http is documented in linkgit:gitformat-protocol-http[5].
    - 
    - The processes invoked in the canonical Git implementation are 'upload-pack'
    - on the server side and 'fetch-pack' on the client side for fetching data;
    -
    - ## Documentation/technical/http-protocol.txt => Documentation/gitformat-protocol-http.txt ##
    + ## Documentation/technical/http-protocol.txt => Documentation/gitprotocol-http.txt ##
     @@
     -HTTP transfer protocols
     -=======================
    -+gitformat-protocol-http(5)
    -+==========================
    ++gitprotocol-http(5)
    ++===================
     +
     +NAME
     +----
    -+gitformat-protocol-http - Git HTTP-based protocols
    ++gitprotocol-http - Git HTTP-based protocols
     +
     +
     +SYNOPSIS
    @@ Documentation/technical/http-protocol.txt => Documentation/gitformat-protocol-ht
      
      Git supports two HTTP based transfer protocols.  A "dumb" protocol
      which requires only a standard HTTP server on the server end of the
    -@@ Documentation/gitformat-protocol-http.txt: the id obtained through ref discovery as old_id.
    +@@ Documentation/gitprotocol-http.txt: the id obtained through ref discovery as old_id.
      
      TODO: Document this further.
      
    @@ Documentation/gitformat-protocol-http.txt: the id obtained through ref discovery
     +SEE ALSO
     +--------
     +
    - linkgit:gitformat-pack-protocol[5]
    - linkgit:gitformat-protocol-capabilities[5]
    + linkgit:gitprotocol-pack[5]
    + linkgit:gitprotocol-capabilities[5]
     +
     +GIT
     +---
     +Part of the linkgit:git[1] suite
     
    - ## Documentation/gitformat-protocol-v2.txt ##
    -@@ Documentation/gitformat-protocol-v2.txt: Initial Client Request
    + ## Documentation/gitprotocol-pack.txt ##
    +@@ Documentation/gitprotocol-pack.txt: 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;
    +
    + ## Documentation/gitprotocol-v2.txt ##
    +@@ Documentation/gitprotocol-v2.txt: Initial Client Request
      In general a client can request to speak protocol v2 by sending
      `version=2` through the respective side-channel for the transport being
      used which inevitably sets `GIT_PROTOCOL`.  More information can be
    --found in linkgit:gitformat-pack-protocol[5] and `http-protocol.txt`, as well as the
    -+found in linkgit:gitformat-pack-protocol[5] and linkgit:gitformat-protocol-http[5], as well as the
    +-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.
      
    -@@ Documentation/gitformat-protocol-v2.txt: HTTP Transport
    +@@ Documentation/gitprotocol-v2.txt: HTTP Transport
      ~~~~~~~~~~~~~~
      
      When using the http:// or https:// transport a client makes a "smart"
     -info/refs request as described in `http-protocol.txt` and requests that
    -+info/refs request as described in linkgit:gitformat-protocol-http[5] and requests that
    ++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
     
      ## command-list.txt ##
    -@@ command-list.txt: gitformat-pack-cruft                    gitformats
    - gitformat-pack-protocol                 gitformats
    - gitformat-protocol-capabilities         gitformats
    - gitformat-protocol-common               gitformats
    -+gitformat-protocol-http                 gitformats
    - gitformat-protocol-v2                   gitformats
    - gitformat-signature                     gitformats
    - gitglossary                             guide
    +@@ command-list.txt: gitmodules                              userinterfaces
    + gitnamespaces                           guide
    + gitprotocol-capabilities                developerinterfaces
    + gitprotocol-common                      developerinterfaces
    ++gitprotocol-http                       developerinterfaces
    + gitprotocol-pack                        developerinterfaces
    + gitprotocol-v2                          developerinterfaces
    + gitremote-helpers                       guide
 8:  f186950e673 !  9:  19601ac36a2 docs: move multi-pack-index docs to man section 5
    @@ Documentation/Makefile: MAN5_TXT += gitformat-bundle.txt
      MAN5_TXT += gitformat-index.txt
     +MAN5_TXT += gitformat-multi-pack-index.txt
      MAN5_TXT += gitformat-pack-cruft.txt
    - MAN5_TXT += gitformat-pack-protocol.txt
      MAN5_TXT += gitformat-pack.txt
    + MAN5_TXT += gitformat-signature.txt
     @@ Documentation/Makefile: TECH_DOCS += ToolsForGit
      TECH_DOCS += technical/bitmap-format
      TECH_DOCS += technical/hash-function-transition
    @@ Documentation/git-multi-pack-index.txt: $ git multi-pack-index verify
      --------
     -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.
    @@ Documentation/gitformat-pack.txt: packs arranged in MIDX order (with the preferr
      Part of the linkgit:git[1] suite
     
      ## command-list.txt ##
    -@@ command-list.txt: gitformat-bundle                        gitformats
    - gitformat-chunk                         gitformats
    - gitformat-commit-graph                  gitformats
    - gitformat-index                         gitformats
    -+gitformat-multi-pack-index              gitformats
    - gitformat-pack                          gitformats
    - gitformat-pack-cruft                    gitformats
    - gitformat-pack-protocol                 gitformats
    +@@ command-list.txt: 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
-- 
2.37.1.1095.g64a1e8362fd


^ permalink raw reply	[flat|nested] 112+ messages in thread

* [PATCH v5 1/9] help.c: BUG() out if "help --guides" can't remove "git" prefixes
  2022-07-21 16:13       ` [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
@ 2022-07-21 16:13         ` Ævar Arnfjörð Bjarmason
  2022-07-21 16:13         ` [PATCH v5 2/9] git help doc: use "<doc>" instead of "<guide>" Ævar Arnfjörð Bjarmason
                           ` (9 subsequent siblings)
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-21 16:13 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 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)
-- 
2.37.1.1095.g64a1e8362fd


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v5 2/9] git help doc: use "<doc>" instead of "<guide>"
  2022-07-21 16:13       ` [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
  2022-07-21 16:13         ` [PATCH v5 1/9] help.c: BUG() out if "help --guides" can't remove "git" prefixes Ævar Arnfjörð Bjarmason
@ 2022-07-21 16:13         ` Ævar Arnfjörð Bjarmason
  2022-07-21 16:13         ` [PATCH v5 3/9] git docs: add a category for user-facing file, repo and command UX Ævar Arnfjörð Bjarmason
                           ` (8 subsequent siblings)
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-21 16:13 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

Replace the use of "<guide>" originally introduced (as "GUIDE") in
a133737b809 (doc: include --guide option description for "git help",
2013-04-02) with the more generic "<doc>". The "<doc>" placeholder is
more generic, and one we'll be able to use as we introduce new
documentation categories.

Let's also add "<doc>" 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 <avarab@gmail.com>
---
 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]] [<command>|<guide>]
+'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]
 'git help' [-g|--guides]
 'git help' [-c|--config]
 
 DESCRIPTION
 -----------
 
-With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
+With no options and no '<command>' or '<doc>' 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]] [<command>]"),
+	N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
 	"git help [-g|--guides]",
 	"git help [-c|--config]",
 	NULL
-- 
2.37.1.1095.g64a1e8362fd


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v5 3/9] git docs: add a category for user-facing file, repo and command UX
  2022-07-21 16:13       ` [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
  2022-07-21 16:13         ` [PATCH v5 1/9] help.c: BUG() out if "help --guides" can't remove "git" prefixes Ævar Arnfjörð Bjarmason
  2022-07-21 16:13         ` [PATCH v5 2/9] git help doc: use "<doc>" instead of "<guide>" Ævar Arnfjörð Bjarmason
@ 2022-07-21 16:13         ` Ævar Arnfjörð Bjarmason
  2022-07-21 16:13         ` [PATCH v5 4/9] git docs: add a category for file formats, protocols and interfaces Ævar Arnfjörð Bjarmason
                           ` (7 subsequent siblings)
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-21 16:13 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 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]] [<command>|<doc>]
 '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]] [<command>|<doc>]"),
 	"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
 '
-- 
2.37.1.1095.g64a1e8362fd


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v5 4/9] git docs: add a category for file formats, protocols and interfaces
  2022-07-21 16:13       ` [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
                           ` (2 preceding siblings ...)
  2022-07-21 16:13         ` [PATCH v5 3/9] git docs: add a category for user-facing file, repo and command UX Ævar Arnfjörð Bjarmason
@ 2022-07-21 16:13         ` Ævar Arnfjörð Bjarmason
  2022-07-21 17:31           ` Eric Sunshine
  2022-07-21 16:13         ` [PATCH v5 5/9] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
                           ` (6 subsequent siblings)
  10 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-21 16:13 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 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 <file>::
 	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
 '
-- 
2.37.1.1095.g64a1e8362fd


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v5 5/9] docs: move commit-graph format docs to man section 5
  2022-07-21 16:13       ` [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
                           ` (3 preceding siblings ...)
  2022-07-21 16:13         ` [PATCH v5 4/9] git docs: add a category for file formats, protocols and interfaces Ævar Arnfjörð Bjarmason
@ 2022-07-21 16:13         ` Ævar Arnfjörð Bjarmason
  2022-07-21 16:13         ` [PATCH v5 6/9] docs: move protocol-related " Ævar Arnfjörð Bjarmason
                           ` (5 subsequent siblings)
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-21 16:13 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 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
-- 
2.37.1.1095.g64a1e8362fd


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v5 6/9] docs: move protocol-related docs to man section 5
  2022-07-21 16:13       ` [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
                           ` (4 preceding siblings ...)
  2022-07-21 16:13         ` [PATCH v5 5/9] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
@ 2022-07-21 16:13         ` Ævar Arnfjörð Bjarmason
  2022-07-21 16:13         ` [PATCH v5 7/9] docs: move pack format " Ævar Arnfjörð Bjarmason
                           ` (4 subsequent siblings)
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-21 16:13 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 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].
 
 <directory>::
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]
+<over-the-wire-protocol>
+
+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]
+<over-the-wire-protocol>
+
+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]
+<over-the-wire-protocol>
+
+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 `<key>=<value>` or `<key>`.
 
 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]
+<over-the-wire-protocol>
+
+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 <prefix> 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
 '
-- 
2.37.1.1095.g64a1e8362fd


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v5 7/9] docs: move pack format docs to man section 5
  2022-07-21 16:13       ` [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
                           ` (5 preceding siblings ...)
  2022-07-21 16:13         ` [PATCH v5 6/9] docs: move protocol-related " Ævar Arnfjörð Bjarmason
@ 2022-07-21 16:13         ` Ævar Arnfjörð Bjarmason
  2022-07-21 16:13         ` [PATCH v5 8/9] docs: move http-protocol " Ævar Arnfjörð Bjarmason
                           ` (3 subsequent siblings)
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-21 16:13 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 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)>
+<over-the-wire protocol>
+
+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
-- 
2.37.1.1095.g64a1e8362fd


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v5 8/9] docs: move http-protocol docs to man section 5
  2022-07-21 16:13       ` [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
                           ` (6 preceding siblings ...)
  2022-07-21 16:13         ` [PATCH v5 7/9] docs: move pack format " Ævar Arnfjörð Bjarmason
@ 2022-07-21 16:13         ` Ævar Arnfjörð Bjarmason
  2022-07-21 16:13         ` [PATCH v5 9/9] docs: move multi-pack-index " Ævar Arnfjörð Bjarmason
                           ` (2 subsequent siblings)
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-21 16:13 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 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].
 
 <directory>::
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]
+<over-the-wire-protocol>
+
+
+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
-- 
2.37.1.1095.g64a1e8362fd


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v5 9/9] docs: move multi-pack-index docs to man section 5
  2022-07-21 16:13       ` [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
                           ` (7 preceding siblings ...)
  2022-07-21 16:13         ` [PATCH v5 8/9] docs: move http-protocol " Ævar Arnfjörð Bjarmason
@ 2022-07-21 16:13         ` Ævar Arnfjörð Bjarmason
  2022-07-21 18:13         ` [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories Junio C Hamano
  2022-07-28 16:46         ` [PATCH v6 " Ævar Arnfjörð Bjarmason
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-21 16:13 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 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
-- 
2.37.1.1095.g64a1e8362fd


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* Re: [PATCH v5 4/9] git docs: add a category for file formats, protocols and interfaces
  2022-07-21 16:13         ` [PATCH v5 4/9] git docs: add a category for file formats, protocols and interfaces Ævar Arnfjörð Bjarmason
@ 2022-07-21 17:31           ` Eric Sunshine
  0 siblings, 0 replies; 112+ messages in thread
From: Eric Sunshine @ 2022-07-21 17:31 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: Git List, Junio C Hamano, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long

/On Thu, Jul 21, 2022 at 12:14 PM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
> 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.

nit: s/compliments/complements/

> 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 <avarab@gmail.com>

^ permalink raw reply	[flat|nested] 112+ messages in thread

* Re: [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories
  2022-07-21 16:13       ` [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
                           ` (8 preceding siblings ...)
  2022-07-21 16:13         ` [PATCH v5 9/9] docs: move multi-pack-index " Ævar Arnfjörð Bjarmason
@ 2022-07-21 18:13         ` Junio C Hamano
  2022-07-28 16:46         ` [PATCH v6 " Ævar Arnfjörð Bjarmason
  10 siblings, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-07-21 18:13 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: git, Eric Sunshine, Philippe Blain, Derrick Stolee, Taylor Blau,
	Jeff King, Teng Long

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

> See v3[1] for lofty goals. The changes since v4 are mainly to rename
> the "user formats" and "developer formats" to "user interfaces" and
> "developer interfaces".
>
> Now:
>
> 	$ ./git help --user-interfaces

Hopefully this is a much better choice of words.  "formats" would
have had a very high chance of getting misunderstood and confusing
readers.  The interaction with hooks (e.g. you stop the operation X
that asks the hook's decision by writing hooks/pre-X that exits with
non-zero status) would probably be much better understood if it is
described as "interface" than "format".

> And for "--developer-interfaces" (I wondered about calling this --apis):

"api" might be less misunderstanding-prone, but both should probably
be OK.  Again, much better than calling it "format".

Thanks.



^ permalink raw reply	[flat|nested] 112+ messages in thread

* [PATCH v6 0/9] docs: create & use "(user|developer) interfaces" categories
  2022-07-21 16:13       ` [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
                           ` (9 preceding siblings ...)
  2022-07-21 18:13         ` [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories Junio C Hamano
@ 2022-07-28 16:46         ` Ævar Arnfjörð Bjarmason
  2022-07-28 16:46           ` [PATCH v6 1/9] help.c: BUG() out if "help --guides" can't remove "git" prefixes Ævar Arnfjörð Bjarmason
                             ` (10 more replies)
  10 siblings, 11 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-28 16:46 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

See the v5 for a general overview:
https://lore.kernel.org/git/cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com/

This trivial v6 fixes a grammar error in a commit message pointed-out
by Eric Sunshine, thanks Eric!

Ævar Arnfjörð Bjarmason (9):
  help.c: BUG() out if "help --guides" can't remove "git" prefixes
  git help doc: use "<doc>" instead of "<guide>"
  git docs: add a category for user-facing file, repo and command UX
  git docs: add a category for file formats, protocols and interfaces
  docs: move commit-graph format docs to man section 5
  docs: move protocol-related docs to man section 5
  docs: move pack format docs to man section 5
  docs: move http-protocol docs to man section 5
  docs: move multi-pack-index docs to man section 5

 Documentation/Makefile                        | 26 +++++-----
 Documentation/config/lsrefs.txt               |  2 +-
 Documentation/config/pack.txt                 |  2 +-
 Documentation/config/protocol.txt             |  2 +-
 Documentation/git-bundle.txt                  | 13 +++--
 Documentation/git-commit-graph.txt            |  5 ++
 Documentation/git-help.txt                    | 27 ++++++++--
 Documentation/git-multi-pack-index.txt        |  6 +--
 Documentation/git-upload-pack.txt             |  7 ++-
 Documentation/git.txt                         | 17 +++++++
 ...bundle-format.txt => gitformat-bundle.txt} | 44 ++++++++++++++---
 .../chunk-format.txt => gitformat-chunk.txt}  | 29 ++++++++---
 ...-format.txt => gitformat-commit-graph.txt} | 49 +++++++++++++------
 .../index-format.txt => gitformat-index.txt}  | 22 ++++++++-
 ...dex.txt => gitformat-multi-pack-index.txt} | 20 +++++++-
 ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++-
 .../pack-format.txt => gitformat-pack.txt}    | 39 +++++++++++++--
 ...ure-format.txt => gitformat-signature.txt} | 21 ++++++--
 ...ities.txt => gitprotocol-capabilities.txt} | 28 ++++++++---
 ...ocol-common.txt => gitprotocol-common.txt} | 23 ++++++++-
 ...http-protocol.txt => gitprotocol-http.txt} | 35 ++++++++++---
 ...pack-protocol.txt => gitprotocol-pack.txt} | 28 ++++++++---
 .../protocol-v2.txt => gitprotocol-v2.txt}    | 27 +++++++---
 .../howto/recover-corrupted-object-harder.txt |  2 +-
 Documentation/lint-man-section-order.perl     |  3 ++
 Documentation/technical/api-simple-ipc.txt    |  2 +-
 .../technical/hash-function-transition.txt    |  2 +-
 .../long-running-process-protocol.txt         |  2 +-
 Documentation/technical/packfile-uri.txt      |  2 +-
 Documentation/technical/partial-clone.txt     |  2 +-
 Documentation/user-manual.txt                 |  2 +-
 Makefile                                      |  1 +
 builtin/help.c                                | 20 +++++++-
 cache.h                                       |  3 +-
 command-list.txt                              | 38 +++++++++++---
 help.c                                        | 34 ++++++++++++-
 help.h                                        |  2 +
 pack-revindex.h                               |  2 +-
 refspec.h                                     |  2 +-
 t/t0012-help.sh                               | 14 +++++-
 t/t5551-http-fetch-smart.sh                   |  4 +-
 41 files changed, 508 insertions(+), 123 deletions(-)
 rename Documentation/{technical/bundle-format.txt => gitformat-bundle.txt} (79%)
 rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (89%)
 rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (87%)
 rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)
 rename Documentation/{technical/multi-pack-index.txt => gitformat-multi-pack-index.txt} (94%)
 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%)
 rename Documentation/{technical/protocol-capabilities.txt => gitprotocol-capabilities.txt} (96%)
 rename Documentation/{technical/protocol-common.txt => gitprotocol-common.txt} (89%)
 rename Documentation/{technical/http-protocol.txt => gitprotocol-http.txt} (97%)
 rename Documentation/{technical/pack-protocol.txt => gitprotocol-pack.txt} (98%)
 rename Documentation/{technical/protocol-v2.txt => gitprotocol-v2.txt} (97%)

Range-diff against v5:
 1:  b0bb29bb131 =  1:  f3588319057 help.c: BUG() out if "help --guides" can't remove "git" prefixes
 2:  2ec00f81552 =  2:  80322d44ea5 git help doc: use "<doc>" instead of "<guide>"
 3:  31be7d01c50 =  3:  0d22eb645bd git docs: add a category for user-facing file, repo and command UX
 4:  a7310898866 !  4:  c25f8ec9bf5 git docs: add a category for file formats, protocols and interfaces
    @@ Commit message
         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,
    +    to it. This complements the newly added and adjacent "Repository,
         command and file interfaces" section.
     
         This makes the technical documentation more accessible and
 5:  62f9020a72d =  5:  466dbd2a993 docs: move commit-graph format docs to man section 5
 6:  019ec8cf73c =  6:  9a551b2d53a docs: move protocol-related docs to man section 5
 7:  5b081e6637a =  7:  92be18b95d9 docs: move pack format docs to man section 5
 8:  8f8214addfd =  8:  a8a883ebf85 docs: move http-protocol docs to man section 5
 9:  19601ac36a2 =  9:  ecfda8c6770 docs: move multi-pack-index docs to man section 5
-- 
2.37.1.1197.g7ed548b7807


^ permalink raw reply	[flat|nested] 112+ messages in thread

* [PATCH v6 1/9] help.c: BUG() out if "help --guides" can't remove "git" prefixes
  2022-07-28 16:46         ` [PATCH v6 " Ævar Arnfjörð Bjarmason
@ 2022-07-28 16:46           ` Ævar Arnfjörð Bjarmason
  2022-07-30  0:17             ` Junio C Hamano
  2022-07-28 16:46           ` [PATCH v6 2/9] git help doc: use "<doc>" instead of "<guide>" Ævar Arnfjörð Bjarmason
                             ` (9 subsequent siblings)
  10 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-28 16:46 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 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)
-- 
2.37.1.1197.g7ed548b7807


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v6 2/9] git help doc: use "<doc>" instead of "<guide>"
  2022-07-28 16:46         ` [PATCH v6 " Ævar Arnfjörð Bjarmason
  2022-07-28 16:46           ` [PATCH v6 1/9] help.c: BUG() out if "help --guides" can't remove "git" prefixes Ævar Arnfjörð Bjarmason
@ 2022-07-28 16:46           ` Ævar Arnfjörð Bjarmason
  2022-07-28 16:46           ` [PATCH v6 3/9] git docs: add a category for user-facing file, repo and command UX Ævar Arnfjörð Bjarmason
                             ` (8 subsequent siblings)
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-28 16:46 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

Replace the use of "<guide>" originally introduced (as "GUIDE") in
a133737b809 (doc: include --guide option description for "git help",
2013-04-02) with the more generic "<doc>". The "<doc>" placeholder is
more generic, and one we'll be able to use as we introduce new
documentation categories.

Let's also add "<doc>" 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 <avarab@gmail.com>
---
 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]] [<command>|<guide>]
+'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]
 'git help' [-g|--guides]
 'git help' [-c|--config]
 
 DESCRIPTION
 -----------
 
-With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
+With no options and no '<command>' or '<doc>' 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]] [<command>]"),
+	N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
 	"git help [-g|--guides]",
 	"git help [-c|--config]",
 	NULL
-- 
2.37.1.1197.g7ed548b7807


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v6 3/9] git docs: add a category for user-facing file, repo and command UX
  2022-07-28 16:46         ` [PATCH v6 " Ævar Arnfjörð Bjarmason
  2022-07-28 16:46           ` [PATCH v6 1/9] help.c: BUG() out if "help --guides" can't remove "git" prefixes Ævar Arnfjörð Bjarmason
  2022-07-28 16:46           ` [PATCH v6 2/9] git help doc: use "<doc>" instead of "<guide>" Ævar Arnfjörð Bjarmason
@ 2022-07-28 16:46           ` Ævar Arnfjörð Bjarmason
  2022-07-28 16:46           ` [PATCH v6 4/9] git docs: add a category for file formats, protocols and interfaces Ævar Arnfjörð Bjarmason
                             ` (7 subsequent siblings)
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-28 16:46 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 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]] [<command>|<doc>]
 'git help' [-g|--guides]
 'git help' [-c|--config]
+'git help' [--user-interfaces]
 
 DESCRIPTION
 -----------
@@ -69,6 +70,19 @@ OPTIONS
 --guides::
 	Prints a list of the Git concept guides on the standard output.
 
+--user-interfaces::
+	Prints a list of the repository, command and file interfaces
+	documentation on the standard output.
++
+In-repository file interfaces such as `.git/info/exclude` are
+documented here (see linkgit:gitrepository-layout[5]), as well as
+in-tree configuration such as `.mailmap` (see linkgit:gitmailmap[5]).
++
+This section of the documentation also covers general or widespread
+user-interface conventions (e.g. linkgit:gitcli[7]), and
+pseudo-configuration such as the file-based `.git/hooks/*` interface
+described in linkgit:githooks[5].
+
 -i::
 --info::
 	Display manual page for the command in the 'info' format. The
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 47a6095ff40..945a1ebd3b1 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -339,6 +339,14 @@ The following documentation pages are guides about Git concepts.
 
 include::cmds-guide.txt[]
 
+Repository, command and file interfaces
+---------------------------------------
+
+This documentation discusses repository and command interfaces which
+users are expected to interact with directly. See `--user-formats` in
+linkgit:git-help[1] for more details on the critera.
+
+include::cmds-userinterfaces.txt[]
 
 Configuration Mechanism
 -----------------------
diff --git a/Makefile b/Makefile
index 1624471badc..ea0ef7df734 100644
--- a/Makefile
+++ b/Makefile
@@ -3532,6 +3532,7 @@ check-docs::
 		sed -e '1,/^### command list/d' \
 		    -e '/^#/d' \
 		    -e '/guide$$/d' \
+		    -e '/interfaces$$/d' \
 		    -e 's/[ 	].*//' \
 		    -e 's/^/listed /' command-list.txt; \
 		$(MAKE) -C Documentation print-man1 | \
diff --git a/builtin/help.c b/builtin/help.c
index dec82d1be27..1ab1c8a0dd7 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -43,6 +43,7 @@ static enum help_action {
 	HELP_ACTION_ALL = 1,
 	HELP_ACTION_GUIDES,
 	HELP_ACTION_CONFIG,
+	HELP_ACTION_USER_INTERFACES,
 	HELP_ACTION_CONFIG_FOR_COMPLETION,
 	HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
 } cmd_mode;
@@ -69,6 +70,9 @@ static struct option builtin_help_options[] = {
 
 	OPT_CMDMODE('g', "guides", &cmd_mode, N_("print list of useful guides"),
 		    HELP_ACTION_GUIDES),
+	OPT_CMDMODE(0, "user-interfaces", &cmd_mode,
+		    N_("print list of user-facing repository, command and file interfaces"),
+		    HELP_ACTION_USER_INTERFACES),
 	OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
 		    HELP_ACTION_CONFIG),
 	OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
@@ -84,6 +88,7 @@ static const char * const builtin_help_usage[] = {
 	N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
 	"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
 '
-- 
2.37.1.1197.g7ed548b7807


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v6 4/9] git docs: add a category for file formats, protocols and interfaces
  2022-07-28 16:46         ` [PATCH v6 " Ævar Arnfjörð Bjarmason
                             ` (2 preceding siblings ...)
  2022-07-28 16:46           ` [PATCH v6 3/9] git docs: add a category for user-facing file, repo and command UX Ævar Arnfjörð Bjarmason
@ 2022-07-28 16:46           ` Ævar Arnfjörð Bjarmason
  2022-07-28 16:46           ` [PATCH v6 5/9] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
                             ` (6 subsequent siblings)
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-28 16:46 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

Create a new "File formats, protocols and other developer interfaces"
section in the main "git help git" manual page and start moving the
documentation that now lives in "Documentation/technical/*.git" over
to it. This complements the newly added and adjacent "Repository,
command and file interfaces" section.

This makes the technical documentation more accessible and
discoverable. Before this we wouldn't install it by default, and had
no ability to build man page versions of them. The links to them from
our existing documentation link to the generated HTML version of these
docs.

So let's start moving those over, starting with just the
"bundle-format.txt" documentation added in 7378ec90e1c (doc: describe
Git bundle format, 2020-02-07). We'll now have a new
gitformat-bundle(5) man page. Subsequent commits will move more git
internal format documentation over.

Unfortunately the syntax of the current Documentation/technical/*.txt
is not the same (when it comes to section headings etc.) as our
Documentation/*.txt documentation, so change the relevant bits of
syntax as we're moving this over.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 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 <file>::
 	commits exist and are fully linked in the current repository.
 	Then, 'git bundle' prints a list of missing commits, if any.
 	Finally, information about additional capabilities, such as "object
-	filter", is printed. See "Capabilities" in link:technical/bundle-format.html
+	filter", is printed. See "Capabilities" in linkgit:gitformat-bundle[5]
 	for more information. The exit code is zero for success, but will
 	be nonzero if the bundle file is invalid.
 
@@ -337,6 +336,11 @@ You can also see what references it offers:
 $ git ls-remote mybundle
 ----------------
 
+FILE FORMAT
+-----------
+
+See linkgit:gitformat-bundle[5].
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index 4eb03bd6c38..2b0b5e390dc 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -13,6 +13,7 @@ SYNOPSIS
 'git help' [-g|--guides]
 'git help' [-c|--config]
 'git help' [--user-interfaces]
+'git help' [--developer-interfaces]
 
 DESCRIPTION
 -----------
@@ -83,6 +84,10 @@ user-interface conventions (e.g. linkgit:gitcli[7]), and
 pseudo-configuration such as the file-based `.git/hooks/*` interface
 described in linkgit:githooks[5].
 
+--developer-interfaces::
+	Print list of file formats, protocols and other developer
+	interfaces documentation on the standard output.
+
 -i::
 --info::
 	Display manual page for the command in the 'info' format. The
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 945a1ebd3b1..0ef7f5e4ece 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -348,6 +348,15 @@ linkgit:git-help[1] for more details on the critera.
 
 include::cmds-userinterfaces.txt[]
 
+File formats, protocols and other developer interfaces
+------------------------------------------------------
+
+This documentation discusses file formats, over-the-wire protocols and
+other git developer interfaces. See `--developer-interfaces` in
+linkgit:git-help[1].
+
+include::cmds-developerinterfaces.txt[]
+
 Configuration Mechanism
 -----------------------
 
diff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt
similarity index 79%
rename from Documentation/technical/bundle-format.txt
rename to Documentation/gitformat-bundle.txt
index b9be8644cf5..6a9d9e5bf6f 100644
--- a/Documentation/technical/bundle-format.txt
+++ b/Documentation/gitformat-bundle.txt
@@ -1,11 +1,33 @@
-= Git bundle v2 format
+gitformat-bundle(5)
+===================
 
-The Git bundle format is a format that represents both refs and Git objects.
+NAME
+----
+gitformat-bundle - The bundle file format
+
+
+SYNOPSIS
+--------
+[verse]
+*.bundle
+*.bdl
+
+DESCRIPTION
+-----------
+
+The Git bundle format is a format that represents both refs and Git
+objects. A bundle is a header in a format similar to
+linkgit:git-show-ref[1] followed by a pack in *.pack format.
 
-== Format
+The format is created and read by the linkgit:git-bundle[1] command,
+and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1].
+
+
+FORMAT
+------
 
 We will use ABNF notation to define the Git bundle format. See
-protocol-common.txt for the details.
+link:technical/protocol-common.html for the details.
 
 A v2 bundle looks like this:
 
@@ -36,7 +58,9 @@ value        = *(%01-09 / %0b-FF)
 pack         = ... ; packfile
 ----
 
-== Semantics
+
+SEMANTICS
+---------
 
 A Git bundle consists of several parts.
 
@@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id.
 This is a comment and it has no specific meaning. The writer of the bundle MAY
 put any string here. The reader of the bundle MUST ignore the comment.
 
-=== Note on the shallow clone and a Git bundle
+Note on the shallow clone and a Git bundle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Note that the prerequisites does not represent a shallow-clone boundary. The
 semantics of the prerequisites and the shallow-clone boundaries are different,
 and the Git bundle v2 format cannot represent a shallow clone repository.
 
-== Capabilities
+CAPABILITIES
+------------
 
 Because there is no opportunity for negotiation, unknown capabilities cause 'git
 bundle' to abort.
@@ -79,3 +105,7 @@ bundle' to abort.
 * `filter` specifies an object filter as in the `--filter` option in
   linkgit:git-rev-list[1]. The resulting pack-file must be marked as a
   `.promisor` pack-file after it is unbundled.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
index 425377dfeb7..02408a0062f 100755
--- a/Documentation/lint-man-section-order.perl
+++ b/Documentation/lint-man-section-order.perl
@@ -32,6 +32,9 @@
 		'SEE ALSO' => {
 			order => $order++,
 		},
+		'FILE FORMAT' => {
+			order => $order++,
+		},
 		'GIT' => {
 			required => 1,
 			order => $order++,
diff --git a/builtin/help.c b/builtin/help.c
index 1ab1c8a0dd7..09ac4289f13 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -44,6 +44,7 @@ static enum help_action {
 	HELP_ACTION_GUIDES,
 	HELP_ACTION_CONFIG,
 	HELP_ACTION_USER_INTERFACES,
+	HELP_ACTION_DEVELOPER_INTERFACES,
 	HELP_ACTION_CONFIG_FOR_COMPLETION,
 	HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
 } cmd_mode;
@@ -73,6 +74,9 @@ static struct option builtin_help_options[] = {
 	OPT_CMDMODE(0, "user-interfaces", &cmd_mode,
 		    N_("print list of user-facing repository, command and file interfaces"),
 		    HELP_ACTION_USER_INTERFACES),
+	OPT_CMDMODE(0, "developer-interfaces", &cmd_mode,
+		    N_("print list of file formats, protocols and other developer interfaces"),
+		    HELP_ACTION_DEVELOPER_INTERFACES),
 	OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
 		    HELP_ACTION_CONFIG),
 	OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
@@ -89,6 +93,7 @@ static const char * const builtin_help_usage[] = {
 	"git help [-g|--guides]",
 	"git help [-c|--config]",
 	"git help [--user-interfaces]",
+	"git help [--developer-interfaces]",
 	NULL
 };
 
@@ -663,6 +668,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		opt_mode_usage(argc, "--user-interfaces", help_format);
 		list_user_interfaces_help();
 		return 0;
+	case HELP_ACTION_DEVELOPER_INTERFACES:
+		opt_mode_usage(argc, "--developer-interfaces", help_format);
+		list_developer_interfaces_help();
+		return 0;
 	case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
 		opt_mode_usage(argc, "--config-sections-for-completion",
 			       help_format);
diff --git a/command-list.txt b/command-list.txt
index 1d45303e14c..1950c4ccd9c 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -48,6 +48,10 @@
 # sections 5 and 7. These entries can only have the "userinterfaces"
 # attribute and nothing else.
 #
+# Git's file formats and protocols, such as documentation for the
+# *.bundle format lives in man section 5. These entries can only have
+# the "developerinterfaces" attribute and nothing else.
+#
 ### command list (do not change this line)
 # command name                          category [category] [category]
 git-add                                 mainporcelain           worktree
@@ -205,6 +209,7 @@ gitcvs-migration                        guide
 gitdiffcore                             guide
 giteveryday                             guide
 gitfaq                                  guide
+gitformat-bundle                        developerinterfaces
 gitglossary                             guide
 githooks                                userinterfaces
 gitignore                               userinterfaces
diff --git a/help.c b/help.c
index 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
 '
-- 
2.37.1.1197.g7ed548b7807


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v6 5/9] docs: move commit-graph format docs to man section 5
  2022-07-28 16:46         ` [PATCH v6 " Ævar Arnfjörð Bjarmason
                             ` (3 preceding siblings ...)
  2022-07-28 16:46           ` [PATCH v6 4/9] git docs: add a category for file formats, protocols and interfaces Ævar Arnfjörð Bjarmason
@ 2022-07-28 16:46           ` Ævar Arnfjörð Bjarmason
  2022-07-28 16:46           ` [PATCH v6 6/9] docs: move protocol-related " Ævar Arnfjörð Bjarmason
                             ` (5 subsequent siblings)
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-28 16:46 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 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
-- 
2.37.1.1197.g7ed548b7807


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v6 6/9] docs: move protocol-related docs to man section 5
  2022-07-28 16:46         ` [PATCH v6 " Ævar Arnfjörð Bjarmason
                             ` (4 preceding siblings ...)
  2022-07-28 16:46           ` [PATCH v6 5/9] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
@ 2022-07-28 16:46           ` Ævar Arnfjörð Bjarmason
  2022-07-28 16:46           ` [PATCH v6 7/9] docs: move pack format " Ævar Arnfjörð Bjarmason
                             ` (4 subsequent siblings)
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-28 16:46 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 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].
 
 <directory>::
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]
+<over-the-wire-protocol>
+
+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]
+<over-the-wire-protocol>
+
+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]
+<over-the-wire-protocol>
+
+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 `<key>=<value>` or `<key>`.
 
 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]
+<over-the-wire-protocol>
+
+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 <prefix> 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
 '
-- 
2.37.1.1197.g7ed548b7807


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v6 7/9] docs: move pack format docs to man section 5
  2022-07-28 16:46         ` [PATCH v6 " Ævar Arnfjörð Bjarmason
                             ` (5 preceding siblings ...)
  2022-07-28 16:46           ` [PATCH v6 6/9] docs: move protocol-related " Ævar Arnfjörð Bjarmason
@ 2022-07-28 16:46           ` Ævar Arnfjörð Bjarmason
  2022-07-28 16:46           ` [PATCH v6 8/9] docs: move http-protocol " Ævar Arnfjörð Bjarmason
                             ` (3 subsequent siblings)
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-28 16:46 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 Documentation/Makefile                        |  9 ++---
 Documentation/config/pack.txt                 |  2 +-
 Documentation/git-bundle.txt                  |  3 +-
 Documentation/git-multi-pack-index.txt        |  4 +--
 .../chunk-format.txt => gitformat-chunk.txt}  | 25 +++++++++++---
 Documentation/gitformat-commit-graph.txt      |  2 +-
 .../index-format.txt => gitformat-index.txt}  | 22 ++++++++++--
 ...uft-packs.txt => gitformat-pack-cruft.txt} | 22 ++++++++++--
 .../pack-format.txt => gitformat-pack.txt}    | 34 +++++++++++++++++--
 ...ure-format.txt => gitformat-signature.txt} | 21 ++++++++++--
 Documentation/gitprotocol-pack.txt            |  2 +-
 .../howto/recover-corrupted-object-harder.txt |  2 +-
 .../technical/hash-function-transition.txt    |  2 +-
 Documentation/user-manual.txt                 |  2 +-
 cache.h                                       |  3 +-
 command-list.txt                              |  5 +++
 pack-revindex.h                               |  2 +-
 17 files changed, 131 insertions(+), 31 deletions(-)
 rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (91%)
 rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)
 rename Documentation/{technical/cruft-packs.txt => gitformat-pack-cruft.txt} (96%)
 rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)
 rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index b53f3c12843..cd09ccd8c13 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -25,7 +25,12 @@ MAN1_TXT += gitweb.txt
 # man5 / man7 guides (note: new guides should also be added to command-list.txt)
 MAN5_TXT += gitattributes.txt
 MAN5_TXT += gitformat-bundle.txt
+MAN5_TXT += gitformat-chunk.txt
 MAN5_TXT += gitformat-commit-graph.txt
+MAN5_TXT += gitformat-index.txt
+MAN5_TXT += gitformat-pack-cruft.txt
+MAN5_TXT += gitformat-pack.txt
+MAN5_TXT += gitformat-signature.txt
 MAN5_TXT += githooks.txt
 MAN5_TXT += gitignore.txt
 MAN5_TXT += gitmailmap.txt
@@ -101,13 +106,10 @@ TECH_DOCS += MyFirstObjectWalk
 TECH_DOCS += SubmittingPatches
 TECH_DOCS += ToolsForGit
 TECH_DOCS += technical/bitmap-format
-TECH_DOCS += technical/cruft-packs
 TECH_DOCS += technical/hash-function-transition
 TECH_DOCS += technical/http-protocol
-TECH_DOCS += technical/index-format
 TECH_DOCS += technical/long-running-process-protocol
 TECH_DOCS += technical/multi-pack-index
-TECH_DOCS += technical/pack-format
 TECH_DOCS += technical/pack-heuristics
 TECH_DOCS += technical/parallel-checkout
 TECH_DOCS += technical/partial-clone
@@ -115,7 +117,6 @@ TECH_DOCS += technical/racy-git
 TECH_DOCS += technical/reftable
 TECH_DOCS += technical/send-pack-pipeline
 TECH_DOCS += technical/shallow
-TECH_DOCS += technical/signature-format
 TECH_DOCS += technical/trivial-merge
 SP_ARTICLES += $(TECH_DOCS)
 SP_ARTICLES += technical/api-index
diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt
index ad7f73a1ead..3e581eab84a 100644
--- a/Documentation/config/pack.txt
+++ b/Documentation/config/pack.txt
@@ -166,7 +166,7 @@ permuted into their appropriate location when writing a new bitmap.
 
 pack.writeReverseIndex::
 	When true, git will write a corresponding .rev file (see:
-	link:../technical/pack-format.html[Documentation/technical/pack-format.txt])
+	linkgit:gitformat-pack[5])
 	for each new packfile that it writes in all places except for
 	linkgit:git-fast-import[1] and in the bulk checkin mechanism.
 	Defaults to false.
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index f0b1282b918..6da61722431 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -57,8 +57,7 @@ size. That they're "thin" under the hood is merely noted here as a
 curiosity, and as a reference to other documentation.
 
 See linkgit:gitformat-bundle[5] for more details and the discussion of
-"thin pack" in link:technical/pack-format.html[the pack format
-documentation] for further details.
+"thin pack" in linkgit:gitformat-pack[5] for further details.
 
 OPTIONS
 -------
diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt
index c588fb91af1..a48c3d5ea63 100644
--- a/Documentation/git-multi-pack-index.txt
+++ b/Documentation/git-multi-pack-index.txt
@@ -128,8 +128,8 @@ $ git multi-pack-index verify
 SEE ALSO
 --------
 See link:technical/multi-pack-index.html[The Multi-Pack-Index Design
-Document] and link:technical/pack-format.html[The Multi-Pack-Index
-Format] for more information on the multi-pack-index feature.
+Document] and linkgit:gitformat-pack[5] for more information on the
+multi-pack-index feature and its file format.
 
 
 GIT
diff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt
similarity index 91%
rename from Documentation/technical/chunk-format.txt
rename to Documentation/gitformat-chunk.txt
index f36ce42f37c..57202ede273 100644
--- a/Documentation/technical/chunk-format.txt
+++ b/Documentation/gitformat-chunk.txt
@@ -1,11 +1,24 @@
-Chunk-based file formats
-========================
+gitformat-chunk(5)
+==================
+
+NAME
+----
+gitformat-chunk - Chunk-based file formats
+
+SYNOPSIS
+--------
+
+Used by linkgit:gitformat-commit-graph[5] and the "MIDX" format (see
+the pack format documentation in linkgit:gitformat-pack[5]).
+
+DESCRIPTION
+-----------
 
 Some file formats in Git use a common concept of "chunks" to describe
 sections of the file. This allows structured access to a large file by
 scanning a small "table of contents" for the remaining data. This common
 format is used by the `commit-graph` and `multi-pack-index` files. See
-link:technical/pack-format.html[the `multi-pack-index` format] and
+the `multi-pack-index` format in linkgit:gitformat-pack[5] and
 the `commit-graph` format in linkgit:gitformat-commit-graph[5] for
 how they use the chunks to describe structured data.
 
@@ -113,4 +126,8 @@ for future formats:
 * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`
   in `midx.c` for how the chunk-format API is used to write and
   parse the multi-pack-index file format documented in
-  link:technical/pack-format.html[the multi-pack-index file format].
+  the multi-pack-index file format section of linkgit:gitformat-pack[5].
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt
index 108dc2295c0..7324665716d 100644
--- a/Documentation/gitformat-commit-graph.txt
+++ b/Documentation/gitformat-commit-graph.txt
@@ -75,7 +75,7 @@ All multi-byte numbers are in network byte order.
       ID appears at most once.
 
   The CHUNK LOOKUP matches the table of contents from
-  link:technical/chunk-format.html[the chunk-based file format].
+  the chunk-based file format, see linkgit:gitformat-chunk[5]
 
   The remaining data in the body is described one chunk at a time, and
   these chunks may be given in any order. Chunks are required unless
diff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt
similarity index 98%
rename from Documentation/technical/index-format.txt
rename to Documentation/gitformat-index.txt
index f691c20ab0a..015cb21bdc0 100644
--- a/Documentation/technical/index-format.txt
+++ b/Documentation/gitformat-index.txt
@@ -1,5 +1,19 @@
+gitformat-index(5)
+==================
+
+NAME
+----
+gitformat-index - Git index format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/index
+
+DESCRIPTION
+-----------
+
 Git index format
-================
 
 == The Git index file has the following format
 
@@ -125,7 +139,7 @@ Git index format
     entry is encoded as if the path name for the previous entry is an
     empty string).  At the beginning of an entry, an integer N in the
     variable width encoding (the same encoding as the offset is encoded
-    for OFS_DELTA pack entries; see pack-format.txt) is stored, followed
+    for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed
     by a NUL-terminated string S.  Removing N bytes from the end of the
     path name for the previous entry, and replacing it with the string S
     yields the path name for this entry.
@@ -402,3 +416,7 @@ The remaining data of each directory block is grouped by type:
   with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,
   tools should avoid interacting with a sparse index unless they understand
   this extension.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/cruft-packs.txt b/Documentation/gitformat-pack-cruft.txt
similarity index 96%
rename from Documentation/technical/cruft-packs.txt
rename to Documentation/gitformat-pack-cruft.txt
index d81f3a8982f..908f752bd84 100644
--- a/Documentation/technical/cruft-packs.txt
+++ b/Documentation/gitformat-pack-cruft.txt
@@ -1,4 +1,17 @@
-= Cruft packs
+gitformat-pack-cruft(5)
+=======================
+
+NAME
+----
+gitformat-pack-cruft - The cruft pack file format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/pack/pack-*.mtimes
+
+DESCRIPTION
+-----------
 
 The cruft packs feature offer an alternative to Git's traditional mechanism of
 removing unreachable objects. This document provides an overview of Git's
@@ -10,10 +23,11 @@ same.
 To remove unreachable objects from your repository, Git offers `git repack -Ad`
 (see linkgit:git-repack[1]). Quoting from the documentation:
 
-[quote]
+----
 [...] unreachable objects in a previous pack become loose, unpacked objects,
 instead of being left in the old pack. [...] loose unreachable objects will be
 pruned according to normal expiry rules with the next 'git gc' invocation.
+----
 
 Unreachable objects aren't removed immediately, since doing so could race with
 an incoming push which may reference an object which is about to be deleted.
@@ -121,3 +135,7 @@ which aren't already stored in an earlier cruft pack) is significantly more
 complicated to construct, and so aren't pursued here. The obvious drawback to
 the current implementation is that the entire cruft pack must be re-written from
 scratch.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/pack-format.txt b/Documentation/gitformat-pack.txt
similarity index 95%
rename from Documentation/technical/pack-format.txt
rename to Documentation/gitformat-pack.txt
index b520aa9c45b..546c99f8871 100644
--- a/Documentation/technical/pack-format.txt
+++ b/Documentation/gitformat-pack.txt
@@ -1,5 +1,29 @@
-Git pack format
-===============
+gitformat-pack(5)
+=================
+
+NAME
+----
+gitformat-pack - Git pack format
+
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/pack/pack-*.{pack,idx}
+$GIT_DIR/objects/pack/pack-*.rev
+$GIT_DIR/objects/pack/multi-pack-index
+
+DESCRIPTION
+-----------
+
+The Git pack format is now Git stores most of its primary repository
+data. Over the lietime af a repository loose objects (if any) and
+smaller packs are consolidated into larger pack(s). See
+linkgit:git-gc[1] and linkgit:git-pack-objects[1].
+
+The pack format is also used over-the-wire, see
+e.g. linkgit:gitprotocol-v2[5], as well as being a part of
+other container formats in the case of linkgit:gitformat-bundle[5].
 
 == Checksums and object IDs
 
@@ -356,7 +380,7 @@ CHUNK LOOKUP:
 	    using the next chunk position if necessary.)
 
 	The CHUNK LOOKUP matches the table of contents from
-	link:technical/chunk-format.html[the chunk-based file format].
+	the chunk-based file format, see linkgit:gitformat-chunk[5].
 
 	The remaining data in the body is described one chunk at a time, and
 	these chunks may be given in any order. Chunks are required unless
@@ -482,3 +506,7 @@ packs arranged in MIDX order (with the preferred pack coming first).
 
 The MIDX's reverse index is stored in the optional 'RIDX' chunk within
 the MIDX itself.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt
similarity index 96%
rename from Documentation/technical/signature-format.txt
rename to Documentation/gitformat-signature.txt
index 166721be6f6..a249869fafa 100644
--- a/Documentation/technical/signature-format.txt
+++ b/Documentation/gitformat-signature.txt
@@ -1,7 +1,18 @@
-Git signature format
-====================
+gitformat-signature(5)
+======================
 
-== Overview
+NAME
+----
+gitformat-signature - Git cryptographic signature formats
+
+SYNOPSIS
+--------
+[verse]
+<[tag|commit] object header(s)>
+<over-the-wire protocol>
+
+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
-- 
2.37.1.1197.g7ed548b7807


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v6 8/9] docs: move http-protocol docs to man section 5
  2022-07-28 16:46         ` [PATCH v6 " Ævar Arnfjörð Bjarmason
                             ` (6 preceding siblings ...)
  2022-07-28 16:46           ` [PATCH v6 7/9] docs: move pack format " Ævar Arnfjörð Bjarmason
@ 2022-07-28 16:46           ` Ævar Arnfjörð Bjarmason
  2022-07-28 16:46           ` [PATCH v6 9/9] docs: move multi-pack-index " Ævar Arnfjörð Bjarmason
                             ` (2 subsequent siblings)
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-28 16:46 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 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].
 
 <directory>::
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]
+<over-the-wire-protocol>
+
+
+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
-- 
2.37.1.1197.g7ed548b7807


^ permalink raw reply related	[flat|nested] 112+ messages in thread

* [PATCH v6 9/9] docs: move multi-pack-index docs to man section 5
  2022-07-28 16:46         ` [PATCH v6 " Ævar Arnfjörð Bjarmason
                             ` (7 preceding siblings ...)
  2022-07-28 16:46           ` [PATCH v6 8/9] docs: move http-protocol " Ævar Arnfjörð Bjarmason
@ 2022-07-28 16:46           ` Ævar Arnfjörð Bjarmason
  2022-07-28 20:40           ` [PATCH v6 0/9] docs: create & use "(user|developer) interfaces" categories Junio C Hamano
  2022-08-02 12:56           ` [PATCH v7 00/10] " Ævar Arnfjörð Bjarmason
  10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-28 16:46 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Eric Sunshine, Philippe Blain, Derrick Stolee,
	Taylor Blau, Jeff King, Teng Long,
	Ævar Arnfjörð Bjarmason

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 <avarab@gmail.com>
---
 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