Re: [PATCH] push: don't guess at qualifying remote refs on deletion

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 5, 2012, 17:26 UTC
Message-ID: <7v3956rufq.fsf@alter.siamese.dyndns.org>
In-Reply-To: <CABURp0r8EfShHVE-Vycz3g8-WPXFzs1-WOT7LRwh-XOuWVYG+Q@mail.gmail.com>

Phil Hord <phil.hord@gmail.com> writes:

> The possible enhancements to cover this I can think of are mostly in
> the form of enhanced help or advice.  For example, I could imagine
> these:

Thanks; I agree discoverability is the key for any large toolset.

Show 6 quoted lines

> 1. Add a link to 'git push' on the 'git-branch' man page.   I suspect
> this is where newbies would go to look for this feature, but I am only
> guessing.  The git-branch help discusses deleting branches and even
> deleting remote-tracking branches.  But it does not discuss deleting
> branches on a remote repository, even to say "this is not the command
> you want" for that action, but "see this other one instead".

Or you can enhance the link to "git push" from "git" manpage (which hopefully exists already), to make it clear that everything that affects branches and tags that appear at a remote site is done via that command.

Show 8 quoted lines

> 2. Add 'apropos' behavior for git help.
>    $ git apropos delete
> ...
> 3. Add a search feature for help.  Currently this feature is provided
> instead by Google and StackOverflow.
>    $ git help --find delete --and branch --and remote
> Except I don't expect this "advanced" form of help, if it existed, to
> be noticed by newbies early enough on the learning curve.

I think you may be onto something here. I can see that we could help "git help -k delete" (modeled after "man -k") by adding keywords to the documentation pages.

> 4. Add advice in appropriate locations.

I have to say that I am fairly negative on any attempt to anticipate and list all the irrelevant possibilities that could come from misunderstandings; it will lead to unreadable mess.