* [PATCH v7 0/5] git help: group common commands by theme
@ 2015-05-15 18:34 Sébastien Guimmara
2015-05-15 18:35 ` [PATCH v7 1/5] command-list.txt: prepare with [commands] header Sébastien Guimmara
` (5 more replies)
0 siblings, 6 replies; 23+ messages in thread
From: Sébastien Guimmara @ 2015-05-15 18:34 UTC (permalink / raw)
To: git, gitster, sunshine; +Cc: Sébastien Guimmara
This v7 is very similar in content to the v5 [1], except minor formatting
adjustments in 'git help' output and recommendations from Eric.
rebased on 'next' (a2776d4)
The major change is in the patch series itself. Commits have been
reordered and adjusted so that each 'apply' doesn't break the build, and
preserve bisectability.
Summary: make 'git help' outputs a more usable and friendlier
list of commands, grouped by theme according to the typical Git workflow:
[...]
The typical Git workflow includes:
start a working area (see also: git help tutorial):
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize an existing one
work on the current change (see also: git help everyday):
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
[...]
Many thanks to Eric Sunshine for the detailed help and advice !
[1]: http://thread.gmane.org/gmane.comp.version-control.git/268701
Eric Sunshine (1):
generate-cmdlist: parse common group commands
Sébastien Guimmara (4):
command-list.txt: prepare with [commands] header
command-list.txt: add a [common] block
command-list.txt: drop the common tag
help.c: output the typical Git workflow
Documentation/cmd-list.perl | 4 +++
Documentation/howto/new-command.txt | 4 ++-
Makefile | 7 ++---
command-list.txt | 53 ++++++++++++++++++++++---------------
generate-cmdlist.awk | 39 +++++++++++++++++++++++++++
generate-cmdlist.sh | 23 ----------------
help.c | 24 ++++++++++++++++-
7 files changed, 105 insertions(+), 49 deletions(-)
create mode 100644 generate-cmdlist.awk
delete mode 100755 generate-cmdlist.sh
--
2.4.0
^ permalink raw reply [flat|nested] 23+ messages in thread
* [PATCH v7 1/5] command-list.txt: prepare with [commands] header
2015-05-15 18:34 [PATCH v7 0/5] git help: group common commands by theme Sébastien Guimmara
@ 2015-05-15 18:35 ` Sébastien Guimmara
2015-05-15 20:26 ` Junio C Hamano
` (2 more replies)
2015-05-15 18:35 ` [PATCH v7 2/5] command-list.txt: add a [common] block Sébastien Guimmara
` (4 subsequent siblings)
5 siblings, 3 replies; 23+ messages in thread
From: Sébastien Guimmara @ 2015-05-15 18:35 UTC (permalink / raw)
To: git, gitster, sunshine; +Cc: Sébastien Guimmara
Add a [commands] header before the actual command list, then make the
following files ignore this header in their parsing:
* cmd-list.perl
* Makefile (check-docks target)
Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
Documentation/cmd-list.perl | 4 ++++
Documentation/howto/new-command.txt | 4 +++-
Makefile | 3 ++-
command-list.txt | 1 +
4 files changed, 10 insertions(+), 2 deletions(-)
diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index 04f9977..06a5fd6 100755
--- a/Documentation/cmd-list.perl
+++ b/Documentation/cmd-list.perl
@@ -38,6 +38,10 @@ sub format_one {
}
}
+while (<>) {
+ last if /^\[commands\]/;
+}
+
my %cmds = ();
for (sort <>) {
next if /^#/;
diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt
index d7de5a3..6d772bd 100644
--- a/Documentation/howto/new-command.txt
+++ b/Documentation/howto/new-command.txt
@@ -95,7 +95,9 @@ your language, document it in the INSTALL file.
that categorizes commands by type, so they can be listed in appropriate
subsections in the documentation's summary command list. Add an entry
for yours. To understand the categories, look at git-commands.txt
-in the main directory.
+in the main directory. If the new command is part of the typical Git
+workflow and you believe it common enough to be mentioned in 'git help',
+map this command to a common group in the column [common].
7. Give the maintainer one paragraph to include in the RelNotes file
to describe the new feature; a good place to do so is in the cover
diff --git a/Makefile b/Makefile
index 25a453b..0cb2045 100644
--- a/Makefile
+++ b/Makefile
@@ -2454,7 +2454,7 @@ check-docs::
esac ; \
test -f "Documentation/$$v.txt" || \
echo "no doc: $$v"; \
- sed -e '/^#/d' command-list.txt | \
+ sed -e '1,/^\[commands\]/d' -e '/^#/d' <command-list.txt | \
grep -q "^$$v[ ]" || \
case "$$v" in \
git) ;; \
@@ -2463,6 +2463,7 @@ check-docs::
done; \
( \
sed -e '/^#/d' \
+ -e '1,/^\[commands\]/d' \
-e 's/[ ].*//' \
-e 's/^/listed /' command-list.txt; \
$(MAKE) -C Documentation print-man1 | \
diff --git a/command-list.txt b/command-list.txt
index 54d8d21..caed872 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,5 +1,6 @@
# List of known git commands.
# command name category [deprecated] [common]
+[commands]
git-add mainporcelain common
git-am mainporcelain
git-annotate ancillaryinterrogators
--
2.4.0
^ permalink raw reply related [flat|nested] 23+ messages in thread
* [PATCH v7 2/5] command-list.txt: add a [common] block
2015-05-15 18:34 [PATCH v7 0/5] git help: group common commands by theme Sébastien Guimmara
2015-05-15 18:35 ` [PATCH v7 1/5] command-list.txt: prepare with [commands] header Sébastien Guimmara
@ 2015-05-15 18:35 ` Sébastien Guimmara
2015-05-15 21:31 ` Eric Sunshine
2015-05-15 18:35 ` [PATCH v7 3/5] generate-cmdlist: parse common group commands Sébastien Guimmara
` (3 subsequent siblings)
5 siblings, 1 reply; 23+ messages in thread
From: Sébastien Guimmara @ 2015-05-15 18:35 UTC (permalink / raw)
To: git, gitster, sunshine; +Cc: Sébastien Guimmara
Add a [common] block at the beginning of command-list.txt:
[common]
init start a working area (see also: git help tutorial)
worktree work on the current change (see also:[...]
info examine the history and state (see also: git [...]
history grow, mark and tweak your history
remote collaborate (see also: git help workflows)
storing information about common commands group, then map each common
command to a group:
git-add mainporcelain common worktree
Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Emma Jane Hogbin Westby <emma.westby@gmail.com>
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
command-list.txt | 52 +++++++++++++++++++++++++++++++---------------------
1 file changed, 31 insertions(+), 21 deletions(-)
diff --git a/command-list.txt b/command-list.txt
index caed872..c00b0b6 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,30 +1,40 @@
+# common commands are grouped by themes
+# this order is the same that output by 'git help'
+# map each common command in the [commands] list to one of these groups.
+[common]
+init start a working area (see also: git help tutorial)
+worktree work on the current change (see also: git help everyday)
+info examine the history and state (see also: git help revisions)
+history grow, mark and tweak your common history
+remote collaborate (see also: git help workflows)
+
# List of known git commands.
# command name category [deprecated] [common]
[commands]
-git-add mainporcelain common
+git-add mainporcelain common worktree
git-am mainporcelain
git-annotate ancillaryinterrogators
git-apply plumbingmanipulators
git-archimport foreignscminterface
git-archive mainporcelain
-git-bisect mainporcelain common
+git-bisect mainporcelain common info
git-blame ancillaryinterrogators
-git-branch mainporcelain common
+git-branch mainporcelain common history
git-bundle mainporcelain
git-cat-file plumbinginterrogators
git-check-attr purehelpers
git-check-ignore purehelpers
git-check-mailmap purehelpers
-git-checkout mainporcelain common
+git-checkout mainporcelain common history
git-checkout-index plumbingmanipulators
git-check-ref-format purehelpers
git-cherry ancillaryinterrogators
git-cherry-pick mainporcelain
git-citool mainporcelain
git-clean mainporcelain
-git-clone mainporcelain common
+git-clone mainporcelain common init
git-column purehelpers
-git-commit mainporcelain common
+git-commit mainporcelain common history
git-commit-tree plumbingmanipulators
git-config ancillarymanipulators
git-count-objects ancillaryinterrogators
@@ -36,14 +46,14 @@ git-cvsimport foreignscminterface
git-cvsserver foreignscminterface
git-daemon synchingrepositories
git-describe mainporcelain
-git-diff mainporcelain common
+git-diff mainporcelain common history
git-diff-files plumbinginterrogators
git-diff-index plumbinginterrogators
git-diff-tree plumbinginterrogators
git-difftool ancillaryinterrogators
git-fast-export ancillarymanipulators
git-fast-import ancillarymanipulators
-git-fetch mainporcelain common
+git-fetch mainporcelain common remote
git-fetch-pack synchingrepositories
git-filter-branch ancillarymanipulators
git-fmt-merge-msg purehelpers
@@ -52,7 +62,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 info
git-gui mainporcelain
git-hash-object plumbingmanipulators
git-help ancillaryinterrogators
@@ -61,17 +71,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 init
git-instaweb ancillaryinterrogators
git-interpret-trailers purehelpers
gitk mainporcelain
-git-log mainporcelain common
+git-log mainporcelain common info
git-ls-files plumbinginterrogators
git-ls-remote plumbinginterrogators
git-ls-tree plumbinginterrogators
git-mailinfo purehelpers
git-mailsplit purehelpers
-git-merge mainporcelain common
+git-merge mainporcelain common history
git-merge-base plumbinginterrogators
git-merge-file plumbingmanipulators
git-merge-index plumbingmanipulators
@@ -80,7 +90,7 @@ git-mergetool ancillarymanipulators
git-merge-tree ancillaryinterrogators
git-mktag plumbingmanipulators
git-mktree plumbingmanipulators
-git-mv mainporcelain common
+git-mv mainporcelain common worktree
git-name-rev plumbinginterrogators
git-notes mainporcelain
git-p4 foreignscminterface
@@ -91,11 +101,11 @@ git-parse-remote synchelpers
git-patch-id purehelpers
git-prune ancillarymanipulators
git-prune-packed plumbingmanipulators
-git-pull mainporcelain common
-git-push mainporcelain common
+git-pull mainporcelain common remote
+git-push mainporcelain common remote
git-quiltimport foreignscminterface
git-read-tree plumbingmanipulators
-git-rebase mainporcelain common
+git-rebase mainporcelain common history
git-receive-pack synchelpers
git-reflog ancillarymanipulators
git-relink ancillarymanipulators
@@ -104,28 +114,28 @@ git-repack ancillarymanipulators
git-replace ancillarymanipulators
git-request-pull foreignscminterface
git-rerere ancillaryinterrogators
-git-reset mainporcelain common
+git-reset mainporcelain common worktree
git-revert mainporcelain
git-rev-list plumbinginterrogators
git-rev-parse ancillaryinterrogators
-git-rm mainporcelain common
+git-rm mainporcelain common worktree
git-send-email foreignscminterface
git-send-pack synchingrepositories
git-shell synchelpers
git-shortlog mainporcelain
-git-show mainporcelain common
+git-show mainporcelain common 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 info
git-stripspace purehelpers
git-submodule mainporcelain
git-svn foreignscminterface
git-symbolic-ref plumbingmanipulators
-git-tag mainporcelain common
+git-tag mainporcelain common history
git-unpack-file plumbinginterrogators
git-unpack-objects plumbingmanipulators
git-update-index plumbingmanipulators
--
2.4.0
^ permalink raw reply related [flat|nested] 23+ messages in thread
* [PATCH v7 3/5] generate-cmdlist: parse common group commands
2015-05-15 18:34 [PATCH v7 0/5] git help: group common commands by theme Sébastien Guimmara
2015-05-15 18:35 ` [PATCH v7 1/5] command-list.txt: prepare with [commands] header Sébastien Guimmara
2015-05-15 18:35 ` [PATCH v7 2/5] command-list.txt: add a [common] block Sébastien Guimmara
@ 2015-05-15 18:35 ` Sébastien Guimmara
2015-05-15 21:34 ` Eric Sunshine
2015-05-15 18:35 ` [PATCH v7 4/5] command-list.txt: drop the common tag Sébastien Guimmara
` (2 subsequent siblings)
5 siblings, 1 reply; 23+ messages in thread
From: Sébastien Guimmara @ 2015-05-15 18:35 UTC (permalink / raw)
To: git, gitster, sunshine; +Cc: Sébastien Guimmara
From: Eric Sunshine <sunshine@sunshineco.com>
Parse the [common] block to create the array of group descriptions:
static char *common_cmd_groups[] = {
N_("starting a working area"),
N_("working on the current change"),
N_("working with others"),
N_("examining the history and state"),
N_("growing, marking and tweaking your history"),
};
then map each element of common_cmds[] to a group via its index:
static struct cmdname_help common_cmds[] = {
{"add", N_("Add file contents to the index"), 1},
{"branch", N_("List, create, or delete branches"), 4},
{"checkout", N_("Checkout a branch or paths to the ..."), 4},
{"clone", N_("Clone a repository into a new directory"), 0},
{"commit", N_("Record changes to the repository"), 4},
...
};
so that 'git help' can print those commands grouped by theme.
Only commands tagged with an attribute from [common] are emitted to
common_cmds[].
[commit message by Sébastien Guimmara <sebastien.guimmara@gmail.com>]
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
Makefile | 4 ++--
generate-cmdlist.awk | 39 +++++++++++++++++++++++++++++++++++++++
generate-cmdlist.sh | 23 -----------------------
3 files changed, 41 insertions(+), 25 deletions(-)
create mode 100644 generate-cmdlist.awk
delete mode 100755 generate-cmdlist.sh
diff --git a/Makefile b/Makefile
index 0cb2045..fdf9318 100644
--- a/Makefile
+++ b/Makefile
@@ -1693,10 +1693,10 @@ $(BUILT_INS): git$X
ln -s $< $@ 2>/dev/null || \
cp $< $@
-common-cmds.h: ./generate-cmdlist.sh command-list.txt
+common-cmds.h: generate-cmdlist.awk command-list.txt
common-cmds.h: $(wildcard Documentation/git-*.txt)
- $(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@
+ $(QUIET_GEN)awk -f generate-cmdlist.awk command-list.txt > $@+ && mv $@+ $@
SCRIPT_DEFINES = $(SHELL_PATH_SQ):$(DIFF_SQ):$(GIT_VERSION):\
$(localedir_SQ):$(NO_CURL):$(USE_GETTEXT_SCHEME):$(SANE_TOOL_PATH_SQ):\
diff --git a/generate-cmdlist.awk b/generate-cmdlist.awk
new file mode 100644
index 0000000..b5cc789
--- /dev/null
+++ b/generate-cmdlist.awk
@@ -0,0 +1,39 @@
+BEGIN {
+ print "/* Automatically generated by generate-cmdlist.awk */\n"
+ print "struct cmdname_help {"
+ print "\tchar name[16];"
+ print "\tchar help[80];"
+ print "\tunsigned char group;"
+ print "};\n"
+ print "static char *common_cmd_groups[] = {"
+}
+/^#/ || /^[ ]*$/ { next }
+state == 2 {
+ for (i = 2; i <= NF; i++)
+ if (grp[$i]) {
+ f = "Documentation/"$1".txt"
+ while (getline s <f > 0)
+ if (match(s, $1" - ")) {
+ t = substr(s, length($1" - ") + 1)
+ break
+ }
+ close(f)
+ printf "\t{\"%s\", N_(\"%s\"), %s},\n",
+ substr($1, length("git-") + 1), t, grp[$i] - 1
+ break
+ }
+}
+/\[commands\]/ {
+ print "};\n\nstatic struct cmdname_help common_cmds[] = {"
+ state = 2
+}
+state == 1 {
+ grp[$1] = ++n
+ sub($1"[ ][ ]*", "")
+ printf "\tN_(\"%s\"),\n", $0
+ next
+}
+/\[common\]/ {
+ state = 1
+}
+END { print "};" }
diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
deleted file mode 100755
index 9a4c9b9..0000000
--- a/generate-cmdlist.sh
+++ /dev/null
@@ -1,23 +0,0 @@
-#!/bin/sh
-
-echo "/* Automatically generated by $0 */
-struct cmdname_help {
- char name[16];
- char help[80];
-};
-
-static struct cmdname_help common_cmds[] = {"
-
-sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' command-list.txt |
-sort |
-while read cmd
-do
- sed -n '
- /^NAME/,/git-'"$cmd"'/H
- ${
- x
- s/.*git-'"$cmd"' - \(.*\)/ {"'"$cmd"'", N_("\1")},/
- p
- }' "Documentation/git-$cmd.txt"
-done
-echo "};"
--
2.4.0
^ permalink raw reply related [flat|nested] 23+ messages in thread
* [PATCH v7 4/5] command-list.txt: drop the common tag
2015-05-15 18:34 [PATCH v7 0/5] git help: group common commands by theme Sébastien Guimmara
` (2 preceding siblings ...)
2015-05-15 18:35 ` [PATCH v7 3/5] generate-cmdlist: parse common group commands Sébastien Guimmara
@ 2015-05-15 18:35 ` Sébastien Guimmara
2015-05-15 21:41 ` Eric Sunshine
2015-05-15 18:35 ` [PATCH v7 5/5] help.c: output the typical Git workflow Sébastien Guimmara
2015-05-15 20:41 ` [PATCH v7 0/5] git help: group common commands by theme Eric Sunshine
5 siblings, 1 reply; 23+ messages in thread
From: Sébastien Guimmara @ 2015-05-15 18:35 UTC (permalink / raw)
To: git, gitster, sunshine; +Cc: Sébastien Guimmara
The parser generate-cmdlist.awk gathers all group information without
needing the common tag.
before:
git-add mainporcelain common worktree
after:
git-add mainporcelain worktree
Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
command-list.txt | 42 +++++++++++++++++++++---------------------
1 file changed, 21 insertions(+), 21 deletions(-)
diff --git a/command-list.txt b/command-list.txt
index c00b0b6..2203566 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -11,30 +11,30 @@ remote collaborate (see also: git help workflows)
# List of known git commands.
# command name category [deprecated] [common]
[commands]
-git-add mainporcelain common worktree
+git-add mainporcelain worktree
git-am mainporcelain
git-annotate ancillaryinterrogators
git-apply plumbingmanipulators
git-archimport foreignscminterface
git-archive mainporcelain
-git-bisect mainporcelain common info
+git-bisect mainporcelain info
git-blame ancillaryinterrogators
-git-branch mainporcelain common history
+git-branch mainporcelain history
git-bundle mainporcelain
git-cat-file plumbinginterrogators
git-check-attr purehelpers
git-check-ignore purehelpers
git-check-mailmap purehelpers
-git-checkout mainporcelain common history
+git-checkout mainporcelain history
git-checkout-index plumbingmanipulators
git-check-ref-format purehelpers
git-cherry ancillaryinterrogators
git-cherry-pick mainporcelain
git-citool mainporcelain
git-clean mainporcelain
-git-clone mainporcelain common init
+git-clone mainporcelain init
git-column purehelpers
-git-commit mainporcelain common history
+git-commit mainporcelain history
git-commit-tree plumbingmanipulators
git-config ancillarymanipulators
git-count-objects ancillaryinterrogators
@@ -46,14 +46,14 @@ git-cvsimport foreignscminterface
git-cvsserver foreignscminterface
git-daemon synchingrepositories
git-describe mainporcelain
-git-diff mainporcelain common history
+git-diff mainporcelain history
git-diff-files plumbinginterrogators
git-diff-index plumbinginterrogators
git-diff-tree plumbinginterrogators
git-difftool ancillaryinterrogators
git-fast-export ancillarymanipulators
git-fast-import ancillarymanipulators
-git-fetch mainporcelain common remote
+git-fetch mainporcelain remote
git-fetch-pack synchingrepositories
git-filter-branch ancillarymanipulators
git-fmt-merge-msg purehelpers
@@ -62,7 +62,7 @@ git-format-patch mainporcelain
git-fsck ancillaryinterrogators
git-gc mainporcelain
git-get-tar-commit-id ancillaryinterrogators
-git-grep mainporcelain common info
+git-grep mainporcelain info
git-gui mainporcelain
git-hash-object plumbingmanipulators
git-help ancillaryinterrogators
@@ -71,17 +71,17 @@ git-http-fetch synchelpers
git-http-push synchelpers
git-imap-send foreignscminterface
git-index-pack plumbingmanipulators
-git-init mainporcelain common init
+git-init mainporcelain init
git-instaweb ancillaryinterrogators
git-interpret-trailers purehelpers
gitk mainporcelain
-git-log mainporcelain common info
+git-log mainporcelain info
git-ls-files plumbinginterrogators
git-ls-remote plumbinginterrogators
git-ls-tree plumbinginterrogators
git-mailinfo purehelpers
git-mailsplit purehelpers
-git-merge mainporcelain common history
+git-merge mainporcelain history
git-merge-base plumbinginterrogators
git-merge-file plumbingmanipulators
git-merge-index plumbingmanipulators
@@ -90,7 +90,7 @@ git-mergetool ancillarymanipulators
git-merge-tree ancillaryinterrogators
git-mktag plumbingmanipulators
git-mktree plumbingmanipulators
-git-mv mainporcelain common worktree
+git-mv mainporcelain worktree
git-name-rev plumbinginterrogators
git-notes mainporcelain
git-p4 foreignscminterface
@@ -101,11 +101,11 @@ git-parse-remote synchelpers
git-patch-id purehelpers
git-prune ancillarymanipulators
git-prune-packed plumbingmanipulators
-git-pull mainporcelain common remote
-git-push mainporcelain common remote
+git-pull mainporcelain remote
+git-push mainporcelain remote
git-quiltimport foreignscminterface
git-read-tree plumbingmanipulators
-git-rebase mainporcelain common history
+git-rebase mainporcelain history
git-receive-pack synchelpers
git-reflog ancillarymanipulators
git-relink ancillarymanipulators
@@ -114,28 +114,28 @@ git-repack ancillarymanipulators
git-replace ancillarymanipulators
git-request-pull foreignscminterface
git-rerere ancillaryinterrogators
-git-reset mainporcelain common worktree
+git-reset mainporcelain worktree
git-revert mainporcelain
git-rev-list plumbinginterrogators
git-rev-parse ancillaryinterrogators
-git-rm mainporcelain common worktree
+git-rm mainporcelain worktree
git-send-email foreignscminterface
git-send-pack synchingrepositories
git-shell synchelpers
git-shortlog mainporcelain
-git-show mainporcelain common info
+git-show mainporcelain info
git-show-branch ancillaryinterrogators
git-show-index plumbinginterrogators
git-show-ref plumbinginterrogators
git-sh-i18n purehelpers
git-sh-setup purehelpers
git-stash mainporcelain
-git-status mainporcelain common info
+git-status mainporcelain info
git-stripspace purehelpers
git-submodule mainporcelain
git-svn foreignscminterface
git-symbolic-ref plumbingmanipulators
-git-tag mainporcelain common history
+git-tag mainporcelain history
git-unpack-file plumbinginterrogators
git-unpack-objects plumbingmanipulators
git-update-index plumbingmanipulators
--
2.4.0
^ permalink raw reply related [flat|nested] 23+ messages in thread
* [PATCH v7 5/5] help.c: output the typical Git workflow
2015-05-15 18:34 [PATCH v7 0/5] git help: group common commands by theme Sébastien Guimmara
` (3 preceding siblings ...)
2015-05-15 18:35 ` [PATCH v7 4/5] command-list.txt: drop the common tag Sébastien Guimmara
@ 2015-05-15 18:35 ` Sébastien Guimmara
2015-05-15 21:45 ` Eric Sunshine
2015-05-15 20:41 ` [PATCH v7 0/5] git help: group common commands by theme Eric Sunshine
5 siblings, 1 reply; 23+ messages in thread
From: Sébastien Guimmara @ 2015-05-15 18:35 UTC (permalink / raw)
To: git, gitster, sunshine; +Cc: Sébastien Guimmara
'git help' shows common commands in alphabetical order:
The most commonly used git commands are:
add Add file contents to the index
bisect Find by binary search the change that introduced a bug
branch List, create, or delete branches
checkout Checkout a branch or paths to the working tree
clone Clone a repository into a new directory
commit Record changes to the repository
[...]
without any indication of how commands relate to high-level
concepts or each other. Revise the output to explain their relationship
with the typical Git workflow:
The typical Git workflow includes:
start a working area (see also: git help tutorial):
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize [...]
work on the current change (see also: git help everyday):
add Add file contents to the index
reset Reset current HEAD to the specified state
examine the history and state (see also: git help revisions):
log Show commit logs
status Show the working tree status
[...]
Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
help.c | 24 +++++++++++++++++++++++-
1 file changed, 23 insertions(+), 1 deletion(-)
diff --git a/help.c b/help.c
index 2072a87..bdb69d1 100644
--- a/help.c
+++ b/help.c
@@ -218,17 +218,39 @@ void list_commands(unsigned int colopts,
}
}
+int cmd_group_cmp(const void *elem1, const void *elem2)
+{
+ const struct cmdname_help *e1 = elem1;
+ const struct cmdname_help *e2 = elem2;
+
+ if (e1->group < e2->group)
+ return -1;
+ if (e1->group > e2->group)
+ return 1;
+ return strcmp(e1->name, e2->name);
+}
+
void list_common_cmds_help(void)
{
int i, longest = 0;
+ int current_grp = -1;
for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
if (longest < strlen(common_cmds[i].name))
longest = strlen(common_cmds[i].name);
}
- puts(_("The most commonly used git commands are:"));
+ qsort(common_cmds, ARRAY_SIZE(common_cmds),
+ sizeof(common_cmds[0]), cmd_group_cmp);
+
+ puts(_("The typical Git workflow includes:"));
+
for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
+ if (common_cmds[i].group != current_grp) {
+ printf("\n%s:\n", _(common_cmd_groups[common_cmds[i].group]));
+ current_grp = common_cmds[i].group;
+ }
+
printf(" %s ", common_cmds[i].name);
mput_char(' ', longest - strlen(common_cmds[i].name));
puts(_(common_cmds[i].help));
--
2.4.0
^ permalink raw reply related [flat|nested] 23+ messages in thread
* Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header
2015-05-15 18:35 ` [PATCH v7 1/5] command-list.txt: prepare with [commands] header Sébastien Guimmara
@ 2015-05-15 20:26 ` Junio C Hamano
2015-05-15 20:33 ` Sébastien Guimmara
2015-05-15 21:15 ` Eric Sunshine
2015-05-16 9:44 ` Philip Oakley
2 siblings, 1 reply; 23+ messages in thread
From: Junio C Hamano @ 2015-05-15 20:26 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: git, sunshine
Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
> diff --git a/Makefile b/Makefile
> index 25a453b..0cb2045 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -2454,7 +2454,7 @@ check-docs::
> esac ; \
> test -f "Documentation/$$v.txt" || \
> echo "no doc: $$v"; \
> - sed -e '/^#/d' command-list.txt | \
> + sed -e '1,/^\[commands\]/d' -e '/^#/d' <command-list.txt | \
> grep -q "^$$v[ ]" || \
> case "$$v" in \
> git) ;; \
> @@ -2463,6 +2463,7 @@ check-docs::
> done; \
> ( \
> sed -e '/^#/d' \
> + -e '1,/^\[commands\]/d' \
> -e 's/[ ].*//' \
> -e 's/^/listed /' command-list.txt; \
> $(MAKE) -C Documentation print-man1 | \
> diff --git a/command-list.txt b/command-list.txt
> index 54d8d21..caed872 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -1,5 +1,6 @@
> # List of known git commands.
> # command name category [deprecated] [common]
> +[commands]
> git-add mainporcelain common
> git-am mainporcelain
> git-annotate ancillaryinterrogators
This is largely just a "taste" thing, but with all these backslashes
in the supporting infrastructure you had to add in Makefiles and
scripts, don't you think the choice of the way you designed the
format to use '[commands]' was a rather poor one? After all, all
you need is a clear separator line for a block of commands and
another block of groups, and there wasn't a reason why you needed to
use square brackets for that, and the sed scripts are suffering from
that poor choice.
You could for example have used the existing "# List of known git
commands" as such a signal to tell that all the no comment lines
below are commands.
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header
2015-05-15 20:26 ` Junio C Hamano
@ 2015-05-15 20:33 ` Sébastien Guimmara
2015-05-15 20:44 ` Junio C Hamano
0 siblings, 1 reply; 23+ messages in thread
From: Sébastien Guimmara @ 2015-05-15 20:33 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, Sébastien Guimmara
On 05/15/2015 10:26 PM, Junio C Hamano wrote:
> Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
>
>> diff --git a/Makefile b/Makefile
>> index 25a453b..0cb2045 100644
>> --- a/Makefile
>> +++ b/Makefile
>> @@ -2454,7 +2454,7 @@ check-docs::
>> esac ; \
>> test -f "Documentation/$$v.txt" || \
>> echo "no doc: $$v"; \
>> - sed -e '/^#/d' command-list.txt | \
>> + sed -e '1,/^\[commands\]/d' -e '/^#/d' <command-list.txt | \
>> grep -q "^$$v[ ]" || \
>> case "$$v" in \
>> git) ;; \
>> @@ -2463,6 +2463,7 @@ check-docs::
>> done; \
>> ( \
>> sed -e '/^#/d' \
>> + -e '1,/^\[commands\]/d' \
>> -e 's/[ ].*//' \
>> -e 's/^/listed /' command-list.txt; \
>> $(MAKE) -C Documentation print-man1 | \
>> diff --git a/command-list.txt b/command-list.txt
>> index 54d8d21..caed872 100644
>> --- a/command-list.txt
>> +++ b/command-list.txt
>> @@ -1,5 +1,6 @@
>> # List of known git commands.
>> # command name category [deprecated] [common]
>> +[commands]
>> git-add mainporcelain common
>> git-am mainporcelain
>> git-annotate ancillaryinterrogators
>
> This is largely just a "taste" thing, but with all these backslashes
> in the supporting infrastructure you had to add in Makefiles and
> scripts, don't you think the choice of the way you designed the
> format to use '[commands]' was a rather poor one? After all, all
> you need is a clear separator line for a block of commands and
> another block of groups, and there wasn't a reason why you needed to
> use square brackets for that, and the sed scripts are suffering from
> that poor choice.
>
> You could for example have used the existing "# List of known git
> commands" as such a signal to tell that all the no comment lines
> below are commands.
>
I tend to think that relying on comments as marks for parsers is brittle,
but indeed square brackets get in the way of sed regexes. I'll think of
something better. Thanks.
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v7 0/5] git help: group common commands by theme
2015-05-15 18:34 [PATCH v7 0/5] git help: group common commands by theme Sébastien Guimmara
` (4 preceding siblings ...)
2015-05-15 18:35 ` [PATCH v7 5/5] help.c: output the typical Git workflow Sébastien Guimmara
@ 2015-05-15 20:41 ` Eric Sunshine
2015-05-15 20:48 ` Junio C Hamano
5 siblings, 1 reply; 23+ messages in thread
From: Eric Sunshine @ 2015-05-15 20:41 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano
On Fri, May 15, 2015 at 2:34 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> This v7 is very similar in content to the v5 [1], except minor formatting
> adjustments in 'git help' output and recommendations from Eric.
>
> rebased on 'next' (a2776d4)
Something to keep in mind for the future: It's usually easier to
manage preparatory cleanup patches by incorporating them into the
series which needs/wants them rather than posting them as separate
topics. That way, your patch series isn't held hostage by those
separate topics. For instance, if your "whitespace fix" cleanup patch,
bf990a2 (command-list.txt: fix whitespace inconsistency, 2015-05-08),
which is already in 'next', had been an early patch in the current
series (say patch 1/6), then you wouldn't have had to base this series
on 'next'.
> The major change is in the patch series itself. Commits have been
> reordered and adjusted so that each 'apply' doesn't break the build, and
> preserve bisectability.
Thanks, the patch organization of this version (v7) looks much better
than that of v5.
> Summary: make 'git help' outputs a more usable and friendlier
> list of commands, grouped by theme according to the typical Git workflow:
>
> The typical Git workflow includes:
>
> start a working area (see also: git help tutorial):
> clone Clone a repository into a new directory
> init Create an empty Git repository or reinitialize an existing one
>
> work on the current change (see also: git help everyday):
> 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
Nice. This looks better with the extra indentation dropped[1], and it
once again fits my 80-column terminal window.
One minor bike-shedding observation: The colon ":" at the end of the
group headings seems unnecessary and a bit redundant with the colon at
the end of "The typical Git workflow includes:". I think the group
headings would read just as well (or a bit better) without the
trailing colon, but I don't care strongly.
[1]: http://article.gmane.org/gmane.comp.version-control.git/268759
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header
2015-05-15 20:33 ` Sébastien Guimmara
@ 2015-05-15 20:44 ` Junio C Hamano
2015-05-15 20:52 ` Eric Sunshine
0 siblings, 1 reply; 23+ messages in thread
From: Junio C Hamano @ 2015-05-15 20:44 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: git
Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
>> This is largely just a "taste" thing, but with all these backslashes
>> in the supporting infrastructure you had to add in Makefiles and
>> scripts, don't you think the choice of the way you designed the
>> format to use '[commands]' was a rather poor one? After all, all
>> you need is a clear separator line for a block of commands and
>> another block of groups, and there wasn't a reason why you needed to
>> use square brackets for that, and the sed scripts are suffering from
>> that poor choice.
>>
>> You could for example have used the existing "# List of known git
>> commands" as such a signal to tell that all the no comment lines
>> below are commands.
>
> I tend to think that relying on comments as marks for parsers is brittle,
> but indeed square brackets get in the way of sed regexes. I'll think of
> something better. Thanks.
Heh, we, and more importantly our users, already rely on a marker in
comments when writing their commit log messages ;-)
I would not be opposed to a new header that is outside comment, but
I do not think the marker line that is also a comment is "brittle"
and would not be opposed to that, either.
# do not molest the next line
### command list
# name category
git-add mainporcelain
...
would be perfectly acceptable.
I was just pointing out that you did not even have to have patch
1/5.
Thanks.
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v7 0/5] git help: group common commands by theme
2015-05-15 20:41 ` [PATCH v7 0/5] git help: group common commands by theme Eric Sunshine
@ 2015-05-15 20:48 ` Junio C Hamano
2015-05-15 20:50 ` Sébastien Guimmara
0 siblings, 1 reply; 23+ messages in thread
From: Junio C Hamano @ 2015-05-15 20:48 UTC (permalink / raw)
To: Eric Sunshine; +Cc: Sébastien Guimmara, Git List
Eric Sunshine <sunshine@sunshineco.com> writes:
>> rebased on 'next' (a2776d4)
>
> Something to keep in mind for the future: It's usually easier to
> manage preparatory cleanup patches by incorporating them into the
> series which needs/wants them rather than posting them as separate
> topics. That way, your patch series isn't held hostage by those
> separate topics.
Not a big deal in this case, as I was very well aware that there was
a preparatory change sent, so no harm done to me personally; I even
asked Sébastien to rebuild on top of that patch.
For people who are helping to review the series but haven't paid
attention to everything that was said on the list (read: almost all
the people), it would have been better if it said "depends on
bf990a2", instead of saying that it depends on the 'next' as a whole
(which it doesn't).
Thanks.
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v7 0/5] git help: group common commands by theme
2015-05-15 20:48 ` Junio C Hamano
@ 2015-05-15 20:50 ` Sébastien Guimmara
0 siblings, 0 replies; 23+ messages in thread
From: Sébastien Guimmara @ 2015-05-15 20:50 UTC (permalink / raw)
To: Junio C Hamano, Eric Sunshine; +Cc: Git List, Sébastien Guimmara
On 05/15/2015 10:48 PM, Junio C Hamano wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
>
>>> rebased on 'next' (a2776d4)
>>
>> Something to keep in mind for the future: It's usually easier to
>> manage preparatory cleanup patches by incorporating them into the
>> series which needs/wants them rather than posting them as separate
>> topics. That way, your patch series isn't held hostage by those
>> separate topics.
>
> Not a big deal in this case, as I was very well aware that there was
> a preparatory change sent, so no harm done to me personally; I even
> asked Sébastien to rebuild on top of that patch.
>
> For people who are helping to review the series but haven't paid
> attention to everything that was said on the list (read: almost all
> the people), it would have been better if it said "depends on
> bf990a2", instead of saying that it depends on the 'next' as a whole
> (which it doesn't).
>
> Thanks.
>
Lesson learnt. I'll mention the commit itself instead of the branch
for the next series. Thanks :)
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header
2015-05-15 20:44 ` Junio C Hamano
@ 2015-05-15 20:52 ` Eric Sunshine
2015-05-15 22:26 ` Junio C Hamano
0 siblings, 1 reply; 23+ messages in thread
From: Eric Sunshine @ 2015-05-15 20:52 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Sébastien Guimmara, Git List
On Fri, May 15, 2015 at 4:44 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
>>> You could for example have used the existing "# List of known git
>>> commands" as such a signal to tell that all the no comment lines
>>> below are commands.
>>
>> I tend to think that relying on comments as marks for parsers is brittle,
>> but indeed square brackets get in the way of sed regexes. I'll think of
>> something better. Thanks.
>
> Heh, we, and more importantly our users, already rely on a marker in
> comments when writing their commit log messages ;-)
>
> I would not be opposed to a new header that is outside comment, but
> I do not think the marker line that is also a comment is "brittle"
> and would not be opposed to that, either.
>
> # do not molest the next line
> ### command list
> # name category
> git-add mainporcelain
> ...
>
> would be perfectly acceptable.
>
> I was just pointing out that you did not even have to have patch
> 1/5.
Is that entirely accurate? The machinery (Makefiles, cmd-list.perl)
does have to be updated at some point to skip the "common" block which
get added in patch 2/5. That work could be done as part of patch 2/5,
though it seemed cleaner to me to make it separate (though I don't
care too strongly).
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header
2015-05-15 18:35 ` [PATCH v7 1/5] command-list.txt: prepare with [commands] header Sébastien Guimmara
2015-05-15 20:26 ` Junio C Hamano
@ 2015-05-15 21:15 ` Eric Sunshine
2015-05-16 9:44 ` Philip Oakley
2 siblings, 0 replies; 23+ messages in thread
From: Eric Sunshine @ 2015-05-15 21:15 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano
On Fri, May 15, 2015 at 2:35 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> command-list.txt: prepare with [commands] header
>
> Add a [commands] header before the actual command list, then make the
> following files ignore this header in their parsing:
>
> * cmd-list.perl
> * Makefile (check-docks target)
When these patches are ultimately applied, they won't have the benefit
of the cover letter to explain the purpose of this change and,
unfortunately, this commit message is lacking in that respect. The
commit message should explain the reason you're making this change
("prepare machinery to deal with upcoming new common group
specification" or such). With a proper explanation, it's not necessary
to state (as you do above) precisely which bits of machinery you are
changing. The patch itself already does that well enough.
More below.
> Helped-by: Eric Sunshine <sunshine@sunshineco.com>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt
> index d7de5a3..6d772bd 100644
> --- a/Documentation/howto/new-command.txt
> +++ b/Documentation/howto/new-command.txt
> @@ -95,7 +95,9 @@ your language, document it in the INSTALL file.
> that categorizes commands by type, so they can be listed in appropriate
> subsections in the documentation's summary command list. Add an entry
> for yours. To understand the categories, look at git-commands.txt
> -in the main directory.
> +in the main directory. If the new command is part of the typical Git
> +workflow and you believe it common enough to be mentioned in 'git help',
> +map this command to a common group in the column [common].
I think you meant to fold this change into patch 2/5 where the
[common] block is actually added. It doesn't make much sense to talk
about it here before exists.
> 7. Give the maintainer one paragraph to include in the RelNotes file
> to describe the new feature; a good place to do so is in the cover
> diff --git a/Makefile b/Makefile
> index 25a453b..0cb2045 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -2454,7 +2454,7 @@ check-docs::
> esac ; \
> test -f "Documentation/$$v.txt" || \
> echo "no doc: $$v"; \
> - sed -e '/^#/d' command-list.txt | \
> + sed -e '1,/^\[commands\]/d' -e '/^#/d' <command-list.txt | \
This is partly my fault since my original suggestion for how to skip
[common] and [commands] sections[1] was typed on-the-spot when
composing the mail message, without the context of looking at this
Makefile, but changing this invocation to use redirection
(<command-list.txt) rather than a simple argument (command-list.txt)
seems unwarranted. Worse, it may confuse readers into thinking that
there is some important but obscure reason for the change which they
cannot fathom. Also, the invocation in the hunk just below this one
does not bother with redirection, so use of redirection here seems
doubly mysterious.
[1]: http://article.gmane.org/gmane.comp.version-control.git/268598
> grep -q "^$$v[ ]" || \
> case "$$v" in \
> git) ;; \
> @@ -2463,6 +2463,7 @@ check-docs::
> done; \
> ( \
> sed -e '/^#/d' \
> + -e '1,/^\[commands\]/d' \
This won't work as expected. If you invoke 'check-docs', you'll see
this (undesired) output:
% make check-docs
removed but listed: [commands]
removed but listed: [common]
removed but listed: history
removed but listed: info
removed but listed: init
removed but listed: remote
removed but listed: worktree
%
which is the two [headers] you added plus all the new common group
tags. To fix, re-order the sed expressions so that 1,/^\[commands\]/d
comes first:
sed -e '1,/^\[commands\]/d' \
-e '/^#/d' \
...
> -e 's/[ ].*//' \
> -e 's/^/listed /' command-list.txt; \
> $(MAKE) -C Documentation print-man1 | \
> diff --git a/command-list.txt b/command-list.txt
> index 54d8d21..caed872 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -1,5 +1,6 @@
> # List of known git commands.
> # command name category [deprecated] [common]
> +[commands]
> git-add mainporcelain common
> git-am mainporcelain
> git-annotate ancillaryinterrogators
> --
> 2.4.0
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v7 2/5] command-list.txt: add a [common] block
2015-05-15 18:35 ` [PATCH v7 2/5] command-list.txt: add a [common] block Sébastien Guimmara
@ 2015-05-15 21:31 ` Eric Sunshine
0 siblings, 0 replies; 23+ messages in thread
From: Eric Sunshine @ 2015-05-15 21:31 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano
On Fri, May 15, 2015 at 2:35 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> Add a [common] block at the beginning of command-list.txt:
Without benefit of the explanation in the cover letter, the reason for
this change is a bit mysterious. Even a single sentence preceding this
one could help clarify. Perhaps the above could be rewritten something
like this:
The ultimate goal is for "git help" to display common commands in
groups rather than alphabetically. As a first step, define the
groups in a new [common] block, and then assign a group to each
common command.
> [common]
> init start a working area (see also: git help tutorial)
> worktree work on the current change (see also:[...]
> info examine the history and state (see also: git [...]
> history grow, mark and tweak your history
> remote collaborate (see also: git help workflows)
>
> storing information about common commands group, then map each common
> command to a group:
>
> git-add mainporcelain common worktree
With the above rewritten explanation, the rest of the commit message
(the above examples) becomes pretty much unnecessary and merely
repeats what the patch itself already says.
> Helped-by: Eric Sunshine <sunshine@sunshineco.com>
> Helped-by: Junio C Hamano <gitster@pobox.com>
> Helped-by: Emma Jane Hogbin Westby <emma.westby@gmail.com>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v7 3/5] generate-cmdlist: parse common group commands
2015-05-15 18:35 ` [PATCH v7 3/5] generate-cmdlist: parse common group commands Sébastien Guimmara
@ 2015-05-15 21:34 ` Eric Sunshine
0 siblings, 0 replies; 23+ messages in thread
From: Eric Sunshine @ 2015-05-15 21:34 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano
On Fri, May 15, 2015 at 2:35 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> From: Eric Sunshine <sunshine@sunshineco.com>
>
> Parse the [common] block to create the array of group descriptions:
> [...]
> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> diff --git a/generate-cmdlist.awk b/generate-cmdlist.awk
> new file mode 100644
> index 0000000..b5cc789
> --- /dev/null
> +++ b/generate-cmdlist.awk
> @@ -0,0 +1,39 @@
> +BEGIN {
> + print "/* Automatically generated by generate-cmdlist.awk */\n"
> + print "struct cmdname_help {"
> + print "\tchar name[16];"
> + print "\tchar help[80];"
> + print "\tunsigned char group;"
> + print "};\n"
> + print "static char *common_cmd_groups[] = {"
> +}
> +/^#/ || /^[ ]*$/ { next }
> +state == 2 {
> + for (i = 2; i <= NF; i++)
> + if (grp[$i]) {
> + f = "Documentation/"$1".txt"
> + while (getline s <f > 0)
> + if (match(s, $1" - ")) {
> + t = substr(s, length($1" - ") + 1)
> + break
> + }
> + close(f)
> + printf "\t{\"%s\", N_(\"%s\"), %s},\n",
> + substr($1, length("git-") + 1), t, grp[$i] - 1
> + break
> + }
> +}
> +/\[commands\]/ {
> + print "};\n\nstatic struct cmdname_help common_cmds[] = {"
> + state = 2
> +}
> +state == 1 {
> + grp[$1] = ++n
> + sub($1"[ ][ ]*", "")
> + printf "\tN_(\"%s\"),\n", $0
> + next
It probably would be best to drop this unnecessary and potentially
confusing "next" line[1].
[1]: http://thread.gmane.org/gmane.comp.version-control.git/268348/focus=268599
> +}
> +/\[common\]/ {
> + state = 1
> +}
> +END { print "};" }
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v7 4/5] command-list.txt: drop the common tag
2015-05-15 18:35 ` [PATCH v7 4/5] command-list.txt: drop the common tag Sébastien Guimmara
@ 2015-05-15 21:41 ` Eric Sunshine
0 siblings, 0 replies; 23+ messages in thread
From: Eric Sunshine @ 2015-05-15 21:41 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano
On Fri, May 15, 2015 at 2:35 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> The parser generate-cmdlist.awk gathers all group information without
> needing the common tag.
This might leave the reader wondering why the "common" tag was there
in the first place. I probably would have written it this way:
command-list.sh, retired in the previous patch, was the only
consumer of the "common" tag, so drop this now-unnecessary
attribute.
> before:
> git-add mainporcelain common worktree
>
> after:
> git-add mainporcelain worktree
which makes this example effectively unnecessary (plus, the patch
itself already says the same thing).
> Helped-by: Eric Sunshine <sunshine@sunshineco.com>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> diff --git a/command-list.txt b/command-list.txt
> index c00b0b6..2203566 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -11,30 +11,30 @@ remote collaborate (see also: git help workflows)
> # List of known git commands.
> # command name category [deprecated] [common]
> [commands]
> -git-add mainporcelain common worktree
> +git-add mainporcelain worktree
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v7 5/5] help.c: output the typical Git workflow
2015-05-15 18:35 ` [PATCH v7 5/5] help.c: output the typical Git workflow Sébastien Guimmara
@ 2015-05-15 21:45 ` Eric Sunshine
0 siblings, 0 replies; 23+ messages in thread
From: Eric Sunshine @ 2015-05-15 21:45 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano
On Fri, May 15, 2015 at 2:35 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> Subject: help.c: output the typical Git workflow
A more meaningful summary might be:
help: respect new common command grouping
or something.
> 'git help' shows common commands in alphabetical order:
>
> The most commonly used git commands are:
> add Add file contents to the index
> bisect Find by binary search the change that introduced a bug
> branch List, create, or delete branches
> checkout Checkout a branch or paths to the working tree
> clone Clone a repository into a new directory
> commit Record changes to the repository
> [...]
>
> without any indication of how commands relate to high-level
> concepts or each other. Revise the output to explain their relationship
> with the typical Git workflow:
>
> The typical Git workflow includes:
>
> start a working area (see also: git help tutorial):
> clone Clone a repository into a new directory
> init Create an empty Git repository or reinitialize [...]
>
> work on the current change (see also: git help everyday):
> add Add file contents to the index
> reset Reset current HEAD to the specified state
>
> examine the history and state (see also: git help revisions):
> log Show commit logs
> status Show the working tree status
The remainder of the commit message makes sense, and the patch itself
looks good. Thanks.
> Helped-by: Eric Sunshine <sunshine@sunshineco.com>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> help.c | 24 +++++++++++++++++++++++-
> 1 file changed, 23 insertions(+), 1 deletion(-)
>
> diff --git a/help.c b/help.c
> index 2072a87..bdb69d1 100644
> --- a/help.c
> +++ b/help.c
> @@ -218,17 +218,39 @@ void list_commands(unsigned int colopts,
> }
> }
>
> +int cmd_group_cmp(const void *elem1, const void *elem2)
> +{
> + const struct cmdname_help *e1 = elem1;
> + const struct cmdname_help *e2 = elem2;
> +
> + if (e1->group < e2->group)
> + return -1;
> + if (e1->group > e2->group)
> + return 1;
> + return strcmp(e1->name, e2->name);
> +}
> +
> void list_common_cmds_help(void)
> {
> int i, longest = 0;
> + int current_grp = -1;
>
> for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
> if (longest < strlen(common_cmds[i].name))
> longest = strlen(common_cmds[i].name);
> }
>
> - puts(_("The most commonly used git commands are:"));
> + qsort(common_cmds, ARRAY_SIZE(common_cmds),
> + sizeof(common_cmds[0]), cmd_group_cmp);
> +
> + puts(_("The typical Git workflow includes:"));
> +
> for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
> + if (common_cmds[i].group != current_grp) {
> + printf("\n%s:\n", _(common_cmd_groups[common_cmds[i].group]));
> + current_grp = common_cmds[i].group;
> + }
> +
> printf(" %s ", common_cmds[i].name);
> mput_char(' ', longest - strlen(common_cmds[i].name));
> puts(_(common_cmds[i].help));
> --
> 2.4.0
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header
2015-05-15 20:52 ` Eric Sunshine
@ 2015-05-15 22:26 ` Junio C Hamano
2015-05-15 23:55 ` Eric Sunshine
0 siblings, 1 reply; 23+ messages in thread
From: Junio C Hamano @ 2015-05-15 22:26 UTC (permalink / raw)
To: Eric Sunshine; +Cc: Sébastien Guimmara, Git List
Eric Sunshine <sunshine@sunshineco.com> writes:
> On Fri, May 15, 2015 at 4:44 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
>>>> You could for example have used the existing "# List of known git
>>>> commands" as such a signal to tell that all the no comment lines
>>>> below are commands.
>>>
>>> I tend to think that relying on comments as marks for parsers is brittle,
>>> but indeed square brackets get in the way of sed regexes. I'll think of
>>> something better. Thanks.
>>
>> Heh, we, and more importantly our users, already rely on a marker in
>> comments when writing their commit log messages ;-)
>>
>> I would not be opposed to a new header that is outside comment, but
>> I do not think the marker line that is also a comment is "brittle"
>> and would not be opposed to that, either.
>>
>> # do not molest the next line
>> ### command list
>> # name category
>> git-add mainporcelain
>> ...
>>
>> would be perfectly acceptable.
>>
>> I was just pointing out that you did not even have to have patch
>> 1/5.
>
> Is that entirely accurate? The machinery (Makefiles, cmd-list.perl)
> does have to be updated at some point to skip the "common" block which
> get added in patch 2/5.
That is true, but if "# List of known git commands" instead of
[commands] were used as the separator line, 1/5 wouldn't have needed
any change to the Makefile.
Of course, if you need to add lines that would appear as junk to the
old parser (e.g. the grouping info), at that point you would of
course need to tell the parser to skip them.
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header
2015-05-15 22:26 ` Junio C Hamano
@ 2015-05-15 23:55 ` Eric Sunshine
2015-05-18 16:25 ` Sébastien Guimmara
0 siblings, 1 reply; 23+ messages in thread
From: Eric Sunshine @ 2015-05-15 23:55 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Sébastien Guimmara, Git List
On Fri, May 15, 2015 at 03:26:52PM -0700, Junio C Hamano wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
> > On Fri, May 15, 2015 at 4:44 PM, Junio C Hamano <gitster@pobox.com> wrote:
> >> I was just pointing out that you did not even have to have patch
> >> 1/5.
> >
> > Is that entirely accurate? The machinery (Makefiles, cmd-list.perl)
> > does have to be updated at some point to skip the "common" block which
> > get added in patch 2/5.
>
> That is true, but if "# List of known git commands" instead of
> [commands] were used as the separator line, 1/5 wouldn't have needed
> any change to the Makefile.
>
> Of course, if you need to add lines that would appear as junk to the
> old parser (e.g. the grouping info), at that point you would of
> course need to tell the parser to skip them.
Right. Preparing the machinery for the the upcoming "common" group
was actually the intent of patch 1/5 in the proposal[1]. Introducing
the [commands] header at that stage was merely a rather ugly
implementation detail of that goal, and I wasn't particularly happy
about suggesting it due to its ugliness. Unfortunately, the 1/5
commit message didn't clarify the matter. So, your observation of the
seeming pointlessness of patch 1/5 (which adds the [commands] header
for apparently no good reason) is quite understandable.
A more properly focused commit message (along with your suggestion to
scan for a comment or other separator) might help to salvage 1/5.
Perhaps something like this:
--- >8 ---
From: Eric Sunshine <sunshine@sunshineco.com>
Subject: [PATCH 1/5] command-list: prepare machinery for upcoming "common
groups" section
The ultimate goal is for "git help" to classify common commands by
group. Toward this end, a subsequent patch will add a new "common
groups" section to command-list.txt preceding the actual command list.
As preparation, teach existing command-list.txt parsing machinery, which
doesn't care about grouping, to skip over this upcoming "common groups"
section.
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---
Documentation/cmd-list.perl | 4 ++++
Makefile | 5 +++--
command-list.txt | 3 ++-
3 files changed, 9 insertions(+), 3 deletions(-)
diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index 04f9977..5aa73cf 100755
--- a/Documentation/cmd-list.perl
+++ b/Documentation/cmd-list.perl
@@ -38,6 +38,10 @@ sub format_one {
}
}
+while (<>) {
+ last if /^### command list/;
+}
+
my %cmds = ();
for (sort <>) {
next if /^#/;
diff --git a/Makefile b/Makefile
index 25a453b..5ed0acf 100644
--- a/Makefile
+++ b/Makefile
@@ -2454,7 +2454,7 @@ check-docs::
esac ; \
test -f "Documentation/$$v.txt" || \
echo "no doc: $$v"; \
- sed -e '/^#/d' command-list.txt | \
+ sed -e '1,/^### command list/d' -e '/^#/d' command-list.txt | \
grep -q "^$$v[ ]" || \
case "$$v" in \
git) ;; \
@@ -2462,7 +2462,8 @@ check-docs::
esac ; \
done; \
( \
- sed -e '/^#/d' \
+ sed -e '1,/^### command list/d' \
+ -e '/^#/d' \
-e 's/[ ].*//' \
-e 's/^/listed /' command-list.txt; \
$(MAKE) -C Documentation print-man1 | \
diff --git a/command-list.txt b/command-list.txt
index 54d8d21..609b344 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,4 +1,5 @@
-# List of known git commands.
+# do not molest the next line
+### command list
# command name category [deprecated] [common]
git-add mainporcelain common
git-am mainporcelain
--
2.4.1.260.ga2776d4
--- >8 ---
[1]: http://article.gmane.org/gmane.comp.version-control.git/268756
^ permalink raw reply related [flat|nested] 23+ messages in thread
* Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header
2015-05-16 9:44 ` Philip Oakley
@ 2015-05-16 9:44 ` Sébastien Guimmara
0 siblings, 0 replies; 23+ messages in thread
From: Sébastien Guimmara @ 2015-05-16 9:44 UTC (permalink / raw)
To: Philip Oakley, Git Users
On 05/16/2015 11:44 AM, Philip Oakley wrote:
> From: "Sébastien Guimmara" <sebastien.guimmara@gmail.com>
>> Add a [commands] header before the actual command list, then make the
>> following files ignore this header in their parsing:
>>
>> * cmd-list.perl
>> * Makefile (check-docks target)
>
> s/docks/docs/
> or even fuller as "(the check-docs target)"?
> I'd misunderstood this as (verb) check the doumentation targets within the Makefile, rather than the (definite article) 'check-docs' target within the Makefile ~#L2554.
> --
> Philip
>
That's right, thanks for pointing that out.
>>
>> Helped-by: Eric Sunshine <sunshine@sunshineco.com>
>> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
>> ---
>> Documentation/cmd-list.perl | 4 ++++
>> Documentation/howto/new-command.txt | 4 +++-
>> Makefile | 3 ++-
>> command-list.txt | 1 +
>> 4 files changed, 10 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
>> index 04f9977..06a5fd6 100755
>> --- a/Documentation/cmd-list.perl
>> +++ b/Documentation/cmd-list.perl
>> @@ -38,6 +38,10 @@ sub format_one {
>> }
>> }
>>
>> +while (<>) {
>> + last if /^\[commands\]/;
>> +}
>> +
>> my %cmds = ();
>> for (sort <>) {
>> next if /^#/;
>> diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt
>> index d7de5a3..6d772bd 100644
>> --- a/Documentation/howto/new-command.txt
>> +++ b/Documentation/howto/new-command.txt
>> @@ -95,7 +95,9 @@ your language, document it in the INSTALL file.
>> that categorizes commands by type, so they can be listed in appropriate
>> subsections in the documentation's summary command list. Add an entry
>> for yours. To understand the categories, look at git-commands.txt
>> -in the main directory.
>> +in the main directory. If the new command is part of the typical Git
>> +workflow and you believe it common enough to be mentioned in 'git help',
>> +map this command to a common group in the column [common].
>>
>> 7. Give the maintainer one paragraph to include in the RelNotes file
>> to describe the new feature; a good place to do so is in the cover
>> diff --git a/Makefile b/Makefile
>> index 25a453b..0cb2045 100644
>> --- a/Makefile
>> +++ b/Makefile
>> @@ -2454,7 +2454,7 @@ check-docs::
>> esac ; \
>> test -f "Documentation/$$v.txt" || \
>> echo "no doc: $$v"; \
>> - sed -e '/^#/d' command-list.txt | \
>> + sed -e '1,/^\[commands\]/d' -e '/^#/d' <command-list.txt | \
>> grep -q "^$$v[ ]" || \
>> case "$$v" in \
>> git) ;; \
>> @@ -2463,6 +2463,7 @@ check-docs::
>> done; \
>> ( \
>> sed -e '/^#/d' \
>> + -e '1,/^\[commands\]/d' \
>> -e 's/[ ].*//' \
>> -e 's/^/listed /' command-list.txt; \
>> $(MAKE) -C Documentation print-man1 | \
>> diff --git a/command-list.txt b/command-list.txt
>> index 54d8d21..caed872 100644
>> --- a/command-list.txt
>> +++ b/command-list.txt
>> @@ -1,5 +1,6 @@
>> # List of known git commands.
>> # command name category [deprecated] [common]
>> +[commands]
>> git-add mainporcelain common
>> git-am mainporcelain
>> git-annotate ancillaryinterrogators
>> --
>> 2.4.0
>
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at http://vger.kernel.org/majordomo-info.html
>
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header
2015-05-15 18:35 ` [PATCH v7 1/5] command-list.txt: prepare with [commands] header Sébastien Guimmara
2015-05-15 20:26 ` Junio C Hamano
2015-05-15 21:15 ` Eric Sunshine
@ 2015-05-16 9:44 ` Philip Oakley
2015-05-16 9:44 ` Sébastien Guimmara
2 siblings, 1 reply; 23+ messages in thread
From: Philip Oakley @ 2015-05-16 9:44 UTC (permalink / raw)
To: Sébastien Guimmara, git, gitster, sunshine; +Cc: Sébastien Guimmara
From: "Sébastien Guimmara" <sebastien.guimmara@gmail.com>
> Add a [commands] header before the actual command list, then make the
> following files ignore this header in their parsing:
>
> * cmd-list.perl
> * Makefile (check-docks target)
s/docks/docs/
or even fuller as "(the check-docs target)"?
I'd misunderstood this as (verb) check the doumentation targets within
the Makefile, rather than the (definite article) 'check-docs' target
within the Makefile ~#L2554.
--
Philip
>
> Helped-by: Eric Sunshine <sunshine@sunshineco.com>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> Documentation/cmd-list.perl | 4 ++++
> Documentation/howto/new-command.txt | 4 +++-
> Makefile | 3 ++-
> command-list.txt | 1 +
> 4 files changed, 10 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
> index 04f9977..06a5fd6 100755
> --- a/Documentation/cmd-list.perl
> +++ b/Documentation/cmd-list.perl
> @@ -38,6 +38,10 @@ sub format_one {
> }
> }
>
> +while (<>) {
> + last if /^\[commands\]/;
> +}
> +
> my %cmds = ();
> for (sort <>) {
> next if /^#/;
> diff --git a/Documentation/howto/new-command.txt
> b/Documentation/howto/new-command.txt
> index d7de5a3..6d772bd 100644
> --- a/Documentation/howto/new-command.txt
> +++ b/Documentation/howto/new-command.txt
> @@ -95,7 +95,9 @@ your language, document it in the INSTALL file.
> that categorizes commands by type, so they can be listed in
> appropriate
> subsections in the documentation's summary command list. Add an entry
> for yours. To understand the categories, look at git-commands.txt
> -in the main directory.
> +in the main directory. If the new command is part of the typical Git
> +workflow and you believe it common enough to be mentioned in 'git
> help',
> +map this command to a common group in the column [common].
>
> 7. Give the maintainer one paragraph to include in the RelNotes file
> to describe the new feature; a good place to do so is in the cover
> diff --git a/Makefile b/Makefile
> index 25a453b..0cb2045 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -2454,7 +2454,7 @@ check-docs::
> esac ; \
> test -f "Documentation/$$v.txt" || \
> echo "no doc: $$v"; \
> - sed -e '/^#/d' command-list.txt | \
> + sed -e '1,/^\[commands\]/d' -e '/^#/d' <command-list.txt | \
> grep -q "^$$v[ ]" || \
> case "$$v" in \
> git) ;; \
> @@ -2463,6 +2463,7 @@ check-docs::
> done; \
> ( \
> sed -e '/^#/d' \
> + -e '1,/^\[commands\]/d' \
> -e 's/[ ].*//' \
> -e 's/^/listed /' command-list.txt; \
> $(MAKE) -C Documentation print-man1 | \
> diff --git a/command-list.txt b/command-list.txt
> index 54d8d21..caed872 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -1,5 +1,6 @@
> # List of known git commands.
> # command name category [deprecated] [common]
> +[commands]
> git-add mainporcelain common
> git-am mainporcelain
> git-annotate ancillaryinterrogators
> --
> 2.4.0
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header
2015-05-15 23:55 ` Eric Sunshine
@ 2015-05-18 16:25 ` Sébastien Guimmara
0 siblings, 0 replies; 23+ messages in thread
From: Sébastien Guimmara @ 2015-05-18 16:25 UTC (permalink / raw)
To: git
Eric Sunshine <sunshine <at> sunshineco.com> writes:
>
> Perhaps something like this:
>
Great, I'll look into this for the v8. Thanks :)
^ permalink raw reply [flat|nested] 23+ messages in thread
end of thread, other threads:[~2015-05-18 16:30 UTC | newest]
Thread overview: 23+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2015-05-15 18:34 [PATCH v7 0/5] git help: group common commands by theme Sébastien Guimmara
2015-05-15 18:35 ` [PATCH v7 1/5] command-list.txt: prepare with [commands] header Sébastien Guimmara
2015-05-15 20:26 ` Junio C Hamano
2015-05-15 20:33 ` Sébastien Guimmara
2015-05-15 20:44 ` Junio C Hamano
2015-05-15 20:52 ` Eric Sunshine
2015-05-15 22:26 ` Junio C Hamano
2015-05-15 23:55 ` Eric Sunshine
2015-05-18 16:25 ` Sébastien Guimmara
2015-05-15 21:15 ` Eric Sunshine
2015-05-16 9:44 ` Philip Oakley
2015-05-16 9:44 ` Sébastien Guimmara
2015-05-15 18:35 ` [PATCH v7 2/5] command-list.txt: add a [common] block Sébastien Guimmara
2015-05-15 21:31 ` Eric Sunshine
2015-05-15 18:35 ` [PATCH v7 3/5] generate-cmdlist: parse common group commands Sébastien Guimmara
2015-05-15 21:34 ` Eric Sunshine
2015-05-15 18:35 ` [PATCH v7 4/5] command-list.txt: drop the common tag Sébastien Guimmara
2015-05-15 21:41 ` Eric Sunshine
2015-05-15 18:35 ` [PATCH v7 5/5] help.c: output the typical Git workflow Sébastien Guimmara
2015-05-15 21:45 ` Eric Sunshine
2015-05-15 20:41 ` [PATCH v7 0/5] git help: group common commands by theme Eric Sunshine
2015-05-15 20:48 ` Junio C Hamano
2015-05-15 20:50 ` Sébastien Guimmara
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.