* [PATCH 0/3] git help: group common commands by theme
@ 2015-05-04 20:28 Sébastien Guimmara
2015-05-04 20:28 ` [PATCH 1/3] command-list.txt: " Sébastien Guimmara
` (6 more replies)
0 siblings, 7 replies; 39+ messages in thread
From: Sébastien Guimmara @ 2015-05-04 20:28 UTC (permalink / raw)
To: git; +Cc: Sébastien Guimmara, gitster, sunshine
This v4 includes the following suggestions:
In command-list.txt:
- Add a [groups] block containing names and description for groups:
[groups]
init starting a working area
worktree working on the current change
remote working with others
info examining the history and state
history growing, marking and tweaking your history
- Add a [commands] header on top of the known command list, and
group names as a third column.
[commands]
git-add mainporcelain common-worktree
git-am mainporcelain
git-annotate ancillaryinterrogators
git-apply plumbingmanipulators
git-archimport foreignscminterface
git-archive mainporcelain
git-bisect mainporcelain
git-blame ancillaryinterrogators
git-branch mainporcelain common-history
This produces the following output of $ git help:
[...]
The most commonly used git commands are:
* starting a working area:
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize [...]
* working on the current change:
add Add file contents to the index
reset Reset current HEAD to the specified state
* working with others:
fetch Download objects and refs from another repository
pull Fetch from and integrate with another repository [...]
push Update remote refs along with associated objects
* examining the history and state:
log Show commit logs
status Show the working tree status
* growing, marking and tweaking your history:
branch List, create, or delete branches
checkout Checkout a branch or paths to the working tree
commit Record changes to the repository
diff Show changes between commits, commit and working [...]
merge Join two or more development histories together
[...]
I removed from the list of common commands: rebase, rm, mv, bisect
because [1] they are not really common to an unfamiliar user, [2] to
save vertical space occupied by group headers.
Thanks to Junio and Eric for their suggestions.
Sébastien Guimmara (3):
command-list.txt: group common commands by theme
generate-cmdlist.sh: parse common group commands
git help: group common commands by theme
command-list.txt | 64 +++++++++++++++++++++++++++++++----------------------
generate-cmdlist.sh | 43 +++++++++++++++++++++++++----------
help.c | 28 ++++++++++++++++++++++-
3 files changed, 95 insertions(+), 40 deletions(-)
--
2.4.0
^ permalink raw reply [flat|nested] 39+ messages in thread
* [PATCH 1/3] command-list.txt: group common commands by theme
2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara
@ 2015-05-04 20:28 ` Sébastien Guimmara
2015-05-06 6:57 ` Eric Sunshine
2015-05-04 20:28 ` [PATCH 2/3] generate-cmdlist.sh: parse common group commands Sébastien Guimmara
` (5 subsequent siblings)
6 siblings, 1 reply; 39+ messages in thread
From: Sébastien Guimmara @ 2015-05-04 20:28 UTC (permalink / raw)
To: git; +Cc: Sébastien Guimmara, gitster, sunshine
Declare groups for common commands in the [groups] block,
followed by group names and descriptions:
[groups]
init starting a working area
worktree working on the current change
remote working with others
info examining the history and state
history growing, marking and tweaking your history
Then, in the [commands] block, map all common commands with a group:
[commands]
git-add mainporcelain common-worktree
git-branch mainporcelain common-history
git-checkout mainporcelain common-history
[...]
command names and groups are then parsed with generate-cmdlist.sh to
generate common-commands.h.
Those commands are displayed in groups in the output of 'git help'.
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
command-list.txt | 64 ++++++++++++++++++++++++++++++++------------------------
1 file changed, 37 insertions(+), 27 deletions(-)
diff --git a/command-list.txt b/command-list.txt
index f1eae08..64394ca 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,29 +1,39 @@
# List of known git commands.
-# command name category [deprecated] [common]
-git-add mainporcelain common
+# only add group information for common commands
+
+[groups]
+init starting a working area
+worktree working on the current change
+remote working with others
+info examining the history and state
+history growing, marking and tweaking your history
+
+# command name [deprecated] category [group]
+[commands]
+git-add mainporcelain common-worktree
git-am mainporcelain
git-annotate ancillaryinterrogators
git-apply plumbingmanipulators
git-archimport foreignscminterface
git-archive mainporcelain
-git-bisect mainporcelain common
+git-bisect mainporcelain
git-blame ancillaryinterrogators
-git-branch mainporcelain common
+git-branch mainporcelain common-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 common-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 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,42 +45,42 @@ git-cvsimport foreignscminterface
git-cvsserver foreignscminterface
git-daemon synchingrepositories
git-describe mainporcelain
-git-diff mainporcelain common
+git-diff mainporcelain common-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-fast-export ancillarymanipulators
+git-fast-import ancillarymanipulators
+git-fetch mainporcelain common-remote
git-fetch-pack synchingrepositories
git-filter-branch ancillarymanipulators
git-fmt-merge-msg purehelpers
git-for-each-ref plumbinginterrogators
git-format-patch mainporcelain
-git-fsck ancillaryinterrogators
+git-fsck ancillaryinterrogators
git-gc mainporcelain
git-get-tar-commit-id ancillaryinterrogators
-git-grep mainporcelain common
+git-grep mainporcelain
git-gui mainporcelain
git-hash-object plumbingmanipulators
-git-help ancillaryinterrogators
+git-help ancillaryinterrogators
git-http-backend synchingrepositories
git-http-fetch synchelpers
git-http-push synchelpers
git-imap-send foreignscminterface
git-index-pack plumbingmanipulators
-git-init mainporcelain common
+git-init mainporcelain common-init
git-instaweb ancillaryinterrogators
git-interpret-trailers purehelpers
gitk mainporcelain
-git-log mainporcelain common
+git-log mainporcelain common-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 common-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
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 common-remote
+git-push mainporcelain common-remote
git-quiltimport foreignscminterface
git-read-tree plumbingmanipulators
-git-rebase mainporcelain common
+git-rebase mainporcelain
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 common-worktree
git-revert mainporcelain
git-rev-list plumbinginterrogators
git-rev-parse ancillaryinterrogators
-git-rm mainporcelain common
+git-rm mainporcelain
git-send-email foreignscminterface
git-send-pack synchingrepositories
git-shell synchelpers
git-shortlog mainporcelain
-git-show mainporcelain common
+git-show mainporcelain
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 common-info
git-stripspace purehelpers
git-submodule mainporcelain
git-svn foreignscminterface
git-symbolic-ref plumbingmanipulators
-git-tag mainporcelain common
+git-tag mainporcelain
git-unpack-file plumbinginterrogators
git-unpack-objects plumbingmanipulators
git-update-index plumbingmanipulators
@@ -138,4 +148,4 @@ git-verify-pack plumbinginterrogators
git-verify-tag ancillaryinterrogators
gitweb ancillaryinterrogators
git-whatchanged ancillaryinterrogators
-git-write-tree plumbingmanipulators
+git-write-tree plumbingmanipulators
\ No newline at end of file
--
2.4.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH 2/3] generate-cmdlist.sh: parse common group commands
2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara
2015-05-04 20:28 ` [PATCH 1/3] command-list.txt: " Sébastien Guimmara
@ 2015-05-04 20:28 ` Sébastien Guimmara
2015-05-08 3:20 ` Eric Sunshine
2015-05-04 20:28 ` [PATCH 3/3] git help: group common commands by theme Sébastien Guimmara
` (4 subsequent siblings)
6 siblings, 1 reply; 39+ messages in thread
From: Sébastien Guimmara @ 2015-05-04 20:28 UTC (permalink / raw)
To: git; +Cc: Sébastien Guimmara, gitster, sunshine
parse the [groups] 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 working tree"), 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 command grouped by theme.
Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
generate-cmdlist.sh | 43 +++++++++++++++++++++++++++++++------------
1 file changed, 31 insertions(+), 12 deletions(-)
diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
index 9a4c9b9..724bb8d 100755
--- a/generate-cmdlist.sh
+++ b/generate-cmdlist.sh
@@ -1,23 +1,42 @@
#!/bin/sh
+content=$(cat command-list.txt)
+
+group_line_no=$(expr $(echo "$content" | grep -n '^\[groups\]' | cut -f1 -d:) + 1)
+command_line_no=$(expr $(echo "$content" | grep -n '^\[commands\]' | cut -f1 -d:) + 1)
+groups=$(echo "$content" | sed -n ''$group_line_no', '$(expr $command_line_no)'p')
echo "/* Automatically generated by $0 */
+
struct cmdname_help {
char name[16];
char help[80];
+ unsigned char group;
};
+static char *common_cmd_groups[] = {"
+echo "$groups" |
+while read group description; do
+ if [ -z $group ]; then
+ break
+ fi
+ echo ' N_("'$description'"),'
+done
+echo "};
+
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"
+echo "$content" | grep 'common-' |
+awk '{ print $1, "\t", $3 }' |
+while read cmd grp; do
+ cmd_name=$(echo $cmd | cut -d - -f 2)
+ group_name=$(echo $grp | cut -d - -f 2)
+ group_idx=$(expr $(echo "$groups" | grep -n "^$group_name" | cut -c 1) - 1)
+ sed -n '
+ /^NAME/,/git-'"$cmd_name"'/H
+ ${
+ x
+ s/.*git-'"$cmd_name"' - \(.*\)/ {"'"$cmd_name"'", N_("\1"), '"$group_idx"'},/
+ p
+ }' "Documentation/$cmd.txt"
done
-echo "};"
+echo "};"
\ No newline at end of file
--
2.4.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH 3/3] git help: group common commands by theme
2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara
2015-05-04 20:28 ` [PATCH 1/3] command-list.txt: " Sébastien Guimmara
2015-05-04 20:28 ` [PATCH 2/3] generate-cmdlist.sh: parse common group commands Sébastien Guimmara
@ 2015-05-04 20:28 ` Sébastien Guimmara
2015-05-06 3:16 ` Eric Sunshine
2015-05-06 3:08 ` [PATCH 0/3] " Eric Sunshine
` (3 subsequent siblings)
6 siblings, 1 reply; 39+ messages in thread
From: Sébastien Guimmara @ 2015-05-04 20:28 UTC (permalink / raw)
To: git; +Cc: Sébastien Guimmara, gitster, sunshine
'git help' shows common commands in alphabetical order:
The most commonly used git commands are:
add Add 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 group commands by
concept, like this:
The most commonly used git commands are:
* starting a working area:
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize an existing one
* working on the current change:
add Add file contents to the index
reset Reset current HEAD to the specified state
[...]
Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
help.c | 28 +++++++++++++++++++++++++++-
1 file changed, 27 insertions(+), 1 deletion(-)
diff --git a/help.c b/help.c
index 2072a87..c8b0bb6 100644
--- a/help.c
+++ b/help.c
@@ -218,18 +218,44 @@ void list_commands(unsigned int colopts,
}
}
+int cmd_group_cmp(const void *elem1, const void *elem2)
+{
+ int group1, group2;
+
+ group1 = ((struct cmdname_help *) elem1)->group;
+ group2 = ((struct cmdname_help *) elem2)->group;
+
+ if (group1 == group2)
+ return 0;
+ if (group1 > group2)
+ return 1;
+ else
+ return -1;
+}
+
void list_common_cmds_help(void)
{
int i, longest = 0;
+ unsigned char 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);
}
+ qsort(common_cmds, ARRAY_SIZE(common_cmds),
+ sizeof(common_cmds[0]), cmd_group_cmp);
+
puts(_("The most commonly used git commands are:"));
+
for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
- printf(" %s ", common_cmds[i].name);
+ 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
^ permalink raw reply related [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara
` (2 preceding siblings ...)
2015-05-04 20:28 ` [PATCH 3/3] git help: group common commands by theme Sébastien Guimmara
@ 2015-05-06 3:08 ` Eric Sunshine
2015-05-06 20:26 ` Sébastien Guimmara
2015-05-06 3:41 ` Junio C Hamano
` (2 subsequent siblings)
6 siblings, 1 reply; 39+ messages in thread
From: Eric Sunshine @ 2015-05-06 3:08 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano
On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> This v4 includes the following suggestions:
>
> In command-list.txt:
> - Add a [groups] block containing names and description for groups:
>
> [groups]
> init starting a working area
> worktree working on the current change
> remote working with others
> info examining the history and state
> history growing, marking and tweaking your history
>
> - Add a [commands] header on top of the known command list, and
> group names as a third column.
>
> [commands]
> git-add mainporcelain common-worktree
> git-am mainporcelain
> git-annotate ancillaryinterrogators
> git-apply plumbingmanipulators
> git-archimport foreignscminterface
> git-archive mainporcelain
> git-bisect mainporcelain
> git-blame ancillaryinterrogators
> git-branch mainporcelain common-history
Thanks, this version is looking better. I, personally, still find the
redundant "command-" prefix ugly and would just as soon see it go
away. I'll make some suggestions about that when reviewing patch 2/3.
More below.
> This produces the following output of $ git help:
>
> [...]
> The most commonly used git commands are:
>
> * starting a working area:
> clone Clone a repository into a new directory
> init Create an empty Git repository or reinitialize [...]
>
> * working on the current change:
> add Add file contents to the index
> reset Reset current HEAD to the specified state
>
> * working with others:
> fetch Download objects and refs from another repository
> pull Fetch from and integrate with another repository [...]
> push Update remote refs along with associated objects
>
> * examining the history and state:
> log Show commit logs
> status Show the working tree status
>
> * growing, marking and tweaking your history:
> branch List, create, or delete branches
> checkout Checkout a branch or paths to the working tree
> commit Record changes to the repository
> diff Show changes between commits, commit and working [...]
> merge Join two or more development histories together
> [...]
>
> I removed from the list of common commands: rebase, rm, mv, bisect
> because [1] they are not really common to an unfamiliar user, [2] to
> save vertical space occupied by group headers.
Please perform the removals in a separate (preparatory) patch. Not
only is it difficult to spot the removals mixed in with the primary
changes of 1/3, but they are not even mentioned in the commit message
of that patch. More generally, the removals are a logically distinct
change from assigning groupings to the common commands, thus deserve
their own patch.
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 3/3] git help: group common commands by theme
2015-05-04 20:28 ` [PATCH 3/3] git help: group common commands by theme Sébastien Guimmara
@ 2015-05-06 3:16 ` Eric Sunshine
2015-05-06 20:31 ` Sébastien Guimmara
2015-05-08 21:08 ` Sébastien Guimmara
0 siblings, 2 replies; 39+ messages in thread
From: Eric Sunshine @ 2015-05-06 3:16 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano
On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> 'git help' shows common commands in alphabetical order:
>
> The most commonly used git commands are:
> add Add 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 group commands by
> concept, like this:
>
> The most commonly used git commands are:
>
> * starting a working area:
> clone Clone a repository into a new directory
> init Create an empty Git repository or reinitialize an existing one
>
> * working on the current change:
> add Add file contents to the index
> reset Reset current HEAD to the specified state
> [...]
This looks better. A couple minor style nits and a question below...
> ---
> diff --git a/help.c b/help.c
> index 2072a87..c8b0bb6 100644
> --- a/help.c
> +++ b/help.c
> @@ -218,18 +218,44 @@ void list_commands(unsigned int colopts,
> }
> }
>
> +int cmd_group_cmp(const void *elem1, const void *elem2)
> +{
> + int group1, group2;
> +
> + group1 = ((struct cmdname_help *) elem1)->group;
> + group2 = ((struct cmdname_help *) elem2)->group;
Style: Drop space after the cast: (type *)var
> +
> + if (group1 == group2)
> + return 0;
> + if (group1 > group2)
> + return 1;
> + else
> + return -1;
Do you also want to sort the commands alphabetically within group?
That is, something like this?
struct cmdname_help *e1 = elem1;
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;
> + unsigned char 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);
> }
>
> + qsort(common_cmds, ARRAY_SIZE(common_cmds),
> + sizeof(common_cmds[0]), cmd_group_cmp);
> +
> puts(_("The most commonly used git commands are:"));
> +
> for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
> - printf(" %s ", common_cmds[i].name);
> + if (common_cmds[i].group != current_grp) {
> + printf("\n * %s:\n", _(common_cmd_groups[common_cmds[i].group]));
> + }
Style: Drop unnecessary braces.
> + current_grp = common_cmds[i].group;
Alternately, move this assignment inside the braces.
> + printf(" %s ", common_cmds[i].name);
> mput_char(' ', longest - strlen(common_cmds[i].name));
> puts(_(common_cmds[i].help));
> }
> --
> 2.4.0
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara
` (3 preceding siblings ...)
2015-05-06 3:08 ` [PATCH 0/3] " Eric Sunshine
@ 2015-05-06 3:41 ` Junio C Hamano
2015-05-08 18:00 ` Sébastien Guimmara
2015-05-06 7:59 ` Matthieu Moy
2015-05-07 9:31 ` Emma Jane Hogbin Westby
6 siblings, 1 reply; 39+ messages in thread
From: Junio C Hamano @ 2015-05-06 3:41 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: git, sunshine
Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
> command-list.txt | 64 +++++++++++++++++++++++++++++++----------------------
> generate-cmdlist.sh | 43 +++++++++++++++++++++++++----------
> help.c | 28 ++++++++++++++++++++++-
I did not apply any of these patches to my tree, but
$ git grep command-list.txt
shows that Documentation/Makefile and Makefile reads from
command-list.txt to do their own useful tasks. A patch series that
does not touch either of them makes me suspect that it may be
breaking a lot of things.
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme
2015-05-04 20:28 ` [PATCH 1/3] command-list.txt: " Sébastien Guimmara
@ 2015-05-06 6:57 ` Eric Sunshine
2015-05-06 20:58 ` Sébastien Guimmara
0 siblings, 1 reply; 39+ messages in thread
From: Eric Sunshine @ 2015-05-06 6:57 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano
On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> Declare groups for common commands in the [groups] block,
> followed by group names and descriptions:
>
> [groups]
> init starting a working area
> worktree working on the current change
> remote working with others
> info examining the history and state
> history growing, marking and tweaking your history
>
> Then, in the [commands] block, map all common commands with a group:
>
> [commands]
> git-add mainporcelain common-worktree
> git-branch mainporcelain common-history
> git-checkout mainporcelain common-history
> [...]
>
> command names and groups are then parsed with generate-cmdlist.sh to
> generate common-commands.h.
>
> Those commands are displayed in groups in the output of 'git help'.
It probably also is important to mention that the order of the items
in [groups] is the order in which groups are output by 'git help'
More below.
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> diff --git a/command-list.txt b/command-list.txt
> index f1eae08..64394ca 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -1,29 +1,39 @@
> # List of known git commands.
> -# command name category [deprecated] [common]
> -git-add mainporcelain common
> +# only add group information for common commands
Perhaps mention also that the order of groups here is the order in
which they are output by 'git help'?
> +[groups]
Thinking on this a bit more, perhaps [groups] is too generic. Maybe
[common] or [commongroups] would be more descriptive?
> +init starting a working area
> +worktree working on the current change
> +remote working with others
"collaborating with others" perhaps?
More below.
> +info examining the history and state
> +history growing, marking and tweaking your history
> +
> +# command name [deprecated] category [group]
> +[commands]
> +git-add mainporcelain common-worktree
> [...]
> -git-bisect mainporcelain common
> +git-bisect mainporcelain
> [...]
> -git-branch mainporcelain common
> +git-branch mainporcelain common-history
> [...]
> -git-checkout mainporcelain common
> +git-checkout mainporcelain common-history
> [...]
> -git-clone mainporcelain common
> +git-clone mainporcelain common-init
> [...]
> -git-commit mainporcelain common
> +git-commit mainporcelain common-history
> [...]
> -git-diff mainporcelain common
> +git-diff mainporcelain common-history
> [...]
> -git-fast-export ancillarymanipulators
> -git-fast-import ancillarymanipulators
> -git-fetch mainporcelain common
> +git-fast-export ancillarymanipulators
> +git-fast-import ancillarymanipulators
Unintended whitespace changes for fast-export and fast-import lines? I
wouldn't have expected to see these lines change in this patch.
> +git-fetch mainporcelain common-remote
> [...]
> -git-fsck ancillaryinterrogators
> +git-fsck ancillaryinterrogators
Unintended whitespace change?
> [...]
> -git-grep mainporcelain common
> +git-grep mainporcelain
This change isn't mentioned anywhere, not even in the cover letter.
Did you intend to drop 'grep' from the common command list?
> [...]
> -git-help ancillaryinterrogators
> +git-help ancillaryinterrogators
Whitespace change?
More below.
> [...]
> -git-init mainporcelain common
> +git-init mainporcelain common-init
> [...]
> -git-log mainporcelain common
> +git-log mainporcelain common-info
> [...]
> -git-merge mainporcelain common
> +git-merge mainporcelain common-history
> [...]
> -git-mv mainporcelain common
> +git-mv mainporcelain
> [...]
> -git-pull mainporcelain common
> -git-push mainporcelain common
> +git-pull mainporcelain common-remote
> +git-push mainporcelain common-remote
> [...]
> -git-rebase mainporcelain common
> +git-rebase mainporcelain
> [...]
> -git-reset mainporcelain common
> +git-reset mainporcelain common-worktree
> [...]
> -git-rm mainporcelain common
> +git-rm mainporcelain
> [...]
> -git-show mainporcelain common
> +git-show mainporcelain
> [...]
> -git-status mainporcelain common
> +git-status mainporcelain common-info
> [...]
> -git-tag mainporcelain common
> +git-tag mainporcelain
This change also is not mentioned anywhere.
> [...]
> -git-write-tree plumbingmanipulators
> +git-write-tree plumbingmanipulators
> \ No newline at end of file
Your editor is perhaps dropping the final newline in the file? This is
an undesirable change. Patch 2/3 exhibits the same problem.
> --
> 2.4.0
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara
` (4 preceding siblings ...)
2015-05-06 3:41 ` Junio C Hamano
@ 2015-05-06 7:59 ` Matthieu Moy
2015-05-06 17:42 ` Junio C Hamano
2015-05-07 9:31 ` Emma Jane Hogbin Westby
6 siblings, 1 reply; 39+ messages in thread
From: Matthieu Moy @ 2015-05-06 7:59 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: git, gitster, sunshine
Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
> * examining the history and state:
> log Show commit logs
> status Show the working tree status
>
> * growing, marking and tweaking your history:
> branch List, create, or delete branches
> checkout Checkout a branch or paths to the working tree
> commit Record changes to the repository
> diff Show changes between commits, commit and working [...]
> merge Join two or more development histories together
I would have put "diff" next to "status" in the "examining the history
and state" section. It's neither growing, marking nor tweaking the
history.
> I removed from the list of common commands: rebase, rm, mv, bisect
> because [1] they are not really common to an unfamiliar user,
I tend to agree for rebase and bisect (even though showing them to
beginners may give them a hint on why Git can be good for them).
But removing rm and mv seems weird. It seems to me that the obvious
question of someone who just learnt "add" would be "and how do I do the
opposite?".
--
Matthieu Moy
http://www-verimag.imag.fr/~moy/
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-06 7:59 ` Matthieu Moy
@ 2015-05-06 17:42 ` Junio C Hamano
2015-05-07 8:42 ` Matthieu Moy
0 siblings, 1 reply; 39+ messages in thread
From: Junio C Hamano @ 2015-05-06 17:42 UTC (permalink / raw)
To: Matthieu Moy; +Cc: Sébastien Guimmara, git, sunshine
Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
> Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
>
>> * examining the history and state:
>> log Show commit logs
>> status Show the working tree status
>>
>> * growing, marking and tweaking your history:
>> branch List, create, or delete branches
>> checkout Checkout a branch or paths to the working tree
>> commit Record changes to the repository
>> diff Show changes between commits, commit and working [...]
>> merge Join two or more development histories together
>
> I would have put "diff" next to "status" in the "examining the history
> and state" section. It's neither growing, marking nor tweaking the
> history.
I am somewhat torn on this.
Your suggestion is about "what does this command do?" Which is a
perfectly acceptable way to categorize commands once you nailed your
workflow down.
There is another school of thought to organize them according to "in
which phase in your development cycle do you use this command?",
i.e. more workflow oriented categorization. From this point of
view, "diff" and "status" are important tools you use while "growing
your own history".
> But removing rm and mv seems weird. It seems to me that the obvious
> question of someone who just learnt "add" would be "and how do I do the
> opposite?".
And the answer may confuse that someone even further (it is not
necessarily "rm", but is often "reset"). As a list of simple
command set to help the dip-your-toes-in-water process, a new user
may be better off starting with "add", "add ." and "commit -a", and
learn from the last part of "git add --help" that there are "rm" and
"mv" (both of which happen a lot less often than "add").
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-06 3:08 ` [PATCH 0/3] " Eric Sunshine
@ 2015-05-06 20:26 ` Sébastien Guimmara
2015-05-06 20:49 ` Eric Sunshine
0 siblings, 1 reply; 39+ messages in thread
From: Sébastien Guimmara @ 2015-05-06 20:26 UTC (permalink / raw)
To: Eric Sunshine; +Cc: Git List, Junio C Hamano
On 05/06/2015 05:08 AM, Eric Sunshine wrote:
> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
> <sebastien.guimmara@gmail.com> wrote:
>> This v4 includes the following suggestions:
>>
>> In command-list.txt:
>> - Add a [groups] block containing names and description for groups:
>>
>> [groups]
>> init starting a working area
>> worktree working on the current change
>> remote working with others
>> info examining the history and state
>> history growing, marking and tweaking your history
>>
>> - Add a [commands] header on top of the known command list, and
>> group names as a third column.
>>
>> [commands]
>> git-add mainporcelain common-worktree
>> git-am mainporcelain
>> git-annotate ancillaryinterrogators
>> git-apply plumbingmanipulators
>> git-archimport foreignscminterface
>> git-archive mainporcelain
>> git-bisect mainporcelain
>> git-blame ancillaryinterrogators
>> git-branch mainporcelain common-history
>
> Thanks, this version is looking better. I, personally, still find the
> redundant "command-" prefix ugly and would just as soon see it go
> away. I'll make some suggestions about that when reviewing patch 2/3.
Indeed, I'm a bit annoyed by this prefix. We could do two things:
- either drop the [deprecated] options, since it's never used.
- or keep it, but make it exclusive with [common]. It makes sense after
all that if a command is deprecated, we don't want to consider it
common anymore.
In both cases, we end up with only three columns, the third being
optional.
The common- prefix can then be removed in favor of the group ID alone.
>> I removed from the list of common commands: rebase, rm, mv, bisect
>> because [1] they are not really common to an unfamiliar user, [2] to
>> save vertical space occupied by group headers.
>
> Please perform the removals in a separate (preparatory) patch. Not
> only is it difficult to spot the removals mixed in with the primary
> changes of 1/3, but they are not even mentioned in the commit message
> of that patch. More generally, the removals are a logically distinct
> change from assigning groupings to the common commands, thus deserve
> their own patch.
>
Thanks. I will separate both patches.
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 3/3] git help: group common commands by theme
2015-05-06 3:16 ` Eric Sunshine
@ 2015-05-06 20:31 ` Sébastien Guimmara
2015-05-08 21:08 ` Sébastien Guimmara
1 sibling, 0 replies; 39+ messages in thread
From: Sébastien Guimmara @ 2015-05-06 20:31 UTC (permalink / raw)
To: Eric Sunshine; +Cc: Git List, Junio C Hamano, Sébastien Guimmara
On 05/06/2015 05:16 AM, Eric Sunshine wrote:
> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
> <sebastien.guimmara@gmail.com> wrote:
>> 'git help' shows common commands in alphabetical order:
>>
>> The most commonly used git commands are:
>> add Add 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 group commands by
>> concept, like this:
>>
>> The most commonly used git commands are:
>>
>> * starting a working area:
>> clone Clone a repository into a new directory
>> init Create an empty Git repository or reinitialize an existing one
>>
>> * working on the current change:
>> add Add file contents to the index
>> reset Reset current HEAD to the specified state
>> [...]
>
> This looks better. A couple minor style nits and a question below...
>
>> ---
>> diff --git a/help.c b/help.c
>> index 2072a87..c8b0bb6 100644
>> --- a/help.c
>> +++ b/help.c
>> @@ -218,18 +218,44 @@ void list_commands(unsigned int colopts,
>> }
>> }
>>
>> +int cmd_group_cmp(const void *elem1, const void *elem2)
>> +{
>> + int group1, group2;
>> +
>> + group1 = ((struct cmdname_help *) elem1)->group;
>> + group2 = ((struct cmdname_help *) elem2)->group;
>
> Style: Drop space after the cast: (type *)var
>
>> +
>> + if (group1 == group2)
>> + return 0;
>> + if (group1 > group2)
>> + return 1;
>> + else
>> + return -1;
>
> Do you also want to sort the commands alphabetically within group?
> That is, something like this?
>
> struct cmdname_help *e1 = elem1;
> 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);
>
Hmmm yes. Good idea.
>> +}
>> +
>> void list_common_cmds_help(void)
>> {
>> int i, longest = 0;
>> + unsigned char 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);
>> }
>>
>> + qsort(common_cmds, ARRAY_SIZE(common_cmds),
>> + sizeof(common_cmds[0]), cmd_group_cmp);
>> +
>> puts(_("The most commonly used git commands are:"));
>> +
>> for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
>> - printf(" %s ", common_cmds[i].name);
>> + if (common_cmds[i].group != current_grp) {
>> + printf("\n * %s:\n", _(common_cmd_groups[common_cmds[i].group]));
>> + }
>
> Style: Drop unnecessary braces.
Understood.
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-06 20:26 ` Sébastien Guimmara
@ 2015-05-06 20:49 ` Eric Sunshine
0 siblings, 0 replies; 39+ messages in thread
From: Eric Sunshine @ 2015-05-06 20:49 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano
On Wed, May 6, 2015 at 4:26 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> On 05/06/2015 05:08 AM, Eric Sunshine wrote:
>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
>> <sebastien.guimmara@gmail.com> wrote:
>>> - Add a [groups] block containing names and description for groups:
>>>
>>> [groups]
>>> init starting a working area
>>>
>>> - Add a [commands] header on top of the known command list, and
>>> group names as a third column.
>>>
>>> [commands]
>>> git-add mainporcelain common-worktree
>>
>> Thanks, this version is looking better. I, personally, still find the
>> redundant "command-" prefix ugly and would just as soon see it go
>> away. I'll make some suggestions about that when reviewing patch 2/3.
>
> Indeed, I'm a bit annoyed by this prefix. We could do two things:
> - either drop the [deprecated] options, since it's never used.
> - or keep it, but make it exclusive with [common]. It makes sense after
> all that if a command is deprecated, we don't want to consider it
> common anymore.
>
> In both cases, we end up with only three columns, the third being
> optional.
>
> The common- prefix can then be removed in favor of the group ID alone.
Sorry for not yet reviewing patch 2/3. I'm trying to find time to
review it and make the promised suggestions, however, Real Life keeps
getting in the way. If 'deprecated' has never been used and if it is
not likely to be used in the future, then dropping that column may
indeed be an easy way forward toward the goal of eliminating the
"common-" prefix. A possible shortcoming of this columnar approach,
however, is that if someone someday comes up with some new type of
attribute to assign in a new column, then you still end up in the same
boat where not all entries use all columns, and you have difficulty
figuring out to which column an attribute belongs.
Instead, as mentioned originally, I had envisioned a solution in which
any command tagged with an attribute mentioned in [groups] would be
considered common, without having to resort to a prefix or fixed
columns. This should be more flexible in the long run, but may be
overkill for present day. I think that awk should be able to handle
this easily, but haven't had the time to actually sit down and flesh
it out (which I wanted to do while reviewing 2/3).
And, any solution is likely going to have to take into account the two
Makefiles Junio mentioned.
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme
2015-05-06 6:57 ` Eric Sunshine
@ 2015-05-06 20:58 ` Sébastien Guimmara
2015-05-07 16:50 ` Eric Sunshine
0 siblings, 1 reply; 39+ messages in thread
From: Sébastien Guimmara @ 2015-05-06 20:58 UTC (permalink / raw)
To: Eric Sunshine; +Cc: Git List, Junio C Hamano, Sébastien Guimmara
On 05/06/2015 08:57 AM, Eric Sunshine wrote:
> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
> <sebastien.guimmara@gmail.com> wrote:
>> Declare groups for common commands in the [groups] block,
>> followed by group names and descriptions:
>>
>> [groups]
>> init starting a working area
>> worktree working on the current change
>> remote working with others
>> info examining the history and state
>> history growing, marking and tweaking your history
>>
>> Then, in the [commands] block, map all common commands with a group:
>>
>> [commands]
>> git-add mainporcelain common-worktree
>> git-branch mainporcelain common-history
>> git-checkout mainporcelain common-history
>> [...]
>>
>> command names and groups are then parsed with generate-cmdlist.sh to
>> generate common-commands.h.
>>
>> Those commands are displayed in groups in the output of 'git help'.
>
> It probably also is important to mention that the order of the items
> in [groups] is the order in which groups are output by 'git help'
Yes. I'll add a comment in the file as well as in the commit.
>
> More below.
>
>> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
>> ---
>> diff --git a/command-list.txt b/command-list.txt
>> index f1eae08..64394ca 100644
>> --- a/command-list.txt
>> +++ b/command-list.txt
>> @@ -1,29 +1,39 @@
>> # List of known git commands.
>> -# command name category [deprecated] [common]
>> -git-add mainporcelain common
>> +# only add group information for common commands
>
> Perhaps mention also that the order of groups here is the order in
> which they are output by 'git help'?
It wouldn't be necessary if we reorder alphabetically the content of
each group, no ?
>
>> +[groups]
>
> Thinking on this a bit more, perhaps [groups] is too generic. Maybe
> [common] or [commongroups] would be more descriptive?
>
>> +init starting a working area
>> +worktree working on the current change
>> +remote working with others
>
> "collaborating with others" perhaps?
Yes, "groups" has been itching a bit. I thought about "theme", but
common just does the job too. "collaborating with others" sounds
redundant to me (but I'm being a grammar nazi here).
>> -git-fast-export ancillarymanipulators
>> -git-fast-import ancillarymanipulators
>> -git-fetch mainporcelain common
>> +git-fast-export ancillarymanipulators
>> +git-fast-import ancillarymanipulators
>
> Unintended whitespace changes for fast-export and fast-import lines? I
> wouldn't have expected to see these lines change in this patch.
>
All whitespace changes were intended to align the commands on the same
column. I realize this should be the object of a separate patch.
>> -git-grep mainporcelain common
>> +git-grep mainporcelain
>
> This change isn't mentioned anywhere, not even in the cover letter.
> Did you intend to drop 'grep' from the common command list?
It's a mistake in the cover letter. I indeed intended to propose to
remove grep and tag from the common commands.
>> [...]
>> -git-write-tree plumbingmanipulators
>> +git-write-tree plumbingmanipulators
>> \ No newline at end of file
>
> Your editor is perhaps dropping the final newline in the file? This is
> an undesirable change. Patch 2/3 exhibits the same problem.
As for the final newline, it was deliberately removed. I was not aware it
was necessary in text files. I'll correct this.
Thank you for the help,
Sébastien
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-06 17:42 ` Junio C Hamano
@ 2015-05-07 8:42 ` Matthieu Moy
2015-05-07 18:44 ` Junio C Hamano
0 siblings, 1 reply; 39+ messages in thread
From: Matthieu Moy @ 2015-05-07 8:42 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Sébastien Guimmara, git, sunshine
Junio C Hamano <gitster@pobox.com> writes:
> And the answer may confuse that someone even further (it is not
> necessarily "rm", but is often "reset"). As a list of simple
> command set to help the dip-your-toes-in-water process, a new user
> may be better off starting with "add", "add ." and "commit -a", and
> learn from the last part of "git add --help" that there are "rm" and
> "mv" (both of which happen a lot less often than "add").
If one wonders how to remove a file from Git, expecting that user to
look at the doc for "git add" to find out seems really backwards to me.
--
Matthieu Moy
http://www-verimag.imag.fr/~moy/
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara
` (5 preceding siblings ...)
2015-05-06 7:59 ` Matthieu Moy
@ 2015-05-07 9:31 ` Emma Jane Hogbin Westby
2015-05-08 18:21 ` Sébastien Guimmara
6 siblings, 1 reply; 39+ messages in thread
From: Emma Jane Hogbin Westby @ 2015-05-07 9:31 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: git, gitster, sunshine
Sébastien !
This is fantastic! My apologies for jumping in late. Hopefully I'm not
too late.
Sébastien Guimmara wrote:
> This v4 includes the following suggestions:
>
> In command-list.txt:
> - Add a [groups] block containing names and description for groups:
>
> [groups]
> init starting a working area
> worktree working on the current change
> remote working with others
> info examining the history and state
> history growing, marking and tweaking your history
I like these headings / separation.
As you've already "lost" a line to the header, would it make sense to
add a "see also" into the Guides from here? For example:
starting a working area (see also: git help tutorial)
working on the current change (see also: git help everyday)
working with others (see also: git help workflows)
examining the history and state (see also: git help revisions)
[...]
> This produces the following output of $ git help:
>
> [...]
> The most commonly used git commands are:
>
> * starting a working area:
> clone Clone a repository into a new directory
> init Create an empty Git repository or reinitialize [...]
>
> * working on the current change:
> add Add file contents to the index
> reset Reset current HEAD to the specified state
I could not live without status at this stage, and status always tells
me what I should do next. I'm tempted to see it up here instead...
> * working with others:
> fetch Download objects and refs from another repository
> pull Fetch from and integrate with another repository [...]
> push Update remote refs along with associated objects
>
> * examining the history and state:
> log Show commit logs
> status Show the working tree status
For this grouping, instead of also having "state", I'd like to see log
and diff. Perhaps the header is simply "examining the history". This
narrowing would make more sense to then move status up to "working on
the current change".
> * growing, marking and tweaking your history:
> branch List, create, or delete branches
> checkout Checkout a branch or paths to the working tree
> commit Record changes to the repository
> diff Show changes between commits, commit and working [...]
> merge Join two or more development histories together
By the definition of "tweaking" I would include rebase. Hiding rebase
from the "common" list will increase its mystique and make people even
more hesitant to use it. Best to shine some light on it and help to make
it less scary. I would remove diff from this group as it is a
non-destructive command.
What a wonderful thing to have started, Sébastien ! Thank you. :)
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme
2015-05-06 20:58 ` Sébastien Guimmara
@ 2015-05-07 16:50 ` Eric Sunshine
2015-05-07 19:23 ` Johannes Sixt
2015-05-08 18:43 ` Sébastien Guimmara
0 siblings, 2 replies; 39+ messages in thread
From: Eric Sunshine @ 2015-05-07 16:50 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano
On Wed, May 6, 2015 at 4:58 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> On 05/06/2015 08:57 AM, Eric Sunshine wrote:
>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
>> <sebastien.guimmara@gmail.com> wrote:
>>> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
>>> ---
>>> diff --git a/command-list.txt b/command-list.txt
>>> index f1eae08..64394ca 100644
>>> --- a/command-list.txt
>>> +++ b/command-list.txt
>>> @@ -1,29 +1,39 @@
>>> # List of known git commands.
>>> -# command name category [deprecated] [common]
>>> -git-add mainporcelain common
>>> +# only add group information for common commands
>>
>> Perhaps mention also that the order of groups here is the order in
>> which they are output by 'git help'?
>
> It wouldn't be necessary if we reorder alphabetically the content of
> each group, no ?
I'm not sure to what you are referring here? (Perhaps my comment was
unclear, or perhaps I'm misreading your response.)
I meant only that the comment above [groups] should say that the order
of the items in [groups] is the order in which the groups themselves
are output by "git help".
>>> +[groups]
>>
>> Thinking on this a bit more, perhaps [groups] is too generic. Maybe
>> [common] or [commongroups] would be more descriptive?
>>
>>> +init starting a working area
>>> +worktree working on the current change
>>> +remote working with others
>>
>> "collaborating with others" perhaps?
>
> Yes, "groups" has been itching a bit. I thought about "theme", but
> common just does the job too. "collaborating with others" sounds
> redundant to me (but I'm being a grammar nazi here).
I also think "collaborating" itself is best, but changed it at the
last second before sending the email.
>>> -git-fast-export ancillarymanipulators
>>> -git-fast-import ancillarymanipulators
>>> -git-fetch mainporcelain common
>>> +git-fast-export ancillarymanipulators
>>> +git-fast-import ancillarymanipulators
>>
>> Unintended whitespace changes for fast-export and fast-import lines? I
>> wouldn't have expected to see these lines change in this patch.
>
> All whitespace changes were intended to align the commands on the same
> column. I realize this should be the object of a separate patch.
Strange. In my editor, all columns are already aligned. Perhaps your
tab with setting is incorrect? (It should be set to 8.)
>>> -git-grep mainporcelain common
>>> +git-grep mainporcelain
>>
>> This change isn't mentioned anywhere, not even in the cover letter.
>> Did you intend to drop 'grep' from the common command list?
>
> It's a mistake in the cover letter. I indeed intended to propose to
> remove grep and tag from the common commands.
I personally consider "grep" an important beginner command, but that's
an issue to be argued separately; and it's also why it's a good idea
to put the removals in their own patch, so people can argue about it
without holding up the rest of the patches.
>>> [...]
>>> -git-write-tree plumbingmanipulators
>>> +git-write-tree plumbingmanipulators
>>> \ No newline at end of file
>>
>> Your editor is perhaps dropping the final newline in the file? This is
>> an undesirable change. Patch 2/3 exhibits the same problem.
>
> As for the final newline, it was deliberately removed. I was not aware it
> was necessary in text files. I'll correct this.
Historically, many Unix tools incorrectly handled files lacking that
final newline; sometimes by dropping the line altogether, sometimes
mis-processing it in some way or another. Misbehaviors still exist
today, often in BSD tools. In fact, just a few days ago, such a
problem was reported for git-filter-branch[1]. Consequently, retaining
newline is good insurance against misbehaving tools.
[1]: http://thread.gmane.org/gmane.comp.version-control.git/267828/focus=267957
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-07 8:42 ` Matthieu Moy
@ 2015-05-07 18:44 ` Junio C Hamano
2015-05-08 8:18 ` Matthieu Moy
0 siblings, 1 reply; 39+ messages in thread
From: Junio C Hamano @ 2015-05-07 18:44 UTC (permalink / raw)
To: Matthieu Moy; +Cc: Sébastien Guimmara, git, sunshine
Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> And the answer may confuse that someone even further (it is not
>> necessarily "rm", but is often "reset"). As a list of simple
>> command set to help the dip-your-toes-in-water process, a new user
>> may be better off starting with "add", "add ." and "commit -a", and
>> learn from the last part of "git add --help" that there are "rm" and
>> "mv" (both of which happen a lot less often than "add").
>
> If one wonders how to remove a file from Git, expecting that user to
> look at the doc for "git add" to find out seems really backwards to me.
Yeah, but you are moving the goalpost.
What you are reponding to is my reaction to your earlier "the
obvious question of someone who just learnt 'add' would be 'and how
do I do the _opposite_?'". And I would expect such a person to look
at 'add' to find 'SEE ALSO' section.
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme
2015-05-07 16:50 ` Eric Sunshine
@ 2015-05-07 19:23 ` Johannes Sixt
2015-05-08 10:11 ` Johannes Schindelin
2015-05-08 18:43 ` Sébastien Guimmara
1 sibling, 1 reply; 39+ messages in thread
From: Johannes Sixt @ 2015-05-07 19:23 UTC (permalink / raw)
To: Eric Sunshine, Sébastien Guimmara; +Cc: Git List, Junio C Hamano
Am 07.05.2015 um 18:50 schrieb Eric Sunshine:
> On Wed, May 6, 2015 at 4:58 PM, Sébastien Guimmara
> <sebastien.guimmara@gmail.com> wrote:
>> On 05/06/2015 08:57 AM, Eric Sunshine wrote:
>>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
>>> <sebastien.guimmara@gmail.com> wrote:
>>>> -git-write-tree plumbingmanipulators
>>>> +git-write-tree plumbingmanipulators
>>>> \ No newline at end of file
>>>
>>> Your editor is perhaps dropping the final newline in the file? This is
>>> an undesirable change. Patch 2/3 exhibits the same problem.
>>
>> As for the final newline, it was deliberately removed. I was not aware it
>> was necessary in text files. I'll correct this.
>
> Historically, many Unix tools incorrectly handled files lacking that
> final newline; sometimes by dropping the line altogether, sometimes
> mis-processing it in some way or another. Misbehaviors still exist
> today, often in BSD tools. In fact, just a few days ago, such a
> problem was reported for git-filter-branch[1]. Consequently, retaining
> newline is good insurance against misbehaving tools.
Files lacking the trailing new-line are not "text files" according to
the POSIX definition, BTW.
-- Hannes
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 2/3] generate-cmdlist.sh: parse common group commands
2015-05-04 20:28 ` [PATCH 2/3] generate-cmdlist.sh: parse common group commands Sébastien Guimmara
@ 2015-05-08 3:20 ` Eric Sunshine
2015-05-08 3:39 ` Eric Sunshine
2015-05-08 20:55 ` Sébastien Guimmara
0 siblings, 2 replies; 39+ messages in thread
From: Eric Sunshine @ 2015-05-08 3:20 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: git, gitster
On Mon, May 04, 2015 at 10:28:09PM +0200, Sébastien Guimmara wrote:
> parse the [groups] block to create the array of group descriptions
>
> static char *common_cmd_groups[] = {
> N_("starting a working area"),
> ...
> };
>
> 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},
> ...
>
> So that 'git help' can print those command grouped by theme.
> ---
> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
> @@ -1,23 +1,42 @@
> +content=$(cat command-list.txt)
> +
> +group_line_no=$(expr $(echo "$content" | grep -n '^\[groups\]' | cut -f1 -d:) + 1)
> +command_line_no=$(expr $(echo "$content" | grep -n '^\[commands\]' | cut -f1 -d:) + 1)
> +groups=$(echo "$content" | sed -n ''$group_line_no', '$(expr $command_line_no)'p')
> [...]
> +static char *common_cmd_groups[] = {"
> +echo "$groups" |
> +while read group description; do
> + if [ -z $group ]; then
> + break
> + fi
> + echo ' N_("'$description'"),'
> +done
> +echo "};
> [...]
> +echo "$content" | grep 'common-' |
> +awk '{ print $1, "\t", $3 }' |
> +while read cmd grp; do
> + cmd_name=$(echo $cmd | cut -d - -f 2)
> + group_name=$(echo $grp | cut -d - -f 2)
> + group_idx=$(expr $(echo "$groups" | grep -n "^$group_name" | cut -c 1) - 1)
> + sed -n '
> + /^NAME/,/git-'"$cmd_name"'/H
> + ${
> + x
> + s/.*git-'"$cmd_name"' - \(.*\)/ {"'"$cmd_name"'", N_("\1"), '"$group_idx"'},/
> + p
> + }' "Documentation/$cmd.txt"
Background: In an earlier review, I observed[1] that the "common-" in
the "common-N_group" form was redundant, and I suggested that you
could add a [groups] section listing the groups, and that the order
of items in [groups] would imply the "git help" display order of the
groups, thus allowing you to do away with the "N_" qualifier, as
well. I also observed that you could determine if a command in
[commands] was common by checking if it was tagged with an attribute
from [groups], thus alleviating the need for the "common-" prefix.
This round makes nice headway toward the proposed scheme, although it
still depends upon the redundant "common-" prefix. When I earlier
suggested that awk could be helpful[2], I was thinking of its
associative arrays which could be used to determine if a command in
[commands] was tagged with an attribute from [groups].
I had intended to reply to the current patch with a short "here's
what I had in mind" example of using awk to achieve this goal,
however, the short example ended up implementing the full
functionality, so I went ahead and turned it into a proper patch[6]
(below), and shamelessly re-used your commit message (with minor
changes). You're welcome to include this patch in your re-roll, or
use it as inspiration if you want to write the functionality
yourself.
Some notes about the re-implementation in awk: It assumes that
[groups] has been renamed to [common] as suggested[3], and assumes
that the "common-" prefix has been dropped from the [commands]
attribute entries. The awk script replaces the current shell script
entirely, and all common-cmds.h generation functionality is now
handled by the one awk invocation rather than by a series of commands
invoked by the shell script, which should make it faster (especially
on Windows). Finally, unlike the shell script, the awk script does
not bother sorting commands from command-list.txt since it assumes
that command sorting will happen in parallel with grouping[4].
When the awk script encounters [common], it begins collecting group
names in a grp[] array and emits the appropriate common_cmd_groups[]
"C" initializer for each. Upon encountering [commands], it switches
mode and, for each command line, checks if any attribute with which a
command is tagged exists in grp[]. If so, it emits the appropriate
common_cmds[] "C" initializer. Comment and blank lines are skipped.
By the way, Junio observed[5] that you will need to adjust a couple
Makefiles (and such) to account for the new [common] section and
[commands] header. A good start would be to filter command-list.txt
via this command:
sed '1,/\[commands\]/d' <command-list.txt
which will strip out everything up to and including the [commands]
header.
[1]: http://article.gmane.org/gmane.comp.version-control.git/268291
[2]: http://article.gmane.org/gmane.comp.version-control.git/268294
[3]: http://article.gmane.org/gmane.comp.version-control.git/268453
[4]: http://article.gmane.org/gmane.comp.version-control.git/268442
[5]: http://article.gmane.org/gmane.comp.version-control.git/268443
[6]: Below is full patch which replaces 2/3 from this round:
--- >8 ---
From: Eric Sunshine <sunshine@sunshineco.com>
Subject: [PATCH] generate-cmdlist: parse common group commands
Parse the [common] 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 [common] are emitted to
common_cmds[].
[commit message by Sébastien Guimmara <sebastien.guimmara@gmail.com>]
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---
Makefile | 4 ++--
generate-cmdlist.awk | 39 +++++++++++++++++++++++++++++++++++++++
generate-cmdlist.sh | 23 -----------------------
3 files changed, 41 insertions(+), 25 deletions(-)
create mode 100644 generate-cmdlist.awk
delete mode 100755 generate-cmdlist.sh
diff --git a/Makefile b/Makefile
index 5f3987f..de28ae1 100644
--- a/Makefile
+++ b/Makefile
@@ -1687,10 +1687,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.awk command-list.txt
common-cmds.h: $(wildcard Documentation/git-*.txt)
- $(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@
+ $(QUIET_GEN)awk -f generate-cmdlist.awk 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.awk b/generate-cmdlist.awk
new file mode 100644
index 0000000..19b36e5
--- /dev/null
+++ b/generate-cmdlist.awk
@@ -0,0 +1,39 @@
+BEGIN {
+ print "/* Automatically generated */\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 <f > 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
+ next
+}
+/\[common\]/ {
+ state = 1
+}
+END { print "};" }
diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
deleted file mode 100755
index 9a4c9b9..0000000
--- 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.319.g7a04823
--- >8 ---
^ permalink raw reply related [flat|nested] 39+ messages in thread
* Re: [PATCH 2/3] generate-cmdlist.sh: parse common group commands
2015-05-08 3:20 ` Eric Sunshine
@ 2015-05-08 3:39 ` Eric Sunshine
2015-05-08 20:55 ` Sébastien Guimmara
1 sibling, 0 replies; 39+ messages in thread
From: Eric Sunshine @ 2015-05-08 3:39 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano
On Thu, May 7, 2015 at 11:20 PM, Eric Sunshine <sunshine@sunshineco.com> wrote:
> From: Eric Sunshine <sunshine@sunshineco.com>
> Subject: [PATCH] generate-cmdlist: parse common group commands
>
> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
> ---
> diff --git a/generate-cmdlist.awk b/generate-cmdlist.awk
> new file mode 100644
> index 0000000..19b36e5
> --- /dev/null
> +++ b/generate-cmdlist.awk
> @@ -0,0 +1,39 @@
> [...]
> +state == 1 {
> + grp[$1] = ++n
> + sub($1"[ ][ ]*", "")
> + printf "\tN_(\"%s\"),\n", $0
> + next
By the way, this 'next' line can be deleted. It was leftover gunk from
an earlier iteration. It doesn't harm, but doesn't help either, and is
thus potentially confusing.
> +}
> +/\[common\]/ {
> + state = 1
> +}
> +END { print "};" }
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-07 18:44 ` Junio C Hamano
@ 2015-05-08 8:18 ` Matthieu Moy
2015-05-08 16:19 ` Junio C Hamano
0 siblings, 1 reply; 39+ messages in thread
From: Matthieu Moy @ 2015-05-08 8:18 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Sébastien Guimmara, git, sunshine
Junio C Hamano <gitster@pobox.com> writes:
> Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
>
>> Junio C Hamano <gitster@pobox.com> writes:
>>
>>> And the answer may confuse that someone even further (it is not
>>> necessarily "rm", but is often "reset"). As a list of simple
>>> command set to help the dip-your-toes-in-water process, a new user
>>> may be better off starting with "add", "add ." and "commit -a", and
>>> learn from the last part of "git add --help" that there are "rm" and
>>> "mv" (both of which happen a lot less often than "add").
>>
>> If one wonders how to remove a file from Git, expecting that user to
>> look at the doc for "git add" to find out seems really backwards to me.
>
> Yeah, but you are moving the goalpost.
Yes, because Git has more than one user and each user may have different
ways of thinking. I both find it weird to present "add" without "rm" and
to expect users to look at the doc for "add" to find "rm".
--
Matthieu Moy
http://www-verimag.imag.fr/~moy/
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme
2015-05-07 19:23 ` Johannes Sixt
@ 2015-05-08 10:11 ` Johannes Schindelin
2015-05-08 12:01 ` Andreas Schwab
0 siblings, 1 reply; 39+ messages in thread
From: Johannes Schindelin @ 2015-05-08 10:11 UTC (permalink / raw)
To: Johannes Sixt; +Cc: Sébastien Guimmara, Git List, Junio C Hamano
Hi Hannes,
On 2015-05-07 21:23, Johannes Sixt wrote:
> Files lacking the trailing new-line are not "text files" according to
> the POSIX definition, BTW.
It's probably my failure for not finding the documentation on that, but I really would like to be educated. Do you have an authoritative source for that statement?
Thank you,
Johannes
P.S.: Somehow when I ask GMX to send mail to Eric Sunshine today, it refuses ("mailbox not available"?), so I removed the address from the Cc: list. Will investigate what is wrong if that happens again. Sorry!
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme
2015-05-08 10:11 ` Johannes Schindelin
@ 2015-05-08 12:01 ` Andreas Schwab
2015-05-08 13:02 ` Johannes Schindelin
0 siblings, 1 reply; 39+ messages in thread
From: Andreas Schwab @ 2015-05-08 12:01 UTC (permalink / raw)
To: Johannes Schindelin
Cc: Johannes Sixt, Sébastien Guimmara, Git List, Junio C Hamano
Johannes Schindelin <johannes.schindelin@gmx.de> writes:
> It's probably my failure for not finding the documentation on that, but I really would like to be educated. Do you have an authoritative source for that statement?
http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html
3.206 Line
A sequence of zero or more non- <newline> characters plus a terminating
<newline> character.
3.397 Text File
A file that contains characters organized into zero or more lines. The
lines do not contain NUL characters and none can exceed {LINE_MAX} bytes
in length, including the <newline> character. Although POSIX.1-2008 does
not distinguish between text files and binary files (see the ISO C
standard), many utilities only produce predictable or meaningful output
when operating on text files. The standard utilities that have such
restrictions always specify "text files" in their STDIN or INPUT FILES
sections.
Andreas.
--
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5
"And now for something completely different."
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme
2015-05-08 12:01 ` Andreas Schwab
@ 2015-05-08 13:02 ` Johannes Schindelin
0 siblings, 0 replies; 39+ messages in thread
From: Johannes Schindelin @ 2015-05-08 13:02 UTC (permalink / raw)
To: Andreas Schwab
Cc: Johannes Sixt, Sébastien Guimmara, Git List, Junio C Hamano
Hi Andreas,
On 2015-05-08 14:01, Andreas Schwab wrote:
> Johannes Schindelin <johannes.schindelin@gmx.de> writes:
>
>> It's probably my failure for not finding the documentation on that, but I really would like to be educated. Do you have an authoritative source for that statement?
>
> http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html
>
> 3.206 Line
> A sequence of zero or more non- <newline> characters plus a terminating
> <newline> character.
>
> 3.397 Text File
> A file that contains characters organized into zero or more lines. The
> lines do not contain NUL characters and none can exceed {LINE_MAX} bytes
> in length, including the <newline> character. Although POSIX.1-2008 does
> not distinguish between text files and binary files (see the ISO C
> standard), many utilities only produce predictable or meaningful output
> when operating on text files. The standard utilities that have such
> restrictions always specify "text files" in their STDIN or INPUT FILES
> sections.
Thanks!
Dscho
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-08 8:18 ` Matthieu Moy
@ 2015-05-08 16:19 ` Junio C Hamano
0 siblings, 0 replies; 39+ messages in thread
From: Junio C Hamano @ 2015-05-08 16:19 UTC (permalink / raw)
To: Matthieu Moy; +Cc: Sébastien Guimmara, git, sunshine
Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> Yeah, but you are moving the goalpost.
>
> Yes, because Git has more than one user and each user may have different
> ways of thinking. I both find it weird to present "add" without "rm" and
> to expect users to look at the doc for "add" to find "rm".
I would not expect somebody who wants to find 'rm' to look in 'add',
but you were talking about 'I just learnt add. What is the opposite
of add?' people. 'remove', 'revert', 'reset', 'unadd'...?
Yes, you can try "git help revert", "git help remove", ..., giving
all random words you think of in turn, but that is crazy. That is
why 'git add' lists related subcommands in SEE ALSO.
I do not mind keeping 'rm' with the description of what it does in
the list if we had enough vertical space. I think it would hurt to
have it in the list without the description of what it does, though,
because 'rm' is not opposite of 'add'.
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-06 3:41 ` Junio C Hamano
@ 2015-05-08 18:00 ` Sébastien Guimmara
2015-05-08 18:53 ` Junio C Hamano
0 siblings, 1 reply; 39+ messages in thread
From: Sébastien Guimmara @ 2015-05-08 18:00 UTC (permalink / raw)
To: Junio C Hamano, Git Users
Hi Junio,
A preliminary question to prepare the next round (v5) of this patch:
All versions of these patches were based upon the tip of 'master' 2.4.0
(3d4a3ff).
Should I rebase subsequent patches on top of 'next' ?
Sébastien
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-07 9:31 ` Emma Jane Hogbin Westby
@ 2015-05-08 18:21 ` Sébastien Guimmara
2015-05-08 18:58 ` Junio C Hamano
0 siblings, 1 reply; 39+ messages in thread
From: Sébastien Guimmara @ 2015-05-08 18:21 UTC (permalink / raw)
To: Emma Jane Hogbin Westby; +Cc: git, Sébastien Guimmara
On 05/07/2015 11:31 AM, Emma Jane Hogbin Westby wrote:
> Sébastien !
>
> This is fantastic! My apologies for jumping in late. Hopefully
> I'm not too late.
>
Thank you :) It's just a very modest contribution though.
>
> Sébastien Guimmara wrote:
>> This v4 includes the following suggestions:
>>
>> In command-list.txt:
>> - Add a [groups] block containing names and description for groups:
>>
>> [groups]
>> init starting a working area
>> worktree working on the current change
>> remote working with others
>> info examining the history and state
>> history growing, marking and tweaking your history
> I like these headings / separation.
>
> As you've already "lost" a line to the header, would it make sense to
> add a "see also" into the Guides from here? For example:
>
> starting a working area (see also: git help tutorial)
> working on the current change (see also: git help everyday)
> working with others (see also: git help workflows)
> examining the history and state (see also: git help revisions)
>
I think it's a good idea.
> [...]
>> This produces the following output of $ git help:
>>
>> [...]
>> The most commonly used git commands are:
>>
>> * starting a working area:
>> clone Clone a repository into a new directory
>> init Create an empty Git repository or reinitialize [...]
>>
>> * working on the current change:
>> add Add file contents to the index
>> reset Reset current HEAD to the specified state
> I could not live without status at this stage, and status always tells
> me what I should do next. I'm tempted to see it up here instead...
The layout was not designed to be workflow oriented (even if it appears
so), but rather theme oriented. But I think that a redesign that
introduces the typical Git workflow in a gentle, not intimidating manner
could help beginners realize that Git is extremely simple in its core
principles.
>
>> * working with others:
>> fetch Download objects and refs from another repository
>> pull Fetch from and integrate with another repository [...]
>> push Update remote refs along with associated objects
>>
>> * examining the history and state:
>> log Show commit logs
>> status Show the working tree status
> For this grouping, instead of also having "state", I'd like to see log
> and diff. Perhaps the header is simply "examining the history". This
> narrowing would make more sense to then move status up to "working on
> the current change".
>
>> * growing, marking and tweaking your history:
>> branch List, create, or delete branches
>> checkout Checkout a branch or paths to the working tree
>> commit Record changes to the repository
>> diff Show changes between commits, commit and working [...]
>> merge Join two or more development histories together
> By the definition of "tweaking" I would include rebase. Hiding rebase
> from the "common" list will increase its mystique and make people
> even more hesitant to use it. Best to shine some light on it and help
> to make it less scary. I would remove diff from this group as it is
> a non-destructive command.
In a workflow-oriented 'git help', I believe this would make sense.
The patch originally started by examining what is really a 'common'
command, and I estimated that 'rebase' was not that common. However,
since 'rebase' is such a powerful tool and a killer feature of git
(among others), we could mention it in a way that is less intimidating
(see above)
>
> What a wonderful thing to have started, Sébastien ! Thank you. :)
>
Thank you again :)
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme
2015-05-07 16:50 ` Eric Sunshine
2015-05-07 19:23 ` Johannes Sixt
@ 2015-05-08 18:43 ` Sébastien Guimmara
2015-05-08 19:00 ` Eric Sunshine
1 sibling, 1 reply; 39+ messages in thread
From: Sébastien Guimmara @ 2015-05-08 18:43 UTC (permalink / raw)
To: Eric Sunshine, Git Users
On 05/07/2015 06:50 PM, Eric Sunshine wrote:
> On Wed, May 6, 2015 at 4:58 PM, Sébastien Guimmara
> <sebastien.guimmara@gmail.com> wrote:
>> On 05/06/2015 08:57 AM, Eric Sunshine wrote:
>>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
>>> <sebastien.guimmara@gmail.com> wrote:
>>>> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
>>>> ---
>>>> diff --git a/command-list.txt b/command-list.txt
>>>> index f1eae08..64394ca 100644
>>>> --- a/command-list.txt
>>>> +++ b/command-list.txt
>>>> @@ -1,29 +1,39 @@
>>>> # List of known git commands.
>>>> -# command name category [deprecated] [common]
>>>> -git-add mainporcelain common
>>>> +# only add group information for common commands
>>>
>>> Perhaps mention also that the order of groups here is the order in
>>> which they are output by 'git help'?
>>
>> It wouldn't be necessary if we reorder alphabetically the content of
>> each group, no ?
>
> I'm not sure to what you are referring here? (Perhaps my comment was
> unclear, or perhaps I'm misreading your response.)
>
I was mistaken, I thought you wanted to reorder the commands
alphabetically, which was unnecessary since they were sorted in
help.c anyway. But yes, I shall add a comment in command-list.txt
> I meant only that the comment above [groups] should say that the order
> of the items in [groups] is the order in which the groups themselves
> are output by "git help".
>
>>>> +[groups]
>>>
>>> Thinking on this a bit more, perhaps [groups] is too generic. Maybe
>>> [common] or [commongroups] would be more descriptive?
>>>
>>>> +init starting a working area
>>>> +worktree working on the current change
>>>> +remote working with others
>>>
>>> "collaborating with others" perhaps?
>>
>> Yes, "groups" has been itching a bit. I thought about "theme", but
>> common just does the job too. "collaborating with others" sounds
>> redundant to me (but I'm being a grammar nazi here).
>
> I also think "collaborating" itself is best, but changed it at the
> last second before sending the email.
>
>>>> -git-fast-export ancillarymanipulators
>>>> -git-fast-import ancillarymanipulators
>>>> -git-fetch mainporcelain common
>>>> +git-fast-export ancillarymanipulators
>>>> +git-fast-import ancillarymanipulators
>>>
>>> Unintended whitespace changes for fast-export and fast-import lines? I
>>> wouldn't have expected to see these lines change in this patch.
>>
>> All whitespace changes were intended to align the commands on the same
>> column. I realize this should be the object of a separate patch.
>
> Strange. In my editor, all columns are already aligned. Perhaps your
> tab with setting is incorrect? (It should be set to 8.)
>
Actually I only removed the few tabs that were wandering in some lines
to replace them by spaces (almost all lines were space aligned, only a few
were tab aligned).
>>>> -git-grep mainporcelain common
>>>> +git-grep mainporcelain
>>>
>>> This change isn't mentioned anywhere, not even in the cover letter.
>>> Did you intend to drop 'grep' from the common command list?
>>
>> It's a mistake in the cover letter. I indeed intended to propose to
>> remove grep and tag from the common commands.
>
> I personally consider "grep" an important beginner command, but that's
> an issue to be argued separately; and it's also why it's a good idea
> to put the removals in their own patch, so people can argue about it
> without holding up the rest of the patches.
>
>>>> [...]
>>>> -git-write-tree plumbingmanipulators
>>>> +git-write-tree plumbingmanipulators
>>>> \ No newline at end of file
>>>
>>> Your editor is perhaps dropping the final newline in the file? This is
>>> an undesirable change. Patch 2/3 exhibits the same problem.
>>
>> As for the final newline, it was deliberately removed. I was not aware it
>> was necessary in text files. I'll correct this.
>
> Historically, many Unix tools incorrectly handled files lacking that
> final newline; sometimes by dropping the line altogether, sometimes
> mis-processing it in some way or another. Misbehaviors still exist
> today, often in BSD tools. In fact, just a few days ago, such a
> problem was reported for git-filter-branch[1]. Consequently, retaining
> newline is good insurance against misbehaving tools.
>
> [1]: http://thread.gmane.org/gmane.comp.version-control.git/267828/focus=267957
>
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-08 18:00 ` Sébastien Guimmara
@ 2015-05-08 18:53 ` Junio C Hamano
0 siblings, 0 replies; 39+ messages in thread
From: Junio C Hamano @ 2015-05-08 18:53 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Git Users
Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
> A preliminary question to prepare the next round (v5) of this patch:
>
> All versions of these patches were based upon the tip of 'master' 2.4.0
> (3d4a3ff).
>
> Should I rebase subsequent patches on top of 'next' ?
I think doing it on 2.4.0 is fine.
In general, you shouldn't base anything on 'next', unless you are
using some new features that are still cooking in 'next' on their
own topic branches. And even if that were the case, I would prefer
a series that introduces a new feature to wait for those other topic
branches it wants to use to graduate to 'master'. Alternatively,
you can identify these still-in-flight topics that you absolutely
need to depend on, merge them to 'master' yourself, _and_ build your
patches on top, but please make it clear that you did that when
sending the patches in if you take this route. Your patches would
become hostage of these other topics and cannot graduate to 'master'
before they do, so keep that in mind if you do so.
Whatever you do, you would still need to make sure that the result
of applying your patches merges cleanly to 'next' and works well.
Needless to say, a fix is preferrable to be based on 'maint' (or
even older maintenance tracks when it is feasible), but that does
not concern this "update help output" topic.
Thanks.
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-08 18:21 ` Sébastien Guimmara
@ 2015-05-08 18:58 ` Junio C Hamano
2015-05-08 20:08 ` Sébastien Guimmara
0 siblings, 1 reply; 39+ messages in thread
From: Junio C Hamano @ 2015-05-08 18:58 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Emma Jane Hogbin Westby, git
Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
> On 05/07/2015 11:31 AM, Emma Jane Hogbin Westby wrote:
>
>>> The most commonly used git commands are:
>>>
>>> * starting a working area:
>>> clone Clone a repository into a new directory
>>> init Create an empty Git repository or reinitialize [...]
>>>
>>> * working on the current change:
>>> add Add file contents to the index
>>> reset Reset current HEAD to the specified state
>> I could not live without status at this stage, and status always tells
>> me what I should do next. I'm tempted to see it up here instead...
>
> The layout was not designed to be workflow oriented (even if it appears
> so), but rather theme oriented.
I tend to agree with Emma here; even if your original ordering was
not using the workflow as the grouping criterion, that is something
that can easily be fixed, I would think.
After all, the very original did not categorize and sorted
alphabetically, so there is no room for the "we chose to be
theme-oriented (I am not sure what it means, though) and a major
redesign at this point will confuse users" kind of resistance to
come into the picture. At least not yet.
Thanks.
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme
2015-05-08 18:43 ` Sébastien Guimmara
@ 2015-05-08 19:00 ` Eric Sunshine
0 siblings, 0 replies; 39+ messages in thread
From: Eric Sunshine @ 2015-05-08 19:00 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Git Users
On Fri, May 8, 2015 at 2:43 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> On 05/07/2015 06:50 PM, Eric Sunshine wrote:
>> On Wed, May 6, 2015 at 4:58 PM, Sébastien Guimmara
>> <sebastien.guimmara@gmail.com> wrote:
>>> On 05/06/2015 08:57 AM, Eric Sunshine wrote:
>>>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
>>>> <sebastien.guimmara@gmail.com> wrote:
>>>>> -git-fast-export ancillarymanipulators
>>>>> -git-fast-import ancillarymanipulators
>>>>> -git-fetch mainporcelain common
>>>>> +git-fast-export ancillarymanipulators
>>>>> +git-fast-import ancillarymanipulators
>>>>
>>>> Unintended whitespace changes for fast-export and fast-import lines? I
>>>> wouldn't have expected to see these lines change in this patch.
>>>
>>> All whitespace changes were intended to align the commands on the same
>>> column. I realize this should be the object of a separate patch.
>>
>> Strange. In my editor, all columns are already aligned. Perhaps your
>> tab with setting is incorrect? (It should be set to 8.)
>
> Actually I only removed the few tabs that were wandering in some lines
> to replace them by spaces (almost all lines were space aligned, only a few
> were tab aligned).
Ah, I see. Thanks for the explanation.
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-08 18:58 ` Junio C Hamano
@ 2015-05-08 20:08 ` Sébastien Guimmara
0 siblings, 0 replies; 39+ messages in thread
From: Sébastien Guimmara @ 2015-05-08 20:08 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Emma Jane Hogbin Westby, git
On 05/08/2015 08:58 PM, Junio C Hamano wrote:
> Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
>
>> On 05/07/2015 11:31 AM, Emma Jane Hogbin Westby wrote:
>>
>>>> The most commonly used git commands are:
>>>>
>>>> * starting a working area:
>>>> clone Clone a repository into a new directory
>>>> init Create an empty Git repository or reinitialize [...]
>>>>
>>>> * working on the current change:
>>>> add Add file contents to the index
>>>> reset Reset current HEAD to the specified state
>>> I could not live without status at this stage, and status always tells
>>> me what I should do next. I'm tempted to see it up here instead...
>>
>> The layout was not designed to be workflow oriented (even if it appears
>> so), but rather theme oriented.
>
> I tend to agree with Emma here; even if your original ordering was
> not using the workflow as the grouping criterion, that is something
> that can easily be fixed, I would think.
>
> After all, the very original did not categorize and sorted
> alphabetically, so there is no room for the "we chose to be
> theme-oriented (I am not sure what it means, though) and a major
> redesign at this point will confuse users" kind of resistance to
> come into the picture. At least not yet.
>
> Thanks.
>
Exactly. The new version will be workflow-oriented.
By "theme-oriented", I mean that the group order does not necessarily
follow a "typical workflow" chronological order, even though it was
heavily implied. I should emphasize this "workflow" thing in the next
patch.
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 2/3] generate-cmdlist.sh: parse common group commands
2015-05-08 3:20 ` Eric Sunshine
2015-05-08 3:39 ` Eric Sunshine
@ 2015-05-08 20:55 ` Sébastien Guimmara
1 sibling, 0 replies; 39+ messages in thread
From: Sébastien Guimmara @ 2015-05-08 20:55 UTC (permalink / raw)
To: Eric Sunshine; +Cc: git, gitster
On 05/08/2015 05:20 AM, Eric Sunshine wrote:
> On Mon, May 04, 2015 at 10:28:09PM +0200, Sébastien Guimmara wrote:
>> parse the [groups] block to create the array of group descriptions
>>
>> static char *common_cmd_groups[] = {
>> N_("starting a working area"),
>> ...
>> };
>>
>> 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},
>> ...
>>
>> So that 'git help' can print those command grouped by theme.
>> ---
>> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
>> @@ -1,23 +1,42 @@
>> +content=$(cat command-list.txt)
>> +
>> +group_line_no=$(expr $(echo "$content" | grep -n '^\[groups\]' | cut -f1 -d:) + 1)
>> +command_line_no=$(expr $(echo "$content" | grep -n '^\[commands\]' | cut -f1 -d:) + 1)
>> +groups=$(echo "$content" | sed -n ''$group_line_no', '$(expr $command_line_no)'p')
>> [...]
>> +static char *common_cmd_groups[] = {"
>> +echo "$groups" |
>> +while read group description; do
>> + if [ -z $group ]; then
>> + break
>> + fi
>> + echo ' N_("'$description'"),'
>> +done
>> +echo "};
>> [...]
>> +echo "$content" | grep 'common-' |
>> +awk '{ print $1, "\t", $3 }' |
>> +while read cmd grp; do
>> + cmd_name=$(echo $cmd | cut -d - -f 2)
>> + group_name=$(echo $grp | cut -d - -f 2)
>> + group_idx=$(expr $(echo "$groups" | grep -n "^$group_name" | cut -c 1) - 1)
>> + sed -n '
>> + /^NAME/,/git-'"$cmd_name"'/H
>> + ${
>> + x
>> + s/.*git-'"$cmd_name"' - \(.*\)/ {"'"$cmd_name"'", N_("\1"), '"$group_idx"'},/
>> + p
>> + }' "Documentation/$cmd.txt"
>
> Background: In an earlier review, I observed[1] that the "common-" in
> the "common-N_group" form was redundant, and I suggested that you
> could add a [groups] section listing the groups, and that the order
> of items in [groups] would imply the "git help" display order of the
> groups, thus allowing you to do away with the "N_" qualifier, as
> well. I also observed that you could determine if a command in
> [commands] was common by checking if it was tagged with an attribute
> from [groups], thus alleviating the need for the "common-" prefix.
>
> This round makes nice headway toward the proposed scheme, although it
> still depends upon the redundant "common-" prefix. When I earlier
> suggested that awk could be helpful[2], I was thinking of its
> associative arrays which could be used to determine if a command in
> [commands] was tagged with an attribute from [groups].
>
> I had intended to reply to the current patch with a short "here's
> what I had in mind" example of using awk to achieve this goal,
> however, the short example ended up implementing the full
> functionality, so I went ahead and turned it into a proper patch[6]
> (below), and shamelessly re-used your commit message (with minor
> changes). You're welcome to include this patch in your re-roll, or
> use it as inspiration if you want to write the functionality
> yourself.
>
> Some notes about the re-implementation in awk: It assumes that
> [groups] has been renamed to [common] as suggested[3], and assumes
> that the "common-" prefix has been dropped from the [commands]
> attribute entries. The awk script replaces the current shell script
> entirely, and all common-cmds.h generation functionality is now
> handled by the one awk invocation rather than by a series of commands
> invoked by the shell script, which should make it faster (especially
> on Windows). Finally, unlike the shell script, the awk script does
> not bother sorting commands from command-list.txt since it assumes
> that command sorting will happen in parallel with grouping[4].
>
> When the awk script encounters [common], it begins collecting group
> names in a grp[] array and emits the appropriate common_cmd_groups[]
> "C" initializer for each. Upon encountering [commands], it switches
> mode and, for each command line, checks if any attribute with which a
> command is tagged exists in grp[]. If so, it emits the appropriate
> common_cmds[] "C" initializer. Comment and blank lines are skipped.
>
> By the way, Junio observed[5] that you will need to adjust a couple
> Makefiles (and such) to account for the new [common] section and
> [commands] header. A good start would be to filter command-list.txt
> via this command:
>
> sed '1,/\[commands\]/d' <command-list.txt
>
> which will strip out everything up to and including the [commands]
> header.
>
> [1]: http://article.gmane.org/gmane.comp.version-control.git/268291
> [2]: http://article.gmane.org/gmane.comp.version-control.git/268294
> [3]: http://article.gmane.org/gmane.comp.version-control.git/268453
> [4]: http://article.gmane.org/gmane.comp.version-control.git/268442
> [5]: http://article.gmane.org/gmane.comp.version-control.git/268443
> [6]: Below is full patch which replaces 2/3 from this round:
>
> --- >8 ---
> From: Eric Sunshine <sunshine@sunshineco.com>
> Subject: [PATCH] generate-cmdlist: parse common group commands
>
> Parse the [common] 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 [common] are emitted to
> common_cmds[].
>
> [commit message by Sébastien Guimmara <sebastien.guimmara@gmail.com>]
>
> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
> ---
> Makefile | 4 ++--
> generate-cmdlist.awk | 39 +++++++++++++++++++++++++++++++++++++++
> generate-cmdlist.sh | 23 -----------------------
> 3 files changed, 41 insertions(+), 25 deletions(-)
> create mode 100644 generate-cmdlist.awk
> delete mode 100755 generate-cmdlist.sh
>
> diff --git a/Makefile b/Makefile
> index 5f3987f..de28ae1 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1687,10 +1687,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.awk command-list.txt
>
> common-cmds.h: $(wildcard Documentation/git-*.txt)
> - $(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@
> + $(QUIET_GEN)awk -f generate-cmdlist.awk 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.awk b/generate-cmdlist.awk
> new file mode 100644
> index 0000000..19b36e5
> --- /dev/null
> +++ b/generate-cmdlist.awk
> @@ -0,0 +1,39 @@
> +BEGIN {
> + print "/* Automatically generated */\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 <f > 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
> + next
> +}
> +/\[common\]/ {
> + state = 1
> +}
> +END { print "};" }
> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
> deleted file mode 100755
> index 9a4c9b9..0000000
> --- 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 "};"
>
Wow. Thanks very much. It has been added in the new version of the patch,
including the removal of the 'next' line.
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 3/3] git help: group common commands by theme
2015-05-06 3:16 ` Eric Sunshine
2015-05-06 20:31 ` Sébastien Guimmara
@ 2015-05-08 21:08 ` Sébastien Guimmara
2015-05-08 21:17 ` Stefan Beller
1 sibling, 1 reply; 39+ messages in thread
From: Sébastien Guimmara @ 2015-05-08 21:08 UTC (permalink / raw)
To: Eric Sunshine; +Cc: Git List
On 05/06/2015 05:16 AM, Eric Sunshine wrote:
> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
>> +
>> + if (group1 == group2)
>> + return 0;
>> + if (group1 > group2)
>> + return 1;
>> + else
>> + return -1;
>
> Do you also want to sort the commands alphabetically within group?
> That is, something like this?
>
> struct cmdname_help *e1 = elem1;
> 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);
>
>> +}
Your version raises:
help.c: In function ‘cmd_group_cmp’:
help.c:223:28: warning: initialization discards ‘const’ qualifier from pointer target type [enabled by default]
struct cmdname_help *e1 = elem1;
^
help.c:224:28: warning: initialization discards ‘const’ qualifier from pointer target type [enabled by default]
struct cmdname_help *e2 = elem2;
^
With the cast:
struct cmdname_help *e1 = (struct cmdname_help*)elem1;
It compiles without a warning (gcc (Ubuntu 4.8.2-19ubuntu1) 4.8.2)
>> +
>> void list_common_cmds_help(void)
>> {
>> int i, longest = 0;
>> + unsigned char 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);
>> }
>>
>> + qsort(common_cmds, ARRAY_SIZE(common_cmds),
>> + sizeof(common_cmds[0]), cmd_group_cmp);
>> +
>> puts(_("The most commonly used git commands are:"));
>> +
>> for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
>> - printf(" %s ", common_cmds[i].name);
>> + if (common_cmds[i].group != current_grp) {
>> + printf("\n * %s:\n", _(common_cmd_groups[common_cmds[i].group]));
>> + }
>
> Style: Drop unnecessary braces.
>
>> + current_grp = common_cmds[i].group;
>
> Alternately, move this assignment inside the braces.
>
>> + printf(" %s ", common_cmds[i].name);
>> mput_char(' ', longest - strlen(common_cmds[i].name));
>> puts(_(common_cmds[i].help));
>> }
>> --
>> 2.4.0
>
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 3/3] git help: group common commands by theme
2015-05-08 21:08 ` Sébastien Guimmara
@ 2015-05-08 21:17 ` Stefan Beller
2015-05-08 21:19 ` Eric Sunshine
2015-05-08 21:20 ` Sébastien Guimmara
0 siblings, 2 replies; 39+ messages in thread
From: Stefan Beller @ 2015-05-08 21:17 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Eric Sunshine, Git List
On Fri, May 8, 2015 at 2:08 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> On 05/06/2015 05:16 AM, Eric Sunshine wrote:
>>
>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
>>>
>>> +
>>> + if (group1 == group2)
>>> + return 0;
>>> + if (group1 > group2)
>>> + return 1;
>>> + else
>>> + return -1;
>>
>>
>> Do you also want to sort the commands alphabetically within group?
>> That is, something like this?
>>
>> struct cmdname_help *e1 = elem1;
>> 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);
>>
>>> +}
>
>
> Your version raises:
>
> help.c: In function ‘cmd_group_cmp’:
> help.c:223:28: warning: initialization discards ‘const’ qualifier from
> pointer target type [enabled by default]
> struct cmdname_help *e1 = elem1;
> ^
> help.c:224:28: warning: initialization discards ‘const’ qualifier from
> pointer target type [enabled by default]
> struct cmdname_help *e2 = elem2;
> ^
>
> With the cast:
>
> struct cmdname_help *e1 = (struct cmdname_help*)elem1;
>
> It compiles without a warning (gcc (Ubuntu 4.8.2-19ubuntu1) 4.8.2)
>
>
I'd rather change the type of struct cmdname_help to be const, such
that it reads:
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);
instead of casting if possible.
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 3/3] git help: group common commands by theme
2015-05-08 21:17 ` Stefan Beller
@ 2015-05-08 21:19 ` Eric Sunshine
2015-05-08 21:20 ` Sébastien Guimmara
1 sibling, 0 replies; 39+ messages in thread
From: Eric Sunshine @ 2015-05-08 21:19 UTC (permalink / raw)
To: Stefan Beller; +Cc: Sébastien Guimmara, Git List
On Fri, May 8, 2015 at 5:17 PM, Stefan Beller <sbeller@google.com> wrote:
> On Fri, May 8, 2015 at 2:08 PM, Sébastien Guimmara
> <sebastien.guimmara@gmail.com> wrote:
>> On 05/06/2015 05:16 AM, Eric Sunshine wrote:
>>> Do you also want to sort the commands alphabetically within group?
>>> That is, something like this?
>>>
>>> struct cmdname_help *e1 = elem1;
>>> 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);
>>>
>>>> +}
>>
>> Your version raises:
>>
>> help.c:223:28: warning: initialization discards ‘const’ qualifier from
>> pointer target type [enabled by default]
>> struct cmdname_help *e1 = elem1;
>> ^
>> With the cast:
>> struct cmdname_help *e1 = (struct cmdname_help*)elem1;
>> It compiles without a warning (gcc (Ubuntu 4.8.2-19ubuntu1) 4.8.2)
>
> I'd rather change the type of struct cmdname_help to be const, such
> that it reads:
>
> 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);
>
> instead of casting if possible.
Right. That was just a quickly typed example in the email. The "real"
code should use a 'const' pointer.
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH 3/3] git help: group common commands by theme
2015-05-08 21:17 ` Stefan Beller
2015-05-08 21:19 ` Eric Sunshine
@ 2015-05-08 21:20 ` Sébastien Guimmara
1 sibling, 0 replies; 39+ messages in thread
From: Sébastien Guimmara @ 2015-05-08 21:20 UTC (permalink / raw)
To: Stefan Beller, Git Users
On 05/08/2015 11:17 PM, Stefan Beller wrote:
> On Fri, May 8, 2015 at 2:08 PM, Sébastien Guimmara
> <sebastien.guimmara@gmail.com> wrote:
>> On 05/06/2015 05:16 AM, Eric Sunshine wrote:
>>>
>>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
>>>>
>>>> +
>>>> + if (group1 == group2)
>>>> + return 0;
>>>> + if (group1 > group2)
>>>> + return 1;
>>>> + else
>>>> + return -1;
>>>
>>>
>>> Do you also want to sort the commands alphabetically within group?
>>> That is, something like this?
>>>
>>> struct cmdname_help *e1 = elem1;
>>> 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);
>>>
>>>> +}
>>
>>
>> Your version raises:
>>
>> help.c: In function ‘cmd_group_cmp’:
>> help.c:223:28: warning: initialization discards ‘const’ qualifier from
>> pointer target type [enabled by default]
>> struct cmdname_help *e1 = elem1;
>> ^
>> help.c:224:28: warning: initialization discards ‘const’ qualifier from
>> pointer target type [enabled by default]
>> struct cmdname_help *e2 = elem2;
>> ^
>>
>> With the cast:
>>
>> struct cmdname_help *e1 = (struct cmdname_help*)elem1;
>>
>> It compiles without a warning (gcc (Ubuntu 4.8.2-19ubuntu1) 4.8.2)
>>
>>
>
> I'd rather change the type of struct cmdname_help to be const, such
> that it reads:
>
> 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);
>
> instead of casting if possible.
>
yes, much better, thanks.
^ permalink raw reply [flat|nested] 39+ messages in thread
* [PATCH 0/3] git help: group common commands by theme
@ 2015-05-01 14:51 Sébastien Guimmara
0 siblings, 0 replies; 39+ messages in thread
From: Sébastien Guimmara @ 2015-05-01 14:51 UTC (permalink / raw)
To: git
Hello everyone,
This is my first contribution to an open source project.
I tackled the issue found here:
https://git.wiki.kernel.org/index.php/SmallProjectsIdeas#improve_.22git_help.22
Namely, format the output of 'git help' so that
the commands are grouped by theme.
Author: Sébastien Guimmara <sebastien.guimmara@gmail.com>
Date: Fri May 1 15:48:57 2015 +0200
command-list.txt - added command groups to common commands
groups are in the form: 'x_group',
where x is a number used to order (ascending)
commands in the displayed help.
example: git-add mainporcelain common-2_worktree
diff --git a/command-list.txt b/command-list.txt
index f1eae08..b0730a2 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,29 +1,29 @@
# List of known git commands.
# command name category [deprecated] [common]
-git-add mainporcelain common
+git-add mainporcelain common-3_worktree
git-am mainporcelain
git-annotate ancillaryinterrogators
git-apply plumbingmanipulators
git-archimport foreignscminterface
git-archive mainporcelain
-git-bisect mainporcelain common
+git-bisect mainporcelain common-7_search
git-blame ancillaryinterrogators
-git-branch mainporcelain common
+git-branch mainporcelain common-6_branching
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 common-6_branching
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 common-1_init
git-column purehelpers
-git-commit mainporcelain common
+git-commit mainporcelain common-5_history
git-commit-tree plumbingmanipulators
git-config ancillarymanipulators
git-count-objects ancillaryinterrogators
@@ -35,14 +35,14 @@ git-cvsimport foreignscminterface
git-cvsserver foreignscminterface
git-daemon synchingrepositories
git-describe mainporcelain
-git-diff mainporcelain common
+git-diff mainporcelain common-5_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 common-4_remote
git-fetch-pack synchingrepositories
git-filter-branch ancillarymanipulators
git-fmt-merge-msg purehelpers
@@ -51,7 +51,7 @@ git-format-patch mainporcelain
git-fsck ancillaryinterrogators
git-gc mainporcelain
git-get-tar-commit-id ancillaryinterrogators
-git-grep mainporcelain common
+git-grep mainporcelain common-7_search
git-gui mainporcelain
git-hash-object plumbingmanipulators
git-help ancillaryinterrogators
@@ -60,17 +60,17 @@ git-http-fetch synchelpers
git-http-push synchelpers
git-imap-send foreignscminterface
git-index-pack plumbingmanipulators
-git-init mainporcelain common
+git-init mainporcelain common-1_init
git-instaweb ancillaryinterrogators
git-interpret-trailers purehelpers
gitk mainporcelain
-git-log mainporcelain common
+git-log mainporcelain common-2_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 common-6_branching
git-merge-base plumbinginterrogators
git-merge-file plumbingmanipulators
git-merge-index plumbingmanipulators
@@ -79,7 +79,7 @@ git-mergetool ancillarymanipulators
git-merge-tree ancillaryinterrogators
git-mktag plumbingmanipulators
git-mktree plumbingmanipulators
-git-mv mainporcelain common
+git-mv mainporcelain common-3_worktree
git-name-rev plumbinginterrogators
git-notes mainporcelain
git-p4 foreignscminterface
@@ -90,11 +90,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 common-4_remote
+git-push mainporcelain common-4_remote
git-quiltimport foreignscminterface
git-read-tree plumbingmanipulators
-git-rebase mainporcelain common
+git-rebase mainporcelain common-5_history
git-receive-pack synchelpers
git-reflog ancillarymanipulators
git-relink ancillarymanipulators
@@ -103,28 +103,28 @@ git-repack ancillarymanipulators
git-replace ancillarymanipulators
git-request-pull foreignscminterface
git-rerere ancillaryinterrogators
-git-reset mainporcelain common
+git-reset mainporcelain common-3_worktree
git-revert mainporcelain
git-rev-list plumbinginterrogators
git-rev-parse ancillaryinterrogators
-git-rm mainporcelain common
+git-rm mainporcelain common-3_worktree
git-send-email foreignscminterface
git-send-pack synchingrepositories
git-shell synchelpers
git-shortlog mainporcelain
-git-show mainporcelain common
+git-show mainporcelain common-2_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 common-2_info
git-stripspace purehelpers
git-submodule mainporcelain
git-svn foreignscminterface
git-symbolic-ref plumbingmanipulators
-git-tag mainporcelain common
+git-tag mainporcelain common-5_history
git-unpack-file plumbinginterrogators
git-unpack-objects plumbingmanipulators
git-update-index plumbingmanipulators
^ permalink raw reply related [flat|nested] 39+ messages in thread
end of thread, other threads:[~2015-05-08 21:20 UTC | newest]
Thread overview: 39+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara
2015-05-04 20:28 ` [PATCH 1/3] command-list.txt: " Sébastien Guimmara
2015-05-06 6:57 ` Eric Sunshine
2015-05-06 20:58 ` Sébastien Guimmara
2015-05-07 16:50 ` Eric Sunshine
2015-05-07 19:23 ` Johannes Sixt
2015-05-08 10:11 ` Johannes Schindelin
2015-05-08 12:01 ` Andreas Schwab
2015-05-08 13:02 ` Johannes Schindelin
2015-05-08 18:43 ` Sébastien Guimmara
2015-05-08 19:00 ` Eric Sunshine
2015-05-04 20:28 ` [PATCH 2/3] generate-cmdlist.sh: parse common group commands Sébastien Guimmara
2015-05-08 3:20 ` Eric Sunshine
2015-05-08 3:39 ` Eric Sunshine
2015-05-08 20:55 ` Sébastien Guimmara
2015-05-04 20:28 ` [PATCH 3/3] git help: group common commands by theme Sébastien Guimmara
2015-05-06 3:16 ` Eric Sunshine
2015-05-06 20:31 ` Sébastien Guimmara
2015-05-08 21:08 ` Sébastien Guimmara
2015-05-08 21:17 ` Stefan Beller
2015-05-08 21:19 ` Eric Sunshine
2015-05-08 21:20 ` Sébastien Guimmara
2015-05-06 3:08 ` [PATCH 0/3] " Eric Sunshine
2015-05-06 20:26 ` Sébastien Guimmara
2015-05-06 20:49 ` Eric Sunshine
2015-05-06 3:41 ` Junio C Hamano
2015-05-08 18:00 ` Sébastien Guimmara
2015-05-08 18:53 ` Junio C Hamano
2015-05-06 7:59 ` Matthieu Moy
2015-05-06 17:42 ` Junio C Hamano
2015-05-07 8:42 ` Matthieu Moy
2015-05-07 18:44 ` Junio C Hamano
2015-05-08 8:18 ` Matthieu Moy
2015-05-08 16:19 ` Junio C Hamano
2015-05-07 9:31 ` Emma Jane Hogbin Westby
2015-05-08 18:21 ` Sébastien Guimmara
2015-05-08 18:58 ` Junio C Hamano
2015-05-08 20:08 ` Sébastien Guimmara
-- strict thread matches above, loose matches on Subject: below --
2015-05-01 14:51 Sébastien Guimmara
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.