[PATCH] Add help details to git help command.

[PATCH] Add help details to git help command.

[Steven Cole]

There's a patch at the bottom of this, so please look at that first before
my reading my whining immediately below.

I'm having some troubles with git pull, so this is just an ordinary diff.
Otherwise, I would have used the in-house diff command.

<troubles>
patch: **** Only garbage was found in the patch input.
</troubles>
<more troubles>
Tracked branch, applying changes...
error: bad signature
error: verify header failed
read_cache: Invalid argument
error: bad signature
error: verify header failed
error: bad signature
error: verify header failed
</more troubles>

Anyway, it's late, and I'm sure there is an easy fix to the above.

Here is a patch which provides the comment lines in the associated
script files when the git help command is invoked with an argument
thusly:

[steven@spc git-pasky-new]$ ./git help merge

 Merge a branch to the current tree.
 Copyright (c) Petr Baudis, 2005

 Takes a parameter identifying the branch to be merged.
 Optional "-b base_commit" parameter specifies the base for the
 merge. "-a" parameter may come first to tell git merge
 to check out the full tree to the merge tree.

 It creates a new ,,merge/ directory, which is git-controlled
 but has only the changed files checked out. You then have to
 examine it and then do git commit, which will also automatically
 bring your working tree up-to-date.

---------
This patch will provide the comment lines in the shell script associated
with the command, cleaned up a bit for presentation.

BUGS: This will also print any comments in the entire file, which may
not be desired.  If a command name and shell script filename
do not follow the usual convention, this won't work, e.g. ci for commit.

Signed-off-by: Steven Cole <elenstev@mesatop.com>

--- gp-newest-orig/git	2005-04-17 22:16:55.000000000 -0600
+++ gp-newest/git	2005-04-17 22:19:49.000000000 -0600
@@ -19,6 +19,11 @@
 
 
 help () {
+
+command=$1
+scriptfile=git$command.sh
+
+if [ ! $command ]; then
 	cat <<__END__
 The GIT scripted toolkit  $(gitversion.sh)
 
@@ -48,7 +53,10 @@
 	update		COMMIT_ID
 	version
 
+Additional help is available with: git help COMMAND
+
 Note that these expressions can be used interchangably as "ID"s:
+
 	empty string (current HEAD)
 	local (the local branch if tracking a remote one)
 	remote name (as registered with git addremote)
@@ -57,6 +65,10 @@
 	commit object hash (as returned by commit-id)
 	tree object hash (accepted only by some commands)
 __END__
+fi
+if [ ! $scriptfile = "git.sh" ]; then
+grep ^# $scriptfile | grep -v "!/bin" | cut -c 2-
+fi
 }
 
 

Re: [PATCH] Add help details to git help command.

[Petr Baudis]

Dear diary, on Mon, Apr 18, 2005 at 06:42:26AM CEST, I got a letter
where Steven Cole <elenstev@mesatop.com> told me that...
> There's a patch at the bottom of this, so please look at that first before
> my reading my whining immediately below.
> 
> I'm having some troubles with git pull, so this is just an ordinary diff.
> Otherwise, I would have used the in-house diff command.
> 
> <troubles>
> patch: **** Only garbage was found in the patch input.
> </troubles>
> <more troubles>
> Tracked branch, applying changes...
> error: bad signature
> error: verify header failed
> read_cache: Invalid argument
> error: bad signature
> error: verify header failed
> error: bad signature
> error: verify header failed
> </more troubles>

read-tree $(tree-id) && update-cache --refresh

The directory cache format changed, so it causes this. I'm hoping to
release 0.5 with good cache prepackaged Real Soon Now (tm). :-)

Note that then you will have to recover from the failed apply. If you
had no local commits, it is easy - put that two IDs git pull told
you to git diff and pipe it to git apply. If you had local commits, and
have already GIT version with merge-base, do just git merge pasky and
proceed with the merge. If you don't have merge-base, pass the first
ID from git track to git merge with the -b argument.

> This patch will provide the comment lines in the shell script associated
> with the command, cleaned up a bit for presentation.
> 
> BUGS: This will also print any comments in the entire file, which may
> not be desired.  If a command name and shell script filename
> do not follow the usual convention, this won't work, e.g. ci for commit.

