git docs: add a category for file formats, protocols and interfaces
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Aug 4, 2022 at 18:28 UTC
844739ba275e451e44f09a61c4ce0458a8df6077
11 files changed
+94
-13
Documentation/Makefile
+2
-1
@@ -24,6 +24,7 @@ MAN1_TXT += gitweb.txt
24
25
# man5 / man7 guides (note: new guides should also be added to command-list.txt)
26
MAN5_TXT += gitattributes.txt
27
+MAN5_TXT += gitformat-bundle.txt
28
MAN5_TXT += githooks.txt
29
MAN5_TXT += gitignore.txt
30
MAN5_TXT += gitmailmap.txt
@@ -95,7 +96,6 @@ TECH_DOCS += MyFirstObjectWalk
96
TECH_DOCS += SubmittingPatches
97
TECH_DOCS += ToolsForGit
98
TECH_DOCS += technical/bitmap-format
98
-TECH_DOCS += technical/bundle-format
99
TECH_DOCS += technical/cruft-packs
100
TECH_DOCS += technical/hash-function-transition
101
TECH_DOCS += technical/http-protocol
@@ -290,6 +290,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
290
cmds-synchingrepositories.txt \
291
cmds-synchelpers.txt \
292
cmds-guide.txt \
293
+ cmds-developerinterfaces.txt \
294
cmds-userinterfaces.txt \
295
cmds-purehelpers.txt \
296
cmds-foreignscminterface.txt
Documentation/git-bundle.txt
+9
-5
@@ -56,10 +56,9 @@ using "thin packs", bundles created using exclusions are smaller in
56
size. That they're "thin" under the hood is merely noted here as a
57
curiosity, and as a reference to other documentation.
58
59
-See link:technical/bundle-format.html[the `bundle-format`
60
-documentation] for more details and the discussion of "thin pack" in
61
-link:technical/pack-format.html[the pack format documentation] for
62
-further details.
59
+See linkgit:gitformat-bundle[5] for more details and the discussion of
60
+"thin pack" in link:technical/pack-format.html[the pack format
61
+documentation] for further details.
62
63
OPTIONS
64
-------
@@ -77,7 +76,7 @@ verify <file>::
76
commits exist and are fully linked in the current repository.
77
Then, 'git bundle' prints a list of missing commits, if any.
78
Finally, information about additional capabilities, such as "object
80
- filter", is printed. See "Capabilities" in link:technical/bundle-format.html
79
+ filter", is printed. See "Capabilities" in linkgit:gitformat-bundle[5]
80
for more information. The exit code is zero for success, but will
81
be nonzero if the bundle file is invalid.
82
@@ -337,6 +336,11 @@ You can also see what references it offers:
336
$ git ls-remote mybundle
337
----------------
338
339
+FILE FORMAT
340
+-----------
341
+
342
+See linkgit:gitformat-bundle[5].
343
+
344
GIT
345
---
346
Part of the linkgit:git[1] suite
Documentation/git-help.txt
+5
@@ -13,6 +13,7 @@ SYNOPSIS
13
'git help' [-g|--guides]
14
'git help' [-c|--config]
15
'git help' [--user-interfaces]
16
+'git help' [--developer-interfaces]
17
18
DESCRIPTION
19
-----------
@@ -83,6 +84,10 @@ user-interface conventions (e.g. linkgit:gitcli[7]), and
84
pseudo-configuration such as the file-based `.git/hooks/*` interface
85
described in linkgit:githooks[5].
86
87
+--developer-interfaces::
88
+ Print list of file formats, protocols and other developer
89
+ interfaces documentation on the standard output.
90
+
91
-i::
92
--info::
93
Display manual page for the command in the 'info' format. The
Documentation/git.txt
+9
@@ -348,6 +348,15 @@ linkgit:git-help[1] for more details on the critera.
348
349
include::cmds-userinterfaces.txt[]
350
351
+File formats, protocols and other developer interfaces
352
+------------------------------------------------------
353
+
354
+This documentation discusses file formats, over-the-wire protocols and
355
+other git developer interfaces. See `--developer-interfaces` in
356
+linkgit:git-help[1].
357
+
358
+include::cmds-developerinterfaces.txt[]
359
+
360
Configuration Mechanism
361
-----------------------
362
Documentation/gitformat-bundle.txt
renamed
+37
-7
@@ -1,11 +1,33 @@
1
-= Git bundle v2 format
1
+gitformat-bundle(5)
2
+===================
3
3
-The Git bundle format is a format that represents both refs and Git objects.
4
+NAME
5
+----
6
+gitformat-bundle - The bundle file format
7
+
8
+
9
+SYNOPSIS
10
+--------
11
+[verse]
12
+*.bundle
13
+*.bdl
14
+
15
+DESCRIPTION
16
+-----------
17
+
18
+The Git bundle format is a format that represents both refs and Git
19
+objects. A bundle is a header in a format similar to
20
+linkgit:git-show-ref[1] followed by a pack in *.pack format.
21
5
-== Format
22
+The format is created and read by the linkgit:git-bundle[1] command,
23
+and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1].
24
+
25
+
26
+FORMAT
27
+------
28
29
We will use ABNF notation to define the Git bundle format. See
8
-protocol-common.txt for the details.
30
+link:technical/protocol-common.html for the details.
31
32
A v2 bundle looks like this:
33
@@ -36,7 +58,9 @@ value = *(%01-09 / %0b-FF)
58
pack = ... ; packfile
59
----
60
39
-== Semantics
61
+
62
+SEMANTICS
63
+---------
64
65
A Git bundle consists of several parts.
66
@@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id.
86
This is a comment and it has no specific meaning. The writer of the bundle MAY
87
put any string here. The reader of the bundle MUST ignore the comment.
88
65
-=== Note on the shallow clone and a Git bundle
89
+Note on the shallow clone and a Git bundle
90
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
91
92
Note that the prerequisites does not represent a shallow-clone boundary. The
93
semantics of the prerequisites and the shallow-clone boundaries are different,
94
and the Git bundle v2 format cannot represent a shallow clone repository.
95
71
-== Capabilities
96
+CAPABILITIES
97
+------------
98
99
Because there is no opportunity for negotiation, unknown capabilities cause 'git
100
bundle' to abort.
@@ -79,3 +105,7 @@ bundle' to abort.
105
* `filter` specifies an object filter as in the `--filter` option in
106
linkgit:git-rev-list[1]. The resulting pack-file must be marked as a
107
`.promisor` pack-file after it is unbundled.
108
+
109
+GIT
110
+---
111
+Part of the linkgit:git[1] suite
Documentation/lint-man-section-order.perl
+3
@@ -32,6 +32,9 @@ my %SECTIONS;
32
'SEE ALSO' => {
33
order => $order++,
34
},
35
+ 'FILE FORMAT' => {
36
+ order => $order++,
37
+ },
38
'GIT' => {
39
required => 1,
40
order => $order++,
builtin/help.c
+9
@@ -44,6 +44,7 @@ static enum help_action {
44
HELP_ACTION_GUIDES,
45
HELP_ACTION_CONFIG,
46
HELP_ACTION_USER_INTERFACES,
47
+ HELP_ACTION_DEVELOPER_INTERFACES,
48
HELP_ACTION_CONFIG_FOR_COMPLETION,
49
HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
50
} cmd_mode;
@@ -73,6 +74,9 @@ static struct option builtin_help_options[] = {
74
OPT_CMDMODE(0, "user-interfaces", &cmd_mode,
75
N_("print list of user-facing repository, command and file interfaces"),
76
HELP_ACTION_USER_INTERFACES),
77
+ OPT_CMDMODE(0, "developer-interfaces", &cmd_mode,
78
+ N_("print list of file formats, protocols and other developer interfaces"),
79
+ HELP_ACTION_DEVELOPER_INTERFACES),
80
OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
81
HELP_ACTION_CONFIG),
82
OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
@@ -89,6 +93,7 @@ static const char * const builtin_help_usage[] = {
93
"git help [-g|--guides]",
94
"git help [-c|--config]",
95
"git help [--user-interfaces]",
96
+ "git help [--developer-interfaces]",
97
NULL
98
};
99
@@ -663,6 +668,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)
668
opt_mode_usage(argc, "--user-interfaces", help_format);
669
list_user_interfaces_help();
670
return 0;
671
+ case HELP_ACTION_DEVELOPER_INTERFACES:
672
+ opt_mode_usage(argc, "--developer-interfaces", help_format);
673
+ list_developer_interfaces_help();
674
+ return 0;
675
case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
676
opt_mode_usage(argc, "--config-sections-for-completion",
677
help_format);
command-list.txt
+5
@@ -48,6 +48,10 @@
48
# sections 5 and 7. These entries can only have the "userinterfaces"
49
# attribute and nothing else.
50
#
51
+# Git's file formats and protocols, such as documentation for the
52
+# *.bundle format lives in man section 5. These entries can only have
53
+# the "developerinterfaces" attribute and nothing else.
54
+#
55
### command list (do not change this line)
56
# command name category [category] [category]
57
git-add mainporcelain worktree
@@ -205,6 +209,7 @@ gitcvs-migration guide
209
gitdiffcore guide
210
giteveryday guide
211
gitfaq guide
212
+gitformat-bundle developerinterfaces
213
gitglossary guide
214
githooks userinterfaces
215
gitignore userinterfaces
help.c
+12
@@ -39,6 +39,7 @@ static struct category_description main_categories[] = {
39
{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
40
{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
41
{ CAT_userinterfaces, N_("User-facing repository, command and file interfaces") },
42
+ { CAT_developerinterfaces, N_("Developer-facing file file formats, protocols and interfaces") },
43
{ 0, NULL }
44
};
45
@@ -50,6 +51,7 @@ static const char *drop_prefix(const char *name, uint32_t category)
51
switch (category) {
52
case CAT_guide:
53
case CAT_userinterfaces:
54
+ case CAT_developerinterfaces:
55
prefix = "git";
56
break;
57
default:
@@ -445,6 +447,16 @@ void list_user_interfaces_help(void)
447
putchar('\n');
448
}
449
450
+void list_developer_interfaces_help(void)
451
+{
452
+ struct category_description catdesc[] = {
453
+ { CAT_developerinterfaces, N_("File formats, protocols and other developer interfaces:") },
454
+ { 0, NULL }
455
+ };
456
+ print_cmd_by_category(catdesc, NULL);
457
+ putchar('\n');
458
+}
459
+
460
static int get_alias(const char *var, const char *value, void *data)
461
{
462
struct string_list *list = data;
help.h
+1
@@ -23,6 +23,7 @@ void list_common_cmds_help(void);
23
void list_all_cmds_help(int show_external_commands, int show_aliases);
24
void list_guides_help(void);
25
void list_user_interfaces_help(void);
26
+void list_developer_interfaces_help(void);
27
28
void list_all_main_cmds(struct string_list *list);
29
void list_all_other_cmds(struct string_list *list);
t/t0012-help.sh
+2
@@ -230,6 +230,8 @@ test_expect_success "'git help -a' section spacing" '
230
Low-level Commands / Internal Helpers
231
232
User-facing repository, command and file interfaces
233
+
234
+ Developer-facing file file formats, protocols and interfaces
235
EOF
236
test_cmp expect actual
237
'