git alias and --help

git alias and --help

[Gelonida N]

I'm having a tiny question about git aliases.

in ~/.gitconfig I defined an alias

b = branch



This works well execp if I type


git b --help

Now I get the output
`git b' is aliased to `branch'


which is nice to know however what I reall wanted is to get the helptext
for the branch command.


Is there any trick to get the help text of git branch without
having to type

git branch --help

Re: git alias and --help

[Junio C Hamano]

Gelonida N <gelonida@gmail.com> writes:

> Is there any trick to get the help text of git branch without
> having to type
>
> git branch --help

How about "git help branch"?

Re: git alias and --help

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Gelonida N <gelonida@gmail.com> writes:
>
>> Is there any trick to get the help text of git branch without
>> having to type
>>
>> git branch --help
>
> How about "git help branch"?

It was bad of me to write a tongue-in-cheek answer, get distracted and
ended up sending it without the real answer.

The reason why we do not do what you seem to be suggesting is because
giving the same behaviour to "git b --help" as "git branch --help" is
wrong.

To see why, imagine you have configured an alias that is not a simple and
stupid substitution "b == branch", but something like "bt == branch -t",
and then want to know what you should write after "git bt".  Giving the
manpage for branch without giving them any hint that they configured that
alias to produce customized behaviour that is different from plain vanilla
"branch" is not quite acceptable.

I think you _could_ make a patch that special cases a simple and straight
substitution and skip the "foo is aliased to bar" step, but I doubt it is
worth it to lose consistency between "git b --help" vs "git bt --help"
that way.

Re: git alias and --help

[Gelonida N]

On 10/28/2011 12:50 AM, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
> 
>> Gelonida N <gelonida@gmail.com> writes:
>>
>>> Is there any trick to get the help text of git branch without
>>> having to type
>>>
>>> git branch --help
>>
>> How about "git help branch"?
> 
> It was bad of me to write a tongue-in-cheek answer, get distracted and
> ended up sending it without the real answer.
No issues. At least I got an answer :-)
> 
> The reason why we do not do what you seem to be suggesting is because
> giving the same behaviour to "git b --help" as "git branch --help" is
> wrong.
> 
> To see why, imagine you have configured an alias that is not a simple and
> stupid substitution "b == branch", but something like "bt == branch -t",
> and then want to know what you should write after "git bt".  Giving the
> manpage for branch without giving them any hint that they configured that
> alias to produce customized behaviour that is different from plain vanilla
> "branch" is not quite acceptable.
> 
> I think you _could_ make a patch that special cases a simple and straight
> substitution and skip the "foo is aliased to bar" step, but I doubt it is
> worth it to lose consistency between "git b --help" vs "git bt --help"
> that way.


I understand the reasoning and agree, that as general case it might not
be a good idea to have the behaviour, taht I expected to be the default
behaviour

It's just, that I am lazy so I shortened  my most common commands

For example:
co=checkout
ci=commit
b=branch
sm=submodule

However I'm not smart enough to remember all options for all commands
and so I have to ask git for occasional help.


It feels so 'unlazy' to have to type the full command 'just' to get help


What I wondered though is whether there couldn't be a way to be lazy and
avoid confusion.

1.) prompt for full help
-------------------------

One option would be to display what the command is aliased to and to
prompt whether one wants to see the full help of the base command.

`git b' is aliased to `branch'
pleaset press h if you want to see the full help for git branch
or press q to quit


2.) allow copy paste by displaying the command to be typed for help.
---------------------------------------------------------------------
display sometihing like:

`git b' is aliased to `branch'
for help about the branch command type:  git --help


Then lazy people could copy paste the command instead of typing it.


3.) special alias syntax to allow 'forwarding' of --help
------------------------------------------------------------

some kind of special alias syntax, which explicitely forces that --help
is 'forwarded' to the alias and not treated by git


example:

b = branch   # --help would have the current behaviour

I tried following to see whether '--help' is now being 'forwarded'

b = ! git branch
but also  here --help is treated by git

