Re: git alias and --help

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 28, 2011, 18:07 UTC
Message-ID: <7v62j9t2gj.fsf@alter.siamese.dyndns.org>
In-Reply-To: <m362j95jv3.fsf@localhost.localdomain>

Jakub Narebski <jnareb@gmail.com> writes:

Show 18 quoted lines

>> What I've often wished is that git's help system would output
>> something like:
>> 
>>    $ git help co
>>    `git co' is aliased to `checkout'
>> 
>>    Here's the help entry for `checkout':
>> 
>>    GIT-CHECKOUT(1)                   Git Manual                   GIT-CHECKOUT(1)
>
> Wouldn't it be more useful to say something like this:
>
>   $ git co --help
>   `git co' is aliased to `checkout'
>  
>   You can see help entry for `checkout' with "git checkout --help"
>
> Then help is only copy'n'paste away.

Describe your algorithm to come up with the equivalent to the above 'checkout' in this example:

    $ git one --help
    `git one' is aliased to `!sh -c 'git show -s --pretty="format:%h (%s, %ai" "$@" | sed -e "s/ [012][0-9]:[0-5][0-9]:[0-5][0-9] [-+][0-9][0-9][0-9][0-9]$/)/"' -'

If we decide to punt on the '! <cmd>' form, i.e. "take the first token and if it is a git command then do this special thing but otherwise don't make things worse", then you could improve this example:

    $ git lgf --help
    'git lgf' is aliased to 'log --oneline --boundary --first-parent'

with "git log --help", but that is aiming too low for my taste.

If you are redesigning the help system, isn't it a shame that you are discarding other tokens in the alias when giving help? Wouldn't it be wonderful if you extracted the option descriptions for these three options specified and showing only that, for example?

You would need to ensure that the manual pages for all commands share the same structure to make that happen, which goes without saying.