Phillip (and others) the changes in this patch make "git help -g" now
lists a lot more guides than just the "common" one as advertised (see
below for the exact list). The man page for "git help -g" also
mentions that it would list "useful" guides, not all guides. But we
have no way to list all guides as far as I can tell.
I guess we have two options forward:
- keep "help -g" to common guide (we can tag common guides in
command-list.txt) and add a new option to list all guides ("help
-ag"?)
- reword the man page to make "help -g" list all guides
I'm ok with either direction. What's your preference?
For comparison, this is the new output
The common Git guides are:
attributes Defining attributes per path
cli Git command-line interface and conventions
core-tutorial A Git core tutorial for developers
cvs-migration Git for CVS users
diffcore Tweaking diff output
everyday A useful minimum set of commands for Everyday
Git
glossary A Git Glossary
hooks Hooks used by Git
ignore Specifies intentionally untracked files to
ignore
modules Defining submodule properties
namespaces Git namespaces
repository-layout Git Repository Layout
revisions Specifying revisions and ranges for Git
tutorial A tutorial introduction to Git
tutorial-2 A tutorial introduction to Git: part two
workflows An overview of recommended workflows with Git
compared to the old version
The common Git guides are:
attributes Defining attributes per path
everyday Everyday Git With 20 Commands Or So
glossary A Git glossary
ignore Specifies intentionally untracked files to ignore
modules Defining submodule properties
revisions Specifying revisions and ranges for Git
tutorial A tutorial introduction to Git (for version 1.5.1 or
newer)
workflows An overview of recommended workflows with Git
On Sun, Apr 29, 2018 at 8:18 PM, Nguyễn Thái Ngọc Duy <[email protected]> wrote:
> The help command currently hard codes the list of guides and their
> summary in C. Let's move this list to command-list.txt. This lets us
> extract summary lines from Documentation/git*.txt. This also
> potentially lets us list guides in git.txt, but I'll leave that for
> now.
>
> Signed-off-by: Nguyễn Thái Ngọc Duy <[email protected]>
> ---
> Documentation/gitattributes.txt | 2 +-
> Documentation/gitmodules.txt | 2 +-
> Documentation/gitrevisions.txt | 2 +-
> Makefile | 2 +-
> builtin/help.c | 32 --------------------------
> command-list.txt | 16 +++++++++++++
> contrib/completion/git-completion.bash | 15 ++++++++----
> help.c | 18 ++++++++++++---
> help.h | 1 +
> t/t0012-help.sh | 6 +++++
> 10 files changed, 52 insertions(+), 44 deletions(-)
>
> diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
> index 1094fe2b5b..083c2f380d 100644
> --- a/Documentation/gitattributes.txt
> +++ b/Documentation/gitattributes.txt
> @@ -3,7 +3,7 @@ gitattributes(5)
>
> NAME
> ----
> -gitattributes - defining attributes per path
> +gitattributes - Defining attributes per path
>
> SYNOPSIS
> --------
> diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
> index db5d47eb19..4d63def206 100644
> --- a/Documentation/gitmodules.txt
> +++ b/Documentation/gitmodules.txt
> @@ -3,7 +3,7 @@ gitmodules(5)
>
> NAME
> ----
> -gitmodules - defining submodule properties
> +gitmodules - Defining submodule properties
>
> SYNOPSIS
> --------
> diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt
> index 27dec5b91d..1f6cceaefb 100644
> --- a/Documentation/gitrevisions.txt
> +++ b/Documentation/gitrevisions.txt
> @@ -3,7 +3,7 @@ gitrevisions(7)
>
> NAME
> ----
> -gitrevisions - specifying revisions and ranges for Git
> +gitrevisions - Specifying revisions and ranges for Git
>
> SYNOPSIS
> --------
> diff --git a/Makefile b/Makefile
> index 71b5b594cd..18696e35b0 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1939,7 +1939,7 @@ $(BUILT_INS): git$X
>
> command-list.h: generate-cmdlist.sh command-list.txt
>
> -command-list.h: $(wildcard Documentation/git-*.txt)
> +command-list.h: $(wildcard Documentation/git*.txt)
> $(QUIET_GEN)$(SHELL_PATH) ./generate-cmdlist.sh command-list.txt >$@+
> && mv $@+ $@
>
> SCRIPT_DEFINES = $(SHELL_PATH_SQ):$(DIFF_SQ):$(GIT_VERSION):\
> diff --git a/builtin/help.c b/builtin/help.c
> index 83a7d73afe..b58e8d5f6a 100644
> --- a/builtin/help.c
> +++ b/builtin/help.c
> @@ -402,38 +402,6 @@ static void show_html_page(const char *git_cmd)
> open_html(page_path.buf);
> }
>
> -static struct {
> - const char *name;
> - const char *help;
> -} common_guides[] = {
> - { "attributes", N_("Defining attributes per path") },
> - { "everyday", N_("Everyday Git With 20 Commands Or So") },
> - { "glossary", N_("A Git glossary") },
> - { "ignore", N_("Specifies intentionally untracked files to ignore") },
> - { "modules", N_("Defining submodule properties") },
> - { "revisions", N_("Specifying revisions and ranges for Git") },
> - { "tutorial", N_("A tutorial introduction to Git (for version 1.5.1
> or newer)") },
> - { "workflows", N_("An overview of recommended workflows with Git") },
> -};
> -
> -static void list_common_guides_help(void)
> -{
> - int i, longest = 0;
> -
> - for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
> - if (longest < strlen(common_guides[i].name))
> - longest = strlen(common_guides[i].name);
> - }
> -
> - puts(_("The common Git guides are:\n"));
> - for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
> - printf(" %s ", common_guides[i].name);
> - mput_char(' ', longest - strlen(common_guides[i].name));
> - puts(_(common_guides[i].help));
> - }
> - putchar('\n');
> -}
> -
> static const char *check_git_cmd(const char* cmd)
> {
> char *alias;
> diff --git a/command-list.txt b/command-list.txt
> index 3bd23201a6..99ddc231c1 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -139,3 +139,19 @@ gitweb
> ancillaryinterrogators
> git-whatchanged ancillaryinterrogators
> git-worktree mainporcelain
> git-write-tree plumbingmanipulators
> +gitattributes guide
> +gitcli guide
> +gitcore-tutorial guide
> +gitcvs-migration guide
> +gitdiffcore guide
> +giteveryday guide
> +gitglossary guide
> +githooks guide
> +gitignore guide
> +gitmodules guide
> +gitnamespaces guide
> +gitrepository-layout guide
> +gitrevisions guide
> +gittutorial-2 guide
> +gittutorial guide
> +gitworkflows guide
> diff --git a/contrib/completion/git-completion.bash
> b/contrib/completion/git-completion.bash
> index 77cfb8a20b..50d14a93dc 100644
> --- a/contrib/completion/git-completion.bash
> +++ b/contrib/completion/git-completion.bash
> @@ -1570,6 +1570,13 @@ _git_grep ()
> __git_complete_refs
> }
>
> +__git_all_guides=
> +__git_compute_all_guides ()
> +{
> + test -n "$__git_all_guides" ||
> + __git_all_guides=$(git --list-cmds=list-guide)
> +}
> +
> _git_help ()
> {
> case "$cur" in
> @@ -1579,11 +1586,9 @@ _git_help ()
> ;;
> esac
> __git_compute_all_commands
> - __gitcomp "$__git_all_commands $(__git_aliases)
> - attributes cli core-tutorial cvs-migration
> - diffcore everyday gitk glossary hooks ignore modules
> - namespaces repository-layout revisions tutorial tutorial-2
> - workflows
> + __git_compute_all_guides
> + __gitcomp "$__git_all_commands $(__git_aliases) $__git_all_guides
> + gitk
> "
> }
>
> diff --git a/help.c b/help.c
> index f9da0214f1..f4629d0ee1 100644
> --- a/help.c
> +++ b/help.c
> @@ -39,12 +39,14 @@ static struct category_description main_categories[] = {
> { 0, NULL }
> };
>
> -static const char *drop_prefix(const char *name)
> +static const char *drop_prefix(const char *name, uint32_t category)
> {
> const char *new_name;
>
> if (skip_prefix(name, "git-", &new_name))
> return new_name;
> + if (category == CAT_guide && skip_prefix(name, "git", &new_name))
> + return new_name;
> return name;
>
> }
> @@ -66,7 +68,7 @@ static void extract_cmds(struct cmdname_help **p_cmds,
> uint32_t mask)
> continue;
>
> cmds[nr] = *cmd;
> - cmds[nr].name = drop_prefix(cmd->name);
> + cmds[nr].name = drop_prefix(cmd->name, cmd->category);
>
> nr++;
> }
> @@ -358,10 +360,20 @@ void list_cmds_by_category(const char *cat)
> struct cmdname_help *cmd = command_list + i;
>
> if (cmd->category & cat_id)
> - puts(drop_prefix(cmd->name));
> + puts(drop_prefix(cmd->name, cmd->category));
> }
> }
>
> +void list_common_guides_help(void)
> +{
> + struct category_description catdesc[] = {
> + { CAT_guide, N_("The common Git guides are:") },
> + { 0, NULL }
> + };
> + print_cmd_by_category(catdesc);
> + putchar('\n');
> +}
> +
> void list_all_cmds_help(void)
> {
> print_cmd_by_category(main_categories);
> diff --git a/help.h b/help.h
> index 090d46ba01..5d27368fe4 100644
> --- a/help.h
> +++ b/help.h
> @@ -18,6 +18,7 @@ static inline void mput_char(char c, unsigned int num)
>
> extern void list_common_cmds_help(void);
> extern void list_all_cmds_help(void);
> +extern void list_common_guides_help(void);
> extern void list_all_main_cmds(void);
> extern void list_all_other_cmds(void);
> extern void list_cmds_by_category(const char *category);
> diff --git a/t/t0012-help.sh b/t/t0012-help.sh
> index 060df24c2d..bc27df7f38 100755
> --- a/t/t0012-help.sh
> +++ b/t/t0012-help.sh
> @@ -66,6 +66,12 @@ 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
> +'
>
> test_expect_success 'generate builtin list' '
> git --list-cmds=builtins >builtins
> --
> 2.17.0.664.g8924eee37a
>
--
Duy
