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

From: Phil Hord <phil.hord@gmail.com>
Date: Jul 5, 2012, 15:32 UTC
Message-ID: <CABURp0r8EfShHVE-Vycz3g8-WPXFzs1-WOT7LRwh-XOuWVYG+Q@mail.gmail.com>
In-Reply-To: <1341472926.10752.5.camel@flaca.cmartin.tk>

Show 14 quoted lines

>> > There is also a flag you can pass, which you can see a few
>> paragraphs
>> > under it which. It explains what it does underneath but removes the
>> need
>> > to know that an empty source will delete the ref.
>> >
>> >     --delete
>> >        All listed refs are deleted from the remote repository. This
>> is
>> >        the same as prefixing all refs with a colon.
>>
>>
>> I do like that, but I agree with OP that 'git push' is not an obvious
>> to look for delete branch functionality for new users.

s/obvious/obvious place/

> Like it? I don't get what you mean, it's a quote of what's already
> there.

Yes. I didn't mean I like "the change". I meant that I appreciate this being in the documentation. But it seems insufficient.

> The reason that it's in git-push is because that's the only git command
> that modifies another repository. There isn't another git command where
> it would fit.

Yes, and that's why I said, in the part of my email you did not quote:

"I do not have a good suggestion for improving the situation, however."

> You could try to put it somewhere under git-remote, but
> then you'd have a single subcommand that affects a remote among a lot of
> others that don't, introducing an inconsistency in the command.

git-remote is the wrong place for anything like this. I think git-push is really the correct place for it. I do not think it should be moved.

But this is a common problem in git for newbies, I think. Features are in "the right place" in the command structure, but it is difficult to find where that right place is when you are new to the system, especially when the feature is tucked neatly away as a switch on some other feature.

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:

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

2. Add 'apropos' behavior for git help.
   $ git apropos delete

Except I notice that the system 'apropos' does not turn up 'git-push'
for either of these:
   $ apropos delete
   $ apropos branch

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.

4. Add advice in appropriate locations.
Instead of this:
   $ git remote rm origin/foo
   error: Could not remove config section 'remote.origin/foo'
   $ git branch -d origin/foo
   error: branch 'origin/foo' not found.

Do this:
   $ git remote rm origin/foo
   error: There is no remote named 'origin/foo'
   hint: Did you mean to remove the remote tracking branch 'origin/foo'?
   hint: Try "git branch --delete --remotes origin/foo" instead.
   hint: Did you mean to remove the branch 'foo' on the remote
'origin' repository?
   hint: Try "git push --delete origin foo" instead.

   $ git branch -d origin/foo
   error: branch 'origin/foo' not found.
   hint: To delete the remote-tracking branch origin/foo,
   hint:  use git branch --delete --remotes origin/foo

   $ git branch -dr origin/foo
   Deleted remote branch origin/foo (was fadda12).
   hint: This deleted your remote-tracking branch but
   hint:  did not affect the branch on the remote server.
   hint:  To remove the branch from the remote server,
   hint:  use "git push".  See '--delete' in "git help push" .

I rather like this last bit.  I'll try to roll a patch later on.

Phil