Re: [PATCH v11 5/5] help: respect new common command grouping

2015-05-25 Thread Sébastien Guimmara 



On 05/21/2015 08:04 PM, Eric Sunshine wrote:

On Thu, May 21, 2015 at 1:39 PM, Sébastien Guimmara
sebastien.guimm...@gmail.com wrote:

'git help' shows common commands in alphabetical order:

The most commonly used git commands are:
addAdd 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 most commonly used git commands are:


The above line in the commit message does not match the actual output:

 These are common Git commands used in various situations:



Thanks. Will correct this.


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)
addAdd file contents to the index
reset  Reset current HEAD to the specified state

examine the history and state (see also: git help revisions)
logShow commit logs
status Show the working tree status

[...]

Helped-by: Eric Sunshine sunsh...@sunshineco.com
Signed-off-by: Ramsay Jones ram...@ramsay1.demon.co.uk
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
diff --git a/help.c b/help.c
index 2072a87..8f72051 100644
--- a/help.c
+++ b/help.c
@@ -218,17 +218,39 @@ void list_commands(unsigned int colopts,
 }
  }

+static 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(_(These are common Git commands used in various situations:));
+
 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.GIT

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v11 2/5] command-list.txt: add the common groups block

2015-05-25 Thread Sébastien Guimmara 



On 05/21/2015 08:01 PM, Eric Sunshine wrote:

On Thu, May 21, 2015 at 1:39 PM, Sébastien Guimmara
sebastien.guimm...@gmail.com wrote:

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 block, and then assign a group to each
common command.

Helped-by: Eric Sunshine sunsh...@sunshineco.com
Helped-by: Junio C Hamano gits...@pobox.com
Helped-by:  Emma Jane Hogbin Westby emma.wes...@gmail.com
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
diff --git a/command-list.txt b/command-list.txt
index 181a9c2..32ddab3 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,3 +1,14 @@
+# common commands are grouped by themes
+# these groups are output by 'git help' in the order declared here.
+# map each common command in the command list to one of these groups.
+### common groups (do not change this line)
+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.


This is odd. The above line was removed in 1/5 but then re-appears
here in 2/5. I think the intent is that it should remain removed.


  ### command list (do not change this line)
  # command name  category [deprecated] [common]
  git-add mainporcelain common


My mistake. This will be corrected in the next version. Thank you for taking 
time
to review this series.

Sébastien
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v11 0/5] group common commands by theme

2015-05-21 Thread Sébastien Guimmara 
Just a minor change, the modification of new-command.txt was squashed to 
2/5 instead of 1/5.

Eric Sunshine (2):
  command-list: prepare machinery for upcoming common groups section
  generate-cmdlist: parse common group commands

Sébastien Guimmara (3):
  command-list.txt: add the common groups block
  command-list.txt: drop the common tag
  help: respect new common command grouping

 Documentation/cmd-list.perl |  4 +++
 Documentation/howto/new-command.txt |  4 ++-
 Makefile|  9 ---
 command-list.txt| 53 ++---
 generate-cmdlist.perl   | 50 ++
 generate-cmdlist.sh | 23 
 help.c  | 24 -
 7 files changed, 117 insertions(+), 50 deletions(-)
 create mode 100755 generate-cmdlist.perl
 delete mode 100755 generate-cmdlist.sh

-- 
2.4.0.GIT

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v11 2/5] command-list.txt: add the common groups block

2015-05-21 Thread Sébastien Guimmara 
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 block, and then assign a group to each
common command.

Add a block at the beginning of command-list.txt:

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  mainporcelaincommon worktree

Helped-by: Eric Sunshine sunsh...@sunshineco.com
Helped-by: Junio C Hamano gits...@pobox.com
Helped-by:  Emma Jane Hogbin Westby emma.wes...@gmail.com
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
 Documentation/howto/new-command.txt |  4 ++-
 command-list.txt| 51 ++---
 2 files changed, 34 insertions(+), 21 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 181a9c2..32ddab3 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,3 +1,14 @@
