Re: [PATCH] status: show default branch comparison when tracking non-default branch

[Junio C Hamano <gitster@pobox.com>]

"Harald Nordgren via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Harald Nordgren <haraldnordgren@gmail.com>
>
> When a branch tracks a non-default remote branch (e.g.,
> origin/feature), git status now also displays how the branch
> compares to the default branch (origin/main or upstream/main).

"now" meaning what"?

The usual way to compose a log message of this project is to

 - Give an observation on how the current system works in the
   present tense (so no need to say "Currently X is Y", or
   "Previously X was Y" to describe the state before your change;
   just "X is Y" is enough), and discuss what you perceive as a
   problem in it.

 - Propose a solution (optional---often, problem description
   trivially leads to an obvious solution in reader's minds).

 - Give commands to somebody editing the codebase to "make it so",
   instead of saying "This commit does X".

in this order.

So if you are following the convention, "now also displays" ought to
be about what the current code without this patch does, but I am
sensing that it probably is not the case.

Start your explanation by decribing what the users see in "git
status" output without this patch.  Perhaps like

    "git status" on a branch that follows a remote branch compares
    commits on the current branch and the remote-tracking branch it
    builds upon, to show "ahead" (i.e. you have built new history,
    while others are not touching it), "behind" (i.e. you haven't
    added any work since you were in-sync, while others have added
    their work on the branch), "diverged" (i.e. you have commits
    that you haven't pushed out, while others have added commits).

That is the "giving an observation" part.  And then describe why
that comparison with a single remote branch may be insufficient to
learn the current status.  Your reasoning might be something like

    When you fork a branch 'feature' from the 'main' branch of the
    remote, but then create 'feature' branch at the remote and push
    there, while you still occasionally pull from or rebase onto
    their 'main', you'd _also_ want to know how much you have
    diverged from 'main', in addition to how your 'feature' and
    their 'feature' compares.  Currently the comparison with 'main'
    is not given.

That's the "discuss your problem with the status quo" part.

Only after that, propose to show two sets of comparison.

> This helps users understand if their branch has drifted from the
> main development line even when it's in sync with its tracking
> branch.

Describe what does it help to know that after that sentence, like
"... to get the feel of when to start thinking about rebasing", or
something.

> The comparison is shown as a separate line after the tracking
> branch status:
> - "Ahead of 'origin/main' by N commits" when purely ahead
> - "Behind 'origin/main' by N commits" when purely behind
> - "Diverged from 'origin/main' by N commits" when diverged

In other words, exactly the same way as what we show with the
tracking branch?

The triangular workflow involves two remote things.  One is where
you pull from to catch up.  After building on top, you push to
somewhere else to publish your work.  This may be a different branch
in the same repository you pull from, or a branch in a completely
different repository.  What you pushed out may be processed by
others and may come back in the branch you pull from eventually to
complete the triangle.

In such a triangular workflow, comparison with these two remote
things may be needed. One with the branch you forked your work from
to know how much work _other_ people added to the branch to learn
when to start thinking about catching up, and with the branch you
are pushing your work to to know how much work you are holding
locally without pushing out.

I am not sure what you mean by the word "default" here, though.

You seem to be using the "what would a new user get when they clone
the remote (by virtue of their HEAD pointing at that branch)", but
I am not sure if that is a good way to determine the other remote
thing to compare with.

Even if one remote branch you pull from (but not push to) has a name
that is not one of those usual ones like 'main', 'master', 'trunk',
'default', you would want to compare with it in addition to where
you are pushing to.  So branch.<name>.merge + branch.<name>.remote
that defines where you pull from is one thing to compare with.  To
learn the other, the destination of a push of this branch, would
involve poking at remote.pushdefault, branch.<name>.pushRemote,
branch.<name>.remote to find out which remote repository it goes,
and then remote.<remote>.push to find out where this branch goes,
but the helper functions to learn all that are already available.

So, I think the topic addresses a good problem, its presentation
needs a bit more work, and its design (not the implementation) of
how to figure out the other thing to compare I am not sure about.

Thanks.