* [PATCH 0/5] git help: group common commands by theme
@ 2015-05-14 12:59 Sébastien Guimmara
2015-05-14 12:59 ` [PATCH 1/5] command-list.txt: prepare with [commands] header Sébastien Guimmara
` (6 more replies)
0 siblings, 7 replies; 12+ messages in thread
From: Sébastien Guimmara @ 2015-05-14 12:59 UTC (permalink / raw)
To: git, sunshine, gitster; +Cc: Sébastien Guimmara
This v6 is very similar in content to the v5 [1], except minor formatting
adjustments in 'git help' output and recommendations from Eric.
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 with [common] block
command-list.txt: drop the common- prefix
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] 12+ messages in thread
* [PATCH 1/5] command-list.txt: prepare with [commands] header
2015-05-14 12:59 [PATCH 0/5] git help: group common commands by theme Sébastien Guimmara
@ 2015-05-14 12:59 ` Sébastien Guimmara
2015-05-14 12:59 ` [PATCH 2/5] command-list.txt: add with [common] block Sébastien Guimmara
` (5 subsequent siblings)
6 siblings, 0 replies; 12+ messages in thread
From: Sébastien Guimmara @ 2015-05-14 12:59 UTC (permalink / raw)
To: git, sunshine, gitster; +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 ++++
Makefile | 3 ++-
command-list.txt | 1 +
3 files changed, 7 insertions(+), 1 deletion(-)
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/Makefile b/Makefile
index 5f3987f..7c57369 100644
--- a/Makefile
+++ b/Makefile
@@ -2447,7 +2447,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) ;; \
@@ -2456,6 +2456,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 f1eae08..40fbe2f 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] 12+ messages in thread
* [PATCH 2/5] command-list.txt: add with [common] block
2015-05-14 12:59 [PATCH 0/5] git help: group common commands by theme Sébastien Guimmara
2015-05-14 12:59 ` [PATCH 1/5] command-list.txt: prepare with [commands] header Sébastien Guimmara
@ 2015-05-14 12:59 ` Sébastien Guimmara
2015-05-14 12:59 ` [PATCH 3/5] generate-cmdlist: parse common group commands Sébastien Guimmara
` (4 subsequent siblings)
6 siblings, 0 replies; 12+ messages in thread
From: Sébastien Guimmara @ 2015-05-14 12:59 UTC (permalink / raw)
To: git, sunshine, gitster; +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>
---
Documentation/howto/new-command.txt | 4 ++-
command-list.txt | 52 ++++++++++++++++++++++---------------
2 files changed, 34 insertions(+), 22 deletions(-)
diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt
index d7de5a3..6d772bd 100644
--- a/Documentation/howto/new-command.txt
+++ b/Documentation/howto/new-command.txt
@@ -95,7 +95,9 @@ your language, document it in the INSTALL file.
that categorizes commands by type, so they can be listed in appropriate
subsections in the documentation's summary command list. Add an entry
for yours. To understand the categories, look at git-commands.txt
-in the main directory.
+in the main directory. If the new command is part of the typical Git
+workflow and you believe it common enough to be mentioned in 'git help',
+map this command to a common group in the column [common].
7. Give the maintainer one paragraph to include in the RelNotes file
to describe the new feature; a good place to do so is in the cover
diff --git a/command-list.txt b/command-list.txt
index 40fbe2f..7cb77f0 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 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] 12+ messages in thread
* [PATCH 3/5] generate-cmdlist: parse common group commands
2015-05-14 12:59 [PATCH 0/5] git help: group common commands by theme Sébastien Guimmara
2015-05-14 12:59 ` [PATCH 1/5] command-list.txt: prepare with [commands] header Sébastien Guimmara
2015-05-14 12:59 ` [PATCH 2/5] command-list.txt: add with [common] block Sébastien Guimmara
@ 2015-05-14 12:59 ` Sébastien Guimmara
2015-05-14 20:58 ` Junio C Hamano
2015-05-14 12:59 ` [PATCH 4/5] command-list.txt: drop the common- prefix Sébastien Guimmara
` (3 subsequent siblings)
6 siblings, 1 reply; 12+ messages in thread
From: Sébastien Guimmara @ 2015-05-14 12:59 UTC (permalink / raw)
To: git, sunshine, gitster; +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 7c57369..286a68f 100644
--- a/Makefile
+++ b/Makefile
@@ -1687,10 +1687,10 @@ $(BUILT_INS): git$X
ln -s $< $@ 2>/dev/null || \
cp $< $@
-common-cmds.h: ./generate-cmdlist.sh command-list.txt
+common-cmds.h: generate-cmdlist.awk command-list.txt
common-cmds.h: $(wildcard Documentation/git-*.txt)
- $(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@
+ $(QUIET_GEN)awk -f generate-cmdlist.awk command-list.txt > $@+ && mv $@+ $@
SCRIPT_DEFINES = $(SHELL_PATH_SQ):$(DIFF_SQ):$(GIT_VERSION):\
$(localedir_SQ):$(NO_CURL):$(USE_GETTEXT_SCHEME):$(SANE_TOOL_PATH_SQ):\
diff --git a/generate-cmdlist.awk b/generate-cmdlist.awk
new file mode 100644
index 0000000..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] 12+ messages in thread
* [PATCH 4/5] command-list.txt: drop the common- prefix
2015-05-14 12:59 [PATCH 0/5] git help: group common commands by theme Sébastien Guimmara
` (2 preceding siblings ...)
2015-05-14 12:59 ` [PATCH 3/5] generate-cmdlist: parse common group commands Sébastien Guimmara
@ 2015-05-14 12:59 ` Sébastien Guimmara
2015-05-14 12:59 ` [PATCH 5/5] help.c: output the typical Git workflow Sébastien Guimmara
` (2 subsequent siblings)
6 siblings, 0 replies; 12+ messages in thread
From: Sébastien Guimmara @ 2015-05-14 12:59 UTC (permalink / raw)
To: git, sunshine, gitster; +Cc: Sébastien Guimmara
The parser generate-cmdlist.awk gathers all group information without
needing the common- prefix.
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 7cb77f0..65e40ee 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] 12+ messages in thread
* [PATCH 5/5] help.c: output the typical Git workflow
2015-05-14 12:59 [PATCH 0/5] git help: group common commands by theme Sébastien Guimmara
` (3 preceding siblings ...)
2015-05-14 12:59 ` [PATCH 4/5] command-list.txt: drop the common- prefix Sébastien Guimmara
@ 2015-05-14 12:59 ` Sébastien Guimmara
2015-05-14 12:59 ` Sébastien Guimmara
2015-05-14 20:51 ` [PATCH 0/5] git help: group common commands by theme Junio C Hamano
6 siblings, 0 replies; 12+ messages in thread
From: Sébastien Guimmara @ 2015-05-14 12:59 UTC (permalink / raw)
To: git, sunshine, gitster; +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] 12+ messages in thread
* [PATCH 5/5] help.c: output the typical Git workflow
2015-05-14 12:59 [PATCH 0/5] git help: group common commands by theme Sébastien Guimmara
` (4 preceding siblings ...)
2015-05-14 12:59 ` [PATCH 5/5] help.c: output the typical Git workflow Sébastien Guimmara
@ 2015-05-14 12:59 ` Sébastien Guimmara
2015-05-14 20:51 ` [PATCH 0/5] git help: group common commands by theme Junio C Hamano
6 siblings, 0 replies; 12+ messages in thread
From: Sébastien Guimmara @ 2015-05-14 12:59 UTC (permalink / raw)
To: git, sunshine, gitster
From: Eric Sunshine <sunshine <at> sunshineco.com>
Subject: Re: [PATCH v5 0/6] git help: group common commands by theme
Newsgroups: gmane.comp.version-control.git
Date: 2015-05-11 05:52:50 GMT (1 day, 12 hours and 19 minutes ago)
On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara
<sebastien.guimmara <at> gmail.com> wrote:
> Sébastien Guimmara (6):
> generate-cmdlist: parse common group commands
> help.c: output the typical Git workflow
> command-list.txt: group common commands by theme
> Makefile: update to new command-list.txt format
> new-command.txt: mention the common command groups
> cmd-list.perl: ignore all lines until [commands]
When preparing a patch series, it's important to think not just about
the final result but also the state of the project at any point within
the series. The project should remain in a working state (not broken
and not regressed) at all steps during the patch series[1]. As each
patch is applied, you should be able to build git successfully, and
run "git help" and get expected results (for that point in the
series). If you can't do either, then there is a problem.
Unfortunately, the organization of this series (v5) breaks the build
and raw functionality from the get-go. Here is a proposed organization
which will keep the project in a sane state as each patch is applied:
patch 1:
[x] Add a [commands] header to command-list.txt
[x] check-docs in Makefile, and either
[x] cmd-list.perl to ignore everything up to and including [commands].
You're not actually doing any classification in
command-list.txt at this point, but instead merely preparing the
machinery to deal with the [commands] header (and the [common] section
which you will add in a subsequent patch).
patch 2:
[x] Add the [common] block to command-list.txt and tag each of
the common commands with an attribute from [common]. Do *not*,
however, remove the old "common" tag at this point since
generate-cmdlist.sh still needs it.
patch 3:
[x] Introduce generate-cmdlist.awk and
[x] retire generate-cmdlist.sh,
[x] along with the associated Makefile changes. This
patch should be exactly the one I posted[2] (between the "--- >8 ---"
lines), along with the minor fixup[3]. The changes in that patch are a
logical unit, so they shouldn't be split up (as you did in v5 between
patches 1/6 and 4/6).
patch 4:
[x] Drop the old "common" attribute from command-list.txt items
since it's no longer needed by any machinery.
patch 5: Update help.c to group and sort the commands using the new
common_cmd_groups[] array and common_commands[].group field.
patch 6 [optional]: Update howto/new-command.txt. Alternately, and
probably preferably, fold this documentation update into patch 2 and
omit this step.
[1]: This is called "preserving bisectability". See "git bisect".
[2]: http://article.gmane.org/gmane.comp.version-control.git/268598
[3]: http://article.gmane.org/gmane.comp.version-control.git/268599
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 0/5] git help: group common commands by theme
2015-05-14 12:59 [PATCH 0/5] git help: group common commands by theme Sébastien Guimmara
` (5 preceding siblings ...)
2015-05-14 12:59 ` Sébastien Guimmara
@ 2015-05-14 20:51 ` Junio C Hamano
2015-05-15 14:37 ` Sébastien Guimmara
6 siblings, 1 reply; 12+ messages in thread
From: Junio C Hamano @ 2015-05-14 20:51 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: git, sunshine
Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
> This v6 is very similar in content to the v5 [1], except minor formatting
> adjustments in 'git help' output and recommendations from Eric.
>
> 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.
Hmph, did you decide to abandon the "whitespace fix" patch? This
does not seem to be based on that one, and it would be crazy to
have these patches *and* the other one as independent two topics
and expect them to be merged cleanly later.
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 3/5] generate-cmdlist: parse common group commands
2015-05-14 12:59 ` [PATCH 3/5] generate-cmdlist: parse common group commands Sébastien Guimmara
@ 2015-05-14 20:58 ` Junio C Hamano
2015-05-14 21:05 ` Eric Sunshine
0 siblings, 1 reply; 12+ messages in thread
From: Junio C Hamano @ 2015-05-14 20:58 UTC (permalink / raw)
To: Sébastien Guimmara; +Cc: git, sunshine
Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
> 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>
> ---
I seem to be getting an empty common_cmds[] list after this step
(with GNU Awk 4.0.1, ICIM).
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 3/5] generate-cmdlist: parse common group commands
2015-05-14 20:58 ` Junio C Hamano
@ 2015-05-14 21:05 ` Eric Sunshine
2015-05-15 14:40 ` Sébastien Guimmara
0 siblings, 1 reply; 12+ messages in thread
From: Eric Sunshine @ 2015-05-14 21:05 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Sébastien Guimmara, Git List
On Thu, May 14, 2015 at 4:58 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
>> 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>
>> ---
>
> I seem to be getting an empty common_cmds[] list after this step
> (with GNU Awk 4.0.1, ICIM).
Indeed. I haven't had a chance to look at this version of the series
yet, but a quick glance shows that this is because patch 2/5 uses
"common-" as a prefix rather than as a standalone tag. That is, lines
in patch 2/5 like this:
git-add mainporcelain common-worktree
should be:
git-add mainporcelain common worktree
as proposed here[1]. And, then patch 4/5 should drop the standalone
"common" tag rather than the "common-" prefix.
[1]: http://article.gmane.org/gmane.comp.version-control.git/268756
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 0/5] git help: group common commands by theme
2015-05-14 20:51 ` [PATCH 0/5] git help: group common commands by theme Junio C Hamano
@ 2015-05-15 14:37 ` Sébastien Guimmara
0 siblings, 0 replies; 12+ messages in thread
From: Sébastien Guimmara @ 2015-05-15 14:37 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, Sébastien Guimmara
On 05/14/2015 10:51 PM, Junio C Hamano wrote:
> Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
>
>> This v6 is very similar in content to the v5 [1], except minor formatting
>> adjustments in 'git help' output and recommendations from Eric.
>>
>> 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.
>
> Hmph, did you decide to abandon the "whitespace fix" patch? This
> does not seem to be based on that one, and it would be crazy to
> have these pa beltches *and* the other one as independent two topics
> and expect them to be merged cleanly later.
>
My mistake : I believed the preparatory patch and the new series had to be
independent, and thus had to be merged in your own tree. I will correct this.
Thanks
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 3/5] generate-cmdlist: parse common group commands
2015-05-14 21:05 ` Eric Sunshine
@ 2015-05-15 14:40 ` Sébastien Guimmara
0 siblings, 0 replies; 12+ messages in thread
From: Sébastien Guimmara @ 2015-05-15 14:40 UTC (permalink / raw)
To: Eric Sunshine, Git Users, Junio C Hamano
On 05/14/2015 11:05 PM, Eric Sunshine wrote:
> On Thu, May 14, 2015 at 4:58 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
>>> 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>
>>> ---
>>
>> I seem to be getting an empty common_cmds[] list after this step
>> (with GNU Awk 4.0.1, ICIM).
>
> Indeed. I haven't had a chance to look at this version of the series
> yet, but a quick glance shows that this is because patch 2/5 uses
> "common-" as a prefix rather than as a standalone tag. That is, lines
> in patch 2/5 like this:
>
> git-add mainporcelain common-worktree
>
> should be:
>
> git-add mainporcelain common worktree
>
> as proposed here[1]. And, then patch 4/5 should drop the standalone
> "common" tag rather than the "common-" prefix.
>
> [1]: http://article.gmane.org/gmane.comp.version-control.git/268756
>
Indeed, I misread your description. Thanks for pointing that out,
I will correct this.
^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2015-05-15 14:40 UTC | newest]
Thread overview: 12+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2015-05-14 12:59 [PATCH 0/5] git help: group common commands by theme Sébastien Guimmara
2015-05-14 12:59 ` [PATCH 1/5] command-list.txt: prepare with [commands] header Sébastien Guimmara
2015-05-14 12:59 ` [PATCH 2/5] command-list.txt: add with [common] block Sébastien Guimmara
2015-05-14 12:59 ` [PATCH 3/5] generate-cmdlist: parse common group commands Sébastien Guimmara
2015-05-14 20:58 ` Junio C Hamano
2015-05-14 21:05 ` Eric Sunshine
2015-05-15 14:40 ` Sébastien Guimmara
2015-05-14 12:59 ` [PATCH 4/5] command-list.txt: drop the common- prefix Sébastien Guimmara
2015-05-14 12:59 ` [PATCH 5/5] help.c: output the typical Git workflow Sébastien Guimmara
2015-05-14 12:59 ` Sébastien Guimmara
2015-05-14 20:51 ` [PATCH 0/5] git help: group common commands by theme Junio C Hamano
2015-05-15 14:37 ` 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).