+# common commands are grouped by themes
+# these groups are output by 'git help' in the order declared here.
+# map each common command in the command list to one of these groups.
+### common groups (do not change this line)
+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 list (do not change this line)
 # command name  category [deprecated] [common]
 git-add mainporcelain common
@@ -6,24 +17,24 @@ 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-fileplumbinginterrogators
 git-check-attr  purehelpers
 git-check-ignorepurehelpers
 git-check-mailmap   purehelpers
-git-checkoutmainporcelain common
+git-checkoutmainporcelain   common history
 git-checkout-index  plumbingmanipulators
 git-check-ref-formatpurehelpers
 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
@@ -35,14 +46,14 @@ git-cvsimport   foreignscminterface
 git-cvsserver   foreignscminterface
 git-daemon  synchingrepositories
 git-describe

[PATCH v11 4/5] command-list.txt: drop the common tag

2015-05-21 Thread Sébastien Guimmara 
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  mainporcelaincommon worktree

after:
git-add  mainporcelainworktree

Helped-by: Eric Sunshine sunsh...@sunshineco.com
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
 command-list.txt | 42 +-
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/command-list.txt b/command-list.txt
index 32ddab3..9a98752 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 list (do not change this line)
 # command name  category [deprecated] [common]
-git-add mainporcelain common
+git-add mainporcelain   worktree
 git-am  mainporcelain
 git-annotateancillaryinterrogators
 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-fileplumbinginterrogators
 git-check-attr  purehelpers
 git-check-ignorepurehelpers
 git-check-mailmap   purehelpers
-git-checkoutmainporcelain   common history
+git-checkoutmainporcelain   history
 git-checkout-index  plumbingmanipulators
 git-check-ref-formatpurehelpers
 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-describemainporcelain
-git-diffmainporcelain   common history
+git-diffmainporcelain   history
 git-diff-files  plumbinginterrogators
 git-diff-index  plumbinginterrogators
 git-diff-tree   plumbinginterrogators
 git-difftoolancillaryinterrogators
 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-patchmainporcelain
 git-fsckancillaryinterrogators
 git-gc  mainporcelain
 git-get-tar-commit-id   ancillaryinterrogators
-git-grepmainporcelain   common info
+git-grepmainporcelain   info
 git-gui mainporcelain
 git-hash-object plumbingmanipulators
 git-helpancillaryinterrogators
@@ -71,17 +71,17 @@ git-http-fetch  synchelpers
 git-http-push   synchelpers
 git-imap-send   foreignscminterface
 git-index-pack  plumbingmanipulators
-git-initmainporcelain   common init
+git-init

[PATCH v10 4/5] command-list.txt: drop the common tag

2015-05-21 Thread Sébastien Guimmara 
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  mainporcelaincommon worktree

after:
git-add  mainporcelainworktree

Helped-by: Eric Sunshine sunsh...@sunshineco.com
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
 command-list.txt | 42 +-
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/command-list.txt b/command-list.txt
index 32ddab3..9a98752 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 list (do not change this line)
 # command name  category [deprecated] [common]
-git-add mainporcelain common
+git-add mainporcelain   worktree
 git-am  mainporcelain
 git-annotateancillaryinterrogators
 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-fileplumbinginterrogators
 git-check-attr  purehelpers
 git-check-ignorepurehelpers
 git-check-mailmap   purehelpers
-git-checkoutmainporcelain   common history
+git-checkoutmainporcelain   history
 git-checkout-index  plumbingmanipulators
 git-check-ref-formatpurehelpers
 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-describemainporcelain
-git-diffmainporcelain   common history
+git-diffmainporcelain   history
 git-diff-files  plumbinginterrogators
 git-diff-index  plumbinginterrogators
 git-diff-tree   plumbinginterrogators
 git-difftoolancillaryinterrogators
 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-patchmainporcelain
 git-fsckancillaryinterrogators
 git-gc  mainporcelain
 git-get-tar-commit-id   ancillaryinterrogators
