Skip to content

Commit

Permalink
Merge branch 'sg/help-group'
Browse files Browse the repository at this point in the history 
Group list of commands shown by "git help" along the workflow
elements to help early learners.

* sg/help-group:
  help: respect new common command grouping
  command-list.txt: drop the "common" tag
  generate-cmdlist: parse common group commands
  command-list.txt: add the common groups block
  command-list: prepare machinery for upcoming "common groups" section
  • Loading branch information
Junio C Hamano committed Jun 1, 2015
2 parents abcbafe + 2241477 commit 6dec263
Show file tree
Hide file tree
Showing 7 changed files with 117 additions and 51 deletions.
4 changes: 4 additions & 0 deletions Documentation/cmd-list.perl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,10 @@ sub format_one {
}
}

while (<>) {
last if /^### command list/;
}

my %cmds = ();
for (sort <>) {
next if /^#/;
Expand Down
4 changes: 3 additions & 1 deletion Documentation/howto/new-command.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 5 additions & 4 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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):\
Expand Down Expand Up @@ -2455,15 +2455,16 @@ 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) ;; \
*) echo "no link: $$v";; \
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 | \
Expand Down
54 changes: 32 additions & 22 deletions command-list.txt
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
50 changes: 50 additions & 0 deletions generate-cmdlist.perl
View file
Original file line number Diff line number Diff line change
@@ -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";
23 changes: 0 additions & 23 deletions generate-cmdlist.sh
View file

This file was deleted.

24 changes: 23 additions & 1 deletion help.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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));
Expand Down

0 comments on commit 6dec263

Please sign in to comment.