patchAdd help details to git help command.

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

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...

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.

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 Baudis wrote:

[snippage]

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

On Monday 18 April 2005 10:59 am, Steven Cole wrote:

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.

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...

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 Baudis wrote:

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

David Greaves wrote:

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.

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

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...

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'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 Baudis wrote:

[snippage]

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

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...

..snip a perfect-looking example..

Check/prune your add/rm-queue.

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 Baudis wrote:

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

David Greaves wrote:

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

Steven Cole wrote:

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...

That made me smile. Quite a few entendres in there...

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

David

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 hate it, for one. ;-)

Sounds sensible.

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.

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

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...

I'm not sure what you want here; last time you said:

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"

will do

David

Please ignore the reply marker part. ;-)

Sorry,