-git-grepmainporcelain   common info
+git-grepmainporcelain   info
 git-gui mainporcelain
 git-hash-object plumbingmanipulators
 git-helpancillaryinterrogators
@@ -71,17 +71,17 @@ git-http-fetch  synchelpers
 git-http-push   synchelpers
 git-imap-send   foreignscminterface
 git-index-pack  plumbingmanipulators
-git-initmainporcelain   common init
+git-init

[PATCH v10 0/5] group common commands by theme

2015-05-21 Thread Sébastien Guimmara 
Same as v9 [1], with: 

* command-list.txt: reduce verbosity by squashing the two header lines
  into one:

### command list (do not change this line)

* include a missing update to new-command.txt.

[1] http://thread.gmane.org/gmane.comp.version-control.git/269496

Eric Sunshine (2):
  command-list: prepare machinery for upcoming common groups section
  generate-cmdlist: parse common group commands

Sébastien Guimmara (3):
  command-list.txt: add the common groups block
  command-list.txt: drop the common tag
  help: respect new common command grouping

 Documentation/cmd-list.perl |  4 +++
 Documentation/howto/new-command.txt |  4 ++-
 Makefile|  9 ---
 command-list.txt| 53 ++---
 generate-cmdlist.perl   | 50 ++
 generate-cmdlist.sh | 23 
 help.c  | 24 -
 7 files changed, 117 insertions(+), 50 deletions(-)
 create mode 100755 generate-cmdlist.perl
 delete mode 100755 generate-cmdlist.sh

-- 
2.4.0.GIT

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v10 2/5] command-list.txt: add the common groups block

2015-05-21 Thread Sébastien Guimmara 
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 block, and then assign a group to each
common command.

Add a block at the beginning of command-list.txt:

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  mainporcelaincommon worktree

Helped-by: Eric Sunshine sunsh...@sunshineco.com
Helped-by: Junio C Hamano gits...@pobox.com
Helped-by:  Emma Jane Hogbin Westby emma.wes...@gmail.com
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
 command-list.txt | 51 +++
 1 file changed, 31 insertions(+), 20 deletions(-)

diff --git a/command-list.txt b/command-list.txt
index 181a9c2..32ddab3 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,3 +1,14 @@
+# common commands are grouped by themes
+# these groups are output by 'git help' in the order declared here.
+# map each common command in the command list to one of these groups.
+### common groups (do not change this line)
+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 list (do not change this line)
 # command name  category [deprecated] [common]
 git-add mainporcelain common
@@ -6,24 +17,24 @@ 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-fileplumbinginterrogators
 git-check-attr  purehelpers
 git-check-ignorepurehelpers
 git-check-mailmap   purehelpers
-git-checkoutmainporcelain common
+git-checkoutmainporcelain   common history
 git-checkout-index  plumbingmanipulators
 git-check-ref-formatpurehelpers
 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
@@ -35,14 +46,14 @@ git-cvsimport   foreignscminterface
 git-cvsserver   foreignscminterface
 git-daemon  synchingrepositories
 git-describemainporcelain
-git-diffmainporcelain common
+git-diffmainporcelain   common history
 git-diff-files  plumbinginterrogators
 git-diff-index  plumbinginterrogators
 git-diff-tree   plumbinginterrogators
 git-difftoolancillaryinterrogators
 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
@@ -51,7 +62,7 @@ git-format-patch

[PATCH v10 5/5] help: respect new common command grouping

2015-05-21 Thread Sébastien Guimmara 
'git help' shows common commands in alphabetical order:

The most commonly used git commands are:
   addAdd 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:

These are common Git commands used in various situations:

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)
   addAdd file contents to the index
   reset  Reset current HEAD to the specified state

examine the history and state (see also: git help revisions)
   logShow commit logs
   status Show the working tree status

   [...]

