There are two concepts being confused here: Git branches and what I'll call "logical" branches.
The mutable object in the Git data model known as a "branch" is really just a ref and nothing more. Traditionally it points to a commit, though it could point to a blob or tree or tag object, in which case commit-oriented commands won't work on it (while other commands which wouldn't work on commits may).
A logical branch, on the other hand, is a particular commit, its parent commit(s), their parent(s), etc.—not a sequence per se but rather a tree. The logical branch concept captures the "structure" of the branch. Logical branches are immutable, but new commits can refer back to them to create a new, larger tree.
The logical branch has no intrinsic name, but may optionally be identified extrinsically by one or more named refs, including but not limited to Git branches.
Commands which modify branches generally create a new logical branch composed of one or more new commits referencing zero or more existing commits and also update the Git branch—the ref—to point to the new commit(s). A few commands, e.g. "git reset", update only the ref without creating new commits. It is possible, though awkward, to work exclusively with nameless logical branches and never even create a Git branch referring to those commits.
Contrast this with version control systems like Bazaar where all commits actually do belong to specific named branches, with the branch name recorded in the commit object.
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.
> Are you a Git user who wants to argue about this?
I totally get the author's point, there are other cases in software in which a structure is identified by a single object related to that structure. Mental model and mechanism may not be identical. Pendants may be pedantic, though, wonder how easy it is to convince them.
The mutable object in the Git data model known as a "branch" is really just a ref and nothing more. Traditionally it points to a commit, though it could point to a blob or tree or tag object, in which case commit-oriented commands won't work on it (while other commands which wouldn't work on commits may).
A logical branch, on the other hand, is a particular commit, its parent commit(s), their parent(s), etc.—not a sequence per se but rather a tree. The logical branch concept captures the "structure" of the branch. Logical branches are immutable, but new commits can refer back to them to create a new, larger tree.
The logical branch has no intrinsic name, but may optionally be identified extrinsically by one or more named refs, including but not limited to Git branches.
Commands which modify branches generally create a new logical branch composed of one or more new commits referencing zero or more existing commits and also update the Git branch—the ref—to point to the new commit(s). A few commands, e.g. "git reset", update only the ref without creating new commits. It is possible, though awkward, to work exclusively with nameless logical branches and never even create a Git branch referring to those commits.
Contrast this with version control systems like Bazaar where all commits actually do belong to specific named branches, with the branch name recorded in the commit object.