A possibility could be another 'special' character. For the sake of the
example I used '?'
b = ?branch # 'the question mark would allow 'forwarding' the
             # --help option to the alias'

b = ?! git branch



My workaround
------------

Fort the time being I might do something like

bhlp = branch --help

I would have prefered b_hlp or b_h, but it seems underscore isn't
allowed in an alias.

Re: git alias and --help

[Miles Bader]

Junio C Hamano <gitster@pobox.com> writes:
>>> git branch --help
>>
>> How about "git help branch"?
>
> The reason why we do not do what you seem to be suggesting is because
> giving the same behaviour to "git b --help" as "git branch --help" is
> wrong.

I agree with Gelonida's followup:  although what you say makes sense,
it's still pretty annoying behavior for the very common case of a
simple renaming alias...

E.g., I have "co" aliased to "checkout", and so my fingers are very
very inclined to say "co" when I mean checkout... including when
asking for help.  I actually end up typing "git co --help", grumbling,
and retyping with the full command name, quite reguarly.

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)

   NAME
          git-checkout - Checkout a branch or paths to the working tree
   ...

[with the "`git co' is aliased ..." header included in the pager
output.]

Of course, that would be the wrong thing for somebody that just wants
to be reminded what an alias expands too, but my intuition is that
this is a very tiny minority compared to people that want to examine
the options for the underlying command...

-Miles

-- 
Suburbia: where they tear out the trees and then name streets after them.

Re: git alias and --help

[Junio C Hamano]

Miles Bader <miles@gnu.org> writes:

> Of course, that would be the wrong thing for somebody that just wants
> to be reminded what an alias expands too, but my intuition is that
> this is a very tiny minority compared to people that want to examine
> the options for the underlying command...

And it is doubly wrong if help backend is configured to be anything but
manpages, no?

As I said, you should be able to come up with a patch that detects and
special cases the no frills case (replacement to single token) to get what
you want.

Re: git alias and --help

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 28.10.2011 06:05:
> Miles Bader <miles@gnu.org> writes:
> 
>> Of course, that would be the wrong thing for somebody that just wants
>> to be reminded what an alias expands too, but my intuition is that
>> this is a very tiny minority compared to people that want to examine
>> the options for the underlying command...
> 
> And it is doubly wrong if help backend is configured to be anything but
> manpages, no?
> 
> As I said, you should be able to come up with a patch that detects and
> special cases the no frills case (replacement to single token) to get what
> you want.

But "help" is still too much to type for the OP ;) How about this in
your config:

[alias]
	h = help
	hh = "!sh -c 'a=$(git config --get alias.$1); : ${a:=$1}; git help
${a%% *}' -"

Ugly as hell, I know, and works only for aliases whose first word is the
name of a git command, as well as for non-aliases. Catching "!command"
type aliases is left as an exercise to the reader.

Michael

Re: git alias and --help

[Gelonida N]

On 10/28/2011 06:05 AM, Junio C Hamano wrote:
> Miles Bader <miles@gnu.org> writes:
> 
>> Of course, that would be the wrong thing for somebody that just wants
>> to be reminded what an alias expands too, but my intuition is that
>> this is a very tiny minority compared to people that want to examine
>> the options for the underlying command...
> 
> And it is doubly wrong if help backend is configured to be anything but
> manpages, no?

Well. Then it is already doubly wrong today, isnt it?
The output of 'git help b'
is not a man page I assume.

In my opinion chaning it to a short message + the output of a man page
is not really worse than today's behaviour.

> 
> As I said, you should be able to come up with a patch that detects and
> special cases the no frills case (replacement to single token) to get what
> you want.

That's perhaps the most comfortable one, though occasionally I am even
interested in the help text of a git command if I had an alias like

l = log --name-status

to see what other switches I could add


(Thus an alternative suggestion to display both or to have a special
syntax allowing to force displaying of a man page)



Another small detail:

Let's assume I have following alias:

log = log --name-status