Helped-by: Eric Sunshine sunsh...@sunshineco.com
Helped-by: Ramsay Jones ram...@ramsay1.demon.co.uk
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
 help.c | 24 +++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/help.c b/help.c
index 2072a87..8f72051 100644
--- a/help.c
+++ b/help.c
@@ -218,17 +218,39 @@ void list_commands(unsigned int colopts,
}
 }
 
+static 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(_(These are common Git commands used in various situations:));
+
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.GIT

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v10 1/5] command-list: prepare machinery for upcoming common groups section

2015-05-21 Thread Sébastien Guimmara 



On 05/21/2015 03:48 PM, Eric Sunshine wrote:

On Thu, May 21, 2015 at 9:13 AM, Sébastien Guimmara
sebastien.guimm...@gmail.com wrote:

From: Eric Sunshine sunsh...@sunshineco.com

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 sunsh...@sunshineco.com
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
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/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 squash the documentation update into patch 2/5
where the common groups block is actually introduced. It doesn't
really belong in this patch which is about updating machinery in
preparation for the new block.


I don't mind squashing it with another commit, but in this case, wouldn't it
make more sense to squash it with 4/5, when the 'common' tag is removed and the
file is in its final form ?



Also, it's now spelled ### common groups rather than [common].



actually, this [common] is not the one I added in a previous series,
but the one that was already present:

# command name  category [deprecated] [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 323c401..655740d 100644
--- a/Makefile
+++ b/Makefile
@@ -2455,7 +2455,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) ;; \
@@ -2463,7 +2463,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..181a9c2 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,4 +1,4 @@
-# List of known git commands.
+### command list (do not change this line)
  # command name  category [deprecated] [common]
  git-add mainporcelain common
  git-am  mainporcelain
--
2.4.0.GIT

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v11 1/5] command-list: prepare machinery for upcoming common groups section

2015-05-21 Thread Sébastien Guimmara 
From: Eric Sunshine sunsh...@sunshineco.com

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 sunsh...@sunshineco.com
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
 Documentation/cmd-list.perl | 4 
 Makefile| 5 +++--
 command-list.txt| 2 +-
 3 files changed, 8 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 323c401..655740d 100644
--- a/Makefile
+++ b/Makefile
@@ -2455,7 +2455,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) ;; \
@@ -2463,7 +2463,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..181a9c2 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,4 +1,4 @@
-# List of known git commands.
+### command list (do not change this line)
 # command name  category [deprecated] [common]
 git-add mainporcelain common
 git-am  mainporcelain
-- 
2.4.0.GIT

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v11 5/5] help: respect new common command grouping

2015-05-21 Thread Sébastien Guimmara 
'git help' shows common commands in alphabetical order:

The most commonly used git commands are:
   addAdd 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 most commonly used git commands are:

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)
   addAdd file contents to the index
   reset  Reset current HEAD to the specified state

examine the history and state (see also: git help revisions)
   logShow commit logs
   status Show the working tree status

   [...]

Helped-by: Eric Sunshine sunsh...@sunshineco.com
Signed-off-by: Ramsay Jones ram...@ramsay1.demon.co.uk
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
 help.c | 24 +++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/help.c b/help.c
index 2072a87..8f72051 100644
--- a/help.c
+++ b/help.c
@@ -218,17 +218,39 @@ void list_commands(unsigned int colopts,
}
 }
 
+static 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(_(These are common Git commands used in various situations:));
+
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.GIT

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v11 3/5] generate-cmdlist: parse common group commands

2015-05-21 Thread Sébastien Guimmara 
From: Eric Sunshine sunsh...@sunshineco.com

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 sebastien.guimm...@gmail.com]

Signed-off-by: Eric Sunshine sunsh...@sunshineco.com
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
 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 655740d..54ec511 100644
--- a/Makefile
+++ b/Makefile
@@ -1694,10 +1694,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 000..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..000
--- 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.GIT

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v9 3/5] generate-cmdlist: parse common group commands

