* [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 developerinterfaces
gitformat-signature developerinterfaces
--
2.37.1.1197.g7ed548b7807
^ permalink raw reply related [flat|nested] 112+ messages in thread
* Re: [PATCH v6 0/9] docs: create & use "(user|developer) interfaces" categories
2022-07-28 16:46 ` [PATCH v6 " Ævar Arnfjörð Bjarmason
` (8 preceding siblings ...)
2022-07-28 16:46 ` [PATCH v6 9/9] docs: move multi-pack-index " Ævar Arnfjörð Bjarmason
@ 2022-07-28 20:40 ` 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: Junio C Hamano @ 2022-07-28 20:40 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 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!
This seems to be identical to what we already have in my tree, which
is OK.
Will not queue but instead keep the old one that has the fix applied
when it was queued, to keep the author & committer dates.
Thanks.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v6 1/9] help.c: BUG() out if "help --guides" can't remove "git" prefixes
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-30 0:17 ` Junio C Hamano
2022-08-01 11:55 ` Ævar Arnfjörð Bjarmason
0 siblings, 1 reply; 112+ messages in thread
From: Junio C Hamano @ 2022-07-30 0: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:
> 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.
I am not sure what this buys us. After dealing with pages that
begin with "git-", if the set of documentation we have happen to all
share "git" as their prefix, then this new BUG() does not do
anything to them, and when we ever add say "scalar-guide.txt", the
new BUG() would only force people to rewrite this part of the code.
Instead we could be more forward looking and do something like
"Yield a name without 'git' prefix if it begins with it, or the
original name", and then new guides that are outside "git" namespace
can be added without touching this part of the code again.
IOW, it is not entirely clear to me what we are adding this extra
roadblock for.
> 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)
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v6 1/9] help.c: BUG() out if "help --guides" can't remove "git" prefixes
2022-07-30 0:17 ` Junio C Hamano
@ 2022-08-01 11:55 ` Ævar Arnfjörð Bjarmason
2022-08-01 16:45 ` Junio C Hamano
0 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-01 11:55 UTC (permalink / raw)
To: Junio C Hamano
Cc: git, Eric Sunshine, Philippe Blain, Derrick Stolee, Taylor Blau,
Jeff King, Teng Long
On Fri, Jul 29 2022, Junio C Hamano wrote:
> Æ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.
>
> I am not sure what this buys us. After dealing with pages that
> begin with "git-", if the set of documentation we have happen to all
> share "git" as their prefix, then this new BUG() does not do
> anything to them, and when we ever add say "scalar-guide.txt", the
> new BUG() would only force people to rewrite this part of the code.
>
> Instead we could be more forward looking and do something like
> "Yield a name without 'git' prefix if it begins with it, or the
> original name", and then new guides that are outside "git" namespace
> can be added without touching this part of the code again.
>
> IOW, it is not entirely clear to me what we are adding this extra
> roadblock for.
I think if we ever have non-git documentation such as scalar's being
shipped as part of our build it would be good to run into this BUG(),
since presumably a "git help -g" should not list them, but e.g. "scalar
help -g" or whatever.
Or if "git help -g" should list them we should extend it somehow so that
it's not listed under the main "The Git concept guides are" heading.
But per that rationale I should give "git-" the same BUG() treatment,
which I didn't because I wanted to focus just on "git" here, to make
this easier to explain (but perhaps it wasn't).
So I can remove this stricture entirely, or make the BUG() stricter and
remove the "git" (or "git-" requirenment. Whatever you prefer after
reading the above..
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v6 1/9] help.c: BUG() out if "help --guides" can't remove "git" prefixes
2022-08-01 11:55 ` Ævar Arnfjörð Bjarmason
@ 2022-08-01 16:45 ` Junio C Hamano
0 siblings, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-08-01 16:45 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:
> So I can remove this stricture entirely, or make the BUG() stricter and
> remove the "git" (or "git-" requirenment. Whatever you prefer after
> reading the above..
My preference is that you do not have this patch at all.
We do not need it now, and we do not know, and more imoprtantly, we
do not have to decide, what we want to do when we add a guide whose
name does not want to begin with "git". It would only locally be
one patch we do not have to discuss out of 9, but things add up.
If you switch to the attitude of not churning what you do not have
to touch right at the moment, hopefully it would save reviewers'
time. It unfortunately probably make you spend more time thinking
about everything you do if that is essential or unnecessary churn
after writing but before sending them out.
But hopefully the original author spending more time and effort on
the quality of the primary part of the changes, without getting
distracted and without distracting reviewers by what is not
necessary yet, would contribute positively to the quality of the end
product?
THanks.
^ permalink raw reply [flat|nested] 112+ messages in thread
* [PATCH v7 00/10] docs: create & use "(user|developer) interfaces" categories
2022-07-28 16:46 ` [PATCH v6 " Ævar Arnfjörð Bjarmason
` (9 preceding siblings ...)
2022-07-28 20:40 ` [PATCH v6 0/9] docs: create & use "(user|developer) interfaces" categories Junio C Hamano
@ 2022-08-02 12:56 ` Ævar Arnfjörð Bjarmason
2022-08-02 12:56 ` [PATCH v7 01/10] help.c: refactor drop_prefix() to use a "switch" statement" Ævar Arnfjörð Bjarmason
` (10 more replies)
10 siblings, 11 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-02 12:56 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 v7:
* Gets rid of the BUG() addition in an earlier commit when handle the
command-list.txt data.
* We still need to change that drop_prefix() function to handle our
new categories.
That's now done in a couple of commits. One to
change it to a "switch" statement without any functional changes,
another to strip either "git" or "git-" prefixes, not both.
* There was an indentation error in a command-list.txt addition, fix
it.
Ævar Arnfjörð Bjarmason (10):
help.c: refactor drop_prefix() to use a "switch" statement"
help.c: remove common category behavior from drop_prefix() behavior
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 | 41 ++++++++++++++--
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, 512 insertions(+), 126 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 v6:
1: f3588319057 ! 1: 2665148f45b help.c: BUG() out if "help --guides" can't remove "git" prefixes
@@ Metadata
Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Commit message ##
- help.c: BUG() out if "help --guides" can't remove "git" prefixes
+ help.c: refactor drop_prefix() to use a "switch" statement"
- 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.
+ Refactor the drop_prefix() function in in help.c to make it easier to
+ strip prefixes from categories that aren't "CAT_guide". There are no
+ functional changes here, by doing this we make a subsequent functional
+ change's diff smaller.
- 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.
+ As before we first try to strip "git-" unconditionally, if that works
+ we'll return the stripped string. Then we'll strip "git" if the
+ command is in "CAT_guide".
+
+ This means that we'd in principle strip "git-gitfoo" down to "foo" if
+ it's in CAT_guide. That doesn't make much sense, and we don't have
+ such an entry in command-list.txt, but let's preserve that behavior
+ for now.
While we're at it remove a stray newline that had been added after the
"return name;" statement.
@@ 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;
++ const char *prefix = NULL;
if (skip_prefix(name, "git-", &new_name))
return new_name;
@@ help.c: static struct category_description main_categories[] = {
+ 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;
++ break;
+ }
- return name;
--
++ if (prefix && skip_prefix(name, prefix, &new_name))
+ return new_name;
+- return name;
+
++ return name;
}
static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask)
-: ----------- > 2: 56429194634 help.c: remove common category behavior from drop_prefix() behavior
2: 80322d44ea5 = 3: 2d6c00a51fa git help doc: use "<doc>" instead of "<guide>"
3: 0d22eb645bd ! 4: 8e9384a92f2 git docs: add a category for user-facing file, repo and command UX
@@ help.c: static struct category_description main_categories[] = {
};
@@ help.c: 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",
+ break;
+ default:
@@ help.c: void list_guides_help(void)
putchar('\n');
}
4: c25f8ec9bf5 ! 5: 4367c1e7f50 git docs: add a category for file formats, protocols and interfaces
@@ help.c: static const char *drop_prefix(const char *name, uint32_t category)
case CAT_userinterfaces:
+ case CAT_developerinterfaces:
prefix = "git";
- if (!skip_prefix(name, prefix, &new_name))
- BUG("'%s' in category #%d should have '%s' prefix",
+ break;
+ default:
@@ help.c: void list_user_interfaces_help(void)
putchar('\n');
}
5: 466dbd2a993 = 6: 5adabbb3a26 docs: move commit-graph format docs to man section 5
6: 9a551b2d53a = 7: cfd1b0afb53 docs: move protocol-related docs to man section 5
7: 92be18b95d9 = 8: 3505fa86039 docs: move pack format docs to man section 5
8: a8a883ebf85 ! 9: c4a7fe9d439 docs: move http-protocol docs to man section 5
@@ command-list.txt: gitmodules userinterfaces
gitnamespaces guide
gitprotocol-capabilities developerinterfaces
gitprotocol-common developerinterfaces
-+gitprotocol-http developerinterfaces
++gitprotocol-http developerinterfaces
gitprotocol-pack developerinterfaces
gitprotocol-v2 developerinterfaces
gitremote-helpers guide
9: ecfda8c6770 = 10: 8baf1db4d30 docs: move multi-pack-index docs to man section 5
--
2.37.1.1232.gc0cde427aa7
^ permalink raw reply [flat|nested] 112+ messages in thread
* [PATCH v7 01/10] help.c: refactor drop_prefix() to use a "switch" statement"
2022-08-02 12:56 ` [PATCH v7 00/10] " Ævar Arnfjörð Bjarmason
@ 2022-08-02 12:56 ` Ævar Arnfjörð Bjarmason
2022-08-02 23:01 ` Junio C Hamano
2022-08-02 12:56 ` [PATCH v7 02/10] help.c: remove common category behavior from drop_prefix() behavior Ævar Arnfjörð Bjarmason
` (9 subsequent siblings)
10 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-02 12:56 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
Refactor the drop_prefix() function in in help.c to make it easier to
strip prefixes from categories that aren't "CAT_guide". There are no
functional changes here, by doing this we make a subsequent functional
change's diff smaller.
As before we first try to strip "git-" unconditionally, if that works
we'll return the stripped string. Then we'll strip "git" if the
command is in "CAT_guide".
This means that we'd in principle strip "git-gitfoo" down to "foo" if
it's in CAT_guide. That doesn't make much sense, and we don't have
such an entry in command-list.txt, but let's preserve that behavior
for now.
While we're at it remove a stray newline that had been added after the
"return name;" statement.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
help.c | 10 ++++++++--
1 file changed, 8 insertions(+), 2 deletions(-)
diff --git a/help.c b/help.c
index 41c41c2aa11..7e594d291b0 100644
--- a/help.c
+++ b/help.c
@@ -44,13 +44,19 @@ static struct category_description main_categories[] = {
static const char *drop_prefix(const char *name, uint32_t category)
{
const char *new_name;
+ const char *prefix = NULL;
if (skip_prefix(name, "git-", &new_name))
return new_name;
- if (category == CAT_guide && skip_prefix(name, "git", &new_name))
+ switch (category) {
+ case CAT_guide:
+ prefix = "git";
+ break;
+ }
+ if (prefix && skip_prefix(name, prefix, &new_name))
return new_name;
- return name;
+ return name;
}
static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask)
--
2.37.1.1232.gc0cde427aa7
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v7 02/10] help.c: remove common category behavior from drop_prefix() behavior
2022-08-02 12:56 ` [PATCH v7 00/10] " Ævar Arnfjörð Bjarmason
2022-08-02 12:56 ` [PATCH v7 01/10] help.c: refactor drop_prefix() to use a "switch" statement" Ævar Arnfjörð Bjarmason
@ 2022-08-02 12:56 ` Ævar Arnfjörð Bjarmason
2022-08-02 12:56 ` [PATCH v7 03/10] git help doc: use "<doc>" instead of "<guide>" Ævar Arnfjörð Bjarmason
` (8 subsequent siblings)
10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-02 12:56 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
Change the behavior of the "git" prefix stripping for CAT_guide so
that we don't try to strip the "git-" prefix in that case. We should
be stripping either "git" or "git-" depending on the category. This
change makes it easier to add extra "category" conditions in
subsequent commits.
Before this we'd in principle strip a "git-" prefix from a "guide" in
command-list.txt, in practice we have no such entry there. As we don't
have any entry that looks like "git-gitfoo" in command-list.txt this
changes nothing in practice, but it makes the intent of the code
clearer.
When this code was added in cfb22a02ab5 (help: use command-list.h for
common command list, 2018-05-10) the only entries in command-list.txt
that didn't begin with "git-" were "gitweb" and "gitk".
Then when the "guides" special-case was added in 1b81d8cb19d (help:
use command-list.txt for the source of guides, 2018-05-20) we had the
various "git" (not "git-") prefixed "guide" entries, which the
"CAT_guide" case handles.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
help.c | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
diff --git a/help.c b/help.c
index 7e594d291b0..8a09f18a3d9 100644
--- a/help.c
+++ b/help.c
@@ -44,16 +44,17 @@ static struct category_description main_categories[] = {
static const char *drop_prefix(const char *name, uint32_t category)
{
const char *new_name;
- const char *prefix = NULL;
+ const char *prefix;
- if (skip_prefix(name, "git-", &new_name))
- return new_name;
switch (category) {
case CAT_guide:
prefix = "git";
break;
+ default:
+ prefix = "git-";
+ break;
}
- if (prefix && skip_prefix(name, prefix, &new_name))
+ if (skip_prefix(name, prefix, &new_name))
return new_name;
return name;
--
2.37.1.1232.gc0cde427aa7
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v7 03/10] git help doc: use "<doc>" instead of "<guide>"
2022-08-02 12:56 ` [PATCH v7 00/10] " Ævar Arnfjörð Bjarmason
2022-08-02 12:56 ` [PATCH v7 01/10] help.c: refactor drop_prefix() to use a "switch" statement" Ævar Arnfjörð Bjarmason
2022-08-02 12:56 ` [PATCH v7 02/10] help.c: remove common category behavior from drop_prefix() behavior Ævar Arnfjörð Bjarmason
@ 2022-08-02 12:56 ` Ævar Arnfjörð Bjarmason
2022-08-02 12:56 ` [PATCH v7 04/10] git docs: add a category for user-facing file, repo and command UX Ævar Arnfjörð Bjarmason
` (7 subsequent siblings)
10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-02 12:56 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.1232.gc0cde427aa7
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v7 04/10] git docs: add a category for user-facing file, repo and command UX
2022-08-02 12:56 ` [PATCH v7 00/10] " Ævar Arnfjörð Bjarmason
` (2 preceding siblings ...)
2022-08-02 12:56 ` [PATCH v7 03/10] git help doc: use "<doc>" instead of "<guide>" Ævar Arnfjörð Bjarmason
@ 2022-08-02 12:56 ` Ævar Arnfjörð Bjarmason
2022-08-02 12:56 ` [PATCH v7 05/10] git docs: add a category for file formats, protocols and interfaces Ævar Arnfjörð Bjarmason
` (6 subsequent siblings)
10 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-02 12:56 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 8a09f18a3d9..3e2a78863b7 100644
--- a/help.c
+++ b/help.c
@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {
{ CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") },
{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
+ { CAT_userinterfaces, N_("User-facing repository, command and file interfaces") },
{ 0, NULL }
};
@@ -48,6 +49,7 @@ static const char *drop_prefix(const char *name, uint32_t category)
switch (category) {
case CAT_guide:
+ case CAT_userinterfaces:
prefix = "git";
break;
default:
@@ -433,6 +435,16 @@ void list_guides_help(void)
putchar('\n');
}
+void list_user_interfaces_help(void)
+{
+ struct category_description catdesc[] = {
+ { CAT_userinterfaces, N_("User-facing repository, command and file interfaces:") },
+ { 0, NULL }
+ };
+ print_cmd_by_category(catdesc, NULL);
+ putchar('\n');
+}
+
static int get_alias(const char *var, const char *value, void *data)
{
struct string_list *list = data;
diff --git a/help.h b/help.h
index 971a3ad855a..243104c27a7 100644
--- a/help.h
+++ b/help.h
@@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num)
void list_common_cmds_help(void);
void list_all_cmds_help(int show_external_commands, int show_aliases);
void list_guides_help(void);
+void list_user_interfaces_help(void);
void list_all_main_cmds(struct string_list *list);
void list_all_other_cmds(struct string_list *list);
diff --git a/t/t0012-help.sh b/t/t0012-help.sh
index 6c33a436901..bee5ed12203 100755
--- a/t/t0012-help.sh
+++ b/t/t0012-help.sh
@@ -44,6 +44,8 @@ test_expect_success 'invalid usage' '
test_expect_code 129 git help -g add &&
test_expect_code 129 git help -a -g &&
+ test_expect_code 129 git help --user-interfaces add &&
+
test_expect_code 129 git help -g -c &&
test_expect_code 129 git help --config-for-completion add &&
test_expect_code 129 git help --config-sections-for-completion add
@@ -104,9 +106,9 @@ test_expect_success 'git help' '
test_i18ngrep "^ commit " help.output &&
test_i18ngrep "^ fetch " help.output
'
+
test_expect_success 'git help -g' '
git help -g >help.output &&
- test_i18ngrep "^ attributes " help.output &&
test_i18ngrep "^ everyday " help.output &&
test_i18ngrep "^ tutorial " help.output
'
@@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' '
test_cmp expect test-browser.log
'
+test_expect_success 'git help --user-interfaces' '
+ git help --user-interfaces >help.output &&
+ grep "^ attributes " help.output &&
+ grep "^ mailmap " help.output
+'
+
test_expect_success 'git help -c' '
git help -c >help.output &&
cat >expect <<-\EOF &&
@@ -220,6 +228,8 @@ test_expect_success "'git help -a' section spacing" '
Low-level Commands / Syncing Repositories
Low-level Commands / Internal Helpers
+
+ User-facing repository, command and file interfaces
EOF
test_cmp expect actual
'
--
2.37.1.1232.gc0cde427aa7
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v7 05/10] git docs: add a category for file formats, protocols and interfaces
2022-08-02 12:56 ` [PATCH v7 00/10] " Ævar Arnfjörð Bjarmason
` (3 preceding siblings ...)
2022-08-02 12:56 ` [PATCH v7 04/10] git docs: add a category for user-facing file, repo and command UX Ævar Arnfjörð Bjarmason
@ 2022-08-02 12:56 ` Ævar Arnfjörð Bjarmason
2022-08-02 23:08 ` Junio C Hamano
2022-08-02 12:56 ` [PATCH v7 06/10] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
` (5 subsequent siblings)
10 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-02 12:56 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 3e2a78863b7..991e33f8a6e 100644
--- a/help.c
+++ b/help.c
@@ -39,6 +39,7 @@ static struct category_description main_categories[] = {
{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
{ CAT_userinterfaces, N_("User-facing repository, command and file interfaces") },
+ { CAT_developerinterfaces, N_("Developer-facing file file formats, protocols and interfaces") },
{ 0, NULL }
};
@@ -50,6 +51,7 @@ static const char *drop_prefix(const char *name, uint32_t category)
switch (category) {
case CAT_guide:
case CAT_userinterfaces:
+ case CAT_developerinterfaces:
prefix = "git";
break;
default:
@@ -445,6 +447,16 @@ void list_user_interfaces_help(void)
putchar('\n');
}
+void list_developer_interfaces_help(void)
+{
+ struct category_description catdesc[] = {
+ { CAT_developerinterfaces, N_("File formats, protocols and other developer interfaces:") },
+ { 0, NULL }
+ };
+ print_cmd_by_category(catdesc, NULL);
+ putchar('\n');
+}
+
static int get_alias(const char *var, const char *value, void *data)
{
struct string_list *list = data;
diff --git a/help.h b/help.h
index 243104c27a7..af073a7a026 100644
--- a/help.h
+++ b/help.h
@@ -23,6 +23,7 @@ void list_common_cmds_help(void);
void list_all_cmds_help(int show_external_commands, int show_aliases);
void list_guides_help(void);
void list_user_interfaces_help(void);
+void list_developer_interfaces_help(void);
void list_all_main_cmds(struct string_list *list);
void list_all_other_cmds(struct string_list *list);
diff --git a/t/t0012-help.sh b/t/t0012-help.sh
index bee5ed12203..4ed2f242eb2 100755
--- a/t/t0012-help.sh
+++ b/t/t0012-help.sh
@@ -230,6 +230,8 @@ test_expect_success "'git help -a' section spacing" '
Low-level Commands / Internal Helpers
User-facing repository, command and file interfaces
+
+ Developer-facing file file formats, protocols and interfaces
EOF
test_cmp expect actual
'
--
2.37.1.1232.gc0cde427aa7
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v7 06/10] docs: move commit-graph format docs to man section 5
2022-08-02 12:56 ` [PATCH v7 00/10] " Ævar Arnfjörð Bjarmason
` (4 preceding siblings ...)
2022-08-02 12:56 ` [PATCH v7 05/10] git docs: add a category for file formats, protocols and interfaces Ævar Arnfjörð Bjarmason
@ 2022-08-02 12:56 ` Ævar Arnfjörð Bjarmason
2022-08-03 15:48 ` Junio C Hamano
2022-08-02 12:56 ` [PATCH v7 07/10] docs: move protocol-related " Ævar Arnfjörð Bjarmason
` (4 subsequent siblings)
10 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-02 12:56 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.1232.gc0cde427aa7
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v7 07/10] docs: move protocol-related docs to man section 5
2022-08-02 12:56 ` [PATCH v7 00/10] " Ævar Arnfjörð Bjarmason
` (5 preceding siblings ...)
2022-08-02 12:56 ` [PATCH v7 06/10] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
@ 2022-08-02 12:56 ` Ævar Arnfjörð Bjarmason
2022-08-03 15:53 ` Junio C Hamano
2022-08-02 12:56 ` [PATCH v7 08/10] docs: move pack format " Ævar Arnfjörð Bjarmason
` (3 subsequent siblings)
10 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-02 12:56 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.1232.gc0cde427aa7
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v7 08/10] docs: move pack format docs to man section 5
2022-08-02 12:56 ` [PATCH v7 00/10] " Ævar Arnfjörð Bjarmason
` (6 preceding siblings ...)
2022-08-02 12:56 ` [PATCH v7 07/10] docs: move protocol-related " Ævar Arnfjörð Bjarmason
@ 2022-08-02 12:56 ` Ævar Arnfjörð Bjarmason
2022-08-03 16:25 ` Junio C Hamano
2022-08-02 12:56 ` [PATCH v7 09/10] docs: move http-protocol " Ævar Arnfjörð Bjarmason
` (2 subsequent siblings)
10 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-02 12:56 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.1232.gc0cde427aa7
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v7 09/10] docs: move http-protocol docs to man section 5
2022-08-02 12:56 ` [PATCH v7 00/10] " Ævar Arnfjörð Bjarmason
` (7 preceding siblings ...)
2022-08-02 12:56 ` [PATCH v7 08/10] docs: move pack format " Ævar Arnfjörð Bjarmason
@ 2022-08-02 12:56 ` Ævar Arnfjörð Bjarmason
2022-08-03 16:31 ` Junio C Hamano
2022-08-02 12:56 ` [PATCH v7 10/10] docs: move multi-pack-index " Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
10 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-02 12:56 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..2d5d6d17fb1 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -225,6 +225,7 @@ gitmodules userinterfaces
gitnamespaces guide
gitprotocol-capabilities developerinterfaces
gitprotocol-common developerinterfaces
+gitprotocol-http developerinterfaces
gitprotocol-pack developerinterfaces
gitprotocol-v2 developerinterfaces
gitremote-helpers guide
--
2.37.1.1232.gc0cde427aa7
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v7 10/10] docs: move multi-pack-index docs to man section 5
2022-08-02 12:56 ` [PATCH v7 00/10] " Ævar Arnfjörð Bjarmason
` (8 preceding siblings ...)
2022-08-02 12:56 ` [PATCH v7 09/10] docs: move http-protocol " Ævar Arnfjörð Bjarmason
@ 2022-08-02 12:56 ` Ævar Arnfjörð Bjarmason
2022-08-03 16:37 ` Junio C Hamano
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
10 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-02 12:56 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 2d5d6d17fb1..65b3e739be4 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -213,6 +213,7 @@ gitformat-bundle developerinterfaces
gitformat-chunk developerinterfaces
gitformat-commit-graph developerinterfaces
gitformat-index developerinterfaces
+gitformat-multi-pack-index developerinterfaces
gitformat-pack developerinterfaces
gitformat-pack-cruft developerinterfaces
gitformat-signature developerinterfaces
--
2.37.1.1232.gc0cde427aa7
^ permalink raw reply related [flat|nested] 112+ messages in thread
* Re: [PATCH v7 01/10] help.c: refactor drop_prefix() to use a "switch" statement"
2022-08-02 12:56 ` [PATCH v7 01/10] help.c: refactor drop_prefix() to use a "switch" statement" Ævar Arnfjörð Bjarmason
@ 2022-08-02 23:01 ` Junio C Hamano
0 siblings, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-08-02 23:01 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:
> Refactor the drop_prefix() function in in help.c to make it easier to
> strip prefixes from categories that aren't "CAT_guide". There are no
> functional changes here, by doing this we make a subsequent functional
> change's diff smaller.
>
> As before we first try to strip "git-" unconditionally, if that works
> we'll return the stripped string. Then we'll strip "git" if the
> command is in "CAT_guide".
OK. From the code structure's point of view, it somehow not exactly
satisfactory that we still need two "skip and then if skipped yield
the remainder" in this function. Especially because we only strip
once.
> This means that we'd in principle strip "git-gitfoo" down to "foo" if
> it's in CAT_guide. That doesn't make much sense, and we don't have
> such an entry in command-list.txt, but let's preserve that behavior
> for now.
I am not sure if that is what the code means.
"git-gitfoo" will become "gitfoo" regardless of what category we are
calling drop_prefix() for, because we will return the resulting name
without falling through to the new switch statement, if the first
"strip 'git-'" succeeds, no?
> 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..7e594d291b0 100644
> --- a/help.c
> +++ b/help.c
> @@ -44,13 +44,19 @@ static struct category_description main_categories[] = {
> static const char *drop_prefix(const char *name, uint32_t category)
> {
> const char *new_name;
> + const char *prefix = NULL;
>
> if (skip_prefix(name, "git-", &new_name))
> return new_name;
> - if (category == CAT_guide && skip_prefix(name, "git", &new_name))
> + switch (category) {
> + case CAT_guide:
> + prefix = "git";
> + break;
> + }
> + if (prefix && skip_prefix(name, prefix, &new_name))
> return new_name;
> - return name;
>
> + return name;
> }
The diff algorighm made an interesting choice as to which line to
consider common here. I would have expected to see
return new_name;
+
return name;
-
}
especially after reading the last paragraph of the proposed log
message.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v7 05/10] git docs: add a category for file formats, protocols and interfaces
2022-08-02 12:56 ` [PATCH v7 05/10] git docs: add a category for file formats, protocols and interfaces Ævar Arnfjörð Bjarmason
@ 2022-08-02 23:08 ` Junio C Hamano
0 siblings, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-08-02 23:08 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:
> 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.
Up to this point I think I didn't see anything objectionable (one
paragraph in the proposed log message of an early step was suspect,
though). I'll leave the rest to another sitting, as my
concentration is running out.
Thanks.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v7 06/10] docs: move commit-graph format docs to man section 5
2022-08-02 12:56 ` [PATCH v7 06/10] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
@ 2022-08-03 15:48 ` Junio C Hamano
0 siblings, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-08-03 15:48 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:
> 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(-)
OK. Rename of a single document with a bit of mark-up updates, plus
adjusting the links that refer to the original location to its new
location. Nothing unexpected, other than a single curious bit.
> 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
I do not think we want or need duplicate entries for "bundle",
and it has nothing to do with the "commit-graph" doc.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v7 07/10] docs: move protocol-related docs to man section 5
2022-08-02 12:56 ` [PATCH v7 07/10] docs: move protocol-related " Ævar Arnfjörð Bjarmason
@ 2022-08-03 15:53 ` Junio C Hamano
2022-08-04 16:29 ` Ævar Arnfjörð Bjarmason
0 siblings, 1 reply; 112+ messages in thread
From: Junio C Hamano @ 2022-08-03 15:53 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:
> 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(-)
OK, I see nothing unexpected.
There is a silent "oops that is a screw-up in the previous step that
can be buried in this patch that renames 4 files and hopefully nobody
would notice" included, which should be removed by fixing the original
screw-up in the previous step, though.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v7 08/10] docs: move pack format docs to man section 5
2022-08-02 12:56 ` [PATCH v7 08/10] docs: move pack format " Ævar Arnfjörð Bjarmason
@ 2022-08-03 16:25 ` Junio C Hamano
0 siblings, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-08-03 16:25 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:
> @@ -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
Possible #leftoverbits for cleaning up around here are:
* Update the above description to use the term "offset encoding"
from gitformat-patck[5] to give readers the term to look for;
* Update <varint.h> and mention that the encode/decode pair
declared there are to handle variable-length integers in the
"offset encoding".
* We might want to add an entry to the glossary, but the varint
representation is not end-user facing, so it may not be necessary
and the mention in <varint.h> would be enough.
> 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
I do not think this is quite right.
A reader who wants to learn about cruft packs, they need to know:
* what a packfile is and what is in .pack/.idx pair, as a
prerequisite information, that is described elsewhere
* what it is, what it is used for, and how it is meant to be used,
why the mtimes from the original loose objects need to be kept,
all of which is not file-format per-se, but is part of the
design, described in the original technical/cruft-packs.txt
* how .mtimes file records the _additional_ pieces of per-object
information only maintained for the "cruft pack" objects.
The original technical/cruft-packs.txt document was the design
document for the cruft packs feature as a whole, and it made sense
to write about both design and the implementation detail of the
mtimes format.
But that is not "cruft pack file format". I think this can be fixed
either by having at least two documents (one for "cruft packs"
overall design, plus another one for "mtimes file format"), or by
having one document that is clearly more than "file format". The
posted patch gives us a mixture of the two, that results in neither
of the two.
Stepping back a bit, unless we have separate .pack(5) and .idx(5)
manual pages, I suspect that having the format of .pack, .idx, .midx,
and .mtimes described in the same "file formats for packfiles" document
might make more sense. After all, those who come to the packfile format
document from "pack protocol" document do not mind that the former talks
about .idx file, which they would find no use for.
I hope Taylor can help us with his input when he comes back from his
honeymoon.
> 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
OK.
> 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
OK.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v7 09/10] docs: move http-protocol docs to man section 5
2022-08-02 12:56 ` [PATCH v7 09/10] docs: move http-protocol " Ævar Arnfjörð Bjarmason
@ 2022-08-03 16:31 ` Junio C Hamano
0 siblings, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-08-03 16:31 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:
> 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%)
OK.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v7 10/10] docs: move multi-pack-index docs to man section 5
2022-08-02 12:56 ` [PATCH v7 10/10] docs: move multi-pack-index " Ævar Arnfjörð Bjarmason
@ 2022-08-03 16:37 ` Junio C Hamano
0 siblings, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-08-03 16:37 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:
> 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]
I already sais that midx and mtimes may want to be all described in
the main packfile format documentation, but I am OK to have separate
pages for these auxiliary files that supplement the .pack/.idx pairs
of files. If we were to go that route, we should have a link to
cruft .mtimes page here, next to the link to midx page added here.
I find the direction of the overall goal of the series agreeable.
Thanks for working on the patches.
^ permalink raw reply [flat|nested] 112+ messages in thread
* [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories
2022-08-02 12:56 ` [PATCH v7 00/10] " Ævar Arnfjörð Bjarmason
` (9 preceding siblings ...)
2022-08-02 12:56 ` [PATCH v7 10/10] docs: move multi-pack-index " Ævar Arnfjörð Bjarmason
@ 2022-08-04 16:28 ` Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 01/12] help.c: refactor drop_prefix() to use a "switch" statement" Ævar Arnfjörð Bjarmason
` (12 more replies)
10 siblings, 13 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-04 16:28 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/
Changes since v7:
* Corrects the discussion of existing behavior in 1-2/12 (git-gitfoo
v.s. git-foo).
* Fixes a stray error in previous v7 rebasing in 6/12.
* Splits out the "signature" and "index" format doc conversions into
their own commits (previously part of the "pack" conversion).
* The "gitformat-pack" now contains what was previously in
"gitformat-cruft-pack", i.e. we discuss all of the pack files
(*.pack, *.idx etc.) in the one file.
(The *.bitmap bit is left out for now as before, due to in-flight
conflicts)
* Ejected the conversion of
Documentation/technical/multi-pack-index.txt, we discuss the midx
in the gitformat-pack already, that documentation is more in the
"design notes" category.
Perhaps we should have a gitdesign-* namespace for such things, but
let's leave it aside for now.
Ævar Arnfjörð Bjarmason (12):
help.c: refactor drop_prefix() to use a "switch" statement"
help.c: remove common category behavior from drop_prefix() behavior
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 index format docs to man section 5
docs: move signature docs to man section 5
docs: move pack format docs to man section 5
docs: move cruft pack docs to gitformat-pack
docs: move http-protocol docs to man section 5
Documentation/Makefile | 23 +--
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 | 4 +-
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 ++-
.../pack-format.txt => gitformat-pack.txt} | 160 +++++++++++++++++-
...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 +-
Documentation/technical/cruft-packs.txt | 123 --------------
.../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 | 36 +++-
help.c | 41 ++++-
help.h | 2 +
pack-revindex.h | 2 +-
refspec.h | 2 +-
t/t0012-help.sh | 14 +-
t/t5551-http-fetch-smart.sh | 4 +-
40 files changed, 590 insertions(+), 243 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/pack-format.txt => gitformat-pack.txt} (72%)
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%)
delete mode 100644 Documentation/technical/cruft-packs.txt
Range-diff against v7:
1: 2665148f45b ! 1: 8ae30ce2e80 help.c: refactor drop_prefix() to use a "switch" statement"
@@ Commit message
we'll return the stripped string. Then we'll strip "git" if the
command is in "CAT_guide".
- This means that we'd in principle strip "git-gitfoo" down to "foo" if
+ This means that we'd in principle strip "git-foo" down to "foo" if
it's in CAT_guide. That doesn't make much sense, and we don't have
such an entry in command-list.txt, but let's preserve that behavior
for now.
2: 56429194634 ! 2: aebb56da6e9 help.c: remove common category behavior from drop_prefix() behavior
@@ Commit message
Before this we'd in principle strip a "git-" prefix from a "guide" in
command-list.txt, in practice we have no such entry there. As we don't
- have any entry that looks like "git-gitfoo" in command-list.txt this
+ have any entry that looks like "git-foo" in command-list.txt this
changes nothing in practice, but it makes the intent of the code
- clearer.
+ clearer. In that hypothetical case we'd now strip it down to "-foo",
+ not "foo".
When this code was added in cfb22a02ab5 (help: use command-list.h for
common command list, 2018-05-10) the only entries in command-list.txt
3: 2d6c00a51fa = 3: 6c3c072de6f git help doc: use "<doc>" instead of "<guide>"
4: 8e9384a92f2 = 4: d12db4a9540 git docs: add a category for user-facing file, repo and command UX
5: 4367c1e7f50 = 5: f76e775bfdd git docs: add a category for file formats, protocols and interfaces
6: 5adabbb3a26 ! 6: df3ef265d45 docs: move commit-graph format docs to man section 5
@@ command-list.txt: gitdiffcore guide
giteveryday guide
gitfaq guide
gitformat-bundle developerinterfaces
-+gitformat-bundle developerinterfaces
+gitformat-commit-graph developerinterfaces
gitglossary guide
githooks userinterfaces
7: cfd1b0afb53 ! 7: daafbf9ae90 docs: move protocol-related docs to man section 5
@@ Documentation/technical/partial-clone.txt: Design Details
server to request filtering during packfile construction.
## command-list.txt ##
-@@ command-list.txt: gitdiffcore guide
- giteveryday guide
- gitfaq guide
- gitformat-bundle developerinterfaces
--gitformat-bundle developerinterfaces
- gitformat-commit-graph developerinterfaces
- gitglossary guide
- githooks userinterfaces
@@ command-list.txt: gitk mainporcelain
gitmailmap userinterfaces
gitmodules userinterfaces
10: 8baf1db4d30 ! 8: ea98b37e41a docs: move multi-pack-index docs to man section 5
@@ Metadata
Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Commit message ##
- docs: move multi-pack-index docs to man section 5
+ docs: move index format docs to man section 5
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.
+ the index format documentation.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Documentation/Makefile ##
-@@ Documentation/Makefile: MAN5_TXT += gitformat-bundle.txt
- MAN5_TXT += gitformat-chunk.txt
+@@ Documentation/Makefile: MAN1_TXT += gitweb.txt
+ MAN5_TXT += gitattributes.txt
+ MAN5_TXT += gitformat-bundle.txt
MAN5_TXT += gitformat-commit-graph.txt
- MAN5_TXT += gitformat-index.txt
-+MAN5_TXT += gitformat-multi-pack-index.txt
- MAN5_TXT += gitformat-pack-cruft.txt
- MAN5_TXT += gitformat-pack.txt
- MAN5_TXT += gitformat-signature.txt
-@@ Documentation/Makefile: TECH_DOCS += ToolsForGit
- TECH_DOCS += technical/bitmap-format
++MAN5_TXT += gitformat-index.txt
+ MAN5_TXT += githooks.txt
+ MAN5_TXT += gitignore.txt
+ MAN5_TXT += gitmailmap.txt
+@@ Documentation/Makefile: 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-heuristics
- TECH_DOCS += technical/parallel-checkout
- TECH_DOCS += technical/partial-clone
+ TECH_DOCS += technical/multi-pack-index
+ TECH_DOCS += technical/pack-format
- ## 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 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/technical/multi-pack-index.txt => Documentation/gitformat-multi-pack-index.txt ##
+ ## Documentation/technical/index-format.txt => Documentation/gitformat-index.txt ##
@@
--Multi-Pack-Index (MIDX) Design Notes
--====================================
-+gitformat-multi-pack-index(5)
-+=============================
++gitformat-index(5)
++==================
+
+NAME
+----
-+gitformat-multi-pack-index - The multi-pack-index file format
++gitformat-index - Git index format
+
+SYNOPSIS
+--------
+[verse]
-+$GIT_DIR/objects/pack/multi-pack-index
++$GIT_DIR/index
+
+DESCRIPTION
+-----------
++
+ Git index format
+-================
- The Git object directory contains a 'pack' directory containing
- packfiles (with suffix ".pack") and pack-indexes (with suffix
-@@ Documentation/gitformat-multi-pack-index.txt: Related Links
+ == The Git index file has the following format
- [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)
+@@ 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/gitformat-pack.txt ##
-@@ 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.
-
-+SEE ALSO
-+--------
-+
-+linkgit:gitformat-multi-pack-index[5]
-+
- GIT
- ---
- Part of the linkgit:git[1] suite
-
## command-list.txt ##
-@@ command-list.txt: gitformat-bundle developerinterfaces
- gitformat-chunk developerinterfaces
+@@ command-list.txt: giteveryday guide
+ gitfaq guide
+ gitformat-bundle developerinterfaces
gitformat-commit-graph developerinterfaces
- gitformat-index developerinterfaces
-+gitformat-multi-pack-index developerinterfaces
- gitformat-pack developerinterfaces
- gitformat-pack-cruft developerinterfaces
- gitformat-signature developerinterfaces
++gitformat-index developerinterfaces
+ gitglossary guide
+ githooks userinterfaces
+ gitignore userinterfaces
-: ----------- > 9: 42a4a3c3be8 docs: move signature docs to man section 5
8: 3505fa86039 ! 10: 576c1fef4b3 docs: move pack format docs to man section 5
@@ Commit message
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.
+ gitformat-commit-graph to a gitformat-chunk-format page.
- 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.
+ Integrating "Documentation/technical/bitmap-format.txt" and
+ "Documentation/technical/cruft-packs.txt" might logically be part of
+ this change, but as those cover parts of the wider "pack
+ format" (including associated files) that's documented outside of
+ "Documentation/technical/pack-format.txt" let's leave those for now,
+ subsequent commit(s) will address those.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
@@ Documentation/Makefile: MAN1_TXT += gitweb.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-index.txt
+MAN5_TXT += gitformat-pack.txt
-+MAN5_TXT += gitformat-signature.txt
+ MAN5_TXT += gitformat-signature.txt
MAN5_TXT += githooks.txt
MAN5_TXT += gitignore.txt
- MAN5_TXT += gitmailmap.txt
-@@ Documentation/Makefile: 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
+@@ Documentation/Makefile: 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
-@@ Documentation/Makefile: 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
## Documentation/config/pack.txt ##
@@ Documentation/config/pack.txt: permuted into their appropriate location when writing a new bitmap.
@@ Documentation/gitformat-commit-graph.txt: All multi-byte numbers are in network
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 ##
@@ 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
@@ Documentation/gitformat-index.txt: Git index format
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/cruft-packs.txt => Documentation/gitformat-pack-cruft.txt ##
-@@
--= 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
-@@ 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/technical/pack-format.txt => Documentation/gitformat-pack.txt ##
@@
@@ Documentation/gitformat-pack.txt: packs arranged in MIDX order (with the preferr
+
+GIT
+---
-+Part of the linkgit:git[1] suite
-
- ## Documentation/technical/signature-format.txt => Documentation/gitformat-signature.txt ##
-@@
--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
-@@ Documentation/gitformat-signature.txt: 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
## Documentation/gitprotocol-pack.txt ##
@@ command-list.txt: gitdiffcore guide
gitformat-bundle developerinterfaces
+gitformat-chunk developerinterfaces
gitformat-commit-graph developerinterfaces
-+gitformat-index developerinterfaces
+ gitformat-index developerinterfaces
+gitformat-pack developerinterfaces
-+gitformat-pack-cruft developerinterfaces
-+gitformat-signature developerinterfaces
+ gitformat-signature developerinterfaces
gitglossary guide
githooks userinterfaces
- gitignore userinterfaces
## pack-revindex.h ##
@@
-: ----------- > 11: b9dde9788d4 docs: move cruft pack docs to gitformat-pack
9: c4a7fe9d439 = 12: c572688c525 docs: move http-protocol docs to man section 5
--
2.37.1.1233.g61622908797
^ permalink raw reply [flat|nested] 112+ messages in thread
* [PATCH v8 01/12] help.c: refactor drop_prefix() to use a "switch" statement"
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
@ 2022-08-04 16:28 ` Ævar Arnfjörð Bjarmason
2022-08-04 21:16 ` Junio C Hamano
2022-08-04 16:28 ` [PATCH v8 02/12] help.c: remove common category behavior from drop_prefix() behavior Ævar Arnfjörð Bjarmason
` (11 subsequent siblings)
12 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-04 16:28 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
Refactor the drop_prefix() function in in help.c to make it easier to
strip prefixes from categories that aren't "CAT_guide". There are no
functional changes here, by doing this we make a subsequent functional
change's diff smaller.
As before we first try to strip "git-" unconditionally, if that works
we'll return the stripped string. Then we'll strip "git" if the
command is in "CAT_guide".
This means that we'd in principle strip "git-foo" down to "foo" if
it's in CAT_guide. That doesn't make much sense, and we don't have
such an entry in command-list.txt, but let's preserve that behavior
for now.
While we're at it remove a stray newline that had been added after the
"return name;" statement.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
help.c | 10 ++++++++--
1 file changed, 8 insertions(+), 2 deletions(-)
diff --git a/help.c b/help.c
index 41c41c2aa11..7e594d291b0 100644
--- a/help.c
+++ b/help.c
@@ -44,13 +44,19 @@ static struct category_description main_categories[] = {
static const char *drop_prefix(const char *name, uint32_t category)
{
const char *new_name;
+ const char *prefix = NULL;
if (skip_prefix(name, "git-", &new_name))
return new_name;
- if (category == CAT_guide && skip_prefix(name, "git", &new_name))
+ switch (category) {
+ case CAT_guide:
+ prefix = "git";
+ break;
+ }
+ if (prefix && skip_prefix(name, prefix, &new_name))
return new_name;
- return name;
+ return name;
}
static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask)
--
2.37.1.1233.g61622908797
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v8 02/12] help.c: remove common category behavior from drop_prefix() behavior
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 01/12] help.c: refactor drop_prefix() to use a "switch" statement" Ævar Arnfjörð Bjarmason
@ 2022-08-04 16:28 ` Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 03/12] git help doc: use "<doc>" instead of "<guide>" Ævar Arnfjörð Bjarmason
` (10 subsequent siblings)
12 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-04 16:28 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
Change the behavior of the "git" prefix stripping for CAT_guide so
that we don't try to strip the "git-" prefix in that case. We should
be stripping either "git" or "git-" depending on the category. This
change makes it easier to add extra "category" conditions in
subsequent commits.
Before this we'd in principle strip a "git-" prefix from a "guide" in
command-list.txt, in practice we have no such entry there. As we don't
have any entry that looks like "git-foo" in command-list.txt this
changes nothing in practice, but it makes the intent of the code
clearer. In that hypothetical case we'd now strip it down to "-foo",
not "foo".
When this code was added in cfb22a02ab5 (help: use command-list.h for
common command list, 2018-05-10) the only entries in command-list.txt
that didn't begin with "git-" were "gitweb" and "gitk".
Then when the "guides" special-case was added in 1b81d8cb19d (help:
use command-list.txt for the source of guides, 2018-05-20) we had the
various "git" (not "git-") prefixed "guide" entries, which the
"CAT_guide" case handles.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
help.c | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
diff --git a/help.c b/help.c
index 7e594d291b0..8a09f18a3d9 100644
--- a/help.c
+++ b/help.c
@@ -44,16 +44,17 @@ static struct category_description main_categories[] = {
static const char *drop_prefix(const char *name, uint32_t category)
{
const char *new_name;
- const char *prefix = NULL;
+ const char *prefix;
- if (skip_prefix(name, "git-", &new_name))
- return new_name;
switch (category) {
case CAT_guide:
prefix = "git";
break;
+ default:
+ prefix = "git-";
+ break;
}
- if (prefix && skip_prefix(name, prefix, &new_name))
+ if (skip_prefix(name, prefix, &new_name))
return new_name;
return name;
--
2.37.1.1233.g61622908797
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v8 03/12] git help doc: use "<doc>" instead of "<guide>"
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 01/12] help.c: refactor drop_prefix() to use a "switch" statement" Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 02/12] help.c: remove common category behavior from drop_prefix() behavior Ævar Arnfjörð Bjarmason
@ 2022-08-04 16:28 ` Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 04/12] git docs: add a category for user-facing file, repo and command UX Ævar Arnfjörð Bjarmason
` (9 subsequent siblings)
12 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-04 16:28 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.1233.g61622908797
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v8 04/12] git docs: add a category for user-facing file, repo and command UX
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
` (2 preceding siblings ...)
2022-08-04 16:28 ` [PATCH v8 03/12] git help doc: use "<doc>" instead of "<guide>" Ævar Arnfjörð Bjarmason
@ 2022-08-04 16:28 ` Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 05/12] git docs: add a category for file formats, protocols and interfaces Ævar Arnfjörð Bjarmason
` (8 subsequent siblings)
12 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-04 16:28 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 2ec9b2dc6bb..e8adeb09f1c 100644
--- a/Makefile
+++ b/Makefile
@@ -3531,6 +3531,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 8a09f18a3d9..3e2a78863b7 100644
--- a/help.c
+++ b/help.c
@@ -38,6 +38,7 @@ static struct category_description main_categories[] = {
{ CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") },
{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
+ { CAT_userinterfaces, N_("User-facing repository, command and file interfaces") },
{ 0, NULL }
};
@@ -48,6 +49,7 @@ static const char *drop_prefix(const char *name, uint32_t category)
switch (category) {
case CAT_guide:
+ case CAT_userinterfaces:
prefix = "git";
break;
default:
@@ -433,6 +435,16 @@ void list_guides_help(void)
putchar('\n');
}
+void list_user_interfaces_help(void)
+{
+ struct category_description catdesc[] = {
+ { CAT_userinterfaces, N_("User-facing repository, command and file interfaces:") },
+ { 0, NULL }
+ };
+ print_cmd_by_category(catdesc, NULL);
+ putchar('\n');
+}
+
static int get_alias(const char *var, const char *value, void *data)
{
struct string_list *list = data;
diff --git a/help.h b/help.h
index 971a3ad855a..243104c27a7 100644
--- a/help.h
+++ b/help.h
@@ -22,6 +22,7 @@ static inline void mput_char(char c, unsigned int num)
void list_common_cmds_help(void);
void list_all_cmds_help(int show_external_commands, int show_aliases);
void list_guides_help(void);
+void list_user_interfaces_help(void);
void list_all_main_cmds(struct string_list *list);
void list_all_other_cmds(struct string_list *list);
diff --git a/t/t0012-help.sh b/t/t0012-help.sh
index 6c33a436901..bee5ed12203 100755
--- a/t/t0012-help.sh
+++ b/t/t0012-help.sh
@@ -44,6 +44,8 @@ test_expect_success 'invalid usage' '
test_expect_code 129 git help -g add &&
test_expect_code 129 git help -a -g &&
+ test_expect_code 129 git help --user-interfaces add &&
+
test_expect_code 129 git help -g -c &&
test_expect_code 129 git help --config-for-completion add &&
test_expect_code 129 git help --config-sections-for-completion add
@@ -104,9 +106,9 @@ test_expect_success 'git help' '
test_i18ngrep "^ commit " help.output &&
test_i18ngrep "^ fetch " help.output
'
+
test_expect_success 'git help -g' '
git help -g >help.output &&
- test_i18ngrep "^ attributes " help.output &&
test_i18ngrep "^ everyday " help.output &&
test_i18ngrep "^ tutorial " help.output
'
@@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' '
test_cmp expect test-browser.log
'
+test_expect_success 'git help --user-interfaces' '
+ git help --user-interfaces >help.output &&
+ grep "^ attributes " help.output &&
+ grep "^ mailmap " help.output
+'
+
test_expect_success 'git help -c' '
git help -c >help.output &&
cat >expect <<-\EOF &&
@@ -220,6 +228,8 @@ test_expect_success "'git help -a' section spacing" '
Low-level Commands / Syncing Repositories
Low-level Commands / Internal Helpers
+
+ User-facing repository, command and file interfaces
EOF
test_cmp expect actual
'
--
2.37.1.1233.g61622908797
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v8 05/12] git docs: add a category for file formats, protocols and interfaces
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
` (3 preceding siblings ...)
2022-08-04 16:28 ` [PATCH v8 04/12] git docs: add a category for user-facing file, repo and command UX Ævar Arnfjörð Bjarmason
@ 2022-08-04 16:28 ` Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 06/12] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
` (7 subsequent siblings)
12 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-04 16:28 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 3e2a78863b7..991e33f8a6e 100644
--- a/help.c
+++ b/help.c
@@ -39,6 +39,7 @@ static struct category_description main_categories[] = {
{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
{ CAT_userinterfaces, N_("User-facing repository, command and file interfaces") },
+ { CAT_developerinterfaces, N_("Developer-facing file file formats, protocols and interfaces") },
{ 0, NULL }
};
@@ -50,6 +51,7 @@ static const char *drop_prefix(const char *name, uint32_t category)
switch (category) {
case CAT_guide:
case CAT_userinterfaces:
+ case CAT_developerinterfaces:
prefix = "git";
break;
default:
@@ -445,6 +447,16 @@ void list_user_interfaces_help(void)
putchar('\n');
}
+void list_developer_interfaces_help(void)
+{
+ struct category_description catdesc[] = {
+ { CAT_developerinterfaces, N_("File formats, protocols and other developer interfaces:") },
+ { 0, NULL }
+ };
+ print_cmd_by_category(catdesc, NULL);
+ putchar('\n');
+}
+
static int get_alias(const char *var, const char *value, void *data)
{
struct string_list *list = data;
diff --git a/help.h b/help.h
index 243104c27a7..af073a7a026 100644
--- a/help.h
+++ b/help.h
@@ -23,6 +23,7 @@ void list_common_cmds_help(void);
void list_all_cmds_help(int show_external_commands, int show_aliases);
void list_guides_help(void);
void list_user_interfaces_help(void);
+void list_developer_interfaces_help(void);
void list_all_main_cmds(struct string_list *list);
void list_all_other_cmds(struct string_list *list);
diff --git a/t/t0012-help.sh b/t/t0012-help.sh
index bee5ed12203..4ed2f242eb2 100755
--- a/t/t0012-help.sh
+++ b/t/t0012-help.sh
@@ -230,6 +230,8 @@ test_expect_success "'git help -a' section spacing" '
Low-level Commands / Internal Helpers
User-facing repository, command and file interfaces
+
+ Developer-facing file file formats, protocols and interfaces
EOF
test_cmp expect actual
'
--
2.37.1.1233.g61622908797
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v8 06/12] docs: move commit-graph format docs to man section 5
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
` (4 preceding siblings ...)
2022-08-04 16:28 ` [PATCH v8 05/12] git docs: add a category for file formats, protocols and interfaces Ævar Arnfjörð Bjarmason
@ 2022-08-04 16:28 ` Ævar Arnfjörð Bjarmason
2022-08-04 21:18 ` Junio C Hamano
2022-11-08 18:04 ` SZEDER Gábor
2022-08-04 16:28 ` [PATCH v8 07/12] docs: move protocol-related docs to man section 5 Ævar Arnfjörð Bjarmason
` (6 subsequent siblings)
12 siblings, 2 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-04 16:28 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 | 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 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..3afcfcd35f0 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -210,6 +210,7 @@ gitdiffcore guide
giteveryday guide
gitfaq guide
gitformat-bundle developerinterfaces
+gitformat-commit-graph developerinterfaces
gitglossary guide
githooks userinterfaces
gitignore userinterfaces
--
2.37.1.1233.g61622908797
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v8 07/12] docs: move protocol-related docs to man section 5
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
` (5 preceding siblings ...)
2022-08-04 16:28 ` [PATCH v8 06/12] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
@ 2022-08-04 16:28 ` Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 08/12] docs: move index format " Ævar Arnfjörð Bjarmason
` (5 subsequent siblings)
12 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-04 16:28 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 | 4 +++
refspec.h | 2 +-
t/t5551-http-fetch-smart.sh | 4 +--
17 files changed, 106 insertions(+), 37 deletions(-)
rename Documentation/{technical/protocol-capabilities.txt => gitprotocol-capabilities.txt} (96%)
rename Documentation/{technical/protocol-common.txt => gitprotocol-common.txt} (89%)
rename Documentation/{technical/pack-protocol.txt => gitprotocol-pack.txt} (98%)
rename Documentation/{technical/protocol-v2.txt => gitprotocol-v2.txt} (98%)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 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 3afcfcd35f0..ed859fdd798 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -218,6 +218,10 @@ gitk mainporcelain
gitmailmap userinterfaces
gitmodules userinterfaces
gitnamespaces guide
+gitprotocol-capabilities developerinterfaces
+gitprotocol-common developerinterfaces
+gitprotocol-pack developerinterfaces
+gitprotocol-v2 developerinterfaces
gitremote-helpers guide
gitrepository-layout userinterfaces
gitrevisions userinterfaces
diff --git a/refspec.h b/refspec.h
index 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.1233.g61622908797
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v8 08/12] docs: move index format docs to man section 5
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
` (6 preceding siblings ...)
2022-08-04 16:28 ` [PATCH v8 07/12] docs: move protocol-related docs to man section 5 Ævar Arnfjörð Bjarmason
@ 2022-08-04 16:28 ` Ævar Arnfjörð Bjarmason
2022-08-04 21:24 ` Junio C Hamano
2022-08-04 16:28 ` [PATCH v8 09/12] docs: move signature " Ævar Arnfjörð Bjarmason
` (4 subsequent siblings)
12 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-04 16:28 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 index format documentation.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/Makefile | 2 +-
.../index-format.txt => gitformat-index.txt} | 20 ++++++++++++++++++-
command-list.txt | 1 +
3 files changed, 21 insertions(+), 2 deletions(-)
rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index b53f3c12843..029067a77d5 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -26,6 +26,7 @@ MAN1_TXT += gitweb.txt
MAN5_TXT += gitattributes.txt
MAN5_TXT += gitformat-bundle.txt
MAN5_TXT += gitformat-commit-graph.txt
+MAN5_TXT += gitformat-index.txt
MAN5_TXT += githooks.txt
MAN5_TXT += gitignore.txt
MAN5_TXT += gitmailmap.txt
@@ -104,7 +105,6 @@ TECH_DOCS += technical/bitmap-format
TECH_DOCS += technical/cruft-packs
TECH_DOCS += technical/hash-function-transition
TECH_DOCS += technical/http-protocol
-TECH_DOCS += technical/index-format
TECH_DOCS += technical/long-running-process-protocol
TECH_DOCS += technical/multi-pack-index
TECH_DOCS += technical/pack-format
diff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt
similarity index 98%
rename from Documentation/technical/index-format.txt
rename to Documentation/gitformat-index.txt
index f691c20ab0a..9c3844298b8 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
@@ -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/command-list.txt b/command-list.txt
index ed859fdd798..5e8d8386683 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -211,6 +211,7 @@ giteveryday guide
gitfaq guide
gitformat-bundle developerinterfaces
gitformat-commit-graph developerinterfaces
+gitformat-index developerinterfaces
gitglossary guide
githooks userinterfaces
gitignore userinterfaces
--
2.37.1.1233.g61622908797
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v8 09/12] docs: move signature docs to man section 5
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
` (7 preceding siblings ...)
2022-08-04 16:28 ` [PATCH v8 08/12] docs: move index format " Ævar Arnfjörð Bjarmason
@ 2022-08-04 16:28 ` Ævar Arnfjörð Bjarmason
2022-08-04 21:25 ` Junio C Hamano
2022-08-04 16:28 ` [PATCH v8 10/12] docs: move pack format " Ævar Arnfjörð Bjarmason
` (3 subsequent siblings)
12 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-04 16:28 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 signature format documentation.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/Makefile | 2 +-
...ure-format.txt => gitformat-signature.txt} | 21 ++++++++++++++++---
command-list.txt | 1 +
3 files changed, 20 insertions(+), 4 deletions(-)
rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 029067a77d5..d122d1751d8 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -27,6 +27,7 @@ MAN5_TXT += gitattributes.txt
MAN5_TXT += gitformat-bundle.txt
MAN5_TXT += gitformat-commit-graph.txt
MAN5_TXT += gitformat-index.txt
+MAN5_TXT += gitformat-signature.txt
MAN5_TXT += githooks.txt
MAN5_TXT += gitignore.txt
MAN5_TXT += gitmailmap.txt
@@ -115,7 +116,6 @@ TECH_DOCS += technical/racy-git
TECH_DOCS += technical/reftable
TECH_DOCS += technical/send-pack-pipeline
TECH_DOCS += technical/shallow
-TECH_DOCS += technical/signature-format
TECH_DOCS += technical/trivial-merge
SP_ARTICLES += $(TECH_DOCS)
SP_ARTICLES += technical/api-index
diff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt
similarity index 96%
rename from Documentation/technical/signature-format.txt
rename to Documentation/gitformat-signature.txt
index 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/command-list.txt b/command-list.txt
index 5e8d8386683..68212e3c1bd 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -212,6 +212,7 @@ gitfaq guide
gitformat-bundle developerinterfaces
gitformat-commit-graph developerinterfaces
gitformat-index developerinterfaces
+gitformat-signature developerinterfaces
gitglossary guide
githooks userinterfaces
gitignore userinterfaces
--
2.37.1.1233.g61622908797
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v8 10/12] docs: move pack format docs to man section 5
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
` (8 preceding siblings ...)
2022-08-04 16:28 ` [PATCH v8 09/12] docs: move signature " Ævar Arnfjörð Bjarmason
@ 2022-08-04 16:28 ` Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 11/12] docs: move cruft pack docs to gitformat-pack Ævar Arnfjörð Bjarmason
` (2 subsequent siblings)
12 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-04 16:28 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 to a gitformat-chunk-format page.
Integrating "Documentation/technical/bitmap-format.txt" and
"Documentation/technical/cruft-packs.txt" might logically be part of
this change, but as those cover parts of the wider "pack
format" (including associated files) that's documented outside of
"Documentation/technical/pack-format.txt" let's leave those for now,
subsequent commit(s) will address those.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/Makefile | 3 +-
Documentation/config/pack.txt | 2 +-
Documentation/git-bundle.txt | 3 +-
Documentation/git-multi-pack-index.txt | 4 +--
.../chunk-format.txt => gitformat-chunk.txt} | 25 +++++++++++---
Documentation/gitformat-commit-graph.txt | 2 +-
Documentation/gitformat-index.txt | 2 +-
.../pack-format.txt => gitformat-pack.txt} | 34 +++++++++++++++++--
Documentation/gitprotocol-pack.txt | 2 +-
.../howto/recover-corrupted-object-harder.txt | 2 +-
.../technical/hash-function-transition.txt | 2 +-
Documentation/user-manual.txt | 2 +-
cache.h | 3 +-
command-list.txt | 2 ++
pack-revindex.h | 2 +-
15 files changed, 68 insertions(+), 22 deletions(-)
rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (91%)
rename Documentation/{technical/pack-format.txt => gitformat-pack.txt} (95%)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index d122d1751d8..d4a4a8c8b7d 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -25,8 +25,10 @@ MAN1_TXT += gitweb.txt
# man5 / man7 guides (note: new guides should also be added to command-list.txt)
MAN5_TXT += gitattributes.txt
MAN5_TXT += gitformat-bundle.txt
+MAN5_TXT += gitformat-chunk.txt
MAN5_TXT += gitformat-commit-graph.txt
MAN5_TXT += gitformat-index.txt
+MAN5_TXT += gitformat-pack.txt
MAN5_TXT += gitformat-signature.txt
MAN5_TXT += githooks.txt
MAN5_TXT += gitignore.txt
@@ -108,7 +110,6 @@ TECH_DOCS += technical/hash-function-transition
TECH_DOCS += technical/http-protocol
TECH_DOCS += technical/long-running-process-protocol
TECH_DOCS += technical/multi-pack-index
-TECH_DOCS += technical/pack-format
TECH_DOCS += technical/pack-heuristics
TECH_DOCS += technical/parallel-checkout
TECH_DOCS += technical/partial-clone
diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt
index 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/gitformat-index.txt b/Documentation/gitformat-index.txt
index 9c3844298b8..015cb21bdc0 100644
--- a/Documentation/gitformat-index.txt
+++ b/Documentation/gitformat-index.txt
@@ -139,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.
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/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 4aa1bd079d5..302810b353a 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 68212e3c1bd..5394eefb6ee 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -210,8 +210,10 @@ gitdiffcore guide
giteveryday guide
gitfaq guide
gitformat-bundle developerinterfaces
+gitformat-chunk developerinterfaces
gitformat-commit-graph developerinterfaces
gitformat-index developerinterfaces
+gitformat-pack developerinterfaces
gitformat-signature developerinterfaces
gitglossary guide
githooks userinterfaces
diff --git a/pack-revindex.h b/pack-revindex.h
index 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.1233.g61622908797
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v8 11/12] docs: move cruft pack docs to gitformat-pack
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
` (9 preceding siblings ...)
2022-08-04 16:28 ` [PATCH v8 10/12] docs: move pack format " Ævar Arnfjörð Bjarmason
@ 2022-08-04 16:28 ` Ævar Arnfjörð Bjarmason
2022-08-04 21:34 ` Junio C Hamano
2022-08-04 16:28 ` [PATCH v8 12/12] docs: move http-protocol docs to man section 5 Ævar Arnfjörð Bjarmason
2022-08-04 21:36 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Junio C Hamano
12 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-04 16:28 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
Integrate the cruft packs documentation initially added in
3d89a8c1180 (Documentation/technical: add cruft-packs.txt, 2022-05-20)
to the newly created "gitformat-pack" documentation.
Like the "bitmap-format" added before it in
0d4455a3ab0 (documentation: add documentation for the bitmap format,
2013-11-14) the "cruft-packs" were documented in their own file.
As the diff move detection will show there is no change to
"Documentation/technical/cruft-packs.txt" here except to move it, and
to "indent" the existing sections by adding an extra "=" to them.
We could similarly convert the "bitmap-format.txt", but let's leave it
for now due to a conflict with the in-flight ac/bitmap-lookup-table
series.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/Makefile | 1 -
Documentation/gitformat-pack.txt | 126 ++++++++++++++++++++++++
Documentation/technical/cruft-packs.txt | 123 -----------------------
3 files changed, 126 insertions(+), 124 deletions(-)
delete mode 100644 Documentation/technical/cruft-packs.txt
diff --git a/Documentation/Makefile b/Documentation/Makefile
index d4a4a8c8b7d..41a070ab593 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -105,7 +105,6 @@ TECH_DOCS += MyFirstObjectWalk
TECH_DOCS += SubmittingPatches
TECH_DOCS += ToolsForGit
TECH_DOCS += technical/bitmap-format
-TECH_DOCS += technical/cruft-packs
TECH_DOCS += technical/hash-function-transition
TECH_DOCS += technical/http-protocol
TECH_DOCS += technical/long-running-process-protocol
diff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt
index 546c99f8871..e06af02f211 100644
--- a/Documentation/gitformat-pack.txt
+++ b/Documentation/gitformat-pack.txt
@@ -11,6 +11,7 @@ SYNOPSIS
[verse]
$GIT_DIR/objects/pack/pack-*.{pack,idx}
$GIT_DIR/objects/pack/pack-*.rev
+$GIT_DIR/objects/pack/pack-*.mtimes
$GIT_DIR/objects/pack/multi-pack-index
DESCRIPTION
@@ -507,6 +508,131 @@ packs arranged in MIDX order (with the preferred pack coming first).
The MIDX's reverse index is stored in the optional 'RIDX' chunk within
the MIDX itself.
+== cruft packs
+
+The cruft packs feature offer an alternative to Git's traditional mechanism of
+removing unreachable objects. This document provides an overview of Git's
+pruning mechanism, and how a cruft pack can be used instead to accomplish the
+same.
+
+=== Background
+
+To remove unreachable objects from your repository, Git offers `git repack -Ad`
+(see linkgit:git-repack[1]). Quoting from the documentation:
+
+----
+[...] unreachable objects in a previous pack become loose, unpacked objects,
+instead of being left in the old pack. [...] loose unreachable objects will be
+pruned according to normal expiry rules with the next 'git gc' invocation.
+----
+
+Unreachable objects aren't removed immediately, since doing so could race with
+an incoming push which may reference an object which is about to be deleted.
+Instead, those unreachable objects are stored as loose objects and stay that way
+until they are older than the expiration window, at which point they are removed
+by linkgit:git-prune[1].
+
+Git must store these unreachable objects loose in order to keep track of their
+per-object mtimes. If these unreachable objects were written into one big pack,
+then either freshening that pack (because an object contained within it was
+re-written) or creating a new pack of unreachable objects would cause the pack's
+mtime to get updated, and the objects within it would never leave the expiration
+window. Instead, objects are stored loose in order to keep track of the
+individual object mtimes and avoid a situation where all cruft objects are
+freshened at once.
+
+This can lead to undesirable situations when a repository contains many
+unreachable objects which have not yet left the grace period. Having large
+directories in the shards of `.git/objects` can lead to decreased performance in
+the repository. But given enough unreachable objects, this can lead to inode
+starvation and degrade the performance of the whole system. Since we
+can never pack those objects, these repositories often take up a large amount of
+disk space, since we can only zlib compress them, but not store them in delta
+chains.
+
+=== Cruft packs
+
+A cruft pack eliminates the need for storing unreachable objects in a loose
+state by including the per-object mtimes in a separate file alongside a single
+pack containing all loose objects.
+
+A cruft pack is written by `git repack --cruft` when generating a new pack.
+linkgit:git-pack-objects[1]'s `--cruft` option. Note that `git repack --cruft`
+is a classic all-into-one repack, meaning that everything in the resulting pack is
+reachable, and everything else is unreachable. Once written, the `--cruft`
+option instructs `git repack` to generate another pack containing only objects
+not packed in the previous step (which equates to packing all unreachable
+objects together). This progresses as follows:
+
+ 1. Enumerate every object, marking any object which is (a) not contained in a
+ kept-pack, and (b) whose mtime is within the grace period as a traversal
+ tip.
+
+ 2. Perform a reachability traversal based on the tips gathered in the previous
+ step, adding every object along the way to the pack.
+
+ 3. Write the pack out, along with a `.mtimes` file that records the per-object
+ timestamps.
+
+This mode is invoked internally by linkgit:git-repack[1] when instructed to
+write a cruft pack. Crucially, the set of in-core kept packs is exactly the set
+of packs which will not be deleted by the repack; in other words, they contain
+all of the repository's reachable objects.
+
+When a repository already has a cruft pack, `git repack --cruft` typically only
+adds objects to it. An exception to this is when `git repack` is given the
+`--cruft-expiration` option, which allows the generated cruft pack to omit
+expired objects instead of waiting for linkgit:git-gc[1] to expire those objects
+later on.
+
+It is linkgit:git-gc[1] that is typically responsible for removing expired
+unreachable objects.
+
+=== Caution for mixed-version environments
+
+Repositories that have cruft packs in them will continue to work with any older
+version of Git. Note, however, that previous versions of Git which do not
+understand the `.mtimes` file will use the cruft pack's mtime as the mtime for
+all of the objects in it. In other words, do not expect older (pre-cruft pack)
+versions of Git to interpret or even read the contents of the `.mtimes` file.
+
+Note that having mixed versions of Git GC-ing the same repository can lead to
+unreachable objects never being completely pruned. This can happen under the
+following circumstances:
+
+ - An older version of Git running GC explodes the contents of an existing
+ cruft pack loose, using the cruft pack's mtime.
+ - A newer version running GC collects those loose objects into a cruft pack,
+ where the .mtime file reflects the loose object's actual mtimes, but the
+ cruft pack mtime is "now".
+
+Repeating this process will lead to unreachable objects not getting pruned as a
+result of repeatedly resetting the objects' mtimes to the present time.
+
+If you are GC-ing repositories in a mixed version environment, consider omitting
+the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and
+leaving the `gc.cruftPacks` configuration unset until all writers understand
+cruft packs.
+
+=== Alternatives
+
+Notable alternatives to this design include:
+
+ - The location of the per-object mtime data, and
+ - Storing unreachable objects in multiple cruft packs.
+
+On the location of mtime data, a new auxiliary file tied to the pack was chosen
+to avoid complicating the `.idx` format. If the `.idx` format were ever to gain
+support for optional chunks of data, it may make sense to consolidate the
+`.mtimes` format into the `.idx` itself.
+
+Storing unreachable objects among multiple cruft packs (e.g., creating a new
+cruft pack during each repacking operation including only unreachable objects
+which aren't already stored in an earlier cruft pack) is significantly more
+complicated to construct, and so aren't pursued here. The obvious drawback to
+the current implementation is that the entire cruft pack must be re-written from
+scratch.
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/cruft-packs.txt b/Documentation/technical/cruft-packs.txt
deleted file mode 100644
index d81f3a8982f..00000000000
--- a/Documentation/technical/cruft-packs.txt
+++ /dev/null
@@ -1,123 +0,0 @@
-= Cruft packs
-
-The cruft packs feature offer an alternative to Git's traditional mechanism of
-removing unreachable objects. This document provides an overview of Git's
-pruning mechanism, and how a cruft pack can be used instead to accomplish the
-same.
-
-== Background
-
-To remove unreachable objects from your repository, Git offers `git repack -Ad`
-(see linkgit:git-repack[1]). Quoting from the documentation:
-
-[quote]
-[...] unreachable objects in a previous pack become loose, unpacked objects,
-instead of being left in the old pack. [...] loose unreachable objects will be
-pruned according to normal expiry rules with the next 'git gc' invocation.
-
-Unreachable objects aren't removed immediately, since doing so could race with
-an incoming push which may reference an object which is about to be deleted.
-Instead, those unreachable objects are stored as loose objects and stay that way
-until they are older than the expiration window, at which point they are removed
-by linkgit:git-prune[1].
-
-Git must store these unreachable objects loose in order to keep track of their
-per-object mtimes. If these unreachable objects were written into one big pack,
-then either freshening that pack (because an object contained within it was
-re-written) or creating a new pack of unreachable objects would cause the pack's
-mtime to get updated, and the objects within it would never leave the expiration
-window. Instead, objects are stored loose in order to keep track of the
-individual object mtimes and avoid a situation where all cruft objects are
-freshened at once.
-
-This can lead to undesirable situations when a repository contains many
-unreachable objects which have not yet left the grace period. Having large
-directories in the shards of `.git/objects` can lead to decreased performance in
-the repository. But given enough unreachable objects, this can lead to inode
-starvation and degrade the performance of the whole system. Since we
-can never pack those objects, these repositories often take up a large amount of
-disk space, since we can only zlib compress them, but not store them in delta
-chains.
-
-== Cruft packs
-
-A cruft pack eliminates the need for storing unreachable objects in a loose
-state by including the per-object mtimes in a separate file alongside a single
-pack containing all loose objects.
-
-A cruft pack is written by `git repack --cruft` when generating a new pack.
-linkgit:git-pack-objects[1]'s `--cruft` option. Note that `git repack --cruft`
-is a classic all-into-one repack, meaning that everything in the resulting pack is
-reachable, and everything else is unreachable. Once written, the `--cruft`
-option instructs `git repack` to generate another pack containing only objects
-not packed in the previous step (which equates to packing all unreachable
-objects together). This progresses as follows:
-
- 1. Enumerate every object, marking any object which is (a) not contained in a
- kept-pack, and (b) whose mtime is within the grace period as a traversal
- tip.
-
- 2. Perform a reachability traversal based on the tips gathered in the previous
- step, adding every object along the way to the pack.
-
- 3. Write the pack out, along with a `.mtimes` file that records the per-object
- timestamps.
-
-This mode is invoked internally by linkgit:git-repack[1] when instructed to
-write a cruft pack. Crucially, the set of in-core kept packs is exactly the set
-of packs which will not be deleted by the repack; in other words, they contain
-all of the repository's reachable objects.
-
-When a repository already has a cruft pack, `git repack --cruft` typically only
-adds objects to it. An exception to this is when `git repack` is given the
-`--cruft-expiration` option, which allows the generated cruft pack to omit
-expired objects instead of waiting for linkgit:git-gc[1] to expire those objects
-later on.
-
-It is linkgit:git-gc[1] that is typically responsible for removing expired
-unreachable objects.
-
-== Caution for mixed-version environments
-
-Repositories that have cruft packs in them will continue to work with any older
-version of Git. Note, however, that previous versions of Git which do not
-understand the `.mtimes` file will use the cruft pack's mtime as the mtime for
-all of the objects in it. In other words, do not expect older (pre-cruft pack)
-versions of Git to interpret or even read the contents of the `.mtimes` file.
-
-Note that having mixed versions of Git GC-ing the same repository can lead to
-unreachable objects never being completely pruned. This can happen under the
-following circumstances:
-
- - An older version of Git running GC explodes the contents of an existing
- cruft pack loose, using the cruft pack's mtime.
- - A newer version running GC collects those loose objects into a cruft pack,
- where the .mtime file reflects the loose object's actual mtimes, but the
- cruft pack mtime is "now".
-
-Repeating this process will lead to unreachable objects not getting pruned as a
-result of repeatedly resetting the objects' mtimes to the present time.
-
-If you are GC-ing repositories in a mixed version environment, consider omitting
-the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and
-leaving the `gc.cruftPacks` configuration unset until all writers understand
-cruft packs.
-
-== Alternatives
-
-Notable alternatives to this design include:
-
- - The location of the per-object mtime data, and
- - Storing unreachable objects in multiple cruft packs.
-
-On the location of mtime data, a new auxiliary file tied to the pack was chosen
-to avoid complicating the `.idx` format. If the `.idx` format were ever to gain
-support for optional chunks of data, it may make sense to consolidate the
-`.mtimes` format into the `.idx` itself.
-
-Storing unreachable objects among multiple cruft packs (e.g., creating a new
-cruft pack during each repacking operation including only unreachable objects
-which aren't already stored in an earlier cruft pack) is significantly more
-complicated to construct, and so aren't pursued here. The obvious drawback to
-the current implementation is that the entire cruft pack must be re-written from
-scratch.
--
2.37.1.1233.g61622908797
^ permalink raw reply related [flat|nested] 112+ messages in thread
* [PATCH v8 12/12] docs: move http-protocol docs to man section 5
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
` (10 preceding siblings ...)
2022-08-04 16:28 ` [PATCH v8 11/12] docs: move cruft pack docs to gitformat-pack Ævar Arnfjörð Bjarmason
@ 2022-08-04 16:28 ` Ævar Arnfjörð Bjarmason
2022-08-04 21:36 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Junio C Hamano
12 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-04 16:28 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 41a070ab593..346bbcf8be7 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -36,6 +36,7 @@ MAN5_TXT += gitmailmap.txt
MAN5_TXT += gitmodules.txt
MAN5_TXT += gitprotocol-capabilities.txt
MAN5_TXT += gitprotocol-common.txt
+MAN5_TXT += gitprotocol-http.txt
MAN5_TXT += gitprotocol-pack.txt
MAN5_TXT += gitprotocol-v2.txt
MAN5_TXT += gitrepository-layout.txt
@@ -106,7 +107,6 @@ TECH_DOCS += SubmittingPatches
TECH_DOCS += ToolsForGit
TECH_DOCS += technical/bitmap-format
TECH_DOCS += technical/hash-function-transition
-TECH_DOCS += technical/http-protocol
TECH_DOCS += technical/long-running-process-protocol
TECH_DOCS += technical/multi-pack-index
TECH_DOCS += technical/pack-heuristics
diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt
index 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 5394eefb6ee..f96bdabd7d9 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -224,6 +224,7 @@ gitmodules userinterfaces
gitnamespaces guide
gitprotocol-capabilities developerinterfaces
gitprotocol-common developerinterfaces
+gitprotocol-http developerinterfaces
gitprotocol-pack developerinterfaces
gitprotocol-v2 developerinterfaces
gitremote-helpers guide
--
2.37.1.1233.g61622908797
^ permalink raw reply related [flat|nested] 112+ messages in thread
* Re: [PATCH v7 07/10] docs: move protocol-related docs to man section 5
2022-08-03 15:53 ` Junio C Hamano
@ 2022-08-04 16:29 ` Ævar Arnfjörð Bjarmason
2022-08-04 19:30 ` Junio C Hamano
0 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-04 16:29 UTC (permalink / raw)
To: Junio C Hamano
Cc: git, Eric Sunshine, Philippe Blain, Derrick Stolee, Taylor Blau,
Jeff King, Teng Long
On Wed, Aug 03 2022, Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> 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(-)
>
> OK, I see nothing unexpected.
>
> There is a silent "oops that is a screw-up in the previous step that
> can be buried in this patch that renames 4 files and hopefully nobody
> would notice" included, which should be removed by fixing the original
> screw-up in the previous step, though.
I tried to address all your other concerns in the just-sent v8, but I
don't think there's any rename fix-up here, but maybe I'm missing
something. These files are all being moved to their new
gitprotocol-*.txt homes (and weren't moved in preceding commits).
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v7 07/10] docs: move protocol-related docs to man section 5
2022-08-04 16:29 ` Ævar Arnfjörð Bjarmason
@ 2022-08-04 19:30 ` Junio C Hamano
2022-08-05 8:36 ` Ævar Arnfjörð Bjarmason
0 siblings, 1 reply; 112+ messages in thread
From: Junio C Hamano @ 2022-08-04 19:30 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:
> I tried to address all your other concerns in the just-sent v8, but I
> don't think there's any rename fix-up here, but maybe I'm missing
> something. These files are all being moved to their new
> gitprotocol-*.txt homes (and weren't moved in preceding commits).
Sorry, I thought it was rather obvious from what I wrote in my
review for the step before this one.
This is an "oops" fix-up buried in other changes in 07/10 that fixes
the duplicated entry made in the previous step.
> 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
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v8 01/12] help.c: refactor drop_prefix() to use a "switch" statement"
2022-08-04 16:28 ` [PATCH v8 01/12] help.c: refactor drop_prefix() to use a "switch" statement" Ævar Arnfjörð Bjarmason
@ 2022-08-04 21:16 ` Junio C Hamano
0 siblings, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-08-04 21:16 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 means that we'd in principle strip "git-foo" down to "foo" if
> it's in CAT_guide. That doesn't make much sense, and we don't have
> such an entry in command-list.txt, but let's preserve that behavior
> for now.
That makes sense. I guess the previous round of this step tried to
say the same thing, but it didn't "click" to me. The updated text
does make sense.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v8 06/12] docs: move commit-graph format docs to man section 5
2022-08-04 16:28 ` [PATCH v8 06/12] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
@ 2022-08-04 21:18 ` Junio C Hamano
2022-11-08 18:04 ` SZEDER Gábor
1 sibling, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-08-04 21:18 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:
> Continue the move of existing Documentation/technical/* protocol and
> file-format documentation into our main documentation space.
> ...
> diff --git a/command-list.txt b/command-list.txt
> index 1950c4ccd9c..3afcfcd35f0 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -210,6 +210,7 @@ gitdiffcore guide
> giteveryday guide
> gitfaq guide
> gitformat-bundle developerinterfaces
> +gitformat-commit-graph developerinterfaces
> gitglossary guide
> githooks userinterfaces
> gitignore userinterfaces
This round the entire patch looks good to me, including this file.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v8 08/12] docs: move index format docs to man section 5
2022-08-04 16:28 ` [PATCH v8 08/12] docs: move index format " Ævar Arnfjörð Bjarmason
@ 2022-08-04 21:24 ` Junio C Hamano
0 siblings, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-08-04 21:24 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:
> Continue the move of existing Documentation/technical/* protocol and
> file-format documentation into our main documentation space by moving
> the index format documentation.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> Documentation/Makefile | 2 +-
> .../index-format.txt => gitformat-index.txt} | 20 ++++++++++++++++++-
> command-list.txt | 1 +
> 3 files changed, 21 insertions(+), 2 deletions(-)
> rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)
OK, the corresponding step in the previous round mixed the index
format and the bundle format together with formats of pack-related
files in a single patch, but now we have a separate patch for the
index on its own, which we are seeing here.
Nothing unexpected in the patch. Very cleanly done.
Thanks.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v8 09/12] docs: move signature docs to man section 5
2022-08-04 16:28 ` [PATCH v8 09/12] docs: move signature " Ævar Arnfjörð Bjarmason
@ 2022-08-04 21:25 ` Junio C Hamano
0 siblings, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-08-04 21:25 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:
> Continue the move of existing Documentation/technical/* protocol and
> file-format documentation into our main documentation space by moving
> the signature format documentation.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
Exactly the same comment as the one for the previous one (index)
applies to this step (signature). Nicely done, without anything
unexpected.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v8 11/12] docs: move cruft pack docs to gitformat-pack
2022-08-04 16:28 ` [PATCH v8 11/12] docs: move cruft pack docs to gitformat-pack Ævar Arnfjörð Bjarmason
@ 2022-08-04 21:34 ` Junio C Hamano
2022-08-05 8:29 ` Ævar Arnfjörð Bjarmason
0 siblings, 1 reply; 112+ messages in thread
From: Junio C Hamano @ 2022-08-04 21:34 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:
> Integrate the cruft packs documentation initially added in
> 3d89a8c1180 (Documentation/technical: add cruft-packs.txt, 2022-05-20)
> to the newly created "gitformat-pack" documentation.
>
> Like the "bitmap-format" added before it in
> 0d4455a3ab0 (documentation: add documentation for the bitmap format,
> 2013-11-14) the "cruft-packs" were documented in their own file.
>
> As the diff move detection will show there is no change to
> "Documentation/technical/cruft-packs.txt" here except to move it, and
> to "indent" the existing sections by adding an extra "=" to them.
>
> We could similarly convert the "bitmap-format.txt", but let's leave it
> for now due to a conflict with the in-flight ac/bitmap-lookup-table
> series.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
OK, so this round we roll the "cruft packs" into the main "pack file
format" documentation, because the former is merely a minor deviation
at file format level (i.e. comes with an extra .mtimes file) and the
philosophy behind how they are meant to be used is what makes them,
that is mostly the same as the normal packs, different.
That makes sense to me, and I agree that in the longer term we may
want to treat the pack bitmap format documentation the same way.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
` (11 preceding siblings ...)
2022-08-04 16:28 ` [PATCH v8 12/12] docs: move http-protocol docs to man section 5 Ævar Arnfjörð Bjarmason
@ 2022-08-04 21:36 ` Junio C Hamano
12 siblings, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-08-04 21:36 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 the v5 for a general overview:
> https://lore.kernel.org/git/cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com/
>
> Ævar Arnfjörð Bjarmason (12):
> help.c: refactor drop_prefix() to use a "switch" statement"
> help.c: remove common category behavior from drop_prefix() behavior
> 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 index format docs to man section 5
> docs: move signature docs to man section 5
> docs: move pack format docs to man section 5
> docs: move cruft pack docs to gitformat-pack
> docs: move http-protocol docs to man section 5
OK, I have to admit that my eyes were a bit too tired to give a
fine-toothed-comb review, but between range-diff output and a full
reading of the new ones that range-diff did not match with the old
round, I did not find anything unexpected. Looking good.
Thanks.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v8 11/12] docs: move cruft pack docs to gitformat-pack
2022-08-04 21:34 ` Junio C Hamano
@ 2022-08-05 8:29 ` Ævar Arnfjörð Bjarmason
2022-08-05 16:12 ` Junio C Hamano
0 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-05 8:29 UTC (permalink / raw)
To: Junio C Hamano
Cc: git, Eric Sunshine, Philippe Blain, Derrick Stolee, Taylor Blau,
Jeff King, Teng Long
On Thu, Aug 04 2022, Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> Integrate the cruft packs documentation initially added in
>> 3d89a8c1180 (Documentation/technical: add cruft-packs.txt, 2022-05-20)
>> to the newly created "gitformat-pack" documentation.
>>
>> Like the "bitmap-format" added before it in
>> 0d4455a3ab0 (documentation: add documentation for the bitmap format,
>> 2013-11-14) the "cruft-packs" were documented in their own file.
>>
>> As the diff move detection will show there is no change to
>> "Documentation/technical/cruft-packs.txt" here except to move it, and
>> to "indent" the existing sections by adding an extra "=" to them.
>>
>> We could similarly convert the "bitmap-format.txt", but let's leave it
>> for now due to a conflict with the in-flight ac/bitmap-lookup-table
>> series.
>>
>> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
>> ---
>
> OK, so this round we roll the "cruft packs" into the main "pack file
> format" documentation, because the former is merely a minor deviation
> at file format level (i.e. comes with an extra .mtimes file) and the
> philosophy behind how they are meant to be used is what makes them,
> that is mostly the same as the normal packs, different.
Yes, perhaps we should split all of these out, but it's a smaller
logical change to just bundle the ones that were split out into the main
documentation.
> That makes sense to me, and I agree that in the longer term we may
> want to treat the pack bitmap format documentation the same way.
I have that patch locally already, and figured I'd send it in shortly
after this lands. I just didn't want to burden you with the merge
conflict with c7e7f5dd814 (Documentation/technical: describe bitmap
lookup table extension, 2022-07-20).
The merge conflict is relatively easy to deal with, I included a
resolution in the v3 of this series (but ejected the change out of v4):
https://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/
I can still re-roll with it if you'd like it sooner than later, or
ac/bitmap-lookup-table could be re-rolled on top of this topic
eventually (it seems it needs an eventual re-roll anyway due to SHA-256
flakyness).
Or we could just go with the status quo here and leave it until the dust
eventually settles, which is what I went with so far.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v7 07/10] docs: move protocol-related docs to man section 5
2022-08-04 19:30 ` Junio C Hamano
@ 2022-08-05 8:36 ` Ævar Arnfjörð Bjarmason
0 siblings, 0 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-05 8:36 UTC (permalink / raw)
To: Junio C Hamano
Cc: git, Eric Sunshine, Philippe Blain, Derrick Stolee, Taylor Blau,
Jeff King, Teng Long
On Thu, Aug 04 2022, Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> I tried to address all your other concerns in the just-sent v8, but I
>> don't think there's any rename fix-up here, but maybe I'm missing
>> something. These files are all being moved to their new
>> gitprotocol-*.txt homes (and weren't moved in preceding commits).
>
> Sorry, I thought it was rather obvious from what I wrote in my
> review for the step before this one.
>
> This is an "oops" fix-up buried in other changes in 07/10 that fixes
> the duplicated entry made in the previous step.
Ah!, sorry about not spotting that. I see I misread the "that renames 4
files[...]" part of your reply.
And when I was looking at this patch I'd already locally fixed the
earlier commit that had the duplicate command-list.txt entry, so I
couldn't see any issue with the rest of the commit either :)
In any case, it's all sorted in the v8, thanks!
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v8 11/12] docs: move cruft pack docs to gitformat-pack
2022-08-05 8:29 ` Ævar Arnfjörð Bjarmason
@ 2022-08-05 16:12 ` Junio C Hamano
0 siblings, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-08-05 16:12 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:
>> That makes sense to me, and I agree that in the longer term we may
>> want to treat the pack bitmap format documentation the same way.
>
> I have that patch locally already, and figured I'd send it in shortly
> after this lands. I just didn't want to burden you with the merge
> conflict with c7e7f5dd814 (Documentation/technical: describe bitmap
> lookup table extension, 2022-07-20).
>
> The merge conflict is relatively easy to deal with, I included a
> resolution in the v3 of this series (but ejected the change out of v4):
> https://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/
>
> I can still re-roll with it if you'd like it sooner than later, or
> ac/bitmap-lookup-table could be re-rolled on top of this topic
> eventually (it seems it needs an eventual re-roll anyway due to SHA-256
> flakyness).
>
> Or we could just go with the status quo here and leave it until the dust
> eventually settles, which is what I went with so far.
Let's go slowly. Others may feel differently and prefer separate
manual pages for .mtimes and .bitmap formats instead. They have
more info to form their opinions after this round lands.
Thanks.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v8 06/12] docs: move commit-graph format docs to man section 5
2022-08-04 16:28 ` [PATCH v8 06/12] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
2022-08-04 21:18 ` Junio C Hamano
@ 2022-11-08 18:04 ` SZEDER Gábor
2022-11-08 19:16 ` Ævar Arnfjörð Bjarmason
1 sibling, 1 reply; 112+ messages in thread
From: SZEDER Gábor @ 2022-11-08 18:04 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Junio C Hamano, Eric Sunshine, Philippe Blain,
Derrick Stolee, Taylor Blau, Jeff King, Teng Long
On Thu, Aug 04, 2022 at 06:28:35PM +0200, Ævar Arnfjörð Bjarmason wrote:
> 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.
So after this series I got a couple of gitformat-* manpages, but,
alas, most of them render improperly: a lot of paragraphs are for some
reason fixed width even in a fullscreen terminal window, and their
width is more than 80 chars, so they are rather awkward in a
standard-width terminal. This also affects the html version, where
those paragraphs are rendered with a fixed-width font.
> 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 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..3afcfcd35f0 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -210,6 +210,7 @@ gitdiffcore guide
> giteveryday guide
> gitfaq guide
> gitformat-bundle developerinterfaces
> +gitformat-commit-graph developerinterfaces
> gitglossary guide
> githooks userinterfaces
> gitignore userinterfaces
> --
> 2.37.1.1233.g61622908797
>
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v8 06/12] docs: move commit-graph format docs to man section 5
2022-11-08 18:04 ` SZEDER Gábor
@ 2022-11-08 19:16 ` Ævar Arnfjörð Bjarmason
2022-11-08 21:27 ` SZEDER Gábor
0 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-11-08 19:16 UTC (permalink / raw)
To: SZEDER Gábor
Cc: git, Junio C Hamano, Eric Sunshine, Philippe Blain,
Derrick Stolee, Taylor Blau, Jeff King, Teng Long
On Tue, Nov 08 2022, SZEDER Gábor wrote:
> On Thu, Aug 04, 2022 at 06:28:35PM +0200, Ævar Arnfjörð Bjarmason wrote:
>> 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.
>
> So after this series I got a couple of gitformat-* manpages, but,
> alas, most of them render improperly: a lot of paragraphs are for some
> reason fixed width even in a fullscreen terminal window, and their
> width is more than 80 chars, so they are rather awkward in a
> standard-width terminal. This also affects the html version, where
> those paragraphs are rendered with a fixed-width font.
Do you have examples of that, and are these cases where the formatting
was different before the move from Documentation/technical/*
I'm aware of e.g. gitformat-commit-graph(5) being somewhat funny, and
may have missed some cases, but I think that was also the case before...
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v8 06/12] docs: move commit-graph format docs to man section 5
2022-11-08 19:16 ` Ævar Arnfjörð Bjarmason
@ 2022-11-08 21:27 ` SZEDER Gábor
2022-11-09 1:34 ` Ævar Arnfjörð Bjarmason
0 siblings, 1 reply; 112+ messages in thread
From: SZEDER Gábor @ 2022-11-08 21:27 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Junio C Hamano, Eric Sunshine, Philippe Blain,
Derrick Stolee, Taylor Blau, Jeff King, Teng Long
On Tue, Nov 08, 2022 at 08:16:49PM +0100, Ævar Arnfjörð Bjarmason wrote:
>
> On Tue, Nov 08 2022, SZEDER Gábor wrote:
>
> > On Thu, Aug 04, 2022 at 06:28:35PM +0200, Ævar Arnfjörð Bjarmason wrote:
> >> 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.
> >
> > So after this series I got a couple of gitformat-* manpages, but,
> > alas, most of them render improperly: a lot of paragraphs are for some
> > reason fixed width even in a fullscreen terminal window, and their
> > width is more than 80 chars, so they are rather awkward in a
> > standard-width terminal. This also affects the html version, where
> > those paragraphs are rendered with a fixed-width font.
>
> Do you have examples of that
Here's the description of two chunks copy-pasted from 'man
gitformat-commit-graph' in a full-screen terminal, the first being
properly formatted (i.e. line length adjusted to the width of the
terminal), the latter having fixed-width:
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.
• Generation Data Overflow chunk is present only when Generation 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]
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
on. Starting at that array position, iterate through this list of commit
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.
There are similar formating issues in 'gitformat-index' and
'gitformat-pack' as well. I can see these both with AsciiDoc and
Asciidoctor.
> and are these cases where the formatting
> was different before the move from Documentation/technical/*
>
> I'm aware of e.g. gitformat-commit-graph(5) being somewhat funny, and
> may have missed some cases, but I think that was also the case before...
I'm not sure about "before", because 'make man' never built and
installed these gitformat-* manpages before this series.
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH v8 06/12] docs: move commit-graph format docs to man section 5
2022-11-08 21:27 ` SZEDER Gábor
@ 2022-11-09 1:34 ` Ævar Arnfjörð Bjarmason
2022-11-21 14:15 ` [PATCH] docs: de-indent first paragraph of gitformat-* to flow the text Ævar Arnfjörð Bjarmason
0 siblings, 1 reply; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-11-09 1:34 UTC (permalink / raw)
To: SZEDER Gábor
Cc: git, Junio C Hamano, Eric Sunshine, Philippe Blain,
Derrick Stolee, Taylor Blau, Jeff King, Teng Long
On Tue, Nov 08 2022, SZEDER Gábor wrote:
> On Tue, Nov 08, 2022 at 08:16:49PM +0100, Ævar Arnfjörð Bjarmason wrote:
>>
>> On Tue, Nov 08 2022, SZEDER Gábor wrote:
>>
>> > On Thu, Aug 04, 2022 at 06:28:35PM +0200, Ævar Arnfjörð Bjarmason wrote:
>> >> 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.
>> >
>> > So after this series I got a couple of gitformat-* manpages, but,
>> > alas, most of them render improperly: a lot of paragraphs are for some
>> > reason fixed width even in a fullscreen terminal window, and their
>> > width is more than 80 chars, so they are rather awkward in a
>> > standard-width terminal. This also affects the html version, where
>> > those paragraphs are rendered with a fixed-width font.
>>
>> Do you have examples of that
>
> Here's the description of two chunks copy-pasted from 'man
> gitformat-commit-graph' in a full-screen terminal, the first being
> properly formatted (i.e. line length adjusted to the width of the
> terminal), the latter having fixed-width:
>
> 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.
>
> • Generation Data Overflow chunk is present only when Generation 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]
> 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
> on. Starting at that array position, iterate through this list of commit
> 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.
>
> There are similar formating issues in 'gitformat-index' and
> 'gitformat-pack' as well. I can see these both with AsciiDoc and
> Asciidoctor.
Yeah, they look pretty bad.
>> and are these cases where the formatting
>> was different before the move from Documentation/technical/*
>>
>> I'm aware of e.g. gitformat-commit-graph(5) being somewhat funny, and
>> may have missed some cases, but I think that was also the case before...
>
> I'm not sure about "before", because 'make man' never built and
> installed these gitformat-* manpages before this series.
In the case of "gitformat-commit-graph" there was never a "html" version
of it before c0f6dd49f19 (Merge branch 'ab/tech-docs-to-help',
2022-08-14). But if you check out c0f6dd49f19^1 and:
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 4f801f4e4c9..d7a066a68d0 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -96,6 +96,7 @@ TECH_DOCS += SubmittingPatches
TECH_DOCS += ToolsForGit
TECH_DOCS += technical/bitmap-format
TECH_DOCS += technical/bundle-format
+TECH_DOCS += technical/commit-graph-format
TECH_DOCS += technical/cruft-packs
TECH_DOCS += technical/hash-function-transition
TECH_DOCS += technical/http-protoco
Then "make html" you'll see what the formatting was like before. Here's
generated versions of those & git-scm.com's version for comparison:
https://vm.nix.is/~avar/noindex/2022-11-09-gitdocs/commit-graph-format.html
https://git-scm.com/docs/gitformat-commit-graph
https://vm.nix.is/~avar/noindex/2022-11-09-gitdocs/index-format.html
https://git-scm.com/docs/gitformat-index
https://vm.nix.is/~avar/noindex/2022-11-09-gitdocs/pack-format.html
https://git-scm.com/docs/gitformat-pack
They should obviously be fixed, but I left that out of scope of that
series. If it was a fix-syntax-nits-while-at-it it would have been a lot
longer, and some of it's in some pseudo-syntax that was never quite
valid markdown. E.g. commit-graph-format.txt tried to use link:* syntax
in block-quoted text.
What I found *mostly* worked was to use "==" for sections, which
e.g. for gitformat-commit-graph ends up formatting it nicely as long as
it's followed by a bullet-point list, but as you show with "This lits of
4-byte..." that doesn't do the trick when it's not a list, instead it
uses the literal formatting (which almost the entire body of the text
used before).
I think the most minimal way of fixing it is to de-indent the opening
line of those sections, e.g.:
diff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt
index 31cad585e23..84df4a3ed03 100644
--- a/Documentation/gitformat-commit-graph.txt
+++ b/Documentation/gitformat-commit-graph.txt
@@ -67,17 +67,17 @@ All multi-byte numbers are in network byte order.
=== CHUNK LOOKUP:
- (C + 1) * 12 bytes listing the table of contents for the chunks:
+(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.
Other 8 bytes provide the byte-offset in current file for chunk to
start. (Chunks are ordered contiguously in the file, so you can infer
the length using the next chunk position if necessary.) Each chunk
ID appears at most once.
- The CHUNK LOOKUP matches the table of contents from
+The CHUNK LOOKUP matches the table of contents from
the chunk-based file format, see linkgit:gitformat-chunk[5]
- The remaining data in the body is described one chunk at a time, and
+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
otherwise specified.
@@ -126,7 +126,7 @@ All multi-byte numbers are in network byte order.
be stored within 31 bits.
==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]
- This list of 4-byte values store the second through nth parents for
+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
on. Starting at that array position, iterate through this list of commit
Seems to fix those "flow" issues for me, i.e. it's now a normal
paragraph, instead of a block-quoted fixed-width text.
^ permalink raw reply [flat|nested] 112+ messages in thread
* [PATCH] docs: de-indent first paragraph of gitformat-* to flow the text
2022-11-09 1:34 ` Ævar Arnfjörð Bjarmason
@ 2022-11-21 14:15 ` Ævar Arnfjörð Bjarmason
2022-11-21 17:59 ` Jeff King
2022-11-22 0:36 ` Junio C Hamano
0 siblings, 2 replies; 112+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-11-21 14:15 UTC (permalink / raw)
To: git
Cc: Taylor Blau, Junio C Hamano, SZEDER Gábor, Eric Sunshine,
Philippe Blain, Derrick Stolee, Jeff King, Teng Long,
Ævar Arnfjörð Bjarmason
Fix formatting issues with the documentation added to the new
gitformat-* namespace in c0f6dd49f19 (Merge branch
'ab/tech-docs-to-help', 2022-08-14).
As this documentation didn't have a wide audience before that, some of
these formatting issues pre-dated that change. See [1] for details.
But the end result of having some paragraphs use "<p>" in the HTML
output, and to have others wrapped in "<pre><code>" doesn't look
nice. The most minimal way to fix this is to de-indent the opening
line of paragraphs that don't start with another formatting
element (e.g. "*" or "-" would already format them as text). Let's do
that.
1. https://lore.kernel.org/git/221109.86bkpgriso.gmgdl@evledraar.gmail.com/
Reported-by: SZEDER Gábor <szeder.dev@gmail.com>
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
There's a lot more to fix in these gitformat-* docs (as their
formatting was funny before), but this is a minimal change to fix the
most major issues.
Documentation/gitformat-commit-graph.txt | 10 ++--
Documentation/gitformat-index.txt | 74 ++++++++++++------------
Documentation/gitformat-pack.txt | 4 +-
3 files changed, 44 insertions(+), 44 deletions(-)
diff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt
index 31cad585e23..219265a0c7a 100644
--- a/Documentation/gitformat-commit-graph.txt
+++ b/Documentation/gitformat-commit-graph.txt
@@ -67,17 +67,17 @@ All multi-byte numbers are in network byte order.
=== CHUNK LOOKUP:
- (C + 1) * 12 bytes listing the table of contents for the chunks:
+(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.
Other 8 bytes provide the byte-offset in current file for chunk to
start. (Chunks are ordered contiguously in the file, so you can infer
the length using the next chunk position if necessary.) Each chunk
ID appears at most once.
- The CHUNK LOOKUP matches the table of contents from
+The CHUNK LOOKUP matches the table of contents from
the chunk-based file format, see linkgit:gitformat-chunk[5]
- The remaining data in the body is described one chunk at a time, and
+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
otherwise specified.
@@ -126,7 +126,7 @@ All multi-byte numbers are in network byte order.
be stored within 31 bits.
==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]
- This list of 4-byte values store the second through nth parents for
+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
on. Starting at that array position, iterate through this list of commit
@@ -161,7 +161,7 @@ All multi-byte numbers are in network byte order.
* The BDAT chunk is present if and only if BIDX is present.
==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]
- This list of H-byte hashes describe a set of B commit-graph files that
+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.
diff --git a/Documentation/gitformat-index.txt b/Documentation/gitformat-index.txt
index 015cb21bdc0..bbc188b9e65 100644
--- a/Documentation/gitformat-index.txt
+++ b/Documentation/gitformat-index.txt
@@ -17,7 +17,7 @@ Git index format
== The Git index file has the following format
- All binary numbers are in network byte order.
+All binary numbers are in network byte order.
In a repository using the traditional SHA-1, checksums and object IDs
(object names) mentioned below are all computed using SHA-1. Similarly,
in SHA-256 repositories, these values are computed using SHA-256.
@@ -51,12 +51,12 @@ Git index format
== Index entry
- Index entries are sorted in ascending order on the name field,
+Index entries are sorted in ascending order on the name field,
interpreted as a string of unsigned bytes (i.e. memcmp() order, no
localization, no special casing of directory separator '/'). Entries
with the same name are sorted by their stage field.
- An index entry typically represents a file. However, if sparse-checkout
+An index entry typically represents a file. However, if sparse-checkout
is enabled in cone mode (`core.sparseCheckoutCone` is enabled) and the
`extensions.sparseIndex` extension is enabled, then the index may
contain entries for directories outside of the sparse-checkout definition.
@@ -103,7 +103,7 @@ Git index format
Object name for the represented object
- A 16-bit 'flags' field split into (high to low bits)
+A 16-bit 'flags' field split into (high to low bits)
1-bit assume-valid flag
@@ -114,7 +114,7 @@ Git index format
12-bit name length if the length is less than 0xFFF; otherwise 0xFFF
is stored in this field.
- (Version 3 or later) A 16-bit field, only applicable if the
+(Version 3 or later) A 16-bit field, only applicable if the
"extended flag" above is 1, split into (high to low bits).
1-bit reserved for future
@@ -125,16 +125,16 @@ Git index format
13-bit unused, must be zero
- Entry path name (variable length) relative to top level directory
+Entry path name (variable length) relative to top level directory
(without leading slash). '/' is used as path separator. The special
path components ".", ".." and ".git" (without quotes) are disallowed.
Trailing slash is also disallowed.
- The exact encoding is undefined, but the '.' and '/' characters
+The exact encoding is undefined, but the '.' and '/' characters
are encoded in 7-bit ASCII and the encoding cannot contain a NUL
byte (iow, this is a UNIX pathname).
- (Version 4) In version 4, the entry path name is prefix-compressed
+(Version 4) In version 4, the entry path name is prefix-compressed
relative to the path name for the previous entry (the very first
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
@@ -144,20 +144,20 @@ Git index format
path name for the previous entry, and replacing it with the string S
yields the path name for this entry.
- 1-8 nul bytes as necessary to pad the entry to a multiple of eight bytes
+1-8 nul bytes as necessary to pad the entry to a multiple of eight bytes
while keeping the name NUL-terminated.
- (Version 4) In version 4, the padding after the pathname does not
+(Version 4) In version 4, the padding after the pathname does not
exist.
- Interpretation of index entries in split index mode is completely
+Interpretation of index entries in split index mode is completely
different. See below for details.
== Extensions
=== Cache tree
- Since the index does not record entries for directories, the cache
+Since the index does not record entries for directories, the cache
entries cannot describe tree objects that already exist in the object
database for regions of the index that are unchanged from an existing
commit. The cache tree extension stores a recursive tree structure that
@@ -168,26 +168,26 @@ Git index format
as `HEAD^{tree}`, since sections of the index can be skipped when a tree
comparison demonstrates equality.
- The recursive tree structure uses nodes that store a number of cache
+The recursive tree structure uses nodes that store a number of cache
entries, a list of subnodes, and an object ID (OID). The OID references
the existing tree for that node, if it is known to exist. The subnodes
correspond to subdirectories that themselves have cache tree nodes. The
number of cache entries corresponds to the number of cache entries in
the index that describe paths within that tree's directory.
- The extension tracks the full directory structure in the cache tree
+The extension tracks the full directory structure in the cache tree
extension, but this is generally smaller than the full cache entry list.
- When a path is updated in index, Git invalidates all nodes of the
+When a path is updated in index, Git invalidates all nodes of the
recursive cache tree corresponding to the parent directories of that
path. We store these tree nodes as being "invalid" by using "-1" as the
number of cache entries. Invalid nodes still store a span of index
entries, allowing Git to focus its efforts when reconstructing a full
cache tree.
- The signature for this extension is { 'T', 'R', 'E', 'E' }.
+The signature for this extension is { 'T', 'R', 'E', 'E' }.
- A series of entries fill the entire extension; each of which
+A series of entries fill the entire extension; each of which
consists of:
- NUL-terminated path component (relative to its parent directory);
@@ -205,12 +205,12 @@ Git index format
- Object name for the object that would result from writing this span
of index as a tree.
- An entry can be in an invalidated state and is represented by having
+An entry can be in an invalidated state and is represented by having
a negative number in the entry_count field. In this case, there is no
object name and the next entry starts immediately after the newline.
When writing an invalid entry, -1 should always be used as entry_count.
- The entries are written out in the top-down, depth-first order. The
+The entries are written out in the top-down, depth-first order. The
first entry represents the root level of the repository, followed by the
first subtree--let's call this A--of the root level (with its name
relative to the root level), followed by the first subtree of A (with
@@ -219,19 +219,19 @@ Git index format
=== Resolve undo
- A conflict is represented in the index as a set of higher stage entries.
+A conflict is represented in the index as a set of higher stage entries.
When a conflict is resolved (e.g. with "git add path"), these higher
stage entries will be removed and a stage-0 entry with proper resolution
is added.
- When these higher stage entries are removed, they are saved in the
+When these higher stage entries are removed, they are saved in the
resolve undo extension, so that conflicts can be recreated (e.g. with
"git checkout -m"), in case users want to redo a conflict resolution
from scratch.
- The signature for this extension is { 'R', 'E', 'U', 'C' }.
+The signature for this extension is { 'R', 'E', 'U', 'C' }.
- A series of entries fill the entire extension; each of which
+A series of entries fill the entire extension; each of which
consists of:
- NUL-terminated pathname the entry describes (relative to the root of
@@ -246,13 +246,13 @@ Git index format
=== Split index
- In split index mode, the majority of index entries could be stored
+In split index mode, the majority of index entries could be stored
in a separate file. This extension records the changes to be made on
top of that to produce the final index.
- The signature for this extension is { 'l', 'i', 'n', 'k' }.
+The signature for this extension is { 'l', 'i', 'n', 'k' }.
- The extension consists of:
+The extension consists of:
- Hash of the shared index file. The shared index file path
is $GIT_DIR/sharedindex.<hash>. If all bits are zero, the
@@ -273,17 +273,17 @@ Git index format
first index entry, the second "1" bit to the second entry and so
on. Replaced entries may have empty path names to save space.
- The remaining index entries after replaced ones will be added to the
+The remaining index entries after replaced ones will be added to the
final index. These added entries are also sorted by entry name then
stage.
== Untracked cache
- Untracked cache saves the untracked file list and necessary data to
+Untracked cache saves the untracked file list and necessary data to
verify the cache. The signature for this extension is { 'U', 'N',
'T', 'R' }.
- The extension starts with
+The extension starts with
- A sequence of NUL-terminated strings, preceded by the size of the
sequence in variable width encoding. Each string describes the
@@ -341,11 +341,11 @@ The remaining data of each directory block is grouped by type:
== File System Monitor cache
- The file system monitor cache tracks files for which the core.fsmonitor
+The file system monitor cache tracks files for which the core.fsmonitor
hook has told us about changes. The signature for this extension is
{ 'F', 'S', 'M', 'N' }.
- The extension starts with
+The extension starts with
- 32-bit version number: the current supported versions are 1 and 2.
@@ -366,16 +366,16 @@ The remaining data of each directory block is grouped by type:
== End of Index Entry
- The End of Index Entry (EOIE) is used to locate the end of the variable
+The End of Index Entry (EOIE) is used to locate the end of the variable
length index entries and the beginning of the extensions. Code can take
advantage of this to quickly locate the index extensions without having
to parse through all of the index entries.
- Because it must be able to be loaded before the variable length cache
+Because it must be able to be loaded before the variable length cache
entries and other index extensions, this extension must be written last.
The signature for this extension is { 'E', 'O', 'I', 'E' }.
- The extension consists of:
+The extension consists of:
- 32-bit offset to the end of the index entries
@@ -389,12 +389,12 @@ The remaining data of each directory block is grouped by type:
== Index Entry Offset Table
- The Index Entry Offset Table (IEOT) is used to help address the CPU
+The Index Entry Offset Table (IEOT) is used to help address the CPU
cost of loading the index by enabling multi-threading the process of
converting cache entries from the on-disk format to the in-memory format.
The signature for this extension is { 'I', 'E', 'O', 'T' }.
- The extension consists of:
+The extension consists of:
- 32-bit version (currently 1)
@@ -407,7 +407,7 @@ The remaining data of each directory block is grouped by type:
== Sparse Directory Entries
- When using sparse-checkout in cone mode, some entire directories within
+When using sparse-checkout in cone mode, some entire directories within
the index can be summarized by pointing to a tree object instead of the
entire expanded list of paths within that tree. An index containing such
entries is a "sparse index". Index format versions 4 and less were not
diff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt
index e06af02f211..8a0e8dd160d 100644
--- a/Documentation/gitformat-pack.txt
+++ b/Documentation/gitformat-pack.txt
@@ -294,10 +294,10 @@ Pack file entry: <+
- The same trailer as a v1 pack file:
- A copy of the pack checksum at the end of
+A copy of the pack checksum at the end of
corresponding packfile.
- Index checksum of all of the above.
+Index checksum of all of the above.
== pack-*.rev files have the format:
--
2.38.0.1524.gdb7bac9ecc9
^ permalink raw reply related [flat|nested] 112+ messages in thread
* Re: [PATCH] docs: de-indent first paragraph of gitformat-* to flow the text
2022-11-21 14:15 ` [PATCH] docs: de-indent first paragraph of gitformat-* to flow the text Ævar Arnfjörð Bjarmason
@ 2022-11-21 17:59 ` Jeff King
2022-11-22 0:36 ` Junio C Hamano
1 sibling, 0 replies; 112+ messages in thread
From: Jeff King @ 2022-11-21 17:59 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Taylor Blau, Junio C Hamano, SZEDER Gábor,
Eric Sunshine, Philippe Blain, Derrick Stolee, Teng Long
On Mon, Nov 21, 2022 at 03:15:50PM +0100, Ævar Arnfjörð Bjarmason wrote:
> But the end result of having some paragraphs use "<p>" in the HTML
> output, and to have others wrapped in "<pre><code>" doesn't look
> nice. The most minimal way to fix this is to de-indent the opening
> line of paragraphs that don't start with another formatting
> element (e.g. "*" or "-" would already format them as text). Let's do
> that.
Is there any reason to just touch the opening line of the paragraphs,
and not change the indent of the whole thing? I understand that doing
the first line is sufficient to convince asciidoc to do what we want,
and the diff is technically fewer lines, but the result is rather
confusing for people who will work on the source in the future.
> There's a lot more to fix in these gitformat-* docs (as their
> formatting was funny before), but this is a minimal change to fix the
> most major issues.
I briefly looked at doc-diff output here. Most of them looked obviously
correct (though since there isn't a lot of context in the doc-diff, it's
sometimes hard to tell), but a few were questionable:
> @@ -103,7 +103,7 @@ Git index format
>
> Object name for the represented object
>
> - A 16-bit 'flags' field split into (high to low bits)
> +A 16-bit 'flags' field split into (high to low bits)
>
> 1-bit assume-valid flag
This puts "A 16-bit flags field" at a different indent than the
paragraph before, but I think it is part of a list. It is less indented
than the follow-on paragraph ("1-bit assume-valid flag"), but I think
that is correct, as it is a sub-list of the 16-bit flags.
I know you said that formatting problems remain, and certainly this was
not right before your patch either. But I think your patch makes it
worse, because it pulls the touched line out of the list (and all of the
adjacent parts are still rendered as code blocks, making the structure
even less clear).
> @@ -114,7 +114,7 @@ Git index format
> 12-bit name length if the length is less than 0xFFF; otherwise 0xFFF
> is stored in this field.
>
> - (Version 3 or later) A 16-bit field, only applicable if the
> +(Version 3 or later) A 16-bit field, only applicable if the
> "extended flag" above is 1, split into (high to low bits).
>
> 1-bit reserved for future
This is the same (it's the same list).
> @@ -125,16 +125,16 @@ Git index format
>
> 13-bit unused, must be zero
>
> - Entry path name (variable length) relative to top level directory
> +Entry path name (variable length) relative to top level directory
> (without leading slash). '/' is used as path separator. The special
> path components ".", ".." and ".git" (without quotes) are disallowed.
> Trailing slash is also disallowed.
And I think this is supposed to be part of that same list, too, but now
is de-dented.
> - The exact encoding is undefined, but the '.' and '/' characters
> +The exact encoding is undefined, but the '.' and '/' characters
> are encoded in 7-bit ASCII and the encoding cannot contain a NUL
> byte (iow, this is a UNIX pathname).
This is supposed to be a continuation of the earlier "Entry path name"
item, but now is at the same top-level. Which is not right, but arguably
is not worse than before your patch.
>
> - (Version 4) In version 4, the entry path name is prefix-compressed
> +(Version 4) In version 4, the entry path name is prefix-compressed
> relative to the path name for the previous entry (the very first
> 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
And this one is another top-level part of the list.
> --- a/Documentation/gitformat-pack.txt
> +++ b/Documentation/gitformat-pack.txt
> @@ -294,10 +294,10 @@ Pack file entry: <+
>
> - The same trailer as a v1 pack file:
>
> - A copy of the pack checksum at the end of
> +A copy of the pack checksum at the end of
> corresponding packfile.
>
> - Index checksum of all of the above.
> +Index checksum of all of the above.
These are supposed to be list items of "The same trailer as..." above.
Now they're de-dented, which I think is worse than the state before your
patch.
I don't want to say "we must fix all format problems at once", but I
think in the cases I pointed out that trying to fix the code-block
problem is a losing battle, because the list-like nature is being made
worse. And they probably should remain untouched until somebody is
willing to turn them into actual list elements and continuation markers.
-Peff
^ permalink raw reply [flat|nested] 112+ messages in thread
* Re: [PATCH] docs: de-indent first paragraph of gitformat-* to flow the text
2022-11-21 14:15 ` [PATCH] docs: de-indent first paragraph of gitformat-* to flow the text Ævar Arnfjörð Bjarmason
2022-11-21 17:59 ` Jeff King
@ 2022-11-22 0:36 ` Junio C Hamano
1 sibling, 0 replies; 112+ messages in thread
From: Junio C Hamano @ 2022-11-22 0:36 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Taylor Blau, SZEDER Gábor, Eric Sunshine,
Philippe Blain, Derrick Stolee, Jeff King, Teng Long
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> Fix formatting issues with the documentation added to the new
> gitformat-* namespace in c0f6dd49f19 (Merge branch
> 'ab/tech-docs-to-help', 2022-08-14).
I think I saw you do this before, but please refrain from blaming a
merge UNLESS there is a regression between the tip of the topic
getting merged c0f6dd49f19^2 and the result of the merge c0f6dd49f19
as it is confusing.
> === CHUNK LOOKUP:
>
> - (C + 1) * 12 bytes listing the table of contents for the chunks:
> +(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.
> Other 8 bytes provide the byte-offset in current file for chunk to
> start. (Chunks are ordered contiguously in the file, so you can infer
> the length using the next chunk position if necessary.) Each chunk
> ID appears at most once.
>
> - The CHUNK LOOKUP matches the table of contents from
> +The CHUNK LOOKUP matches the table of contents from
> the chunk-based file format, see linkgit:gitformat-chunk[5]
This makes the result awkward to read for those of us who consume
the text in the source form. I do not think a one-time cost of
reindenting the whole paragraph (and reviewing the patch to do so)
outweighs the cost of burdening the readers with the awkwardness.
^ permalink raw reply [flat|nested] 112+ messages in thread
end of thread, other threads:[~2022-11-22 0:36 UTC | newest]
Thread overview: 112+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
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 ` [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 22:30 ` Eric Sunshine
2021-12-13 9:33 ` Ævar Arnfjörð Bjarmason
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 ` [PATCH v2 4/5] docs: move protocol-related " Æ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
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
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 ` [PATCH v3 3/7] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
2022-07-12 20:06 ` [PATCH v3 4/7] docs: move protocol-related " Ævar Arnfjörð Bjarmason
2022-07-12 20:07 ` [PATCH v3 5/7] docs: move pack format " Ævar Arnfjörð Bjarmason
2022-07-12 20:07 ` [PATCH v3 6/7] docs: move http-protocol " Æ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
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
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
2022-07-19 23:21 ` Junio C Hamano
2022-07-21 7:02 ` Ævar Arnfjörð Bjarmason
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 ` [PATCH v4 4/8] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
2022-07-18 13:29 ` [PATCH v4 5/8] docs: move protocol-related " Ævar Arnfjörð Bjarmason
2022-07-18 13:29 ` [PATCH v4 6/8] docs: move pack format " Ævar Arnfjörð Bjarmason
2022-07-18 13:29 ` [PATCH v4 7/8] docs: move http-protocol " Ævar Arnfjörð Bjarmason
2022-07-18 13:29 ` [PATCH v4 8/8] docs: move multi-pack-index " Æ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-18 17:58 ` Ævar Arnfjörð Bjarmason
2022-07-21 7:12 ` Ævar Arnfjörð Bjarmason
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 ` [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 ` [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
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 ` [PATCH v5 6/9] docs: move protocol-related " Ævar Arnfjörð Bjarmason
2022-07-21 16:13 ` [PATCH v5 7/9] docs: move pack format " Ævar Arnfjörð Bjarmason
2022-07-21 16:13 ` [PATCH v5 8/9] docs: move http-protocol " Ævar Arnfjörð Bjarmason
2022-07-21 16:13 ` [PATCH v5 9/9] docs: move multi-pack-index " Æ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
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-30 0:17 ` Junio C Hamano
2022-08-01 11:55 ` Ævar Arnfjörð Bjarmason
2022-08-01 16:45 ` Junio C Hamano
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 ` [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 ` [PATCH v6 4/9] git docs: add a category for file formats, protocols and interfaces Æ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
2022-07-28 16:46 ` [PATCH v6 6/9] docs: move protocol-related " Ævar Arnfjörð Bjarmason
2022-07-28 16:46 ` [PATCH v6 7/9] docs: move pack format " Ævar Arnfjörð Bjarmason
2022-07-28 16:46 ` [PATCH v6 8/9] docs: move http-protocol " Ævar Arnfjörð Bjarmason
2022-07-28 16:46 ` [PATCH v6 9/9] docs: move multi-pack-index " Æ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
2022-08-02 12:56 ` [PATCH v7 01/10] help.c: refactor drop_prefix() to use a "switch" statement" Ævar Arnfjörð Bjarmason
2022-08-02 23:01 ` Junio C Hamano
2022-08-02 12:56 ` [PATCH v7 02/10] help.c: remove common category behavior from drop_prefix() behavior Ævar Arnfjörð Bjarmason
2022-08-02 12:56 ` [PATCH v7 03/10] git help doc: use "<doc>" instead of "<guide>" Ævar Arnfjörð Bjarmason
2022-08-02 12:56 ` [PATCH v7 04/10] git docs: add a category for user-facing file, repo and command UX Ævar Arnfjörð Bjarmason
2022-08-02 12:56 ` [PATCH v7 05/10] git docs: add a category for file formats, protocols and interfaces Ævar Arnfjörð Bjarmason
2022-08-02 23:08 ` Junio C Hamano
2022-08-02 12:56 ` [PATCH v7 06/10] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
2022-08-03 15:48 ` Junio C Hamano
2022-08-02 12:56 ` [PATCH v7 07/10] docs: move protocol-related " Ævar Arnfjörð Bjarmason
2022-08-03 15:53 ` Junio C Hamano
2022-08-04 16:29 ` Ævar Arnfjörð Bjarmason
2022-08-04 19:30 ` Junio C Hamano
2022-08-05 8:36 ` Ævar Arnfjörð Bjarmason
2022-08-02 12:56 ` [PATCH v7 08/10] docs: move pack format " Ævar Arnfjörð Bjarmason
2022-08-03 16:25 ` Junio C Hamano
2022-08-02 12:56 ` [PATCH v7 09/10] docs: move http-protocol " Ævar Arnfjörð Bjarmason
2022-08-03 16:31 ` Junio C Hamano
2022-08-02 12:56 ` [PATCH v7 10/10] docs: move multi-pack-index " Ævar Arnfjörð Bjarmason
2022-08-03 16:37 ` Junio C Hamano
2022-08-04 16:28 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 01/12] help.c: refactor drop_prefix() to use a "switch" statement" Ævar Arnfjörð Bjarmason
2022-08-04 21:16 ` Junio C Hamano
2022-08-04 16:28 ` [PATCH v8 02/12] help.c: remove common category behavior from drop_prefix() behavior Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 03/12] git help doc: use "<doc>" instead of "<guide>" Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 04/12] git docs: add a category for user-facing file, repo and command UX Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 05/12] git docs: add a category for file formats, protocols and interfaces Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 06/12] docs: move commit-graph format docs to man section 5 Ævar Arnfjörð Bjarmason
2022-08-04 21:18 ` Junio C Hamano
2022-11-08 18:04 ` SZEDER Gábor
2022-11-08 19:16 ` Ævar Arnfjörð Bjarmason
2022-11-08 21:27 ` SZEDER Gábor
2022-11-09 1:34 ` Ævar Arnfjörð Bjarmason
2022-11-21 14:15 ` [PATCH] docs: de-indent first paragraph of gitformat-* to flow the text Ævar Arnfjörð Bjarmason
2022-11-21 17:59 ` Jeff King
2022-11-22 0:36 ` Junio C Hamano
2022-08-04 16:28 ` [PATCH v8 07/12] docs: move protocol-related docs to man section 5 Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 08/12] docs: move index format " Ævar Arnfjörð Bjarmason
2022-08-04 21:24 ` Junio C Hamano
2022-08-04 16:28 ` [PATCH v8 09/12] docs: move signature " Ævar Arnfjörð Bjarmason
2022-08-04 21:25 ` Junio C Hamano
2022-08-04 16:28 ` [PATCH v8 10/12] docs: move pack format " Ævar Arnfjörð Bjarmason
2022-08-04 16:28 ` [PATCH v8 11/12] docs: move cruft pack docs to gitformat-pack Ævar Arnfjörð Bjarmason
2022-08-04 21:34 ` Junio C Hamano
2022-08-05 8:29 ` Ævar Arnfjörð Bjarmason
2022-08-05 16:12 ` Junio C Hamano
2022-08-04 16:28 ` [PATCH v8 12/12] docs: move http-protocol docs to man section 5 Ævar Arnfjörð Bjarmason
2022-08-04 21:36 ` [PATCH v8 00/12] docs: create & use "(user|developer) interfaces" categories Junio C Hamano
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).