* [PATCH 0/3] git help: group common commands by theme
@ 2015-05-01 14:51 Sébastien Guimmara
2015-05-01 15:04 ` [PATCH 1/2] " Sébastien Guimmara
2015-05-01 15:12 ` [PATCH 2/2] " Sébastien Guimmara
0 siblings, 2 replies; 20+ 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] 20+ messages in thread* Re: [PATCH 1/2] git help: group common commands by theme
2015-05-01 14:51 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara
@ 2015-05-01 15:04 ` Sébastien Guimmara
2015-05-01 15:12 ` [PATCH 2/2] " Sébastien Guimmara
1 sibling, 0 replies; 20+ messages in thread
From: Sébastien Guimmara @ 2015-05-01 15:04 UTC (permalink / raw)
To: git
(My mistake, the patch was in 3 parts, not 4)
Author: Sébastien Guimmara <sebastien.guimmara@gmail.com>
Date: Fri May 1 16:25:53 2015 +0200
generate-cmdlist.sh - Add command group information for common commands
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.
diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
index 9a4c9b9..818b2f3 100755
--- a/generate-cmdlist.sh
+++ b/generate-cmdlist.sh
@@ -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
On 05/01/2015 04:51 PM, Sébastien Guimmara wrote:
> 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] 20+ messages in thread* Re: [PATCH 2/2] git help: group common commands by theme
2015-05-01 14:51 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara
2015-05-01 15:04 ` [PATCH 1/2] " Sébastien Guimmara
@ 2015-05-01 15:12 ` Sébastien Guimmara
1 sibling, 0 replies; 20+ messages in thread
From: Sébastien Guimmara @ 2015-05-01 15:12 UTC (permalink / raw)
To: git
Author: Sébastien Guimmara <sebastien.guimmara@gmail.com>
Date: Fri May 1 16:35:41 2015 +0200
help.c - teach list_common_cmds_help() to group common commands by
theme
Until now, the output of list_common_cmds_help() was 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
[...]
This is a bit confusing for a beginner.
This patch changes the output this way:
[...]
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
[...]
diff --git a/help.c b/help.c
index 2072a87..2169a59 100644
--- a/help.c
+++ b/help.c
@@ -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));
Sébastien
On 05/01/2015 04:51 PM, Sébastien Guimmara wrote:
> 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] 20+ messages in thread
* [PATCH 0/3] git help: group common commands by theme
@ 2015-05-04 20:28 Sébastien Guimmara
2015-05-06 3:08 ` Eric Sunshine
` (3 more replies)
0 siblings, 4 replies; 20+ 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] 20+ messages in thread* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-04 20:28 [PATCH 0/3] " 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)
3 siblings, 1 reply; 20+ 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] 20+ messages in thread* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-06 3:08 ` Eric Sunshine
@ 2015-05-06 20:26 ` Sébastien Guimmara
2015-05-06 20:49 ` Eric Sunshine
0 siblings, 1 reply; 20+ 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] 20+ 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; 20+ 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] 20+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-04 20:28 [PATCH 0/3] " Sébastien Guimmara
2015-05-06 3:08 ` 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
3 siblings, 1 reply; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-04 20:28 [PATCH 0/3] " Sébastien Guimmara
2015-05-06 3:08 ` Eric Sunshine
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
3 siblings, 1 reply; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme
2015-05-04 20:28 [PATCH 0/3] " Sébastien Guimmara
` (2 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
3 siblings, 1 reply; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ messages in thread
end of thread, other threads:[~2015-05-08 20:08 UTC | newest]
Thread overview: 20+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2015-05-01 14:51 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara
2015-05-01 15:04 ` [PATCH 1/2] " Sébastien Guimmara
2015-05-01 15:12 ` [PATCH 2/2] " Sébastien Guimmara
-- strict thread matches above, loose matches on Subject: below --
2015-05-04 20:28 [PATCH 0/3] " Sébastien Guimmara
2015-05-06 3:08 ` 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
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).