Hey, those BUGS are the only slightly non-trivial thing on the whole
thing! I could do this patch myself... ;-) Also, you don't want to print
the first newline and the Copyright notices.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
C++: an octopus made by nailing extra legs onto a dog. -- Steve Taylor

Re: [PATCH] Add help details to git help command.

[Steven Cole]

Petr Baudis wrote:
> Dear diary, on Mon, Apr 18, 2005 at 06:42:26AM CEST, I got a letter
> where Steven Cole <elenstev@mesatop.com> told me that...
[snippage]
> 
>>This patch will provide the comment lines in the shell script associated
>>with the command, cleaned up a bit for presentation.
>>
>>BUGS: This will also print any comments in the entire file, which may
>>not be desired.  If a command name and shell script filename
>>do not follow the usual convention, this won't work, e.g. ci for commit.
> 
> 
> Hey, those BUGS are the only slightly non-trivial thing on the whole
> thing! I could do this patch myself... ;-) Also, you don't want to print
> the first newline and the Copyright notices.
> 

Fixed extra vertical whitespace, Copyright notice problems, and issue
with git help ci.

Here's a better version.  Didn't fix the more interesting bugs, as I'm
pressed for time (aren't we all).  Perhaps someone can polish this up.

Anyway, I think it's pretty useful in its present form.

Thanks,
Steven

---------

This patch will provide the comment lines in the shell script associated
with the command, cleaned up a bit for presentation.

BUGS: This will also print any comments in the entire file, which may
not be desired.  If a command name and shell script filename
do not follow the usual convention, this won't work.

git: b648169640025bd68d1b27a0fcc85b65d85e4440
--- git
+++ git	2005-04-18 10:34:17.000000000 -0600
@@ -19,6 +19,11 @@


  help () {
+
+command=$1
+scriptfile=git$command.sh
+
+if [ ! $command ]; then
  	cat <<__END__
  The GIT scripted toolkit  $(gitversion.sh)

@@ -48,7 +53,10 @@
  	track		[RNAME]
  	version

+Additional help is available with: git help COMMAND
+
  Note that these expressions can be used interchangably as "ID"s:
+
  	empty string (current HEAD)
  	local (the local branch if tracking a remote one)
  	remote name (as registered with git addremote)
@@ -57,6 +65,14 @@
  	commit object hash (as returned by commit-id)
  	tree object hash (accepted only by some commands)
  __END__
+fi
+if [ $scriptfile = "gitci.sh" ]; then
+	scriptfile="gitcommit.sh"
+fi
+if [ ! $scriptfile = "git.sh" ]; then
+	grep ^# $scriptfile | grep -v "!/bin" | grep -v "(c)" \
+	| cut -c 2- | grep ^.
+fi
  }

[RFC] Another way to provide help details. (was Re: [PATCH] Add help details to git help command.)

[Steven Cole]

On Monday 18 April 2005 10:59 am, Steven Cole wrote:
> Petr Baudis wrote:
> > Dear diary, on Mon, Apr 18, 2005 at 06:42:26AM CEST, I got a letter
> > where Steven Cole <elenstev@mesatop.com> told me that...
> [snippage]
> > 
> >>This patch will provide the comment lines in the shell script associated
> >>with the command, cleaned up a bit for presentation.
> >>
> >>BUGS: This will also print any comments in the entire file, which may
> >>not be desired.  If a command name and shell script filename
> >>do not follow the usual convention, this won't work, e.g. ci for commit.
> > 
> > 
> > Hey, those BUGS are the only slightly non-trivial thing on the whole
> > thing! I could do this patch myself... ;-) Also, you don't want to print
> > the first newline and the Copyright notices.

Here is perhaps a better way to provide detailed help for each
git command.  A command.help file for each command can be
written in the style of a man page.

The modfication to the main git script will be trivial. 
Here are the two commands I've done so far.

What do folks think about this approach?

Steven

[steven@spc git-pasky]$ ./git help add
NAME
        add - Add new file or files to a GIT repository.

SYNOPSIS
        add FILE...

DESCRIPTION
        Takes a list of file names at the command line, and schedules them
        for addition to the GIT repository at the next commit.

AUTHOR
        Written by Petr Baudis.