2015-05-20 Thread Sébastien Guimmara 

On 05/20/2015 09:32 PM, Stefan Beller wrote:

On Wed, May 20, 2015 at 12:27 PM, Sébastien Guimmara
sebastien.guimm...@gmail.com wrote:

On 05/20/2015 09:22 PM, Sébastien Guimmara wrote:


From: Eric Sunshine sunsh...@sunshineco.com



It looks like 'git send-email' got confused with the CC field.
I'm sorry for that.



It's to keep authorship.

When Junio picks it up, this will show as
authored by Eric, signed off by both of you (Eric+Sébastien)
and committed by Junio.



So it's not a mistake ? I thought the 'From:' line was the email header
as generated by git send-email that got wrongly included in the body.
My mistake then.
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v9 5/5] help: respect new common command grouping

2015-05-20 Thread Sébastien Guimmara 

On 05/20/2015 11:39 PM, Ramsay Jones wrote:

On 20/05/15 20:23, Sébastien Guimmara wrote:


Helped-by: Eric Sunshine sunsh...@sunshineco.com
Signed-off-by: Ramsay Jones ram...@ramsay1.demon.co.uk


This should be (at most) 'Helped-by:' - my 'contribution' was
so minor that even a 'Helped-by:' is generous! :-D

ATB,
Ramsay Jones


Ha! I'm still not very comfortable with picking the right
attribution...
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v9 3/5] generate-cmdlist: parse common group commands

2015-05-20 Thread Sébastien Guimmara 

On 05/20/2015 09:22 PM, Sébastien Guimmara wrote:

From: Eric Sunshine sunsh...@sunshineco.com



It looks like 'git send-email' got confused with the CC field.
I'm sorry for that.
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v9 2/5] command-list.txt: add the common groups block

2015-05-20 Thread Sébastien Guimmara 



On 05/20/2015 09:48 PM, Eric Sunshine wrote:

On Wed, May 20, 2015 at 3:22 PM, Sébastien Guimmara
sebastien.guimm...@gmail.com wrote:

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 block, and then assign a group to each
common command.

Add a block at the beginning of command-list.txt:

 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  mainporcelaincommon worktree

Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
  command-list.txt | 50 ++
  1 file changed, 30 insertions(+), 20 deletions(-)


Hmm, did your update to Documentation/technical/new-command.txt get
lost? I don't see it any of the patches, but would have expected it to
be included in this patch which introduces the common groups
section.



Ah, you're right. A commit got lost in the process. Will fix that. Thanks.


diff --git a/command-list.txt b/command-list.txt
index 609b344..c2bbdc1 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,3 +1,13 @@
+# common commands are grouped by themes output by 'git help'
+# map each common command in the command list to one of these groups.


Discussed previously: It also would be a good idea to mention that the
order in which git help displays the groups themselves is the order
they are declared here. Maybe just add one more line between the two
you already have above:

 # groups are output by 'git help' in the order declared here.



Indeed, I'll add the mention.


+### common groups


In the block below, the ### command list line is protected by a #
do not molest the next line warning. Perhaps the same should be done
here? Alternately, make them more compact by incorporating the
warning:

 ### common groups (do not change this line)
 ...
 ### command list (do not change this line)

?



Yes, it's better. I shall modify this.


+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.
  # do not molest the next line
  ### command list
  # command name  category [deprecated] [common]

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v9 5/5] help: respect new common command grouping

2015-05-20 Thread Sébastien Guimmara 
'git help' shows common commands in alphabetical order:

The most commonly used git commands are:
   addAdd 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:

These are common Git commands used in various situations:

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)
   addAdd file contents to the index
   reset  Reset current HEAD to the specified state

examine the history and state (see also: git help revisions)
   logShow commit logs
   status Show the working tree status

   [...]

Helped-by: Eric Sunshine sunsh...@sunshineco.com
Signed-off-by: Ramsay Jones ram...@ramsay1.demon.co.uk
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
 help.c | 24 +++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/help.c b/help.c
