Re: [PATCH] branch: make -v useful

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

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

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.

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, and I think the commit messages should
discuss whether we break this promise of having consistent output
between "status" and "branch -v" now.

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.

The -v output showing the ahead/behind relationship to that branch
without naming it is thus the best use of the limited space we have, and
with a bit more verbosity under -vv we'd show the (usually the same for
all of those) upstream name.

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.

An additional benefit is that `git branch -v` is slightly faster: 30ms
vs. 60ms on my system.

110ms v.s. 5000ms on my system. Lots of old uncleaned-up topics.

For what it's worth I remember some past discussion where it was
discussed to have some human-readable cut-off so instead of saying:

    ahead 2, behind 38741

We'd just fall back on saying "behind lots" once your number of behind
reached some limit (which could dynamically compute as a heuristic based
on repo size, just like the abbrev length)..