REPORTING BUGS
        Report bugs to <git@vger.kernel.org>

COPYRIGHT
        Copyright (c) Petr Baudis, 2005

BUGS
        Those files are omitted from show-diff output!

SEE ALSO
        The source code for this command is gitadd.sh.

[steven@spc git-pasky]$ ./git help addremote
NAME
        addremote -  Add new "remote" to the GIT repository.

SYNOPSIS
        addremote RNAME RSYNC_URL

DESCRIPTION
        Takes the remote's name and rsync URL.

        After you add a remote, you can "git pull" it whenever you want
        and it will keep your dircache in sync with it. Its latest commit
        is accessible as .git/heads/remotename (or - more conveniently -
        as $(commit-id remotename)). For example, to make a diff between
        Linus (after you added him) and your current tree, do

        git pull linus
        git diff $(commit-id linus)

AUTHOR
        Written by Petr Baudis.

REPORTING BUGS
        Report bugs to <git@vger.kernel.org>

COPYRIGHT
        Copyright (c) Petr Baudis, 2005

TODO
        gitdiff.sh et al should accept remote names as ids.

SEE ALSO
        The source code for this command is gitaddremote.sh.

Re: [RFC] Another way to provide help details. (was Re: [PATCH] Add help details to git help command.)

[Petr Baudis]

Dear diary, on Tue, Apr 19, 2005 at 03:40:54AM CEST, I got a letter
where Steven Cole <elenstev@mesatop.com> told me that...
> Here is perhaps a better way to provide detailed help for each
> git command.  A command.help file for each command can be
> written in the style of a man page.

I don't like it. I think the 'help' command should serve primarily as a
quick reference, which does not blend so well with a manual page - it's
too long and too convoluted by repeated output.

I'd just print the top comment from each file. :-)

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
C++: an octopus made by nailing extra legs onto a dog. -- Steve Taylor

Re: [RFC] Another way to provide help details. (was Re: [PATCH] Add help details to git help command.)

[David Greaves]

Petr Baudis wrote:
> Dear diary, on Tue, Apr 19, 2005 at 03:40:54AM CEST, I got a letter
> where Steven Cole <elenstev@mesatop.com> told me that...
> 
>>Here is perhaps a better way to provide detailed help for each
>>git command.  A command.help file for each command can be
>>written in the style of a man page.
> 
> 
> I don't like it. I think the 'help' command should serve primarily as a
> quick reference, which does not blend so well with a manual page - it's
> too long and too convoluted by repeated output.
> 
> I'd just print the top comment from each file. :-)
> 

On the other hand, having more complete docs seems like an excellent 
idea (and other threads support that)
I'd certainly like to see more specification oriented documentation...
(even if it turns out to be disposable)

Steven, if you carry on sending more verbose docs I'll certainly read 
and work with you on editing them...

Nb kernel-doc doesn't seem appropriate for user level docs.
maybe, whilst there's so much flux, have:
   git man command
that just outputs text

If Petr wants the top comment to be extracted by help then maybe a 
bottom comment block could contain the more complete text?
I *really* think that the user docs should live in the source for now 
(hence I think that git man is better than going straight to man/docbook).

I wasn't sure whether to perlise the code or do a shell-lib - but 
looking at the algorithms needed in things like git status I reckon the 
shell will end up becoming a hackish mess of awk/sed/tr/sort/uniq/pipe 
(ie perl) anyway.

So I'm going to have a go at that - Petr, if you have a minute could you 
send me, off list, a bit of perl code that epitomises the style you like?

David

Re: [RFC] Another way to provide help details. (was Re: [PATCH] Add help details to git help command.)

[Steven Cole]

David Greaves wrote:
> Petr Baudis wrote:
> 
>> Dear diary, on Tue, Apr 19, 2005 at 03:40:54AM CEST, I got a letter
>> where Steven Cole <elenstev@mesatop.com> told me that...
>>
>>> Here is perhaps a better way to provide detailed help for each
>>> git command.  A command.help file for each command can be
>>> written in the style of a man page.
>>
>>
>>
>> I don't like it. I think the 'help' command should serve primarily as a
>> quick reference, which does not blend so well with a manual page - it's
>> too long and too convoluted by repeated output.
>>
>> I'd just print the top comment from each file. :-)
>>
> 
> On the other hand, having more complete docs seems like an excellent 
> idea (and other threads support that)
> I'd certainly like to see more specification oriented documentation...
> (even if it turns out to be disposable)
> 
> Steven, if you carry on sending more verbose docs I'll certainly read 
> and work with you on editing them...