index 2072a87..8f72051 100644
--- a/help.c
+++ b/help.c
@@ -218,17 +218,39 @@ void list_commands(unsigned int colopts,
}
 }
 
+static 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(_(These are common Git commands used in various situations:));
+
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.GIT

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v9 3/5] generate-cmdlist: parse common group commands

2015-05-20 Thread Sébastien Guimmara 
From: Eric Sunshine sunsh...@sunshineco.com

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 sebastien.guimm...@gmail.com]

Signed-off-by: Eric Sunshine sunsh...@sunshineco.com
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
 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 655740d..54ec511 100644
--- a/Makefile
+++ b/Makefile
@@ -1694,10 +1694,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 000..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..000
--- 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.GIT

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v9 2/5] command-list.txt: add the common groups block

2015-05-20 Thread Sébastien Guimmara 
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 block, and then assign a group to each
common command.

Add a block at the beginning of command-list.txt:

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  mainporcelaincommon worktree

Helped-by: Eric Sunshine sunsh...@sunshineco.com
Helped-by: Junio C Hamano gits...@pobox.com
Helped-by:  Emma Jane Hogbin Westby emma.wes...@gmail.com
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
 command-list.txt | 50 ++
 1 file changed, 30 insertions(+), 20 deletions(-)

diff --git a/command-list.txt b/command-list.txt
index 609b344..c2bbdc1 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,3 +1,13 @@
+# common commands are grouped by themes output by 'git help'
+# map each common command in the command list to one of these groups.
+### common groups
+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.
 # do not molest the next line
 ### command list
 # command name  category [deprecated] [common]
@@ -7,24 +17,24 @@ 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-fileplumbinginterrogators
 git-check-attr  purehelpers
 git-check-ignorepurehelpers
 git-check-mailmap   purehelpers
-git-checkoutmainporcelain common
+git-checkoutmainporcelain   common history
 git-checkout-index  plumbingmanipulators
 git-check-ref-formatpurehelpers
 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-describemainporcelain
-git-diffmainporcelain common
+git-diffmainporcelain   common history
 git-diff-files  plumbinginterrogators
 git-diff-index  plumbinginterrogators
 git-diff-tree   plumbinginterrogators
 git-difftoolancillaryinterrogators
 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-patchmainporcelain
 git-fsckancillaryinterrogators
 git-gc

[PATCH v9 1/5] command-list: prepare machinery for upcoming common groups section

2015-05-20 Thread Sébastien Guimmara 
From: Eric Sunshine sunsh...@sunshineco.com

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 sunsh...@sunshineco.com
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.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 323c401..655740d 100644
--- a/Makefile
+++ b/Makefile
@@ -2455,7 +2455,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) ;; \
@@ -2463,7 +2463,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.0.GIT

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v9 4/5] command-list.txt: drop the common tag

2015-05-20 Thread Sébastien Guimmara 
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  mainporcelaincommon worktree

after:
git-add  mainporcelainworktree

Helped-by: Eric Sunshine sunsh...@sunshineco.com
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
 command-list.txt | 42 +-
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/command-list.txt b/command-list.txt
index c2bbdc1..080d6d9 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -11,30 +11,30 @@ remote   collaborate (see also: git help workflows)
 # do not molest the next line
 ### command list
 # command name  category [deprecated] [common]
-git-add mainporcelain common
+git-add mainporcelain   worktree
 git-am  mainporcelain
 git-annotateancillaryinterrogators
 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-fileplumbinginterrogators
 git-check-attr  purehelpers
 git-check-ignorepurehelpers
 git-check-mailmap   purehelpers
-git-checkoutmainporcelain   common history
+git-checkoutmainporcelain   history
 git-checkout-index  plumbingmanipulators
 git-check-ref-formatpurehelpers
 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-describemainporcelain
