git help: group common commands by theme
PATCH v2 1/3 git help: group common commands by theme
This v2 contains exactly the same patches but this time they are properly formatted using format-patch.
Group the common commands printed by 'git help' (or 'git' without any options) a beginner's friendly themes. To achieve this, the file command-list.txt receives an additional information for all 'common' commands, in the form of an indexed group suffix.
Group suffixes are in the form: 'x_group', where x is a number used to order (ascending) commands in the displayed help:
[...]
git-add mainporcelain common-3_worktree git-bisect mainporcelain common-7_search git-branch mainporcelain common-6_branching git-checkout mainporcelain common-6_branching
[...]
Note: the proposed layout comprises:
1_init
2_info
3_worktree
4_remote
5_history
6_branching
7_search
But they can be easily modified by just changing command-list.txt
command-list.txt is then parsed by generate-cmdlist.sh to generate common-cmds.h with the additional group name being a 'group' field in the cmdname_help struct:
[...]
{"add", N_("Add file contents to the index"), "3_worktree"}, {"bisect", N_("Find by binary search the change that introduced a
bug"), "7_search"},
{"branch", N_("List, create, or delete branches"), "6_branching"}, {"checkout", N_("Checkout a branch or paths to the working tree"),
"6_branching"},
[...]
Finally, list_common_cmds_help() prints those common commands by groups, skipping a line between each group:
[...]
The most commonly used git commands are:
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize an
existing one
log Show commit logs show Show various types of objects status Show the working tree status
add Add file contents to the index mv Move or rename a file, a directory, or a symlink reset Reset current HEAD to the specified state rm Remove files from the working tree and from the index
fetch Download objects and refs from another repository
pull Fetch from and integrate with another repository or a
local branch
push Update remote refs along with associated objects
commit Record changes to the repository diff Show changes between commits, commit and working tree, etc rebase Forward-port local commits to the updated upstream head tag Create, list, delete or verify a tag object signed with GPG
[...]
--- command-list.txt | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-)
command-list.txt +21 -21
@@ -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
Signature · 1 line
2.4.0
PATCH v2 2/3 git help: group common commands by theme
Extract the $grp shell variable from command-list.txt (eg: 'common-3_worktree') and add this value to the output:
before/after:
{"add", N_("Add file contents to the index")} {"add", N_("Add file contents to the index"), "3_worktree"}
So that when 'git' is called, we can display common commands grouped by theme instead of a less useful alphabetical order.
Signed-off by Sébastien Guimmara <[email protected]>
--- generate-cmdlist.sh | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-)
generate-cmdlist.sh +6 -3
@@ -4,19 +4,22 @@ echo "/* Automatically generated by $0 */ struct cmdname_help { char name[16]; char help[80]; + char group[20]; }; static struct cmdname_help common_cmds[] = {" -sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' command-list.txt | +sed -n -e 's/^git-\([^ ]*\)[ ].* common-\(.*\)/\1:\2/p' command-list.txt | sort | -while read cmd +while read line do + cmd=`echo $line | cut -d ':' -f 1` + grp=`echo $line | cut -d ':' -f 2` sed -n ' /^NAME/,/git-'"$cmd"'/H ${ x - s/.*git-'"$cmd"' - \(.*\)/ {"'"$cmd"'", N_("\1")},/ + s/.*git-'"$cmd"' - \(.*\)/ {"'"$cmd"'", N_("\1"), "'"$grp"'"},/ p }' "Documentation/git-$cmd.txt" done
Signature · 1 line
2.4.0
Hi!
Quoted 10 lines · Sébastien Guimmara
Extract the $grp shell variable from command-list.txt (eg:
'common-3_worktree') and add
this value to the output:before/after:
{"add",N_("Add file contents to the index")} {"add",N_("Add file contents to the index"), "3_worktree"}So that when 'git' is called, we can display common commands grouped by theme instead of a less useful alphabetical order.
Seems sensible to me but I'm no expert :-)
Quoted 12 lines
Signed-off by Sébastien Guimmara <[email protected]>
--- generate-cmdlist.sh | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-)generate-cmdlist.sh +0
-0
generate-cmdlist.sh echo "/* Automatically generated by $0 */ · line 7
Quoted 4 lines
generate-cmdlist.sh +1
-0@@ -4,19 +4,22 @@ echo "/* Automatically generated by $0 */ struct cmdname_help { char name[16]; char help[80]; + char group[20];
Is 20 chars long enough? git-p4 shows up as "foreignscminterface" which is pretty close to that limit.
generate-cmdlist.sh echo "/* Automatically generated by $0 */ · line 17
Quoted 13 lines
generate-cmdlist.sh +1
-1}; static struct cmdname_help common_cmds[] = {" -sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' command-list.txt | +sed -n -e 's/^git-\([^ ]*\)[ ].* common-\(.*\)/\1:\2/p'command-list.txt |
sort |generate-cmdlist.sh +3
-1-while read cmd +while read line do + cmd=`echo $line | cut -d ':' -f 1` + grp=`echo $line | cut -d ':' -f 2`
Should this use $(...) rather than ... ?
i.e.
cmd=$(echo $(line | cut -d : -f 1)
(And I don't think you need the quotes around the ':'.
Luke
Hello,
Quoted 6 lines · Luke Diamand
Quoted 6 lines
Signed-off by Sébastien Guimmara <[email protected]>
--- generate-cmdlist.sh | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-)
Quoted 11 lines
generate-cmdlist.sh echo "/* Automatically generated by $0 */ · line 7
Quoted 9 lines
generate-cmdlist.sh +1
-0@@ -4,19 +4,22 @@ echo "/* Automatically generated by $0 */ struct cmdname_help { char name[16]; char help[80]; + char group[20];Is 20 chars long enough? git-p4 shows up as "foreignscminterface" which is pretty close to that limit.
This 'foreignscminterface' is actually a category in the 2nd column of the file (like 'porcelain'). It is unrelated to common command groups (3rd column). Since those group names are not meant to be printed, I guess it is sufficient to keep them short.
Quoted 17 lines
generate-cmdlist.sh echo "/* Automatically generated by $0 */ · line 17
Quoted 13 lines
generate-cmdlist.sh +1
-1}; static struct cmdname_help common_cmds[] = {" -sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' command-list.txt | +sed -n -e 's/^git-\([^ ]*\)[ ].* common-\(.*\)/\1:\2/p'command-list.txt |
sort |generate-cmdlist.sh +3
-1-while read cmd +while read line do + cmd=`echo $line | cut -d ':' -f 1` + grp=`echo $line | cut -d ':' -f 2`Should this use $(...) rather than
...?
i.e.
cmd=$(echo $(line | cut -d : -f 1)
Quoted 3 lines
(And I don't think you need the quotes around the ':'.
Luke
Indeed, the quotes are unnecessary and $(...) seems to be more appropriate too.
I'll update the patch.
Thank you,
Sébastien
Quoted 4 lines · Luke Diamand
Quoted 4 lines
};
static struct
cmdname_helpcommon_cmds[] = {"
Quoted 13 lines
generate-cmdlist.sh echo "/* Automatically generated by $0 */ · line 17
Quoted 9 lines
(quoted diff) +1
-1-sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' command-list.txt | +sed -n -e 's/^git-\([^ ]*\)[ ].* common-\(.*\)/\1:\2/p'command-list.txt |
sort |generate-cmdlist.sh +3
-1-while read cmd +while read line do + cmd=`echo $line | cut -d ':' -f 1` + grp=`echo $line | cut -d ':' -f 2`Should this use $(...) rather than
...?
i.e.
cmd=$(echo $(line | cut -d : -f 1)
There are various ways to do that without a command substitution, eg:
cmd=${line%%:*}
grp=${line#:*}or:
IFS=:
set $line
cmd=$1 grp=$2
or:
sort |
while IFS=: read cmd grp
do
Andreas.
Signature · 3 lines
Andreas Schwab, [email protected] GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 "And now for something completely different."
Quoted 7 lines · Andreas Schwab
or:
sort |
while IFS=: read cmd grp
doAndreas.
I believe this is the most legible form, the intention is much clearer.
Sébastien
extract the $grp shell variable from command-list.txt (eg: 'common-3_worktree') and add this value to the output:
before/after:
{"add", N_("Add file contents to the index")} {"add", N_("Add file contents to the index"), "3_worktree"}
When 'git help' is called, the displayed commands can be grouped by theme instead of a less useful alphabetical order.
Signed-off by: Sébastien Guimmara <[email protected]>
--- generate-cmdlist.sh | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)
generate-cmdlist.sh +4 -3
@@ -4,19 +4,20 @@ echo "/* Automatically generated by $0 */ struct cmdname_help { char name[16]; char help[80]; + char group[20]; }; static struct cmdname_help common_cmds[] = {" -sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' command-list.txt | +sed -n -e 's/^git-\([^ ]*\)[ ].* common-\(.*\)/\1:\2/p' command-list.txt | sort | -while read cmd +while IFS=: read cmd grp do sed -n ' /^NAME/,/git-'"$cmd"'/H ${ x - s/.*git-'"$cmd"' - \(.*\)/ {"'"$cmd"'", N_("\1")},/ + s/.*git-'"$cmd"' - \(.*\)/ {"'"$cmd"'", N_("\1"), "'"$grp"'"},/ p }' "Documentation/git-$cmd.txt" done
Signature · 1 line
2.4.0
PATCH v2 3/3 git help: group common commands by theme
In reply to Sébastien Guimmarahelp.c - group common commands by theme
Use qsort to sort the common_cmds array by group name, then print those common commands, skipping a line between each group.
--- help.c | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+)
help.c +21 -0
@@ -218,17 +218,38 @@ void list_commands(unsigned int colopts, } } +/* sort the command name struct by group name */ +int cmd_group_cmp (const void *elem1,const void *elem2) +{ +struct cmdname_help *cmd1 = (struct cmdname_help *) elem1; +struct cmdname_help *cmd2 = (struct cmdname_help *) elem2; + +return strcmp (cmd1->group, cmd2->group); +} +void list_common_cmds_help (void ) {int i, longest =0 ; +char *current_grp =NULL ;for (i =0 ; i <ARRAY_SIZE (common_cmds); i++) {if (longest <strlen (common_cmds[i].name)) longest =strlen (common_cmds[i].name); } +/* sort common commands by group (i.e, beginner's relevance) */ +qsort (common_cmds,ARRAY_SIZE (common_cmds), +sizeof (struct cmdname_help ), cmd_group_cmp); +puts (_ ("The most commonly used git commands are:" ));for (i =0 ; i <ARRAY_SIZE (common_cmds); i++) { + +/* skip a line each time we encounter a new command group */ +if (current_grp !=NULL &&strcmp (common_cmds[i].group, current_grp)) +printf ("\n" ); + + 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));
Signature · 1 line
2.4.0
v3 cover git help: group common commands by themes
In reply to Sébastien GuimmaraGroup the common commands printed by 'git help' (or 'git' without any options) into beginner friendly themes. To achieve this, the file command-list.txt receives an additional information for all 'common' commands, in the form of an indexed group suffix.
Group suffixes are in the form: 'x_group', where x is a number used to order (ascending) commands in the displayed help:
[...]
git-add mainporcelain common-3_worktree git-bisect mainporcelain common-7_search git-branch mainporcelain common-6_branching git-checkout mainporcelain common-6_branching
[...]
Note: the proposed layout comprises:
1_init
2_info
3_worktree
4_remote
5_history
6_branching
7_search
They can be easily modified by just changing command-list.txt
command-list.txt is then parsed by generate-cmdlist.sh to generate common-cmds.h with the additional group name being a 'group' field in the cmdname_help struct:
[...]
{"add", N_("Add file contents to the index"), "3_worktree"}, {"bisect", N_("Find by binary search the change that introduced a
bug"), "7_search"},
{"branch", N_("List, create, or delete branches"), "6_branching"}, {"checkout", N_("Checkout a branch or paths to the working tree"),
"6_branching"},
[...]
Finally, list_common_cmds_help() prints those common commands by groups, skipping a line between each group:
[...]
The most commonly used git commands are:
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize an
existing one
log Show commit logs
show Show various types of objects
status Show the working tree status add Add file contents to the index
mv Move or rename a file, a directory, or a symlink
reset Reset current HEAD to the specified state
rm Remove files from the working tree and from the index fetch Download objects and refs from another repository
pull Fetch from and integrate with another repository or a
local branch
push Update remote refs along with associated objects
commit Record changes to the repository
diff Show changes between commits, commit and working tree, etc
rebase Forward-port local commits to the updated upstream head
tag Create, list, delete or verify a tag object signed with GPG
[...]
The documentation api-builtin.txt is updated to reflect the change.
PATCH v3 1/4 command-list.txt: group common commands by themes
Add a group identifier in the form {x}_{name}, where {x} is a digit identifying the group, and {name} the group name. The digit is used to sort the common commands by groups instead of the less useful alphabetical order.
before the patch:
git-add mainporcelain common
after:
git-add mainporcelain common-3_worktree
--- command-list.txt | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-)
command-list.txt +21 -21
@@ -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
Signature · 1 line
2.4.0
PATCH v3 2/4 generate-cmdlist.sh: parse common command groups
In reply to Sébastien GuimmaraTeach generate-cmdlist.sh to parse common command groups found in command-list.txt in the form
common-3_worktree ('3_worktree' being the group identifier)
Extract the $grp variable, in addition to the previous $cmd, and inject it as a third field in the cmdname_help struct:
{"add", N_("Add file contents to the index"), "3_worktree"},
So that when 'git' is called, we can display common commands grouped by theme instead of a less useful alphabetical order.
Reviewed by: Luke Diamand <[email protected]> Reviewed by: Andreas Schwab <[email protected]>
--- generate-cmdlist.sh | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)
generate-cmdlist.sh +4 -3
@@ -4,19 +4,20 @@ echo "/* Automatically generated by $0 */ struct cmdname_help { char name[16]; char help[80]; + char group[20]; }; static struct cmdname_help common_cmds[] = {" -sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' command-list.txt | +sed -n -e 's/^git-\([^ ]*\)[ ].* common-\(.*\)/\1:\2/p' command-list.txt | sort | -while read cmd +while IFS=: read cmd grp do sed -n ' /^NAME/,/git-'"$cmd"'/H ${ x - s/.*git-'"$cmd"' - \(.*\)/ {"'"$cmd"'", N_("\1")},/ + s/.*git-'"$cmd"' - \(.*\)/ {"'"$cmd"'", N_("\1"), "'"$grp"'"},/ p }' "Documentation/git-$cmd.txt" done
Signature · 1 line
2.4.0
Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups
Quoted 20 lines · Sébastien Guimmara
Teach
generate-cmdlist.shto parse common command groups found in command-list.txt in the formcommon-3_worktree ('3_worktree' being the group identifier)
Extract the $grp variable, in addition to the previous $cmd, and inject it as a third field in the
cmdname_helpstruct:{"add",
N_("Add file contents to the index"), "3_worktree"},So that when 'git' is called, we can display common commands grouped by theme instead of a less useful alphabetical order.
Signed-off-by Sébastien Guimmara <[email protected]>---
generate-cmdlist.sh +0
-0
generate-cmdlist.sh echo "/* Automatically generated by $0 */ · line 11
Quoted 8 lines
generate-cmdlist.sh +2
-0@@ -4,19 +4,20 @@ echo "/* Automatically generated by $0 */ struct cmdname_help { char name[16]; char help[80]; + char group[20]; }; static struct cmdname_help common_cmds[] = {" -sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' [...] +sed -n -e 's/^git-\([^ ]*\)[ ].* common-\(.*\)/\1:\2/p' [...]
Isn't \(.*\) a bit too loose for grabbing $grp? What if someone some day adds another column to express some other sort of attribute? (Or, if someone perhaps uses the "deprecated" attribute but places it in column 3 rather than 2 as documented.) It probably would be better to tighten this up by grabbing only non-whitespace characters, as is already done for $cmd.
(In fact, this sed invocation is already broken for "deprecated", isn't it? According to the command-list.txt header comments, "deprecated" should be placed before "common", yet the sed invocation expects "common" to follow the command immediately. Perhaps a preparatory patch could fix this issue; or just do away with "deprecated" entirely since it's not used.)
generate-cmdlist.sh echo "/* Automatically generated by $0 */ · line 14
Quoted 3 lines
generate-cmdlist.sh +1
-1sort | -while read cmd +while IFS=: read cmd grp
Since both $cmd and $grp are simple tokens, neither of which contain whitespace, this could be handled more simply by just having sed emit them separated by a space rather than by ':'; in which case your 'while read' loop wouldn't need to muck with IFS at all.
Quoted 12 lines
generate-cmdlist.sh +1
-2do sed -n ' /^NAME/,/git-'"$cmd"'/H ${ x - s/.*git-'"$cmd"' - \(.*\)/ {"'"$cmd"'", N_("\1")},/ + s/.*git-'"$cmd"' - \(.*\)/ {"'"$cmd"'", N_("\1"), "'"$grp"'"},/ p }' "Documentation/git-$cmd.txt" done --2.4.0
Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups
Quoted 20 lines · Eric Sunshine
generate-cmdlist.sh echo "/* Automatically generated by $0 */ · line 7
Quoted 10 lines · Sébastien Guimmara
---
generate-cmdlist.sh +1
-0@@ -4,19 +4,20 @@ echo "/* Automatically generated by $0 */ }; static struct cmdname_help common_cmds[] = {" -sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' [...] +sed -n -e 's/^git-\([^ ]*\)[ ].* common-\(.*\)/\1:\2/p' [...]Isn't \(.*\) a bit too loose for grabbing $grp? What if someone some day adds another column to express some other sort of attribute? (Or, if someone perhaps uses the "deprecated" attribute but places it in column 3 rather than 2 as documented.) It probably would be better to tighten this up by grabbing only non-whitespace characters, as is already done for $cmd.
Quoted 6 lines
(In fact, this sed invocation is already broken for "deprecated", isn't it? According to the command-list.txt header comments, "deprecated" should be placed before "common", yet the sed invocation expects "common" to follow the command immediately. Perhaps a preparatory patch could fix this issue; or just do away with "deprecated" entirely since it's not used.)
Ah, I misread the original sed invocation slightly. It's not broken, so scratch the second paragraph.
(Though, it does expect at least one whitespace character and then one space before "common", which is a bit odd, but not a problem with the current content of command-list.txt.)
Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups
In reply to Sébastien GuimmaraQuoted 8 lines · Sébastien Guimmara
Teach
generate-cmdlist.shto parse common command groups found in command-list.txt in the formcommon-3_worktree ('3_worktree' being the group identifier)
Extract the $grp variable, in addition to the previous $cmd, and inject it as a third field in the
cmdname_helpstruct:
Quoted 7 lines
{"add",
N_("Add file contents to the index"), "3_worktree"},So that when 'git' is called, we can display common commands grouped by theme instead of a less useful alphabetical order.
Reviewed by: Luke Diamand <[email protected]> Reviewed by: Andreas Schwab <[email protected]>
These people may have helped you to polish your earlier round to come up with this version, but I do not think they should be listed as reviewed-by (in the sense that they would say "Yes, I read this version and consider it very good--I endorse the change!") yet.
Quoted 11 lines
Signed-off-by Sébastien Guimmara <[email protected]>---
generate-cmdlist.sh | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)generate-cmdlist.sh +0
-0
generate-cmdlist.sh echo "/* Automatically generated by $0 */ · line 7
Quoted 4 lines
generate-cmdlist.sh +1
-0@@ -4,19 +4,20 @@ echo "/* Automatically generated by $0 */ struct cmdname_help { char name[16]; char help[80]; + char group[20];
Storing group name in duplicated text for all commands and then using string comparison at runtime is grossly wasteful, don't you think, especially when the list is not manually maintained?
command-list.txt is something manually maintained, i.e. the source, and it makes sense to use easy-to-see strings like "3_worktree" label there instead of cryptic number, but the whole point of this script is to pre-process that text into .c file to a form that is more suited for machine consumption. I think this script should:
- read command list once to make the list of groups in a new separate array;
- add the group as an "unsigned char group_number" (as we won't have more than 200 groups) field to this struct;
- read command list again and for each command give the group number here.
or something like that.
Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups
Quoted 15 lines · Junio C Hamano
Quoted 13 lines · Sébastien Guimmara
Teach
generate-cmdlist.shto parse common command groups found in command-list.txt in the formcommon-3_worktree ('3_worktree' being the group identifier)
Extract the $grp variable, in addition to the previous $cmd, and inject it as a third field in the
cmdname_helpstruct:{"add",
N_("Add file contents to the index"), "3_worktree"},So that when 'git' is called, we can display common commands grouped by theme instead of a less useful alphabetical order.
Quoted 7 lines
Quoted 2 lines
Reviewed by: Luke Diamand <[email protected]> Reviewed by: Andreas Schwab <[email protected]>
These people may have helped you to polish your earlier round to come up with this version, but I do not think they should be listed as reviewed-by (in the sense that they would say "Yes, I read this version and consider it very good--I endorse the change!") yet.
Minor addendum: If you'd like to acknowledge Luke for $(...) and Andreas for IFS munging, then Helped-by: would be appropriate (and doesn't require their consent).
More below.
Quoted 25 lines
generate-cmdlist.sh echo "/* Automatically generated by $0 */ · line 7
Quoted 11 lines
Signed-off-by Sébastien Guimmara <[email protected]>---
generate-cmdlist.sh +1
-0@@ -4,19 +4,20 @@ echo "/* Automatically generated by $0 */ struct cmdname_help { char name[16]; char help[80]; + char group[20];Storing group name in duplicated text for all commands and then using string comparison at runtime is grossly wasteful, don't you think, especially when the list is not manually maintained?
command-list.txt is something manually maintained, i.e. the source, and it makes sense to use easy-to-see strings like "3_worktree" label there instead of cryptic number, but the whole point of this script is to pre-process that text into .c file to a form that is more suited for machine consumption. I think this script should:
- read command list once to make the list of groups in a new separate array;
Quoted 7 lines
- add the group as an "unsigned char
group_number" (as we won't have more than 200 groups) field to this struct;- read command list again and for each command give the group number here.
or something like that.
Some additional observations:
The "common-N_group" form seems both redundant and unsightly. Redundant because you could just as easily pluck out 'common' lines by searching for "N_group", thus making the "common-" prefix unnecessary. Unsightly because the mix of "-" and "_" is hard to read. (In general, "-" is easier to read, thus probably a better choice.)
Thinking out loud, without regard to implementation complexity...
I might expect to see the table of groups to be declared first, in the order that they should be displayed by "git help". Having the groups in their own table also allows you to give them human-readable descriptions. For actual use, you'd tag each command with the bare group name.
So, something like this, perhaps:
[groups]
init starting a working area
info examining history and state
...
branching branching and merging histories
[commands]
git-branch mainporcelain branching
...
git-clone mainporcelain init
...
This way, the 'N' in "N_group" is unnecessary since presentation order is implied by the [groups] table, and you don't need the "common-" prefix anymore since any command having an attribute from the [groups] table is automatically considered common.
Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups
Quoted 8 lines · Eric Sunshine
Quoted 4 lines
These people may have helped you to polish your earlier round to come up with this version, but I do not think they should be listed as reviewed-by (in the sense that they would say "Yes, I read this version and consider it very good--I endorse the change!") yet.
Minor addendum: If you'd like to acknowledge Luke for $(...) and Andreas for IFS munging, then Helped-by: would be appropriate (and doesn't require their consent).
Thanks for the precision, I got confused with this one.
Quoted 14 lines
So, something like this, perhaps:
[groups]
init starting a working area
info examining history and state
...
branching branching and merging histories[commands]
git-branch mainporcelain branching
...
git-clone mainporcelain init
...
Quoted 5 lines
This way, the 'N' in "
N_group" is unnecessary since presentation order is implied by the [groups] table, and you don't need the "common-" prefix anymore since any command having an attribute from the [groups] table is automatically considered common.
It's a good idea. I'll look into it.
Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups
Quoted 11 lines · Sébastien Guimmara
Quoted 8 lines · Eric Sunshine
Quoted 4 lines
These people may have helped you to polish your earlier round to come up with this version, but I do not think they should be listed as reviewed-by (in the sense that they would say "Yes, I read this version and consider it very good--I endorse the change!") yet.
Minor addendum: If you'd like to acknowledge Luke for $(...) and Andreas for IFS munging, then Helped-by: would be appropriate (and doesn't require their consent).
Thanks for the precision, I got confused with this one.
What Junio meant was that Reviewed-by: is something that reviewers "give" explicitly when they are confident that they understand and believe your patches are correct. You may incorporate a "given"
Reviewed-by: into a patch when re-rolling if the patch hasn't changed since the previous round (or has changed in very minor ways which don't affect the Reviewed-by:). Someone merely reading your patch and commenting on it (and possibly making suggestions) does not warrant a
Reviewed-by: since comments and suggestions alone don't necessarily mean that they agree that a patch is acceptable or correct, thus don't add Reviewed-by: without it being "given".
Helped-by: is for acknowledging someone's assistance.
More below.
Quoted 14 lines
Quoted 14 lines
So, something like this, perhaps:
[groups]
init starting a working area
info examining history and state
...
branching branching and merging histories[commands]
git-branch mainporcelain branching
...
git-clone mainporcelain init
...
Quoted 6 lines
Quoted 4 lines
This way, the 'N' in "
N_group" is unnecessary since presentation order is implied by the [groups] table, and you don't need the "common-" prefix anymore since any command having an attribute from the [groups] table is automatically considered common.It's a good idea. I'll look into it.
'awk' might be helpful to implement this sort of scheme, as well as Junio's suggestion of emitting only a group number in the generated table rather than a string. If so, try to stick to POSIX (and avoid GNU or other extensions).
PATCH v3 3/4 help.c - group common commands by theme
In reply to Sébastien GuimmaraWhen 'git help' is called, a list of common commands are printed:
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
[...]
Instead of a less than optimal alphabetical order, print those commands in theme-related groups:
The most commonly used git commands are:
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize an existing one
log Show commit logs show Show various types of objects status Show the working tree status
add Add file contents to the index mv Move or rename a file, a directory, or a symlink reset Reset current HEAD to the specified state rm Remove files from the working tree and from the index
[...]
To achieve this, qsort the common_cmds array by group name, then print those common commands, skipping a line between each group.
--- help.c | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+)
help.c +21 -0
@@ -218,17 +218,38 @@ void list_commands(unsigned int colopts, } } +/* sort the command name struct by group name */ +int cmd_group_cmp (const void *elem1,const void *elem2) +{ +struct cmdname_help *cmd1 = (struct cmdname_help *) elem1; +struct cmdname_help *cmd2 = (struct cmdname_help *) elem2; + +return strcmp (cmd1->group, cmd2->group); +} +void list_common_cmds_help (void ) {int i, longest =0 ; +char *current_grp =NULL ;for (i =0 ; i <ARRAY_SIZE (common_cmds); i++) {if (longest <strlen (common_cmds[i].name)) longest =strlen (common_cmds[i].name); } +/* sort common commands by group (i.e, beginner's relevance) */ +qsort (common_cmds,ARRAY_SIZE (common_cmds), +sizeof (struct cmdname_help ), cmd_group_cmp); +puts (_ ("The most commonly used git commands are:" ));for (i =0 ; i <ARRAY_SIZE (common_cmds); i++) { + +/* skip a line each time we encounter a new command group */ +if (current_grp !=NULL &&strcmp (common_cmds[i].group, current_grp)) +printf ("\n" ); + + 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));
Signature · 1 line
2.4.0
Re: [PATCH v3 3/4] help.c - group common commands by theme
Quoted 22 lines · Sébastien Guimmara
When 'git help' is called, a list of common commands are printed:
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[...]
Instead of a less than optimal alphabetical order, print those commands in theme-related groups:
The most commonly used git commands are:
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize an existing onelog Show commit logs show Show various types of objects status Show the working tree status
Quoted 8 lines
add Add file contents to the index mv Move or rename a file, a directory, or a symlink reset Reset current HEAD to the specified state rm Remove files from the working tree and from the index[...]
To achieve this, qsort the
common_cmdsarray by group name, then print those common commands, skipping a line between each group.
Just a minor observation regarding the final paragraph (feel free to ignore):
This level of detail is probably overkill. The overall intent of the change has already been spelled out nicely via the examples, so mentioning qsort() is unnecessary since it's a mere implementation detail; one which a reader can easily discover by reading the patch proper. Likewise, the example "new output" already shows clearly the blank line between groups, so there is no need to mention it in prose.
If I was composing the commit message, I'd probably drop the final paragraph altogether and rephrase something like this:
'git help' shows common commands in alphabetical order like this:
<current output>
without any indication of how commands relate to high-level concepts or each other. Revise the output to group commands by concept, like this:
<revised output>
More below.
Quoted 7 lines
Signed-off-by Sébastien Guimmara <[email protected]>---
help.c +0
-0
help.c void list_commands(unsigned int colopts, · line 224
Quoted 7 lines
help.c +4
-0@@ -218,17 +218,38 @@ void list_commands(unsigned int colopts, } } +/* sort the command name struct by group name */ +int cmd_group_cmp(const void *elem1, const void *elem2) +{ + struct cmdname_help *cmd1 = (struct cmdname_help*) elem1; +struct cmdname_help *cmd2 = (struct cmdname_help *) elem2;
As this is C rather than C++, you can drop the cast.
Also, if you were to keep the cast, the prevailing style in git code is to insert a space before the '*' and to drop the space after the ')'.
Quoted 4 lines
help.c +3
-0+return strcmp (cmd1->group, cmd2->group); +} +void list_common_cmds_help (void )
help.c void list_commands(unsigned int colopts, · line 242
Quoted 10 lines
help.c +3
-0{int i, longest =0 ; +char *current_grp =NULL ;for (i =0 ; i <ARRAY_SIZE (common_cmds); i++) {if (longest <strlen (common_cmds[i].name)) longest =strlen (common_cmds[i].name); } +/* sort common commands by group (i.e, beginner's relevance) */ +qsort (common_cmds,ARRAY_SIZE (common_cmds), +sizeof (struct cmdname_help ), cmd_group_cmp);
Slightly more maintenance free would be sizeof(common_cmds[0]) instead of sizeof(struct cmdname_help).
help.c void list_commands(unsigned int colopts, · line 246
Quoted 3 lines
help.c +1
-0puts (_ ("The most commonly used git commands are:" ));for (i =0 ; i <ARRAY_SIZE (common_cmds); i++) { +
Style: Drop this blank line.
help.c void list_commands(unsigned int colopts, · line 249
Quoted 4 lines
help.c +3
-0+/* skip a line each time we encounter a new command group */ +if (current_grp !=NULL &&strcmp (common_cmds[i].group, current_grp)) +printf ("\n" );
This chunk of code is pretty well self-explanatory, so the comment isn't really adding anything. A comment which merely repeat what the code itself already says is typically considered distracting rather than illuminating, thus it could (and probably should) be dropped. The same observation probably applies to the comment preceding the qsort() invocation, as well.
Finally, elsewhere in this source file, a blank line is emitted with the more idiomatic putchar('\n') rather than printf("\n").
Quoted 8 lines
help.c +3
-1+ + 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
PATCH v3 4/4 api-builtin.txt: explain common command groups
In reply to Sébastien GuimmaraUpdate api-builtin.txt to explain how to add the group information for common commands.
--- Documentation/technical/api-builtin.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-)
Documentation/technical/api-builtin.txt +5 -1
@@ -50,7 +50,11 @@ Additionally, if `foo` is a new command, there are 3 more things to do: . Write documentation in `Documentation/git-foo.txt`. -. Add an entry for `git-foo` to `command-list.txt`. +. Add an entry for `git-foo` to `command-list.txt`. If foo is considered + a 'common' command, add 'common-x_group' as the third value, + where x_group is one of the existing themes: + + git-foo mainporcelain common-3_worktree . Add an entry for `/git-foo` to `.gitignore`.
Signature · 1 line
2.4.0
Re: [PATCH v3 4/4] api-builtin.txt: explain common command groups
Quoted 15 lines · Sébastien Guimmara
Update api-builtin.txt to explain how to add the group information for common commands.
Signed-off-by Sébastien Guimmara <[email protected]>---
Documentation/technical/api-builtin.txt +0
-0@@ -50,7 +50,11 @@ Additionally, if `foo` is a new command, there are 3 morethings to do:
. Write documentation inDocumentation/git-foo.txt.
-. Add an entry forgit-footocommand-list.txt.
+. Add an entry forgit-footocommand-list.txt. If foo is considered
Documentation/technical/api-builtin.txt Additionally, if `foo` is a new command, there are 3 more things to do: · line 59
Quoted 5 lines
Documentation/technical/api-builtin.txt +4
-0+ a 'common' command, add 'common-x_group' as the third value, + where x_group is one of the existing themes: + + git-foo mainporcelain common-3_worktree . Add an entry for `/git-foo` to `.gitignore`.
Unfortunately, this change breaks Asciidoc formatting by making the following ".Add an entry..." item get glued to the new "git-foo..." example. Fix by inserting a blank line after the "git-foo...". (And try formatting it yourself to ensure that it is working as expected.)
Finally, all of your patches are whitespace-damaged and fail to apply to the code-base. Did you paste them into your email client or some such? If possible, try to send patches via git-send-email since it does a good job of protecting against whitespace and other types of damage.
Re: [PATCH v3 4/4] api-builtin.txt: explain common command groups
Quoted 19 lines · Eric Sunshine
Quoted 17 lines · Sébastien Guimmara
Update api-builtin.txt to explain how to add the group information for common commands.
Signed-off-by Sébastien Guimmara <[email protected]>---
Documentation/technical/api-builtin.txt +0
-0@@ -50,7 +50,11 @@ Additionally, if `foo` is a new command, there are 3 morethings to do:
. Write documentation inDocumentation/git-foo.txt.
-. Add an entry forgit-footocommand-list.txt.
+. Add an entry forgit-footocommand-list.txt. If foo is consideredDocumentation/technical/api-builtin.txt +2
-0+ a 'common' command, add 'common-x_group' as the third value, + where x_group is one of the existing themes:
Quoted 9 lines
Documentation/technical/api-builtin.txt Additionally, if `foo` is a new command, there are 3 more things to do: · line 59
Quoted 3 lines
Documentation/technical/api-builtin.txt +2
-0+ + git-foo mainporcelain common-3_worktree . Add an entry for `/git-foo` to `.gitignore`.Unfortunately, this change breaks Asciidoc formatting by making the following ".Add an entry..." item get glued to the new "git-foo..." example. Fix by inserting a blank line after the "git-foo...". (And try formatting it yourself to ensure that it is working as expected.)
I'll look into that.
Quoted 6 lines
Finally, all of your patches are whitespace-damaged and fail to apply to the code-base. Did you paste them into your email client or some such? If possible, try to send patches via git-send-email since it does a good job of protecting against whitespace and other types of damage.
I'm having a hard time configuring send-email through gmail, so those patches were indeed pasted into plain text. I'll look into making send-email work.
Thank you for the help,
Sébastien
A message that is not in the archive (sent off-list or not yet received): CAHYJk3S3s4RjFMUaomP2wUVBbcTLRGYrAOa-uDjrfsKqUuWPog@mail.gmail.com
Re: [PATCH v3 4/4] api-builtin.txt: explain common command groups
Quoted 8 lines · Mikael Magnusson
[sendemail]
smtpencryption = tls
smtpserver = smtp.gmail.com
smtpuser = [email protected]
smtpserverport = 587
assume8bitEncoding = UTF-8Should be all that's needed. (in ~/.gitconfig)
Thanks a lot, I was also missing packages. Now it works fine.
Re: [PATCH v3 4/4] api-builtin.txt: explain common command groups
In reply to Sébastien GuimmaraQuoted 10 lines · Sébastien Guimmara
Quoted 5 lines · Eric Sunshine
Finally, all of your patches are whitespace-damaged and fail to apply to the code-base. Did you paste them into your email client or some such? If possible, try to send patches via git-send-email since it does a good job of protecting against whitespace and other types of damage.
I'm having a hard time configuring send-email through gmail, so those patches were indeed pasted into plain text. I'll look into making send-email work.
The Gmail example in the "git send-email" manual should be sufficient. However, perhaps other prerequisites are unmet in your case? (For instance, I had to manually install the Perl Net::SMTP::SSL module on my machine to get git-send-email working.)
Quoted 18 lines · Sébastien Guimmara
Finally,
list_common_cmds_help()prints those common commands by groups, skipping a line between each group:[...]
The most commonly used git commands are:
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize an existing onelog Show commit logs show Show various types of objects status Show the working tree statusadd Add file contents to the index mv Move or rename a file, a directory, or a symlink reset Reset current HEAD to the specified state rm Remove files from the working tree and from the index
Quoted 8 lines
fetch Download objects and refs from another repository pull Fetch from and integrate with another repository or a local branch push Update remote refs along with associated objectscommit Record changes to the repository diff Show changes between commits, commit and working tree, etc rebase Forward-port local commits to the updated upstream head tag Create, list, delete or verify a tag object signed with GPG
What is the target audience? Are they expected to be familiar enough with Git that they can guess what the above grouping is based on without a group header?
I consider myself experienced enough with Git but cannot explain or justify the placement of "diff" in the above list myself, for example. I'd say
* starting a working area (clone, init)
* examining the history and state (log, show, status, diff)
* working on the current change (add, checkout, reset)
* growing, marking and tweaking your history (commit, tag, rebase)
* working with others (fetch, pull, push)
might be a more sensible presentation order (and classification).
Quoted 3 lines · Junio C Hamano
What is the target audience? Are they expected to be familiar enough with Git that they can guess what the above grouping is based on without a group header?
Since this help is not only displayed on '$ git help' but also on '$ git', we can assume it's directed at people not familiar with git and/or the command line usage.
We could then display headers this way:
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
* examining the history and state:
diff Show changes between commits, commit and working tree, etc
log Show commit logs
show Show various types of objects
status Show the working tree status
bisect Find by binary search the change that introduced a bug
grep Print lines matching a pattern* working on the current change:
add Add file contents to the index
checkout Checkout a branch or paths to the working tree
reset Reset current HEAD to the specified state
rm Remove files from the working tree and from the index
mv Move or rename a file, a directory, or a symlink* growing, marking and tweaking your history:
commit Record changes to the repository
rebase Forward-port local commits to the updated upstream head
tag Create, list, delete or verify a tag object signed with GPG* working with others:
fetch Download objects and refs from another repository
pull Fetch from and integrate with another repository or a local branch
push Update remote refs along with associated objects * branching and merging histories:
branch List, create, or delete branches
merge Join two or more development histories together
This raises a few questions:
1. Is 'bisect' really a common command (from the target audience standpoint)
2. Does 'Forward-port local commits to the updated upstream head' really help to grok the idea of 'rebase' ? There are 3 words in this sentence that an unfamiliar git user may not be comfortable with : 'forward-port', 'upstream' and 'head'. I'm not familiar enough with 'rebase' to think of a clearer explanation, but what about:
'Rewrite the history of a branch with commits from another branch'
The formatting in the previous email was a bit off. Here is the proper one.
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
* examining the history and state:
diff Show changes between commits, commit and working tree, etc
log Show commit logs
show Show various types of objects
status Show the working tree status
bisect Find by binary search the change that introduced a bug
grep Print lines matching a pattern* working on the current change:
add Add file contents to the index
checkout Checkout a branch or paths to the working tree
reset Reset current HEAD to the specified state
rm Remove files from the working tree and from the index
mv Move or rename a file, a directory, or a symlink* growing, marking and tweaking your history:
commit Record changes to the repository
rebase Forward-port local commits to the updated upstream head
tag Create, list, delete or verify a tag object signed with GPG* working with others:
fetch Download objects and refs from another repository
pull Fetch from and integrate with another repository or a local branch
push Update remote refs along with associated objects * branching and merging histories:
branch List, create, or delete branches
merge Join two or more development histories together
Quoted 32 lines · Sébastien Guimmara
We could then display headers this way:
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
* examining the history and state:
diff Show changes between commits, commit and working tree, etc
log Show commit logs
show Show various types of objects
status Show the working tree status
bisect Find by binary search the change that introduced a bug
grep Print lines matching a pattern* working on the current change:
add Add file contents to the index checkout Checkout a branch or paths to the working tree reset Reset current HEAD to the specified state rm Remove files from the working tree and from the index mv Move or rename a file, a directory, or a symlink* growing, marking and tweaking your history:
commit Record changes to the repository
rebase Forward-port local commits to the updated upstream head
tag Create, list, delete or verify a tag object signed with GPG
* working with others:
fetch Download objects and refs from another repository
pull Fetch from and integrate with another repository or a local branch
push Update remote refs along with associated objects
* branching and merging histories:
branch List, create, or delete branches
merge Join two or more development histories together
Quoted 3 lines
This raises a few questions:
1. Is 'bisect' really a common command (from the target audience standpoint)
That is a good question, but so are many other commands.
I think that (1) it is a good idea to list commands in groups, (2) having group-head is necessary if we list commands in groups, but
(3) because group-heads consume valuable vertical space in the output, we may have to have fewer commands in the list.
For example, "mv" and "rm" are very questionable things to have in the "most commonly used" list. All you need to start with Git is "add" and "commit -a".
"clone" and "init" are "once per working area for a project you deal with" kind of thing, and cannot be in the "commonly used and you benefit from a gentle nudge to read about it more in the manual to learn Git" category by definition.
"rebase" should be with "merge" and "branch", but I wouldn't have "branching and merging" as a separate category---they are all part of "growing and tweaking". And "branch" itself may be questionable for those who are starting with Git.
Do we care about the ordering of the items within groups, by the way?
Quoted 3 lines
2. Does 'Forward-port local commits to the updated upstream head' really help to grok the idea of 'rebase' ? There are 3 words in this sentence that an unfamiliar git user may not be comfortable with...
"Rebuild the history on a branch on top of a new commit", perhaps?
But this brings us back to "what the target audience?" question.
My answer to the question has always been "the list is a gentle nudge to guide the user to read about it more in the manual to learn." The sooner users are guided to graduate from the "not be comfortable" state, the more productive they will be.
For that to happen, we would need to (1) strongly suggest that the subcommand is what the user wants to use, and (2) carefully avoid giving an impression that the user learned everything there is to know in order to use the command effectively from that single line.
Of course, an argument can be made that the single-line should aim to teach everything there is to know in order to use the command effectively, but because I do not think that is feasible I would aim for the second best, which is why we want to keep the last two lines about "git help <command> for a specific subcommand".