I only did those first two as a straw man.  Doing the others is a couple
hours (or less) work, but I don't want to do it if folks don't want it.

Having the help files separate has advantages/disadvantages.

> 
> Nb kernel-doc doesn't seem appropriate for user level docs.
> maybe, whilst there's so much flux, have:
>   git man command
> that just outputs text
> 
> If Petr wants the top comment to be extracted by help then maybe a 
> bottom comment block could contain the more complete text?
> I *really* think that the user docs should live in the source for now 
> (hence I think that git man is better than going straight to man/docbook).
> 
> I wasn't sure whether to perlise the code or do a shell-lib - but 
> looking at the algorithms needed in things like git status I reckon the 
> shell will end up becoming a hackish mess of awk/sed/tr/sort/uniq/pipe 
> (ie perl) anyway.
> 
> So I'm going to have a go at that - Petr, if you have a minute could you 
> send me, off list, a bit of perl code that epitomises the style you like?
> 
> David
> 

Funny you should mention Perl.  Here is small bit of code:

[steven@spc0 git-pasky-testing]$ cat print_help_header.pl
#!/usr/bin/perl
# reads from stdin   writes to stdout  no error checking
<STDIN>;<STDIN>;
while (substr( $line=<STDIN>, 0, 1) eq "#") {
                  print $line;
}

[steven@spc0 git-pasky-testing]$ ./print_help_header.pl <gitdiff.sh | grep ^# | grep -v "(c)" | cut -c 3-
Make a diff between two GIT trees.

By default compares the current working tree to the state at the
last commit. You can specify -r rev1:rev2 or -r rev1 -r rev2 to
tell it to make a diff between the specified revisions. If you
do not specify a revision, the current working tree is implied
(note that no revision is different from empty revision - -r rev:
compares between rev and HEAD, while -r rev compares between rev
and working tree).

-p instead of one ID denotes a parent commit to the specified ID
(which must not be a tree, obviously).

Outputs a diff converting the first tree to the second one.
-------end of output from perl plus grep and cut.

Without the perl, extra comments came out (plus the dreaded first blank line).


[steven@spc0 git-pasky-testing]$ cat gitdiff.sh | grep -v "/bin" | grep ^# | grep -v "(c)" | cut -c 3-

Make a diff between two GIT trees.

By default compares the current working tree to the state at the
last commit. You can specify -r rev1:rev2 or -r rev1 -r rev2 to
tell it to make a diff between the specified revisions. If you
do not specify a revision, the current working tree is implied
(note that no revision is different from empty revision - -r rev:
compares between rev and HEAD, while -r rev compares between rev
and working tree).

-p instead of one ID denotes a parent commit to the specified ID
(which must not be a tree, obviously).

Outputs a diff converting the first tree to the second one.
FIXME: The commandline parsing is awful.
-------end of output from grep and cut.

David,

I'm a bit pressed for time, so if you or anyone else would like to
use this code to fix up my earlier patch, you're welcome to it.
Otherwise, it will be later this evening or tomorrow before I can
do any more with this.

Steven

Re: [RFC] Another way to provide help details. (was Re: [PATCH] Add help details to git help command.)

[Petr Baudis]

Dear diary, on Tue, Apr 19, 2005 at 04:41:34PM CEST, I got a letter
where David Greaves <david@dgreaves.com> told me that...
> If Petr wants the top comment to be extracted by help then maybe a 
> bottom comment block could contain the more complete text?
> I *really* think that the user docs should live in the source for now 
> (hence I think that git man is better than going straight to man/docbook).

I'd stay with the top comment for now, and go for perldoc in the Perl
scripts. It's cool, nice, and you can export it to anything and it still
looks mostly cute.

> I wasn't sure whether to perlise the code or do a shell-lib - but 
> looking at the algorithms needed in things like git status I reckon the 
> shell will end up becoming a hackish mess of awk/sed/tr/sort/uniq/pipe 
> (ie perl) anyway.