-git-diffmainporcelain   common history
+git-diffmainporcelain   history
 git-diff-files  plumbinginterrogators
 git-diff-index  plumbinginterrogators
 git-diff-tree   plumbinginterrogators
 git-difftoolancillaryinterrogators
 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-patchmainporcelain
 git-fsckancillaryinterrogators
 git-gc  mainporcelain
 git-get-tar-commit-id   ancillaryinterrogators
-git-grepmainporcelain   common info
+git-grepmainporcelain   info
 git-gui mainporcelain
 git-hash-object plumbingmanipulators
 git-helpancillaryinterrogators
@@ -71,17 +71,17 @@ git-http-fetch  synchelpers
 git-http-push   synchelpers
 git-imap-send   foreignscminterface
 git-index-pack  plumbingmanipulators
-git-initmainporcelain   common init
+git-init

[PATCH v9 0/5] group common commands by theme

2015-05-20 Thread Sébastien Guimmara 
The major modification of this reroll [1] is the use of the perl version
of generate-cmdlist instead of the awk one.

help.c:
1. change the introductory message from:
The typical Git workflow includes:
to:
These are common Git commands used in various situations:

2. include Ramsay's patch [2]

[1]: v8: http://thread.gmane.org/gmane.comp.version-control.git/269305
[2]: http://thread.gmane.org/gmane.comp.version-control.git/269387

Eric Sunshine (2):
  command-list: prepare machinery for upcoming common groups section
  generate-cmdlist: parse common group commands

Sébastien Guimmara (3):
  command-list.txt: add the common groups block
  command-list.txt: drop the common tag
  help: respect new common command grouping

 Documentation/cmd-list.perl |  4 
 Makefile|  9 
 command-list.txt| 53 +++--
 generate-cmdlist.perl   | 50 ++
 generate-cmdlist.sh | 23 
 help.c  | 24 +++-
 6 files changed, 114 insertions(+), 49 deletions(-)
 create mode 100755 generate-cmdlist.perl
 delete mode 100755 generate-cmdlist.sh

-- 
2.4.0.GIT

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v7 2/5] command-list.txt: add a [common] block

2015-05-15 Thread 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  mainporcelaincommon worktree

Helped-by: Eric Sunshine sunsh...@sunshineco.com
Helped-by: Junio C Hamano gits...@pobox.com
Helped-by:  Emma Jane Hogbin Westby emma.wes...@gmail.com
Signed-off-by: Sébastien Guimmara sebastien.guimm...@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-annotateancillaryinterrogators
 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-fileplumbinginterrogators
 git-check-attr  purehelpers
 git-check-ignorepurehelpers
 git-check-mailmap   purehelpers
-git-checkoutmainporcelain common
+git-checkoutmainporcelain   common history
 git-checkout-index  plumbingmanipulators
 git-check-ref-formatpurehelpers
 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-describemainporcelain
-git-diffmainporcelain common
+git-diffmainporcelain   common history
 git-diff-files  plumbinginterrogators
 git-diff-index  plumbinginterrogators
 git-diff-tree   plumbinginterrogators
 git-difftoolancillaryinterrogators
 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-patchmainporcelain
 git-fsckancillaryinterrogators
 git-gc  mainporcelain

[PATCH v5 1/6] generate-cmdlist: parse common group commands

2015-05-09 Thread Sébastien Guimmara 
Parse the [common] block to create the array of group descriptions:

static char *common_cmd_groups[] = {
N_(start a working area (see also: git help tutorial)),
N_(work on the current change (see also: git help everyday)),
N_(examine the history and state (see also: git help revisions)),
N_(grow, mark and tweak your history),
N_(collaborate (see also: git help workflows)),
};

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.guimm...@gmail.com]

Signed-off-by: Eric Sunshine sunsh...@sunshineco.com
---
 generate-cmdlist.awk | 38 ++
 1 file changed, 38 insertions(+)
 create mode 100644 generate-cmdlist.awk

