Re: [PATCH] branch: make -v useful

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Mon, Jun 07 2021, Felipe Contreras wrote:

> Ævar Arnfjörð Bjarmason wrote:
>> On Fri, Jun 04 2021, Felipe Contreras wrote:
>> 
>> > Currently `git branch -v` shows something like "[ahead 10]", but ahead
>> > of what?
>> >
>> > We git experts know ahead of what, but not what that what is set to. Just
>> > like "[@{upstream}: ahead 10]" would not be particularly useful to
>> > anyone that doesn't know, or remembers, what @{upstream} is set to.
>> >
>> > On the other hand "[master: ahead 10]" is perfectly clear to anyone.
>> >
>> > This confusion only gets worse when you see "[ahead 10, behind 100]". Is
>> > it master? Is it next? Is it
>> > john/experimental-feature-i-based-my-branch-on?
>> >
>> > Inevitably most users will need to know what @{upstream} is.
>> >
>> > So let's make `git branch -v` output what is most useful:
>> >
>> >   [master]
>> >
>> > Before:
>> >
>> >   * fc/branch/sane-colors b2489a3735 [ahead 1] branch: make -v useful
>> >
>> > After:
>> >
>> >   * fc/branch/sane-colors b2489a3735 [master] branch: make -v useful
>> >
>> 
>> Having applied this patch I find the description a bit confusing. The
>> example led me to believe that you'd stripped the remote name, so the
>> common case of "origin/master" would become "master", but instead the
>> example is from a "fc/branch/sane-colors" branch where your "remote
>> tracking branch" is actually tracking your *local* master, i.e. "remote
>> = ."?
>
> Yes, in my particular setup I have a local "master" and many branches
> based on it. A simply picked a real example.
>
> But yeah, it would have been clearer with origin/master.

*nod*

>> Disambiguating that is one of the reasons we prefix with the remote
>> name, but I'd say it makes for a confusing example in a commit message,
>> and also if instead of saying:
>> 
>>     branch: make -v useful
>> 
>> It said e.g.:
>> 
>>     branch: reverse the priority of what -v and -vv show
>
> I guess that depends on what you consider this patch is doing, why, and how.
>
> But I have no problem with your version.
>
>> Or something similar to note that it's not "useful" now, but an
>> opinionated change about what we should show on verbosity level 1 and 2.
>
> I'm not sure I parsed that correctly, but that's the whole point:
> verbosity level 1 is not very useful (I'd argue not useful at all).

Maybe, anyway I meant to suggest saying something approaching "reverse
the order of the data we consider important" instead of the equivalent
of "make the data useful".

>> In any case, this proposed patch is missing a doc update, in
>> git-branch.txt we say both:
>> 
>>     When in list mode, show sha1 and commit subject line for each head,
>>     along with relationship to upstream branch (if any). If given twice,
>>     print the path of the linked worktree (if any) and the name of the
>>     upstream branch, as well (see also git remote show <remote>).
>> 
>> And later, for the --track option:
>> 
>>     When creating a new branch, set up branch.<name>.remote and
>>     branch.<name>.merge configuration entries to mark the start-point
>>     branch as "upstream" from the new branch. This configuration will
>>     tell git to show the relationship between the two branches in git
>>     status and git branch -v.
>> 
>> Both of those need to be updated,
>
> Sure, I missed that.
>
>> and I think the commit messages should discuss whether we break this
>> promise of having consistent output between "status" and "branch -v"
>> now.
>
> But we don't with "branch -vv".

I think the wording there needs to be changed in any case, I'm not sure
what it's supposed to mean.

I think the "show the relationship between" there is referring to the
ahead/behind relationship, or maybe it's just speaking more generally
about the short (branch -v[-v]) v.s. long (git status) blurb we show
about the branch status overall.

>> As for the proposal, I don't use "branch -v" all that much much, so I
>> don't have strong knee-jerk feelings on it, but just considering it now
>> I'd think that the current default is a fundamentally better
>> approximation of what most users would like as a default.
>> 
>> I.e. I think it's fair to say that to the extent that most users have
>> topic branches they're part of some pull-request workflow where they're
>> always tracking the one upstream they always care about, usually
>> origin/master.
>
> Because git has poor support for triangular workflows users are forced
> to pick between one of two approaches:
>
>  1. If you rebase a lot you pick origin/master
>  2. If you push a lot you pick github/my-pull-request
>
> There's a reason `git push --set-upstream` exists.
>
> A quick Google search shows these top results:
>
> 1. https://devconnected.com/how-to-set-upstream-branch-on-git/
>
>  * git push --set-upstream <remote> <branch>
>  * git branch -vv
>
> The author doesn't even mention any other way to setup branches, and of
> course doesn't bother himself with `git branch -v`, which is not useful
> at all for his purposes.
>
> 2. https://git-scm.com/book/en/v2/Git-Branching-Remote-Branches
>
>   If you want to see what tracking branches you have set up, you can use
>   the -vv option to git branch. This will list out your local branches
>   with more information including what each branch is tracking and if
>   your local branch is ahead, behind or both.
>
> Once again another author that doesn't bother himself with
> `git branch -v`.
>
> And the examples show why:
>
>     iss53     7e424c3 [origin/iss53: ahead 2] Add forgotten brackets
>     master    1ae2a45 [origin/master] Deploy index fix
>   * serverfix f8674d9 [teamone/server-fix-good: ahead 3, behind 1] This should do it
>     testing   5ea463a Try something new
>
> In only one example is the upstream branch origin/master.
>
> 3. https://stackoverflow.com/questions/1783405/how-do-i-check-out-a-remote-git-branch
>
> The top answer to "How do I check out a remote Git branch?" mentions:
>
>   git checkout -t <name of remote>/test
>
> This most certainly will not create an origin/master upstream.
>
> 4. https://www.git-tower.com/learn/git/faq/track-remote-upstream-branch/
>
>   git checkout --track origin/dev
>   git push -u origin dev
>   git branch -u origin/dev
>
> Once again no sight of origin/master, which isn't even mentioned in the
> whole article.
>
>
> So no, I don't think it's accurate to say that most people would track
> origin/master, in fact, I would say of the people that know how to set
> upstream tracking branches, the minority would pick origin/master.
>
>> The -v output showing the ahead/behind relationship to that branch
>
> What branch?
>
> If I show you the output of my `git branch -v` on git.git do you think you
> would be able to figure out what branch is being tracked? Not even I
> could figure that out.
>
>> Whereas you are presumably tracking origin/master for some, building on
>> your own topic (or other people's topics) for another etc., I think that
>> workflow is much rarer outside of linux.git and git.git, and even for
>> those most people usually track origin/master with most of their topics.
>
> That's an unsupported assumption.
>
> As I showed above, most pople track the branch they push to, not
> origin/master.
>
> Google "git branch -v", and you will find mostly official documentation
> and man pages.
>
> Google "git branch -vv", and you will find mostly blog posts, Stack
> Overflow questions, and cheat sheets.
>
> I think the reason why is obvious.

Yes, I stand corrected.

For what it's worth I think one thing to salvage from my ill-informed
rambling is that I was under that impression because I set
push.default=upstream.

But yes, with "simple" being the default and refusing to have
avar/my-topic have an upstream of origin/master my setup is probably not
the common case.

I wonder if this should depend on the setting of push.default, or
whether we can infer anything at all from that setting. After all you
can set it to whatever and then either manually do "git push <remote>
<src>:<dst>" (my usual worklow is just "git push origin HEAD"), or
manually do the "git rebase origin/master" or whatever in the case where
your upstream is your own topic branch.