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

Phil Hord [off-list ref] 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.

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.

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.