diff --git a/generate-cmdlist.awk b/generate-cmdlist.awk
new file mode 100644
index 000..cbaac88
--- /dev/null
+++ b/generate-cmdlist.awk
@@ -0,0 +1,38 @@
+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
+}
+/\[common\]/ {
+   state = 1
+}
+END { print }; }
-- 
2.4.0

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v5 5/6] new-command.txt: mention the common command groups

2015-05-09 Thread Sébastien Guimmara 
In the 6. step, add information about the common group commands
found in command-list.txt.

Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
 Documentation/howto/new-command.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/howto/new-command.txt 
b/Documentation/howto/new-command.txt
index d7de5a3..e7b0cc2 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's 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
-- 
2.4.0

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v5 3/6] command-list.txt: group common commands by theme

2015-05-09 Thread Sébastien Guimmara 
Declare groups for common commands in the [common] block,
followed by group names and descriptions:

[common]
init start a working area (see also: git help tutorial)
worktree work on the current change (see also: git [...]
info examine the history and state (see also: git [...]
history  grow, mark and tweak your history
remote   collaborate (see also: git help workflows)

Some descriptions include a 'see also' to redirect user to more
detailed documentation.

Then, in the [commands] block, map all common commands with a group:

[commands]
git-addmainporcelain worktree
git-branch mainporcelain history
git-checkout   mainporcelain history
[...]

So that 'git help' outputs those commands in headered groups.

Helped-by: Junio C Hamano gits...@pobox.com
Helped-by:  Emma Jane Hogbin Westby emma.wes...@gmail.com
Signed-off-by: Sébastien Guimmara sebastien.guimm...@gmail.com
---
 command-list.txt | 56 ++--
 1 file changed, 34 insertions(+), 22 deletions(-)

diff --git a/command-list.txt b/command-list.txt
index f1eae08..7e7ce53 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,29 +1,41 @@
+# common commands are grouped by themes
+# this order is the same that output by 'git help'
+# map each common commands in the [commands] list to one of the groups.
+# a command should not be marked both [deprecated] and [common]
+[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]
-git-add mainporcelain common
+# command name [deprecated] category[common]
+[commands]
+git-add mainporcelain   worktree
 git-am  mainporcelain
 git-annotateancillaryinterrogators
 git-apply   plumbingmanipulators
 git-archimport  foreignscminterface
 git-archive mainporcelain
-git-bisect  mainporcelain common
+git-bisect  mainporcelain   info
 git-blame   ancillaryinterrogators
-git-branch  mainporcelain common
+git-branch  mainporcelain   history
 git-bundle  mainporcelain
 git-cat-fileplumbinginterrogators
 git-check-attr  purehelpers
 git-check-ignorepurehelpers
 git-check-mailmap   purehelpers
-git-checkoutmainporcelain common
+git-checkoutmainporcelain   history
 git-checkout-index  plumbingmanipulators
 git-check-ref-formatpurehelpers
 git-cherry  ancillaryinterrogators
 git-cherry-pick mainporcelain
 git-citool  mainporcelain
 git-clean   mainporcelain
-git-clone   mainporcelain common
+git-clone   mainporcelain   init
 git-column  purehelpers
-git-commit  mainporcelain common
+git-commit  mainporcelain   history
 git-commit-tree plumbingmanipulators
 git-config  ancillarymanipulators
 git-count-objects   ancillaryinterrogators
@@ -35,14 +47,14 @@ git-cvsimport   foreignscminterface
 git-cvsserver   foreignscminterface
 git-daemon  synchingrepositories
 git-describemainporcelain
-git-diffmainporcelain common
+git-diffmainporcelain   history
 git-diff-files  plumbinginterrogators
 git-diff-index  plumbinginterrogators
 git-diff-tree   plumbinginterrogators
 git-difftoolancillaryinterrogators
 git-fast-exportancillarymanipulators
 git-fast-importancillarymanipulators
-git-fetch   mainporcelain common
+git-fetch   mainporcelain   remote
 git-fetch-pack