Re: [PATCH] branch: make -v useful

[Felipe Contreras <felipe.contreras@gmail.com>]

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

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

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

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

Cheers.

-- 
Felipe Contreras