git alias and --help

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

Gelonida N <gelonida@gmail.com> writes:

How about "git help branch"?

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

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.

On 10/28/2011 12:50 AM, Junio C Hamano wrote:

No issues. At least I got an answer :-)

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.

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

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

Miles Bader <miles@gnu.org> writes:

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.

Junio C Hamano venit, vidit, dixit 28.10.2011 06:05:

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

On 10/28/2011 06:05 AM, Junio C Hamano wrote:

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.

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.

Gelonida N <gelonida@gmail.com> writes:

[...]

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

On 10/28/2011 03:27 PM, Jakub Narebski wrote:

Well this explains why. Thanks

Miles Bader <miles@gnu.org> writes:

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 Narebski <jnareb@gmail.com> writes:

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.

2011/10/29 Junio C Hamano <gitster@pobox.com>:

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

On 10/28/2011 03:26 PM, Jakub Narebski wrote:

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)