freshlybakedca.ke
Git fork
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>
authored by
Ævar Arnfjörð Bjarmason
and committed by
Junio C Hamano
844739ba
d976c510
+2
-1
Documentation/Makefile
+2
-1
Documentation/Makefile
···
24
24
25
25
# man5 / man7 guides (note: new guides should also be added to command-list.txt)
26
26
MAN5_TXT += gitattributes.txt
27
+
MAN5_TXT += gitformat-bundle.txt
27
28
MAN5_TXT += githooks.txt
28
29
MAN5_TXT += gitignore.txt
29
30
MAN5_TXT += gitmailmap.txt
···
95
96
TECH_DOCS += SubmittingPatches
96
97
TECH_DOCS += ToolsForGit
97
98
TECH_DOCS += technical/bitmap-format
98
-
TECH_DOCS += technical/bundle-format
99
99
TECH_DOCS += technical/cruft-packs
100
100
TECH_DOCS += technical/hash-function-transition
101
101
TECH_DOCS += technical/http-protocol
···
290
290
cmds-synchingrepositories.txt \
291
291
cmds-synchelpers.txt \
292
292
cmds-guide.txt \
293
+
cmds-developerinterfaces.txt \
293
294
cmds-userinterfaces.txt \
294
295
cmds-purehelpers.txt \
295
296
cmds-foreignscminterface.txt
+9
-5
Documentation/git-bundle.txt
+9
-5
Documentation/git-bundle.txt
···
56
56
size. That they're "thin" under the hood is merely noted here as a
57
57
curiosity, and as a reference to other documentation.
58
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.
63
62
64
63
OPTIONS
65
64
-------
···
77
76
commits exist and are fully linked in the current repository.
78
77
Then, 'git bundle' prints a list of missing commits, if any.
79
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]
81
80
for more information. The exit code is zero for success, but will
82
81
be nonzero if the bundle file is invalid.
83
82
···
336
335
----------------
337
336
$ git ls-remote mybundle
338
337
----------------
338
+
339
+
FILE FORMAT
340
+
-----------
341
+
342
+
See linkgit:gitformat-bundle[5].
339
343
340
344
GIT
341
345
---
+5
Documentation/git-help.txt
+5
Documentation/git-help.txt
···
13
13
'git help' [-g|--guides]
14
14
'git help' [-c|--config]
15
15
'git help' [--user-interfaces]
16
+
'git help' [--developer-interfaces]
16
17
17
18
DESCRIPTION
18
19
-----------
···
82
83
user-interface conventions (e.g. linkgit:gitcli[7]), and
83
84
pseudo-configuration such as the file-based `.git/hooks/*` interface
84
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.
85
90
86
91
-i::
87
92
--info::
+9
Documentation/git.txt
+9
Documentation/git.txt
···
348
348
349
349
include::cmds-userinterfaces.txt[]
350
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
+
351
360
Configuration Mechanism
352
361
-----------------------
353
362
+3
Documentation/lint-man-section-order.perl
+3
Documentation/lint-man-section-order.perl
+37
-7
Documentation/technical/bundle-format.txt
Documentation/gitformat-bundle.txt
+37
-7
Documentation/technical/bundle-format.txt
Documentation/gitformat-bundle.txt
···
1
-
= Git bundle v2 format
1
+
gitformat-bundle(5)
2
+
===================
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
4
7
5
-
== Format
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
+
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
+
------
6
28
7
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.
9
31
10
32
A v2 bundle looks like this:
11
33
···
36
58
pack = ... ; packfile
37
59
----
38
60
39
-
== Semantics
61
+
62
+
SEMANTICS
63
+
---------
40
64
41
65
A Git bundle consists of several parts.
42
66
···
62
86
This is a comment and it has no specific meaning. The writer of the bundle MAY
63
87
put any string here. The reader of the bundle MUST ignore the comment.
64
88
65
-
=== Note on the shallow clone and a Git bundle
89
+
Note on the shallow clone and a Git bundle
90
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66
91
67
92
Note that the prerequisites does not represent a shallow-clone boundary. The
68
93
semantics of the prerequisites and the shallow-clone boundaries are different,
69
94
and the Git bundle v2 format cannot represent a shallow clone repository.
70
95
71
-
== Capabilities
96
+
CAPABILITIES
97
+
------------
72
98
73
99
Because there is no opportunity for negotiation, unknown capabilities cause 'git
74
100
bundle' to abort.
···
79
105
* `filter` specifies an object filter as in the `--filter` option in
80
106
linkgit:git-rev-list[1]. The resulting pack-file must be marked as a
81
107
`.promisor` pack-file after it is unbundled.
108
+
109
+
GIT
110
+
---
111
+
Part of the linkgit:git[1] suite
+9
builtin/help.c
+9
builtin/help.c
···
44
44
HELP_ACTION_GUIDES,
45
45
HELP_ACTION_CONFIG,
46
46
HELP_ACTION_USER_INTERFACES,
47
+
HELP_ACTION_DEVELOPER_INTERFACES,
47
48
HELP_ACTION_CONFIG_FOR_COMPLETION,
48
49
HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
49
50
} cmd_mode;
···
73
74
OPT_CMDMODE(0, "user-interfaces", &cmd_mode,
74
75
N_("print list of user-facing repository, command and file interfaces"),
75
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),
76
80
OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
77
81
HELP_ACTION_CONFIG),
78
82
OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
···
89
93
"git help [-g|--guides]",
90
94
"git help [-c|--config]",
91
95
"git help [--user-interfaces]",
96
+
"git help [--developer-interfaces]",
92
97
NULL
93
98
};
94
99
···
662
667
case HELP_ACTION_USER_INTERFACES:
663
668
opt_mode_usage(argc, "--user-interfaces", help_format);
664
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();
665
674
return 0;
666
675
case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
667
676
opt_mode_usage(argc, "--config-sections-for-completion",
+5
command-list.txt
+5
command-list.txt
···
48
48
# sections 5 and 7. These entries can only have the "userinterfaces"
49
49
# attribute and nothing else.
50
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
+
#
51
55
### command list (do not change this line)
52
56
# command name category [category] [category]
53
57
git-add mainporcelain worktree
···
205
209
gitdiffcore guide
206
210
giteveryday guide
207
211
gitfaq guide
212
+
gitformat-bundle developerinterfaces
208
213
gitglossary guide
209
214
githooks userinterfaces
210
215
gitignore userinterfaces
+12
help.c
+12
help.c
···
39
39
{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
40
40
{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
41
41
{ CAT_userinterfaces, N_("User-facing repository, command and file interfaces") },
42
+
{ CAT_developerinterfaces, N_("Developer-facing file file formats, protocols and interfaces") },
42
43
{ 0, NULL }
43
44
};
44
45
···
50
51
switch (category) {
51
52
case CAT_guide:
52
53
case CAT_userinterfaces:
54
+
case CAT_developerinterfaces:
53
55
prefix = "git";
54
56
break;
55
57
default:
···
439
441
{
440
442
struct category_description catdesc[] = {
441
443
{ CAT_userinterfaces, N_("User-facing repository, command and file interfaces:") },
444
+
{ 0, NULL }
445
+
};
446
+
print_cmd_by_category(catdesc, NULL);
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:") },
442
454
{ 0, NULL }
443
455
};
444
456
print_cmd_by_category(catdesc, NULL);
+1
help.h
+1
help.h
···
23
23
void list_all_cmds_help(int show_external_commands, int show_aliases);
24
24
void list_guides_help(void);
25
25
void list_user_interfaces_help(void);
26
+
void list_developer_interfaces_help(void);
26
27
27
28
void list_all_main_cmds(struct string_list *list);
28
29
void list_all_other_cmds(struct string_list *list);