Sébastien Guimmara [off-list ref] writes:
'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
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
examine the history and state (see also: git help revisions)
log Show commit logs
status Show the working tree status
[...]
Helped-by: Eric Sunshine [off-list ref]
Signed-off-by: Sébastien Guimmara <redacted>
---
I cannot exactly pinpoint what bothers me, but "The typical Git
workflow includes:" sounds a bit awkward.
What does a workflow "include"? What are components included in a
workflow? Are "starting a repository", "working on a single thing",
"collabolating", etc. components that are incuded in a workflow?
If so, the fact that "clone", "init", etc. are "commands that are
commonly used in each component of the workflow" is a more important
thing to say; in other words, the header does not explain what list
it is presenting the user.
Or does a workflow consists of "clone", "init", "add", "mv", etc.
that are included in it? Then it is left unexplained what the
section headings stand for.
Perhaps something like
These are common Git commands used in various situations:
may lessen the uneasiness I felt above. I dunno.
Other than that, this round looks ready for 'next'.
I am not absolutely sure if new dependency on "awk" will not present
portability issues, though. So far we only used it in scripts in
the fringes and only a few tests.
Thanks.
On Mon, May 18, 2015 at 02:39:42PM -0700, Junio C Hamano wrote:
Sébastien Guimmara [off-list ref] writes:
quoted
'git help' shows common commands in alphabetical order:
[...]
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:
Helped-by: Eric Sunshine [off-list ref]
Signed-off-by: Sébastien Guimmara <redacted>
I cannot exactly pinpoint what bothers me, but "The typical Git
workflow includes:" sounds a bit awkward.
What does a workflow "include"? [...]
Other than that, this round looks ready for 'next'.
I came to the same conclusion. FWIW, the entire series is:
Reviewed-by: Eric Sunshine <redacted>
I am not absolutely sure if new dependency on "awk" will not present
portability issues, though. So far we only used it in scripts in
the fringes and only a few tests.
The awk script restricts itself to POSIX, and I did test it on Linux,
Mac OS X, and FreeBSD, so it seems pretty portable. However, if it
worries you sufficiently, here's the equivalent Perl version:
From: Eric Sunshine <redacted>
Subject: [PATCH 3/5] generate-cmdlist: parse common group commands
Parse the group 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 the group block are emitted to
common_cmds[].
[commit message by Sébastien Guimmara [off-list ref]]
Signed-off-by: Eric Sunshine <redacted>
---
Makefile | 4 ++--
generate-cmdlist.perl | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
generate-cmdlist.sh | 23 -----------------------
3 files changed, 52 insertions(+), 25 deletions(-)
create mode 100755 generate-cmdlist.perl
delete mode 100755 generate-cmdlist.sh
diff --git a/Makefile b/Makefile
index 5ed0acf..c133a96 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.perl command-list.txt
common-cmds.h: $(wildcard Documentation/git-*.txt)
- $(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@
+ $(QUIET_GEN)$(PERL_PATH) generate-cmdlist.perl 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.perl b/generate-cmdlist.perl
new file mode 100755
index 0000000..31516e3
--- /dev/null
+++ b/generate-cmdlist.perl
@@ -0,0 +1,50 @@
+#!/usr/bin/perl
+use strict;
+use warnings;
+
+print <<"EOT";
+/* Automatically generated by $0 */
+
+struct cmdname_help {
+ char name[16];
+ char help[80];
+ unsigned char group;
+};
+
+static char *common_cmd_groups[] = {
+EOT
+
+my $n = 0;
+my %grp;
+while (<>) {
+ last if /^### command list/;
+ next if (1../^### common groups/) || /^#/ || /^\s*$/;
+ chop;
+ my ($k, $v) = split ' ', $_, 2;
+ $grp{$k} = $n++;
+ print "\tN_(\"$v\"),\n";
+}
+
+print "};\n\nstatic struct cmdname_help common_cmds[] = {\n";
+
+while (<>) {
+ next if /^#/ || /^\s*$/;
+ my @tags = split;
+ my $cmd = shift @tags;
+ for my $t (@tags) {
+ if (exists $grp{$t}) {
+ my $s;
+ open my $f, '<', "Documentation/$cmd.txt" or die;
+ while (<$f>) {
+ ($s) = /^$cmd - (.+)$/;
+ last if $s;
+ }
+ close $f;
+ $cmd =~ s/^git-//;
+ print "\t{\"$cmd\", N_(\"$s\"), $grp{$t}},\n";
+ last;
+ }
+ }
+}
+
+print "};\n";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.1.260.ga2776d4
--- >8 ---
On 05/18/2015 11:39 PM, Junio C Hamano wrote:
I cannot exactly pinpoint what bothers me, but "The typical Git
workflow includes:" sounds a bit awkward.
What does a workflow "include"? What are components included in a
workflow? Are "starting a repository", "working on a single thing",
"collabolating", etc. components that are incuded in a workflow?
If so, the fact that "clone", "init", etc. are "commands that are
commonly used in each component of the workflow" is a more important
thing to say; in other words, the header does not explain what list
it is presenting the user.
Or does a workflow consists of "clone", "init", "add", "mv", etc.
that are included in it? Then it is left unexplained what the
section headings stand for.
Perhaps something like
These are common Git commands used in various situations:
may lessen the uneasiness I felt above. I dunno.
This sounds better indeed.
Other than that, this round looks ready for 'next'.
I am not absolutely sure if new dependency on "awk" will not present
portability issues, though. So far we only used it in scripts in
the fringes and only a few tests.
Thanks.
We can use Eric's perl version instead of the awk one.
Should I make another series or amend this one ?
Thank you.