diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index 04f99778d8..5aa73cfe45 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -38,6 +38,10 @@ sub format_one { } } +while (<>) { + last if /^### command list/; +} + my %cmds = (); for (sort <>) { next if /^#/; diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt index d7de5a3e9e..6d772bd927 100644 --- a/Documentation/howto/new-command.txt +++ b/Documentation/howto/new-command.txt @@ -95,7 +95,9 @@ your language, document it in the INSTALL file. that categorizes commands by type, so they can be listed in appropriate subsections in the documentation's summary command list. Add an entry for yours. To understand the categories, look at git-commands.txt -in the main directory. +in the main directory. If the new command is part of the typical Git +workflow and you believe it common enough to be mentioned in 'git help', +map this command to a common group in the column [common]. 7. Give the maintainer one paragraph to include in the RelNotes file to describe the new feature; a good place to do so is in the cover diff --git a/Makefile b/Makefile index 323c401e96..54ec511dff 100644 --- a/Makefile +++ b/Makefile @@ -1694,10 +1694,10 @@ $(BUILT_INS): git$X ln -s $< $@ 2>/dev/null || \ cp $< $@ -common-cmds.h: ./generate-cmdlist.sh command-list.txt +common-cmds.h: generate-cmdlist.perl command-list.txt common-cmds.h: $(wildcard Documentation/git-*.txt) - $(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@ + $(QUIET_GEN)$(PERL_PATH) generate-cmdlist.perl command-list.txt > $@+ && mv $@+ $@ SCRIPT_DEFINES = $(SHELL_PATH_SQ):$(DIFF_SQ):$(GIT_VERSION):\ $(localedir_SQ):$(NO_CURL):$(USE_GETTEXT_SCHEME):$(SANE_TOOL_PATH_SQ):\ @@ -2455,7 +2455,7 @@ check-docs:: esac ; \ test -f "Documentation/$$v.txt" || \ echo "no doc: $$v"; \ - sed -e '/^#/d' command-list.txt | \ + sed -e '1,/^### command list/d' -e '/^#/d' command-list.txt | \ grep -q "^$$v[ ]" || \ case "$$v" in \ git) ;; \ @@ -2463,7 +2463,8 @@ check-docs:: esac ; \ done; \ ( \ - sed -e '/^#/d' \ + sed -e '1,/^### command list/d' \ + -e '/^#/d' \ -e 's/[ ].*//' \ -e 's/^/listed /' command-list.txt; \ $(MAKE) -C Documentation print-man1 | \ diff --git a/command-list.txt b/command-list.txt index 54d8d21ad2..b17c011bfd 100644 --- a/command-list.txt +++ b/command-list.txt @@ -1,29 +1,39 @@ -# List of known git commands. +# common commands are grouped by themes +# these groups are output by 'git help' in the order declared here. +# map each common command in the command list to one of these groups. +### common groups (do not change this line) +init start a working area (see also: git help tutorial) +worktree work on the current change (see also: git help everyday) +info examine the history and state (see also: git help revisions) +history grow, mark and tweak your common history +remote collaborate (see also: git help workflows) + +### command list (do not change this line) # command name category [deprecated] [common] -git-add mainporcelain common +git-add mainporcelain worktree git-am mainporcelain git-annotate ancillaryinterrogators git-apply plumbingmanipulators git-archimport foreignscminterface git-archive mainporcelain -git-bisect mainporcelain common +git-bisect mainporcelain info git-blame ancillaryinterrogators -git-branch mainporcelain common +git-branch mainporcelain history git-bundle mainporcelain git-cat-file plumbinginterrogators git-check-attr purehelpers git-check-ignore purehelpers git-check-mailmap purehelpers -git-checkout mainporcelain common +git-checkout mainporcelain history git-checkout-index plumbingmanipulators git-check-ref-format purehelpers git-cherry ancillaryinterrogators git-cherry-pick mainporcelain git-citool mainporcelain git-clean mainporcelain -git-clone mainporcelain common +git-clone mainporcelain init git-column purehelpers -git-commit mainporcelain common +git-commit mainporcelain history git-commit-tree plumbingmanipulators git-config ancillarymanipulators git-count-objects ancillaryinterrogators @@ -35,14 +45,14 @@ git-cvsimport foreignscminterface git-cvsserver foreignscminterface git-daemon synchingrepositories git-describe mainporcelain -git-diff mainporcelain common +git-diff mainporcelain history git-diff-files plumbinginterrogators git-diff-index plumbinginterrogators git-diff-tree plumbinginterrogators git-difftool ancillaryinterrogators git-fast-export ancillarymanipulators git-fast-import ancillarymanipulators -git-fetch mainporcelain common +git-fetch mainporcelain remote git-fetch-pack synchingrepositories git-filter-branch ancillarymanipulators git-fmt-merge-msg purehelpers @@ -51,7 +61,7 @@ git-format-patch mainporcelain git-fsck ancillaryinterrogators git-gc mainporcelain git-get-tar-commit-id ancillaryinterrogators -git-grep mainporcelain common +git-grep mainporcelain info git-gui mainporcelain git-hash-object plumbingmanipulators git-help ancillaryinterrogators @@ -60,17 +70,17 @@ git-http-fetch synchelpers git-http-push synchelpers git-imap-send foreignscminterface git-index-pack plumbingmanipulators -git-init mainporcelain common +git-init mainporcelain init git-instaweb ancillaryinterrogators git-interpret-trailers purehelpers gitk mainporcelain -git-log mainporcelain common +git-log mainporcelain info git-ls-files plumbinginterrogators git-ls-remote plumbinginterrogators git-ls-tree plumbinginterrogators git-mailinfo purehelpers git-mailsplit purehelpers -git-merge mainporcelain common +git-merge mainporcelain history git-merge-base plumbinginterrogators git-merge-file plumbingmanipulators git-merge-index plumbingmanipulators @@ -79,7 +89,7 @@ git-mergetool ancillarymanipulators git-merge-tree ancillaryinterrogators git-mktag plumbingmanipulators git-mktree plumbingmanipulators -git-mv mainporcelain common +git-mv mainporcelain worktree git-name-rev plumbinginterrogators git-notes mainporcelain git-p4 foreignscminterface @@ -90,11 +100,11 @@ git-parse-remote synchelpers git-patch-id purehelpers git-prune ancillarymanipulators git-prune-packed plumbingmanipulators -git-pull mainporcelain common -git-push mainporcelain common +git-pull mainporcelain remote +git-push mainporcelain remote git-quiltimport foreignscminterface git-read-tree plumbingmanipulators -git-rebase mainporcelain common +git-rebase mainporcelain history git-receive-pack synchelpers git-reflog ancillarymanipulators git-relink ancillarymanipulators @@ -103,28 +113,28 @@ git-repack ancillarymanipulators git-replace ancillarymanipulators git-request-pull foreignscminterface git-rerere ancillaryinterrogators -git-reset mainporcelain common +git-reset mainporcelain worktree git-revert mainporcelain git-rev-list plumbinginterrogators git-rev-parse ancillaryinterrogators -git-rm mainporcelain common +git-rm mainporcelain worktree git-send-email foreignscminterface git-send-pack synchingrepositories git-shell synchelpers git-shortlog mainporcelain -git-show mainporcelain common +git-show mainporcelain info git-show-branch ancillaryinterrogators git-show-index plumbinginterrogators git-show-ref plumbinginterrogators git-sh-i18n purehelpers git-sh-setup purehelpers git-stash mainporcelain -git-status mainporcelain common +git-status mainporcelain info git-stripspace purehelpers git-submodule mainporcelain git-svn foreignscminterface git-symbolic-ref plumbingmanipulators -git-tag mainporcelain common +git-tag mainporcelain history git-unpack-file plumbinginterrogators git-unpack-objects plumbingmanipulators git-update-index plumbingmanipulators diff --git a/generate-cmdlist.perl b/generate-cmdlist.perl new file mode 100755 index 0000000000..31516e36ac --- /dev/null +++ b/generate-cmdlist.perl @@ -0,0 +1,50 @@ +#!/usr/bin/perl +use strict; +use warnings; + +print <<"EOT"; +/* Automatically generated by $0 */ + +struct cmdname_help { + char name[16]; + char help[80]; + unsigned char group; +}; + +static char *common_cmd_groups[] = { +EOT + +my $n = 0; +my %grp; +while (<>) { + last if /^### command list/; + next if (1../^### common groups/) || /^#/ || /^\s*$/; + chop; + my ($k, $v) = split ' ', $_, 2; + $grp{$k} = $n++; + print "\tN_(\"$v\"),\n"; +} + +print "};\n\nstatic struct cmdname_help common_cmds[] = {\n"; + +while (<>) { + next if /^#/ || /^\s*$/; + my @tags = split; + my $cmd = shift @tags; + for my $t (@tags) { + if (exists $grp{$t}) { + my $s; + open my $f, '<', "Documentation/$cmd.txt" or die; + while (<$f>) { + ($s) = /^$cmd - (.+)$/; + last if $s; + } + close $f; + $cmd =~ s/^git-//; + print "\t{\"$cmd\", N_(\"$s\"), $grp{$t}},\n"; + last; + } + } +} + +print "};\n"; diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh deleted file mode 100755 index 9a4c9b94e6..0000000000 --- a/generate-cmdlist.sh +++ /dev/null @@ -1,23 +0,0 @@ -#!/bin/sh - -echo "/* Automatically generated by $0 */ -struct cmdname_help { - char name[16]; - char help[80]; -}; - -static struct cmdname_help common_cmds[] = {" - -sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' command-list.txt | -sort | -while read cmd -do - sed -n ' - /^NAME/,/git-'"$cmd"'/H - ${ - x - s/.*git-'"$cmd"' - \(.*\)/ {"'"$cmd"'", N_("\1")},/ - p - }' "Documentation/git-$cmd.txt" -done -echo "};" diff --git a/help.c b/help.c index 2072a873e2..8f72051ae0 100644 --- a/help.c +++ b/help.c @@ -218,17 +218,39 @@ void list_commands(unsigned int colopts, } } +static int cmd_group_cmp(const void *elem1, const void *elem2) +{ + const struct cmdname_help *e1 = elem1; + const struct cmdname_help *e2 = elem2; + + if (e1->group < e2->group) + return -1; + if (e1->group > e2->group) + return 1; + return strcmp(e1->name, e2->name); +} + void list_common_cmds_help(void) { int i, longest = 0; + int current_grp = -1; for (i = 0; i < ARRAY_SIZE(common_cmds); i++) { if (longest < strlen(common_cmds[i].name)) longest = strlen(common_cmds[i].name); } - puts(_("The most commonly used git commands are:")); + qsort(common_cmds, ARRAY_SIZE(common_cmds), + sizeof(common_cmds[0]), cmd_group_cmp); + + puts(_("These are common Git commands used in various situations:")); + for (i = 0; i < ARRAY_SIZE(common_cmds); i++) { + if (common_cmds[i].group != current_grp) { + printf("\n%s\n", _(common_cmd_groups[common_cmds[i].group])); + current_grp = common_cmds[i].group; + } + printf(" %s ", common_cmds[i].name); mput_char(' ', longest - strlen(common_cmds[i].name)); puts(_(common_cmds[i].help));