[nybble41]

To follow up on this, since we may still be talking past one another, I do not believe that the software design is deficient or that the disconnect between the implementation and actual use is nearly so large as the article makes it out to be. Taking the examples one by one:

> First ask yourself what we mean when we say “is your topic branch up to date?”

Does your local ref identify the same commit as the upstream ref?

> “be sure to fetch the dev branch”

Be sure to update your remote tracking branch ref to match the corresponding upstream ref and download all related commits.

> “what branch did I do that work on?”

Which branch(es) (which refs) point to commits with trees which contain that work?

> “is that commit on the main branch or the dev branch?”

Is that commit reachable by following the parent links from the main branch ref or the dev branch ref (or both)?

> “Has that work landed on the main branch?”

Is that work present in the tree of the commit identified by the main branch ref?

And then there is the last example which isn't even talking about branches in the version-control sense but rather the much older "split path" sense.

The documentation is fine. The way people talk about branches in the context of Git is (mostly) fine. It's only the author's understanding which is at odds with the reality of what branches are in the Git ecosystem. Which could possibly be due to trying to coerce Git into the mold of other version control systems with incompatible concepts of branching.