I'm all for slow migration from sh to Perl so that we can add more cream
on the stuff. Shell was great for the first phase of rapid development
(where basically the most important thing was to be able to call the
core git easily, and just wrap it around) but now if you want to do the
fancier stuff (like git status, or even git log), it's getting more of a
nuisance.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
C++: an octopus made by nailing extra legs onto a dog. -- Steve Taylor

Re: [PATCH] Add help details to git help command. (This time with Perl)

[Steven Cole]

Petr Baudis wrote:
> Dear diary, on Mon, Apr 18, 2005 at 06:42:26AM CEST, I got a letter
> where Steven Cole <elenstev@mesatop.com> told me that...

[snippage]

> 
>>This patch will provide the comment lines in the shell script associated
>>with the command, cleaned up a bit for presentation.
>>
>>BUGS: This will also print any comments in the entire file, which may
>>not be desired.  If a command name and shell script filename
>>do not follow the usual convention, this won't work, e.g. ci for commit.
> 
> 
> Hey, those BUGS are the only slightly non-trivial thing on the whole
> thing! I could do this patch myself... ;-) Also, you don't want to print
> the first newline and the Copyright notices.
> 

OK, here is a patch which _may_ do what you want.

This one no longer prints comments embedded later in the file,
and doesn't print the first newline and disposes of the (c) notices
as requested.  And does the right thing for git help ci.

Example:

[steven@spc0 git-pasky-testing]$ ./git help diff
Make a diff between two GIT trees.

By default compares the current working tree to the state at the
last commit. You can specify -r rev1:rev2 or -r rev1 -r rev2 to
tell it to make a diff between the specified revisions. If you
do not specify a revision, the current working tree is implied
(note that no revision is different from empty revision - -r rev:
compares between rev and HEAD, while -r rev compares between rev
and working tree).

-p instead of one ID denotes a parent commit to the specified ID
(which must not be a tree, obviously).

Outputs a diff converting the first tree to the second one.

---------
Speaking of 'git diff', I ran that before applying the following patch,
and got a diff starting thusly:

  --- /dev/null
  +++ b/gitmerge-file.sh

I had earlier done a 'git pull pasky', which was 'Up to date'.

So, the following patch is a conventional diff.

If the Perl filename or code  is too hideous, you're more than
welcome to change it.

Steven
---------
This patch will provide the comment lines in the shell script associated
with the command, cleaned up a bit for presentation.

Thanks to Bob Newell for some Perl help.

Signed-off-by: Steven Cole <elenstev@mesatop.com>

diff -urN git-pasky-orig/git git-pasky-testing/git
--- git-pasky-orig/git	2005-04-19 10:27:54.000000000 -0600
+++ git-pasky-testing/git	2005-04-19 10:19:08.000000000 -0600
@@ -19,6 +19,11 @@


  help () {
+
+command=$1
+scriptfile=git$command.sh
+
+if [ ! $command ]; then
  	cat <<__END__
  The GIT scripted toolkit  $(gitversion.sh)

@@ -48,6 +53,8 @@
  	track		[RNAME]
  	version

+Additional help is available with: git help COMMAND
+
  Note that these expressions can be used interchangably as "ID"s:
  	empty string (current HEAD)
  	remote name (as registered with git addremote)
@@ -56,6 +63,13 @@
  	commit object hash (as returned by commit-id)
  	tree object hash (accepted only by some commands)
  __END__
+fi
+if [ $scriptfile = "gitci.sh" ]; then
+	scriptfile="gitcommit.sh"
+fi
+if [ ! $scriptfile = "git.sh" ]; then
+	print_help_header.pl <$scriptfile  | grep -v "(c)" | cut -c 3-
+fi
  }


diff -urN git-pasky-orig/Makefile git-pasky-testing/Makefile
--- git-pasky-orig/Makefile	2005-04-19 10:27:54.000000000 -0600
+++ git-pasky-testing/Makefile	2005-04-19 10:32:50.000000000 -0600
@@ -21,7 +21,7 @@
  	gitcommit.sh gitdiff-do gitdiff.sh gitlog.sh gitls.sh gitlsobj.sh \
  	gitmerge.sh gitpull.sh gitrm.sh gittag.sh gittrack.sh gitexport.sh \
  	gitapply.sh gitcancel.sh gitXlntree.sh commit-id gitlsremote.sh \
