From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: git@vger.kernel.org
Cc: "Junio C Hamano" <gitster@pobox.com>,
"Eric Sunshine" <sunshine@sunshineco.com>,
"Philippe Blain" <levraiphilippeblain@gmail.com>,
"Derrick Stolee" <stolee@gmail.com>,
"Taylor Blau" <me@ttaylorr.com>, "Jeff King" <peff@peff.net>,
"Teng Long" <dyroneteng@gmail.com>,
"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Subject: [PATCH v7 00/10] docs: create & use "(user|developer) interfaces" categories
Date: Tue, 2 Aug 2022 14:56:49 +0200 [thread overview]
Message-ID: <cover-v7-00.10-00000000000-20220802T125258Z-avarab@gmail.com> (raw)
In-Reply-To: <cover-v6-0.9-00000000000-20220728T164243Z-avarab@gmail.com>
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
next prev parent reply other threads:[~2022-08-02 12:58 UTC|newest]
Thread overview: 112+ messages / expand[flat|nested] mbox.gz Atom feed top
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 ` Ævar Arnfjörð Bjarmason [this message]
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=cover-v7-00.10-00000000000-20220802T125258Z-avarab@gmail.com \
--to=avarab@gmail.com \
--cc=dyroneteng@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=levraiphilippeblain@gmail.com \
--cc=me@ttaylorr.com \
--cc=peff@peff.net \
--cc=stolee@gmail.com \
--cc=sunshine@sunshineco.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).