Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header
- From
Eric Sunshine <sunshine@sunshineco.com>
- Date
- May 15, 2015, 23:55 UTC
- Message-ID
- <20150515235534.GA31000@flurp.local>
- In-Reply-To
- <xmqqegmhfpeb.fsf@gitster.dls.corp.google.com>
On Fri, May 15, 2015 at 03:26:52PM -0700, Junio C Hamano wrote:
Show 16 quoted lines
> Eric Sunshine <sunshine@sunshineco.com> writes: > > On Fri, May 15, 2015 at 4:44 PM, Junio C Hamano <gitster@pobox.com> wrote: > >> I was just pointing out that you did not even have to have patch > >> 1/5. > > > > Is that entirely accurate? The machinery (Makefiles, cmd-list.perl) > > does have to be updated at some point to skip the "common" block which > > get added in patch 2/5. > > That is true, but if "# List of known git commands" instead of > [commands] were used as the separator line, 1/5 wouldn't have needed > any change to the Makefile. > > Of course, if you need to add lines that would appear as junk to the > old parser (e.g. the grouping info), at that point you would of > course need to tell the parser to skip them.
Right. Preparing the machinery for the the upcoming "common" group was actually the intent of patch 1/5 in the proposal[1]. Introducing the [commands] header at that stage was merely a rather ugly implementation detail of that goal, and I wasn't particularly happy about suggesting it due to its ugliness. Unfortunately, the 1/5 commit message didn't clarify the matter. So, your observation of the seeming pointlessness of patch 1/5 (which adds the [commands] header for apparently no good reason) is quite understandable.
A more properly focused commit message (along with your suggestion to scan for a comment or other separator) might help to salvage 1/5. Perhaps something like this:
--- >8 --- From: Eric Sunshine <sunshine@sunshineco.com> Subject: [PATCH 1/5] command-list: prepare machinery for upcoming "common groups" section
The ultimate goal is for "git help" to classify common commands by group. Toward this end, a subsequent patch will add a new "common groups" section to command-list.txt preceding the actual command list. As preparation, teach existing command-list.txt parsing machinery, which doesn't care about grouping, to skip over this upcoming "common groups" section.
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> --- Documentation/cmd-list.perl | 4 ++++ Makefile | 5 +++-- command-list.txt | 3 ++- 3 files changed, 9 insertions(+), 3 deletions(-)
diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index 04f9977..5aa73cf 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -38,6 +38,10 @@ sub format_one { } } +while (<>) { + last if /^### command list/; +} + my %cmds = (); for (sort <>) { next if /^#/; diff --git a/Makefile b/Makefile index 25a453b..5ed0acf 100644 --- a/Makefile +++ b/Makefile @@ -2454,7 +2454,7 @@ check-docs:: esac ; \ test -f "Documentation/$$v.txt" || \ echo "no doc: $$v"; \ - sed -e '/^#/d' command-list.txt | \ + sed -e '1,/^### command list/d' -e '/^#/d' command-list.txt | \ grep -q "^$$v[ ]" || \ case "$$v" in \ git) ;; \ @@ -2462,7 +2462,8 @@ check-docs:: esac ; \ done; \ ( \ - sed -e '/^#/d' \ + sed -e '1,/^### command list/d' \ + -e '/^#/d' \ -e 's/[ ].*//' \ -e 's/^/listed /' command-list.txt; \ $(MAKE) -C Documentation print-man1 | \ diff --git a/command-list.txt b/command-list.txt index 54d8d21..609b344 100644 --- a/command-list.txt +++ b/command-list.txt @@ -1,4 +1,5 @@ -# List of known git commands. +# do not molest the next line +### command list # command name category [deprecated] [common] git-add mainporcelain common git-am mainporcelain
-- 2.4.1.260.ga2776d4 --- >8 --- [1]: http://article.gmane.org/gmane.comp.version-control.git/268756