-	gitfork.sh gitinit.sh gitseek.sh gitstatus.sh
+	gitfork.sh gitinit.sh gitseek.sh gitstatus.sh print_help_header.pl

  COMMON=	read-cache.o

diff -urN git-pasky-orig/print_help_header.pl git-pasky-testing/print_help_header.pl
--- git-pasky-orig/print_help_header.pl	1969-12-31 17:00:00.000000000 -0700
+++ git-pasky-testing/print_help_header.pl	2005-04-19 10:24:34.000000000 -0600
@@ -0,0 +1,10 @@
+#!/usr/bin/perl
+#
+# Prints the block of text preceded by #
+# Copyright (c) Steven Cole, 2005
+#
+# reads from stdin   writes to stdout  no error checking
+<STDIN>;<STDIN>;
+while (substr( $line=<STDIN>, 0, 1) eq "#") {
+                 print $line;
+}

Re: [PATCH] Add help details to git help command. (This time with Perl)

[Petr Baudis]

Dear diary, on Tue, Apr 19, 2005 at 07:35:15PM CEST, I got a letter
where Steven Cole <elenstev@mesatop.com> told me that...
> Example:
..snip a perfect-looking example..
> ---------
> Speaking of 'git diff', I ran that before applying the following patch,
> and got a diff starting thusly:
> 
>  --- /dev/null
>  +++ b/gitmerge-file.sh
> 
> I had earlier done a 'git pull pasky', which was 'Up to date'.

Check/prune your add/rm-queue.

> So, the following patch is a conventional diff.
> 
> If the Perl filename or code  is too hideous, you're more than
> welcome to change it.

I'd actually prefer to just throw the whole help command handling
to githelp.pl. I dislike helper scripts if I can avoid them. ;-)

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
C++: an octopus made by nailing extra legs onto a dog. -- Steve Taylor

Re: [PATCH] Add help details to git help command. (This time with Perl)

[David Greaves]

