Re: [PATCH v11 2/5] command-list.txt: add the common groups block
On 05/21/2015 08:01 PM, Eric Sunshine wrote: On Thu, May 21, 2015 at 1:39 PM, Sébastien Guimmara wrote: The ultimate goal is for "git help" to display common commands in groups rather than alphabetically. As a first step, define the groups in a new block, and then assign a group to each common command. Helped-by: Eric Sunshine Helped-by: Junio C Hamano Helped-by: Emma Jane Hogbin Westby Signed-off-by: Sébastien Guimmara --- diff --git a/command-list.txt b/command-list.txt index 181a9c2..32ddab3 100644 --- a/command-list.txt +++ b/command-list.txt @@ -1,3 +1,14 @@ +# 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) + +# List of known git commands. This is odd. The above line was removed in 1/5 but then re-appears here in 2/5. I think the intent is that it should remain removed. ### command list (do not change this line) # command name category [deprecated] [common] git-add mainporcelain common My mistake. This will be corrected in the next version. Thank you for taking time to review this series. Sébastien -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v11 5/5] help: respect new common command grouping
On 05/21/2015 08:04 PM, Eric Sunshine wrote:
On Thu, May 21, 2015 at 1:39 PM, Sébastien Guimmara
wrote:
'git help' shows common commands in alphabetical order:
The most commonly used git commands are:
addAdd file contents to the index
bisect Find by binary search the change that introduced a bug
branch List, create, or delete branches
checkout Checkout a branch or paths to the working tree
clone Clone a repository into a new directory
commit Record changes to the repository
[...]
without any indication of how commands relate to high-level
concepts or each other. Revise the output to explain their relationship
with the typical Git workflow:
The most commonly used git commands are:
The above line in the commit message does not match the actual output:
"These are common Git commands used in various situations:"
Thanks. Will correct this.
start a working area (see also: git help tutorial)
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize [...]
work on the current change (see also: git help everyday)
addAdd file contents to the index
reset Reset current HEAD to the specified state
examine the history and state (see also: git help revisions)
logShow commit logs
status Show the working tree status
[...]
Helped-by: Eric Sunshine
Signed-off-by: Ramsay Jones
Signed-off-by: Sébastien Guimmara
---
diff --git a/help.c b/help.c
index 2072a87..8f72051 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));
--
2.4.0.GIT
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v11 1/5] command-list: prepare machinery for upcoming "common groups" section
From: Eric Sunshine
The ultimate goal is for "git help" to classify common commands by
group. Toward this end, a subsequent patch will add a new "common
groups" section to command-list.txt preceding the actual command list.
As preparation, teach existing command-list.txt parsing machinery, which
doesn't care about grouping, to skip over this upcoming "common groups"
section.
Signed-off-by: Eric Sunshine
Signed-off-by: Sébastien Guimmara
---
Documentation/cmd-list.perl | 4
Makefile| 5 +++--
command-list.txt| 2 +-
3 files changed, 8 insertions(+), 3 deletions(-)
diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index 04f9977..5aa73cf 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/Makefile b/Makefile
index 323c401..655740d 100644
--- a/Makefile
+++ b/Makefile
@@ -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 54d8d21..181a9c2 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,4 +1,4 @@
-# List of known git commands.
+### command list (do not change this line)
# command name category [deprecated] [common]
git-add mainporcelain common
git-am mainporcelain
--
2.4.0.GIT
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v11 5/5] help: respect new common command grouping
'git help' shows common commands in alphabetical order:
The most commonly used git commands are:
addAdd file contents to the index
bisect Find by binary search the change that introduced a bug
branch List, create, or delete branches
checkout Checkout a branch or paths to the working tree
clone Clone a repository into a new directory
commit Record changes to the repository
[...]
without any indication of how commands relate to high-level
concepts or each other. Revise the output to explain their relationship
with the typical Git workflow:
The most commonly used git commands are:
start a working area (see also: git help tutorial)
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize [...]
work on the current change (see also: git help everyday)
addAdd file contents to the index
reset Reset current HEAD to the specified state
examine the history and state (see also: git help revisions)
logShow commit logs
status Show the working tree status
[...]
Helped-by: Eric Sunshine
Signed-off-by: Ramsay Jones
Signed-off-by: Sébastien Guimmara
---
help.c | 24 +++-
1 file changed, 23 insertions(+), 1 deletion(-)
diff --git a/help.c b/help.c
index 2072a87..8f72051 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));
--
2.4.0.GIT
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v11 0/5] group common commands by theme
Just a minor change, the modification of new-command.txt was squashed to 2/5 instead of 1/5. Eric Sunshine (2): command-list: prepare machinery for upcoming "common groups" section generate-cmdlist: parse common group commands Sébastien Guimmara (3): command-list.txt: add the common groups block command-list.txt: drop the "common" tag help: respect new common command grouping Documentation/cmd-list.perl | 4 +++ Documentation/howto/new-command.txt | 4 ++- Makefile| 9 --- command-list.txt| 53 ++--- generate-cmdlist.perl | 50 ++ generate-cmdlist.sh | 23 help.c | 24 - 7 files changed, 117 insertions(+), 50 deletions(-) create mode 100755 generate-cmdlist.perl delete mode 100755 generate-cmdlist.sh -- 2.4.0.GIT -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v11 2/5] command-list.txt: add the common groups block
The ultimate goal is for "git help" to display common commands in groups rather than alphabetically. As a first step, define the groups in a new block, and then assign a group to each common command. Add a block at the beginning of command-list.txt: init start a working area (see also: git help tutorial) worktree work on the current change (see also:[...] info examine the history and state (see also: git [...] history grow, mark and tweak your history remote collaborate (see also: git help workflows) storing information about common commands group, then map each common command to a group: git-add mainporcelaincommon worktree Helped-by: Eric Sunshine Helped-by: Junio C Hamano Helped-by: Emma Jane Hogbin Westby Signed-off-by: Sébastien Guimmara --- Documentation/howto/new-command.txt | 4 ++- command-list.txt| 51 ++--- 2 files changed, 34 insertions(+), 21 deletions(-) diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt index d7de5a3..6d772bd 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/command-list.txt b/command-list.txt index 181a9c2..32ddab3 100644 --- a/command-list.txt +++ b/command-list.txt @@ -1,3 +1,14 @@ +# 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) + +# List of known git commands. ### command list (do not change this line) # command name category [deprecated] [common] git-add mainporcelain common @@ -6,24 +17,24 @@ git-annotate ancillaryinterrogators git-apply plumbingmanipulators git-archimport foreignscminterface git-archive mainporcelain -git-bisect mainporcelain common +git-bisect mainporcelain common info git-blame ancillaryinterrogators -git-branch mainporcelain common +git-branch mainporcelain common history git-bundle mainporcelain git-cat-fileplumbinginterrogators git-check-attr purehelpers git-check-ignorepurehelpers git-check-mailmap purehelpers -git-checkoutmainporcelain common +git-checkoutmainporcelain common history git-checkout-index plumbingmanipulators git-check-ref-formatpurehelpers git-cherry ancillaryinterrogators git-cherry-pick mainporcelain git-citool mainporcelain git-clean mainporcelain -git-clone mainporcelain common +git-clone mainporcelain common init git-column purehelpers -git-commit mainporcelain common +git-commit mainporcelain common history git-commit-tree plumbingmanipulators git-config ancillarymanipulators git-count-objects ancillaryinterrogators @@ -35,14 +46,14 @@ git-cvsimport foreignscminterface git-cvsserver foreignscminterface git-daemon synchingrepositories git-describemainporcelain -git-diff
[PATCH v11 4/5] command-list.txt: drop the "common" tag
command-list.sh, retired in the previous patch, was the only consumer of the "common" tag, so drop this now-unnecessary attribute. before: git-add mainporcelaincommon worktree after: git-add mainporcelainworktree Helped-by: Eric Sunshine Signed-off-by: Sébastien Guimmara --- command-list.txt | 42 +- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/command-list.txt b/command-list.txt index 32ddab3..9a98752 100644 --- a/command-list.txt +++ b/command-list.txt @@ -11,30 +11,30 @@ remote collaborate (see also: git help workflows) # List of known git commands. ### command list (do not change this line) # command name category [deprecated] [common] -git-add mainporcelain common +git-add mainporcelain worktree git-am mainporcelain git-annotateancillaryinterrogators git-apply plumbingmanipulators git-archimport foreignscminterface git-archive mainporcelain -git-bisect mainporcelain common info +git-bisect mainporcelain info git-blame ancillaryinterrogators -git-branch mainporcelain common history +git-branch mainporcelain history git-bundle mainporcelain git-cat-fileplumbinginterrogators git-check-attr purehelpers git-check-ignorepurehelpers git-check-mailmap purehelpers -git-checkoutmainporcelain common history +git-checkoutmainporcelain history git-checkout-index plumbingmanipulators git-check-ref-formatpurehelpers git-cherry ancillaryinterrogators git-cherry-pick mainporcelain git-citool mainporcelain git-clean mainporcelain -git-clone mainporcelain common init +git-clone mainporcelain init git-column purehelpers -git-commit mainporcelain common history +git-commit mainporcelain history git-commit-tree plumbingmanipulators git-config ancillarymanipulators git-count-objects ancillaryinterrogators @@ -46,14 +46,14 @@ git-cvsimport foreignscminterface git-cvsserver foreignscminterface git-daemon synchingrepositories git-describemainporcelain -git-diffmainporcelain common history +git-diffmainporcelain history git-diff-files plumbinginterrogators git-diff-index plumbinginterrogators git-diff-tree plumbinginterrogators git-difftoolancillaryinterrogators git-fast-export ancillarymanipulators git-fast-import ancillarymanipulators -git-fetch mainporcelain common remote +git-fetch mainporcelain remote git-fetch-pack synchingrepositories git-filter-branch ancillarymanipulators git-fmt-merge-msg purehelpers @@ -62,7 +62,7 @@ git-format-patchmainporcelain git-fsckancillaryinterrogators git-gc mainporcelain git-get-tar-commit-id ancillaryinterrogators -git-grepmainporcelain common info +git-grepmainporcelain info git-gui mainporcelain git-hash-object plumbingmanipulators git-helpancillaryinterrogators @@ -71,17 +71,17 @@ git-http-fetch synchelpers git-http-push synchelpers git-imap-send foreignscminterface git-index-pack plumbingmanipulators -git-initmainporcelain common init +git-initmainporcelain
[PATCH v11 3/5] generate-cmdlist: parse common group commands
From: Eric Sunshine
Parse the group block to create the array of group descriptions:
static char *common_cmd_groups[] = {
N_("starting a working area"),
N_("working on the current change"),
N_("working with others"),
N_("examining the history and state"),
N_("growing, marking and tweaking your history"),
};
then map each element of common_cmds[] to a group via its index:
static struct cmdname_help common_cmds[] = {
{"add", N_("Add file contents to the index"), 1},
{"branch", N_("List, create, or delete branches"), 4},
{"checkout", N_("Checkout a branch or paths to the ..."), 4},
{"clone", N_("Clone a repository into a new directory"), 0},
{"commit", N_("Record changes to the repository"), 4},
...
};
so that 'git help' can print those commands grouped by theme.
Only commands tagged with an attribute from the group block are emitted to
common_cmds[].
[commit message by Sébastien Guimmara ]
Signed-off-by: Eric Sunshine
Signed-off-by: Sébastien Guimmara
---
Makefile | 4 ++--
generate-cmdlist.perl | 50 ++
generate-cmdlist.sh | 23 ---
3 files changed, 52 insertions(+), 25 deletions(-)
create mode 100755 generate-cmdlist.perl
delete mode 100755 generate-cmdlist.sh
diff --git a/Makefile b/Makefile
index 655740d..54ec511 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):\
diff --git a/generate-cmdlist.perl b/generate-cmdlist.perl
new file mode 100755
index 000..31516e3
--- /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 9a4c9b9..000
--- 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 "};"
--
2.4.0.GIT
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v10 1/5] command-list: prepare machinery for upcoming "common groups" section
On 05/21/2015 03:48 PM, Eric Sunshine wrote:
On Thu, May 21, 2015 at 9:13 AM, Sébastien Guimmara
wrote:
From: Eric Sunshine
The ultimate goal is for "git help" to classify common commands by
group. Toward this end, a subsequent patch will add a new "common
groups" section to command-list.txt preceding the actual command list.
As preparation, teach existing command-list.txt parsing machinery, which
doesn't care about grouping, to skip over this upcoming "common groups"
section.
Signed-off-by: Eric Sunshine
Signed-off-by: Sébastien Guimmara
---
diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index 04f9977..5aa73cf 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 d7de5a3..6d772bd 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].
I think you meant to squash the documentation update into patch 2/5
where the "common groups" block is actually introduced. It doesn't
really belong in this patch which is about updating machinery in
preparation for the new block.
I don't mind squashing it with another commit, but in this case, wouldn't it
make more sense to squash it with 4/5, when the 'common' tag is removed and the
file is in its final form ?
Also, it's now spelled "### common groups" rather than "[common]".
actually, this [common] is not the one I added in a previous series,
but the one that was already present:
# command name category [deprecated] [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 323c401..655740d 100644
--- a/Makefile
+++ b/Makefile
@@ -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 54d8d21..181a9c2 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,4 +1,4 @@
-# List of known git commands.
+### command list (do not change this line)
# command name category [deprecated] [common]
git-add mainporcelain common
git-am mainporcelain
--
2.4.0.GIT
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v10 5/5] help: respect new common command grouping
'git help' shows common commands in alphabetical order:
The most commonly used git commands are:
addAdd file contents to the index
bisect Find by binary search the change that introduced a bug
branch List, create, or delete branches
checkout Checkout a branch or paths to the working tree
clone Clone a repository into a new directory
commit Record changes to the repository
[...]
without any indication of how commands relate to high-level
concepts or each other. Revise the output to explain their relationship
with the typical Git workflow:
These are common Git commands used in various situations:
start a working area (see also: git help tutorial)
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize [...]
work on the current change (see also: git help everyday)
addAdd file contents to the index
reset Reset current HEAD to the specified state
examine the history and state (see also: git help revisions)
logShow commit logs
status Show the working tree status
[...]
Helped-by: Eric Sunshine
Helped-by: Ramsay Jones
Signed-off-by: Sébastien Guimmara
---
help.c | 24 +++-
1 file changed, 23 insertions(+), 1 deletion(-)
diff --git a/help.c b/help.c
index 2072a87..8f72051 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));
--
2.4.0.GIT
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v10 2/5] command-list.txt: add the common groups block
The ultimate goal is for "git help" to display common commands in groups rather than alphabetically. As a first step, define the groups in a new block, and then assign a group to each common command. Add a block at the beginning of command-list.txt: init start a working area (see also: git help tutorial) worktree work on the current change (see also:[...] info examine the history and state (see also: git [...] history grow, mark and tweak your history remote collaborate (see also: git help workflows) storing information about common commands group, then map each common command to a group: git-add mainporcelaincommon worktree Helped-by: Eric Sunshine Helped-by: Junio C Hamano Helped-by: Emma Jane Hogbin Westby Signed-off-by: Sébastien Guimmara --- command-list.txt | 51 +++ 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/command-list.txt b/command-list.txt index 181a9c2..32ddab3 100644 --- a/command-list.txt +++ b/command-list.txt @@ -1,3 +1,14 @@ +# 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) + +# List of known git commands. ### command list (do not change this line) # command name category [deprecated] [common] git-add mainporcelain common @@ -6,24 +17,24 @@ git-annotate ancillaryinterrogators git-apply plumbingmanipulators git-archimport foreignscminterface git-archive mainporcelain -git-bisect mainporcelain common +git-bisect mainporcelain common info git-blame ancillaryinterrogators -git-branch mainporcelain common +git-branch mainporcelain common history git-bundle mainporcelain git-cat-fileplumbinginterrogators git-check-attr purehelpers git-check-ignorepurehelpers git-check-mailmap purehelpers -git-checkoutmainporcelain common +git-checkoutmainporcelain common history git-checkout-index plumbingmanipulators git-check-ref-formatpurehelpers git-cherry ancillaryinterrogators git-cherry-pick mainporcelain git-citool mainporcelain git-clean mainporcelain -git-clone mainporcelain common +git-clone mainporcelain common init git-column purehelpers -git-commit mainporcelain common +git-commit mainporcelain common history git-commit-tree plumbingmanipulators git-config ancillarymanipulators git-count-objects ancillaryinterrogators @@ -35,14 +46,14 @@ git-cvsimport foreignscminterface git-cvsserver foreignscminterface git-daemon synchingrepositories git-describemainporcelain -git-diffmainporcelain common +git-diffmainporcelain common history git-diff-files plumbinginterrogators git-diff-index plumbinginterrogators git-diff-tree plumbinginterrogators git-difftoolancillaryinterrogators git-fast-export ancillarymanipulators git-fast-import ancillarymanipulators -git-fetch mainporcelain common +git-fetch mainporcelain common remote git-fetch-pack synchingrepositories git-filter-branch ancillarymanipulators git-fmt-merge-msg purehelpers @@ -51,7 +62,7 @@ git-format-patchmainporcelain git-fsckancilla
[PATCH v10 4/5] command-list.txt: drop the "common" tag
command-list.sh, retired in the previous patch, was the only consumer of the "common" tag, so drop this now-unnecessary attribute. before: git-add mainporcelaincommon worktree after: git-add mainporcelainworktree Helped-by: Eric Sunshine Signed-off-by: Sébastien Guimmara --- command-list.txt | 42 +- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/command-list.txt b/command-list.txt index 32ddab3..9a98752 100644 --- a/command-list.txt +++ b/command-list.txt @@ -11,30 +11,30 @@ remote collaborate (see also: git help workflows) # List of known git commands. ### command list (do not change this line) # command name category [deprecated] [common] -git-add mainporcelain common +git-add mainporcelain worktree git-am mainporcelain git-annotateancillaryinterrogators git-apply plumbingmanipulators git-archimport foreignscminterface git-archive mainporcelain -git-bisect mainporcelain common info +git-bisect mainporcelain info git-blame ancillaryinterrogators -git-branch mainporcelain common history +git-branch mainporcelain history git-bundle mainporcelain git-cat-fileplumbinginterrogators git-check-attr purehelpers git-check-ignorepurehelpers git-check-mailmap purehelpers -git-checkoutmainporcelain common history +git-checkoutmainporcelain history git-checkout-index plumbingmanipulators git-check-ref-formatpurehelpers git-cherry ancillaryinterrogators git-cherry-pick mainporcelain git-citool mainporcelain git-clean mainporcelain -git-clone mainporcelain common init +git-clone mainporcelain init git-column purehelpers -git-commit mainporcelain common history +git-commit mainporcelain history git-commit-tree plumbingmanipulators git-config ancillarymanipulators git-count-objects ancillaryinterrogators @@ -46,14 +46,14 @@ git-cvsimport foreignscminterface git-cvsserver foreignscminterface git-daemon synchingrepositories git-describemainporcelain -git-diffmainporcelain common history +git-diffmainporcelain history git-diff-files plumbinginterrogators git-diff-index plumbinginterrogators git-diff-tree plumbinginterrogators git-difftoolancillaryinterrogators git-fast-export ancillarymanipulators git-fast-import ancillarymanipulators -git-fetch mainporcelain common remote +git-fetch mainporcelain remote git-fetch-pack synchingrepositories git-filter-branch ancillarymanipulators git-fmt-merge-msg purehelpers @@ -62,7 +62,7 @@ git-format-patchmainporcelain git-fsckancillaryinterrogators git-gc mainporcelain git-get-tar-commit-id ancillaryinterrogators -git-grepmainporcelain common info +git-grepmainporcelain info git-gui mainporcelain git-hash-object plumbingmanipulators git-helpancillaryinterrogators @@ -71,17 +71,17 @@ git-http-fetch synchelpers git-http-push synchelpers git-imap-send foreignscminterface git-index-pack plumbingmanipulators -git-initmainporcelain common init +git-initmainporcelain
[PATCH v10 0/5] group common commands by theme
Same as v9 [1], with: * command-list.txt: reduce verbosity by squashing the two header lines into one: ### command list (do not change this line) * include a missing update to new-command.txt. [1] http://thread.gmane.org/gmane.comp.version-control.git/269496 Eric Sunshine (2): command-list: prepare machinery for upcoming "common groups" section generate-cmdlist: parse common group commands Sébastien Guimmara (3): command-list.txt: add the common groups block command-list.txt: drop the "common" tag help: respect new common command grouping Documentation/cmd-list.perl | 4 +++ Documentation/howto/new-command.txt | 4 ++- Makefile| 9 --- command-list.txt| 53 ++--- generate-cmdlist.perl | 50 ++ generate-cmdlist.sh | 23 help.c | 24 - 7 files changed, 117 insertions(+), 50 deletions(-) create mode 100755 generate-cmdlist.perl delete mode 100755 generate-cmdlist.sh -- 2.4.0.GIT -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v10 1/5] command-list: prepare machinery for upcoming "common groups" section
From: Eric Sunshine
The ultimate goal is for "git help" to classify common commands by
group. Toward this end, a subsequent patch will add a new "common
groups" section to command-list.txt preceding the actual command list.
As preparation, teach existing command-list.txt parsing machinery, which
doesn't care about grouping, to skip over this upcoming "common groups"
section.
Signed-off-by: Eric Sunshine
Signed-off-by: Sébastien Guimmara
---
Documentation/cmd-list.perl | 4
Documentation/howto/new-command.txt | 4 +++-
Makefile| 5 +++--
command-list.txt| 2 +-
4 files changed, 11 insertions(+), 4 deletions(-)
diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index 04f9977..5aa73cf 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 d7de5a3..6d772bd 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 323c401..655740d 100644
--- a/Makefile
+++ b/Makefile
@@ -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 54d8d21..181a9c2 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,4 +1,4 @@
-# List of known git commands.
+### command list (do not change this line)
# command name category [deprecated] [common]
git-add mainporcelain common
git-am mainporcelain
--
2.4.0.GIT
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v10 3/5] generate-cmdlist: parse common group commands
From: Eric Sunshine
Parse the group block to create the array of group descriptions:
static char *common_cmd_groups[] = {
N_("starting a working area"),
N_("working on the current change"),
N_("working with others"),
N_("examining the history and state"),
N_("growing, marking and tweaking your history"),
};
then map each element of common_cmds[] to a group via its index:
static struct cmdname_help common_cmds[] = {
{"add", N_("Add file contents to the index"), 1},
{"branch", N_("List, create, or delete branches"), 4},
{"checkout", N_("Checkout a branch or paths to the ..."), 4},
{"clone", N_("Clone a repository into a new directory"), 0},
{"commit", N_("Record changes to the repository"), 4},
...
};
so that 'git help' can print those commands grouped by theme.
Only commands tagged with an attribute from the group block are emitted to
common_cmds[].
[commit message by Sébastien Guimmara ]
Signed-off-by: Eric Sunshine
Signed-off-by: Sébastien Guimmara
---
Makefile | 4 ++--
generate-cmdlist.perl | 50 ++
generate-cmdlist.sh | 23 ---
3 files changed, 52 insertions(+), 25 deletions(-)
create mode 100755 generate-cmdlist.perl
delete mode 100755 generate-cmdlist.sh
diff --git a/Makefile b/Makefile
index 655740d..54ec511 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):\
diff --git a/generate-cmdlist.perl b/generate-cmdlist.perl
new file mode 100755
index 000..31516e3
--- /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 9a4c9b9..000
--- 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 "};"
--
2.4.0.GIT
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v9 5/5] help: respect new common command grouping
On 05/20/2015 11:39 PM, Ramsay Jones wrote: On 20/05/15 20:23, Sébastien Guimmara wrote: Helped-by: Eric Sunshine Signed-off-by: Ramsay Jones This should be (at most) 'Helped-by:' - my 'contribution' was so minor that even a 'Helped-by:' is generous! :-D ATB, Ramsay Jones Ha! I'm still not very comfortable with picking the right attribution... -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v9 2/5] command-list.txt: add the common groups block
On 05/20/2015 09:48 PM, Eric Sunshine wrote: On Wed, May 20, 2015 at 3:22 PM, Sébastien Guimmara wrote: The ultimate goal is for "git help" to display common commands in groups rather than alphabetically. As a first step, define the groups in a new block, and then assign a group to each common command. Add a block at the beginning of command-list.txt: init start a working area (see also: git help tutorial) worktree work on the current change (see also:[...] info examine the history and state (see also: git [...] history grow, mark and tweak your history remote collaborate (see also: git help workflows) storing information about common commands group, then map each common command to a group: git-add mainporcelaincommon worktree Signed-off-by: Sébastien Guimmara --- command-list.txt | 50 ++ 1 file changed, 30 insertions(+), 20 deletions(-) Hmm, did your update to Documentation/technical/new-command.txt get lost? I don't see it any of the patches, but would have expected it to be included in this patch which introduces the "common groups" section. Ah, you're right. A commit got lost in the process. Will fix that. Thanks. diff --git a/command-list.txt b/command-list.txt index 609b344..c2bbdc1 100644 --- a/command-list.txt +++ b/command-list.txt @@ -1,3 +1,13 @@ +# common commands are grouped by themes output by 'git help' +# map each common command in the command list to one of these groups. Discussed previously: It also would be a good idea to mention that the order in which "git help" displays the groups themselves is the order they are declared here. Maybe just add one more line between the two you already have above: # groups are output by 'git help' in the order declared here. Indeed, I'll add the mention. +### common groups In the block below, the "### command list" line is protected by a "# do not molest the next line" warning. Perhaps the same should be done here? Alternately, make them more compact by incorporating the warning: ### common groups (do not change this line) ... ### command list (do not change this line) ? Yes, it's better. I shall modify this. +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) + +# List of known git commands. # do not molest the next line ### command list # command name category [deprecated] [common] -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v9 3/5] generate-cmdlist: parse common group commands
On 05/20/2015 09:32 PM, Stefan Beller wrote: On Wed, May 20, 2015 at 12:27 PM, Sébastien Guimmara wrote: On 05/20/2015 09:22 PM, Sébastien Guimmara wrote: From: Eric Sunshine It looks like 'git send-email' got confused with the CC field. I'm sorry for that. It's to keep authorship. When Junio picks it up, this will show as authored by Eric, signed off by both of you (Eric+Sébastien) and committed by Junio. So it's not a mistake ? I thought the 'From:' line was the email header as generated by git send-email that got wrongly included in the body. My mistake then. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v9 3/5] generate-cmdlist: parse common group commands
On 05/20/2015 09:22 PM, Sébastien Guimmara wrote: From: Eric Sunshine It looks like 'git send-email' got confused with the CC field. I'm sorry for that. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v9 4/5] command-list.txt: drop the "common" tag
command-list.sh, retired in the previous patch, was the only consumer of the "common" tag, so drop this now-unnecessary attribute. before: git-add mainporcelaincommon worktree after: git-add mainporcelainworktree Helped-by: Eric Sunshine Signed-off-by: Sébastien Guimmara --- command-list.txt | 42 +- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/command-list.txt b/command-list.txt index c2bbdc1..080d6d9 100644 --- a/command-list.txt +++ b/command-list.txt @@ -11,30 +11,30 @@ remote collaborate (see also: git help workflows) # do not molest the next line ### command list # command name category [deprecated] [common] -git-add mainporcelain common +git-add mainporcelain worktree git-am mainporcelain git-annotateancillaryinterrogators git-apply plumbingmanipulators git-archimport foreignscminterface git-archive mainporcelain -git-bisect mainporcelain common info +git-bisect mainporcelain info git-blame ancillaryinterrogators -git-branch mainporcelain common history +git-branch mainporcelain history git-bundle mainporcelain git-cat-fileplumbinginterrogators git-check-attr purehelpers git-check-ignorepurehelpers git-check-mailmap purehelpers -git-checkoutmainporcelain common history +git-checkoutmainporcelain history git-checkout-index plumbingmanipulators git-check-ref-formatpurehelpers git-cherry ancillaryinterrogators git-cherry-pick mainporcelain git-citool mainporcelain git-clean mainporcelain -git-clone mainporcelain common init +git-clone mainporcelain init git-column purehelpers -git-commit mainporcelain common history +git-commit mainporcelain history git-commit-tree plumbingmanipulators git-config ancillarymanipulators git-count-objects ancillaryinterrogators @@ -46,14 +46,14 @@ git-cvsimport foreignscminterface git-cvsserver foreignscminterface git-daemon synchingrepositories git-describemainporcelain -git-diffmainporcelain common history +git-diffmainporcelain history git-diff-files plumbinginterrogators git-diff-index plumbinginterrogators git-diff-tree plumbinginterrogators git-difftoolancillaryinterrogators git-fast-export ancillarymanipulators git-fast-import ancillarymanipulators -git-fetch mainporcelain common remote +git-fetch mainporcelain remote git-fetch-pack synchingrepositories git-filter-branch ancillarymanipulators git-fmt-merge-msg purehelpers @@ -62,7 +62,7 @@ git-format-patchmainporcelain git-fsckancillaryinterrogators git-gc mainporcelain git-get-tar-commit-id ancillaryinterrogators -git-grepmainporcelain common info +git-grepmainporcelain info git-gui mainporcelain git-hash-object plumbingmanipulators git-helpancillaryinterrogators @@ -71,17 +71,17 @@ git-http-fetch synchelpers git-http-push synchelpers git-imap-send foreignscminterface git-index-pack plumbingmanipulators -git-initmainporcelain common init +git-initmainporcelain init gi
[PATCH v9 1/5] command-list: prepare machinery for upcoming "common groups" section
From: Eric Sunshine
The ultimate goal is for "git help" to classify common commands by
group. Toward this end, a subsequent patch will add a new "common
groups" section to command-list.txt preceding the actual command list.
As preparation, teach existing command-list.txt parsing machinery, which
doesn't care about grouping, to skip over this upcoming "common groups"
section.
Signed-off-by: Eric Sunshine
Signed-off-by: Sébastien Guimmara
---
Documentation/cmd-list.perl | 4
Makefile| 5 +++--
command-list.txt| 3 ++-
3 files changed, 9 insertions(+), 3 deletions(-)
diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index 04f9977..5aa73cf 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/Makefile b/Makefile
index 323c401..655740d 100644
--- a/Makefile
+++ b/Makefile
@@ -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 54d8d21..609b344 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,4 +1,5 @@
-# List of known git commands.
+# do not molest the next line
+### command list
# command name category [deprecated] [common]
git-add mainporcelain common
git-am mainporcelain
--
2.4.0.GIT
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v9 3/5] generate-cmdlist: parse common group commands
From: Eric Sunshine
Parse the group block to create the array of group descriptions:
static char *common_cmd_groups[] = {
N_("starting a working area"),
N_("working on the current change"),
N_("working with others"),
N_("examining the history and state"),
N_("growing, marking and tweaking your history"),
};
then map each element of common_cmds[] to a group via its index:
static struct cmdname_help common_cmds[] = {
{"add", N_("Add file contents to the index"), 1},
{"branch", N_("List, create, or delete branches"), 4},
{"checkout", N_("Checkout a branch or paths to the ..."), 4},
{"clone", N_("Clone a repository into a new directory"), 0},
{"commit", N_("Record changes to the repository"), 4},
...
};
so that 'git help' can print those commands grouped by theme.
Only commands tagged with an attribute from the group block are emitted to
common_cmds[].
[commit message by Sébastien Guimmara ]
Signed-off-by: Eric Sunshine
Signed-off-by: Sébastien Guimmara
---
Makefile | 4 ++--
generate-cmdlist.perl | 50 ++
generate-cmdlist.sh | 23 ---
3 files changed, 52 insertions(+), 25 deletions(-)
create mode 100755 generate-cmdlist.perl
delete mode 100755 generate-cmdlist.sh
diff --git a/Makefile b/Makefile
index 655740d..54ec511 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):\
diff --git a/generate-cmdlist.perl b/generate-cmdlist.perl
new file mode 100755
index 000..31516e3
--- /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 9a4c9b9..000
--- 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 "};"
--
2.4.0.GIT
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v9 2/5] command-list.txt: add the common groups block
The ultimate goal is for "git help" to display common commands in groups rather than alphabetically. As a first step, define the groups in a new block, and then assign a group to each common command. Add a block at the beginning of command-list.txt: init start a working area (see also: git help tutorial) worktree work on the current change (see also:[...] info examine the history and state (see also: git [...] history grow, mark and tweak your history remote collaborate (see also: git help workflows) storing information about common commands group, then map each common command to a group: git-add mainporcelaincommon worktree Helped-by: Eric Sunshine Helped-by: Junio C Hamano Helped-by: Emma Jane Hogbin Westby Signed-off-by: Sébastien Guimmara --- command-list.txt | 50 ++ 1 file changed, 30 insertions(+), 20 deletions(-) diff --git a/command-list.txt b/command-list.txt index 609b344..c2bbdc1 100644 --- a/command-list.txt +++ b/command-list.txt @@ -1,3 +1,13 @@ +# common commands are grouped by themes output by 'git help' +# map each common command in the command list to one of these groups. +### common groups +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) + +# List of known git commands. # do not molest the next line ### command list # command name category [deprecated] [common] @@ -7,24 +17,24 @@ git-annotate ancillaryinterrogators git-apply plumbingmanipulators git-archimport foreignscminterface git-archive mainporcelain -git-bisect mainporcelain common +git-bisect mainporcelain common info git-blame ancillaryinterrogators -git-branch mainporcelain common +git-branch mainporcelain common history git-bundle mainporcelain git-cat-fileplumbinginterrogators git-check-attr purehelpers git-check-ignorepurehelpers git-check-mailmap purehelpers -git-checkoutmainporcelain common +git-checkoutmainporcelain common history git-checkout-index plumbingmanipulators git-check-ref-formatpurehelpers git-cherry ancillaryinterrogators git-cherry-pick mainporcelain git-citool mainporcelain git-clean mainporcelain -git-clone mainporcelain common +git-clone mainporcelain common init git-column purehelpers -git-commit mainporcelain common +git-commit mainporcelain common history git-commit-tree plumbingmanipulators git-config ancillarymanipulators git-count-objects ancillaryinterrogators @@ -36,14 +46,14 @@ git-cvsimport foreignscminterface git-cvsserver foreignscminterface git-daemon synchingrepositories git-describemainporcelain -git-diffmainporcelain common +git-diffmainporcelain common history git-diff-files plumbinginterrogators git-diff-index plumbinginterrogators git-diff-tree plumbinginterrogators git-difftoolancillaryinterrogators git-fast-export ancillarymanipulators git-fast-import ancillarymanipulators -git-fetch mainporcelain common +git-fetch mainporcelain common remote git-fetch-pack synchingrepositories git-filter-branch ancillarymanipulators git-fmt-merge-msg purehelpers @@ -52,7 +62,7 @@ git-format-patchmainporcelain git-fsckancillaryinterrogators git-gc mainporcelain git-get-tar-commit-id ancillaryint
[PATCH v9 5/5] help: respect new common command grouping
'git help' shows common commands in alphabetical order:
The most commonly used git commands are:
addAdd file contents to the index
bisect Find by binary search the change that introduced a bug
branch List, create, or delete branches
checkout Checkout a branch or paths to the working tree
clone Clone a repository into a new directory
commit Record changes to the repository
[...]
without any indication of how commands relate to high-level
concepts or each other. Revise the output to explain their relationship
with the typical Git workflow:
These are common Git commands used in various situations:
start a working area (see also: git help tutorial)
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize [...]
work on the current change (see also: git help everyday)
addAdd file contents to the index
reset Reset current HEAD to the specified state
examine the history and state (see also: git help revisions)
logShow commit logs
status Show the working tree status
[...]
Helped-by: Eric Sunshine
Signed-off-by: Ramsay Jones
Signed-off-by: Sébastien Guimmara
---
help.c | 24 +++-
1 file changed, 23 insertions(+), 1 deletion(-)
diff --git a/help.c b/help.c
index 2072a87..8f72051 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));
--
2.4.0.GIT
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v9 0/5] group common commands by theme
The major modification of this reroll [1] is the use of the perl version of generate-cmdlist instead of the awk one. help.c: 1. change the introductory message from: "The typical Git workflow includes:" to: "These are common Git commands used in various situations:" 2. include Ramsay's patch [2] [1]: v8: http://thread.gmane.org/gmane.comp.version-control.git/269305 [2]: http://thread.gmane.org/gmane.comp.version-control.git/269387 Eric Sunshine (2): command-list: prepare machinery for upcoming "common groups" section generate-cmdlist: parse common group commands Sébastien Guimmara (3): command-list.txt: add the common groups block command-list.txt: drop the "common" tag help: respect new common command grouping Documentation/cmd-list.perl | 4 Makefile| 9 command-list.txt| 53 +++-- generate-cmdlist.perl | 50 ++ generate-cmdlist.sh | 23 help.c | 24 +++- 6 files changed, 114 insertions(+), 49 deletions(-) create mode 100755 generate-cmdlist.perl delete mode 100755 generate-cmdlist.sh -- 2.4.0.GIT -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v7 2/5] command-list.txt: add a [common] block
Add a [common] block at the beginning of command-list.txt: [common] init start a working area (see also: git help tutorial) worktree work on the current change (see also:[...] info examine the history and state (see also: git [...] history grow, mark and tweak your history remote collaborate (see also: git help workflows) storing information about common commands group, then map each common command to a group: git-add mainporcelaincommon worktree Helped-by: Eric Sunshine Helped-by: Junio C Hamano Helped-by: Emma Jane Hogbin Westby Signed-off-by: Sébastien Guimmara --- command-list.txt | 52 +++- 1 file changed, 31 insertions(+), 21 deletions(-) diff --git a/command-list.txt b/command-list.txt index caed872..c00b0b6 100644 --- a/command-list.txt +++ b/command-list.txt @@ -1,30 +1,40 @@ +# common commands are grouped by themes +# this order is the same that output by 'git help' +# map each common command in the [commands] list to one of these groups. +[common] +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) + # List of known git commands. # command name category [deprecated] [common] [commands] -git-add mainporcelain common +git-add mainporcelain common worktree git-am mainporcelain git-annotateancillaryinterrogators git-apply plumbingmanipulators git-archimport foreignscminterface git-archive mainporcelain -git-bisect mainporcelain common +git-bisect mainporcelain common info git-blame ancillaryinterrogators -git-branch mainporcelain common +git-branch mainporcelain common history git-bundle mainporcelain git-cat-fileplumbinginterrogators git-check-attr purehelpers git-check-ignorepurehelpers git-check-mailmap purehelpers -git-checkoutmainporcelain common +git-checkoutmainporcelain common history git-checkout-index plumbingmanipulators git-check-ref-formatpurehelpers git-cherry ancillaryinterrogators git-cherry-pick mainporcelain git-citool mainporcelain git-clean mainporcelain -git-clone mainporcelain common +git-clone mainporcelain common init git-column purehelpers -git-commit mainporcelain common +git-commit mainporcelain common history git-commit-tree plumbingmanipulators git-config ancillarymanipulators git-count-objects ancillaryinterrogators @@ -36,14 +46,14 @@ git-cvsimport foreignscminterface git-cvsserver foreignscminterface git-daemon synchingrepositories git-describemainporcelain -git-diffmainporcelain common +git-diffmainporcelain common history git-diff-files plumbinginterrogators git-diff-index plumbinginterrogators git-diff-tree plumbinginterrogators git-difftoolancillaryinterrogators git-fast-export ancillarymanipulators git-fast-import ancillarymanipulators -git-fetch mainporcelain common +git-fetch mainporcelain common remote git-fetch-pack synchingrepositories git-filter-branch ancillarymanipulators git-fmt-merge-msg purehelpers @@ -52,7 +62,7 @@ git-format-patchmainporcelain git-fsckancillaryinterrogators git-gc mainporcelain git-get-tar-commit-id ancillaryinterrogators
[PATCH v5 5/6] new-command.txt: mention the common command groups
In the 6. step, add information about the common group commands found in command-list.txt. Signed-off-by: Sébastien Guimmara --- Documentation/howto/new-command.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt index d7de5a3..e7b0cc2 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's 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 -- 2.4.0 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v5 3/6] command-list.txt: group common commands by theme
Declare groups for common commands in the [common] block, followed by group names and descriptions: [common] init start a working area (see also: git help tutorial) worktree work on the current change (see also: git [...] info examine the history and state (see also: git [...] history grow, mark and tweak your history remote collaborate (see also: git help workflows) Some descriptions include a 'see also' to redirect user to more detailed documentation. Then, in the [commands] block, map all common commands with a group: [commands] git-addmainporcelain worktree git-branch mainporcelain history git-checkout mainporcelain history [...] So that 'git help' outputs those commands in headered groups. Helped-by: Junio C Hamano Helped-by: Emma Jane Hogbin Westby Signed-off-by: Sébastien Guimmara --- command-list.txt | 56 ++-- 1 file changed, 34 insertions(+), 22 deletions(-) diff --git a/command-list.txt b/command-list.txt index f1eae08..7e7ce53 100644 --- a/command-list.txt +++ b/command-list.txt @@ -1,29 +1,41 @@ +# common commands are grouped by themes +# this order is the same that output by 'git help' +# map each common commands in the [commands] list to one of the groups. +# a command should not be marked both [deprecated] and [common] +[common] +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 history +remote collaborate (see also: git help workflows) + # List of known git commands. -# command name category [deprecated] [common] -git-add mainporcelain common +# command name [deprecated] category[common] +[commands] +git-add mainporcelain worktree git-am mainporcelain git-annotateancillaryinterrogators 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-fileplumbinginterrogators git-check-attr purehelpers git-check-ignorepurehelpers git-check-mailmap purehelpers -git-checkoutmainporcelain common +git-checkoutmainporcelain history git-checkout-index plumbingmanipulators git-check-ref-formatpurehelpers 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 +47,14 @@ git-cvsimport foreignscminterface git-cvsserver foreignscminterface git-daemon synchingrepositories git-describemainporcelain -git-diffmainporcelain common +git-diffmainporcelain history git-diff-files plumbinginterrogators git-diff-index plumbinginterrogators git-diff-tree plumbinginterrogators git-difftoolancillaryinterrogators git-fast-exportancillarymanipulators git-fast-importancillarymanipulators -git-fetch mainporcelain common +git-fetch mainporcelain remote git-fetch-pack synchingr
[PATCH v5 1/6] generate-cmdlist: parse common group commands
Parse the [common] block to create the array of group descriptions:
static char *common_cmd_groups[] = {
N_("start a working area (see also: git help tutorial)"),
N_("work on the current change (see also: git help everyday)"),
N_("examine the history and state (see also: git help revisions)"),
N_("grow, mark and tweak your history"),
N_("collaborate (see also: git help workflows)"),
};
then map each element of common_cmds[] to a group via its index:
static struct cmdname_help common_cmds[] = {
{"add", N_("Add file contents to the index"), 1},
{"branch", N_("List, create, or delete branches"), 4},
{"checkout", N_("Checkout a branch or paths to the ..."), 4},
{"clone", N_("Clone a repository into a new directory"), 0},
{"commit", N_("Record changes to the repository"), 4},
...
};
so that 'git help' can print those commands grouped by theme.
Only commands tagged with an attribute from [common] are emitted to
common_cmds[].
[commit message by Sébastien Guimmara ]
Signed-off-by: Eric Sunshine
---
generate-cmdlist.awk | 38 ++
1 file changed, 38 insertions(+)
create mode 100644 generate-cmdlist.awk
diff --git a/generate-cmdlist.awk b/generate-cmdlist.awk
new file mode 100644
index 000..cbaac88
--- /dev/null
+++ b/generate-cmdlist.awk
@@ -0,0 +1,38 @@
+BEGIN {
+ print "/* Automatically generated by generate-cmdlist.awk */\n"
+ print "struct cmdname_help {"
+ print "\tchar name[16];"
+ print "\tchar help[80];"
+ print "\tunsigned char group;"
+ print "};\n"
+ print "static char *common_cmd_groups[] = {"
+}
+/^#/ || /^[]*$/ { next }
+state == 2 {
+ for (i = 2; i <= NF; i++)
+ if (grp[$i]) {
+ f = "Documentation/"$1".txt"
+ while (getline s 0)
+ if (match(s, $1" - ")) {
+ t = substr(s, length($1" - ") + 1)
+ break
+ }
+ close(f)
+ printf "\t{\"%s\", N_(\"%s\"), %s},\n",
+ substr($1, length("git-") + 1), t, grp[$i] - 1
+ break
+ }
+}
+/\[commands\]/ {
+ print "};\n\nstatic struct cmdname_help common_cmds[] = {"
+ state = 2
+}
+state == 1 {
+ grp[$1] = ++n
+ sub($1"[][ ]*", "")
+ printf "\tN_(\"%s\"),\n", $0
+}
+/\[common\]/ {
+ state = 1
+}
+END { print "};" }
--
2.4.0
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