In this case I directly get the help text for git log
if I typed 'git log --help' (or 'git help log').
I don't even see, that my log is in reality aliased.

Re: git alias and --help

[Jakub Narebski]

Gelonida N <gelonida@gmail.com> writes:

[...]

> Another small detail:
> 
> Let's assume I have following alias:
> 
> log = log --name-status
> 
> 
> In this case I directly get the help text for git log
> if I typed 'git log --help' (or 'git help log').
> I don't even see, that my log is in reality aliased.

That is because it doesn't work: git does not allow for aliasing its
built-in commands.

-- 
Jakub Narębski

Re: git alias and --help

[Gelonida N]

On 10/28/2011 03:27 PM, Jakub Narebski wrote:
> Gelonida N <gelonida@gmail.com> writes:
> 
> [...]
> 
>> Another small detail:
>>
>> Let's assume I have following alias:
>>
>> log = log --name-status
>>
>>
>> In this case I directly get the help text for git log
>> if I typed 'git log --help' (or 'git help log').
>> I don't even see, that my log is in reality aliased.
> 
> That is because it doesn't work: git does not allow for aliasing its
> built-in commands.


Well this explains why.
Thanks

Re: git alias and --help

[Jakub Narebski]

Miles Bader <miles@gnu.org> writes:
> Junio C Hamano <gitster@pobox.com> writes:

> > > > git branch --help
> > >
> > > How about "git help branch"?
> >
> > The reason why we do not do what you seem to be suggesting is because
> > giving the same behaviour to "git b --help" as "git branch --help" is
> > wrong.
> 
> I agree with Gelonida's followup:  although what you say makes sense,
> it's still pretty annoying behavior for the very common case of a
> simple renaming alias...
> 
> E.g., I have "co" aliased to "checkout", and so my fingers are very
> very inclined to say "co" when I mean checkout... including when
> asking for help.  I actually end up typing "git co --help", grumbling,
> and retyping with the full command name, quite reguarly.
> 
> 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.  

(This helping text probably should be controlled by some advice.*
config variable).


P.S. I wonder if allowing to run command if you specify unambiguous
prefix would be a good replacement for such aliases?

-- 
Jakub Narębski

Re: git alias and --help

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

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

Re: git alias and --help

[Miles Bader]

2011/10/29 Junio C Hamano <gitster@pobox.com>:
>    $ 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?

I think that would be the wrong thing in most cases though:  an alias
like the above happily allows the user to specify other git-log
options on the command line; when I get help on an aliased option,
it's often precisely because I want to see the _other_ options I can
use...

E.g., I have:

   $ git slog --help
   `git slog' is aliased to `log --date=short --pretty=tformat:"%h
%ad  %s" --abbrev-commit'

But the typical question I want to answer is something like "OK, how
do I reverse the output order of slog?" or "how do I limit the output
of slog to a certain date range?"

-miles

-- 
Cat is power.  Cat is peace.

Re: git alias and --help

[Gelonida N]

On 10/28/2011 03:26 PM, Jakub Narebski wrote:
> Miles Bader <miles@gnu.org> writes:
>> Junio C Hamano <gitster@pobox.com> writes:
> 
>>>>> git branch --help
>>>>
>>>> How about "git help branch"?
>>>
>>> The reason why we do not do what you seem to be suggesting is because
>>> giving the same behaviour to "git b --help" as "git branch --help" is
>>> wrong.
>>
>> I agree with Gelonida's followup:  although what you say makes sense,
>> it's still pretty annoying behavior for the very common case of a
>> simple renaming alias...
>>
>> E.g., I have "co" aliased to "checkout", and so my fingers are very
>> very inclined to say "co" when I mean checkout... including when
>> asking for help.  I actually end up typing "git co --help", grumbling,
>> and retyping with the full command name, quite reguarly.
>>
>> 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.  
> 
> (This helping text probably should be controlled by some advice.*
> config variable).

This is definitely an option and something which I suggested as one
option myself (however my example had a typo and was perhaps therefore
not understandable)