[-- Attachment #1: Type: text/plain, Size: 1045 bytes --]

Petr Baudis wrote:
> Dear diary, on Tue, Apr 19, 2005 at 07:35:15PM CEST, I got a letter
> where Steven Cole <elenstev@mesatop.com> told me that...
> 

I've been working on git.pl and getting help working nicely

things to try:
git.pl help
git.pl add
git.pl add --help
git.pl add --man
git.pl help add

The main objectives:
* get a reasonable perl code base in git.pl
* provide some way to document WTF is going on :)
* keep the docs near the developer
* allow variations in verbosity
* modularise
* don't use modules outside the base perl set
* allow a gentle migration (so start by calling the .sh's)

I don't like the pod2usage calling convention but I use them for now.

I don't love the 'require gitadd.pl' but it's a gradual start...

Cogito.pm seems to be a good place for the library stuff.

git.pl
passes everything to scripts except gitadd.pl
works when called from somewhere other than the git dir
I don't feel 100% about the fixup ports

gitadd.pl


I thought I'd ask for comments before I spent too much time on this...

David

-- 

[-- Attachment #2: Cogito.pm --]
[-- Type: application/x-perl, Size: 449 bytes --]

[-- Attachment #3: gitadd.pl --]
[-- Type: application/x-perl, Size: 1919 bytes --]

[-- Attachment #4: git.pl --]
[-- Type: application/x-perl, Size: 3681 bytes --]

Re: [PATCH] Add help details to git help command. (This time with Perl)

[Steven Cole]

David Greaves wrote:
> Petr Baudis wrote:
> 
>> Dear diary, on Tue, Apr 19, 2005 at 07:35:15PM CEST, I got a letter
>> where Steven Cole <elenstev@mesatop.com> told me that...
>>
> 
> I've been working on git.pl and getting help working nicely
> 
> things to try:
> git.pl help
> git.pl add
> git.pl add --help
> git.pl add --man
> git.pl help add
> 
> The main objectives:
> * get a reasonable perl code base in git.pl
> * provide some way to document WTF is going on :)
> * keep the docs near the developer
> * allow variations in verbosity
> * modularise
> * don't use modules outside the base perl set
> * allow a gentle migration (so start by calling the .sh's)
> 
> I don't like the pod2usage calling convention but I use them for now.
> 
> I don't love the 'require gitadd.pl' but it's a gradual start...
> 
> Cogito.pm seems to be a good place for the library stuff.
> 
> git.pl
> passes everything to scripts except gitadd.pl
> works when called from somewhere other than the git dir
> I don't feel 100% about the fixup ports
> 
> gitadd.pl
> 
> 
> I thought I'd ask for comments before I spent too much time on this...
> 
> David
> 

I only did my version which spits out the comments at the top of the
shell script as a quick hack.

This looks good to me. Keeping the docs near the developer is essential,
I think.  Speaking of "I think", the name "cogito" was suggested for the
SCM layer, but IIRC Linus suggested staying with just plain git. Petr
suggested tig, perhaps because it looks at git from another point of view.

If we ever do decide to name the SCM layer (the git-pasky stuff) something
with "git inside", other choices are:

agitato		Beethoven's "Moonlight Sonata" 3rd movment is "Presto agitato"
legit		Since git is GPLv2, but perhaps a little too French.
regurgitate	No comment neccessary.

Steven

Re: [PATCH] Add help details to git help command. (This time with Perl)

[David Greaves]

Steven Cole wrote:
> Speaking of "I think", the name "cogito" was suggested for the
> SCM layer, but IIRC Linus suggested staying with just plain git. Petr
> suggested tig, perhaps because it looks at git from another point of view.
I haven't read _all_ the mails - I thought cogito was kinda selected and 
  I got the feeling that Linus wasn't exactly bothered what it was called.
Anyway, git has a rename that needs testing at some point...

> legit        Since git is GPLv2, but perhaps a little too French.
That made me smile.
Quite a few entendres in there...

It's Petr's baby - he gets to name it.

David

Re: [PATCH] Add help details to git help command. (This time with Perl)

[Petr Baudis]

Dear diary, on Tue, Apr 19, 2005 at 09:04:16PM CEST, I got a letter
where David Greaves <david@dgreaves.com> told me that...
> I don't love the 'require gitadd.pl' but it's a gradual start...

I hate it, for one. ;-)

> Cogito.pm seems to be a good place for the library stuff.

Sounds sensible.

> git.pl
> passes everything to scripts except gitadd.pl

We've decided to go for the individual scripts directly. :-)

Unfortunately, you didn't send the attachments inline, so I can't
comment on them sensibly.

Perhaps my main problem is now style. I'd prefer you do format it alike
the C sources of git, with 8-chars indentation and such. Also make sure
you use spaces around (or after) operators. Also, for just few short
functions I prefer putting the functions before the code itself.

> use IO::File;   # leads to less perlish syntax and is standard in perl dists

Oh come on. Are you writing Perl or not? I think it looks pretty awful,
and you are using Perl filehandle idioms anyway, so...

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
C++: an octopus made by nailing extra legs onto a dog. -- Steve Taylor

Re: [PATCH] Add help details to git help command. (This time with Perl)

[David Greaves]

> We've decided to go for the individual scripts directly. :-)
Just to clarify - individual scripts or $0 name handling?

I kinda like one big script - also means we don't need to 'install' it 
to get access to Cogito.pm...

> 
> Unfortunately, you didn't send the attachments inline, so I can't
> comment on them sensibly.

I'm not sure what you want here; last time you said:
> Thanks. Could you please send the patches signed off and either with
> content-disposition: inline or in the mail body?

So I dug around Thunderbird's config and, this time, from my email on 
the git list:
--------------050206040606040908050407
Content-Type: application/x-perl;
  name="gitadd.pl"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
  filename="gitadd.pl"


> Perhaps my main problem is now style. I'd prefer you do format it alike
> the C sources of git, with 8-chars indentation and such. Also make sure
> you use spaces around (or after) operators. Also, for just few short
> functions I prefer putting the functions before the code itself.
will do


David

Re: [PATCH] Add help details to git help command. (This time with Perl)

[Petr Baudis]

Please ignore the reply marker part. ;-)

Sorry,

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
C++: an octopus made by nailing extra legs onto a dog. -- Steve Taylor