Re: [PATCH v6] doc: add an explanation of Git's data model

From: Julia Evans <julia@jvns.ca>
Date: Nov 13, 2025, 20:18 UTC
Message-ID: <160ef4a8-8e9c-4034-9607-2f268fdbf29d@app.fastmail.com>
In-Reply-To: <2265ecb5-b0ba-4a28-904f-186ef5318562@app.fastmail.com>

On Thu, Nov 13, 2025, at 2:50 PM, Julia Evans wrote:

Show 49 quoted lines

> On Wed, Nov 12, 2025, at 5:49 PM, Junio C Hamano wrote:
>> Junio C Hamano <gitster@pobox.com> writes:
>>
>>> If we do not hesitate using a new word and introduce "label", "a
>>> branch works as a label for a commit object" may probably work,
>>> probably.
>>
>> Another thing.
>>
>> Do we want to limit the definition of "branch" very narrowly, i.e.,
>> "subset of refs whose refname begins with refs/heads/"?  
>>
>> Or do we want to give a description at a bit higher conceptual
>> level, something like:
>>
>>   A branch is a mechanism to help you grow one line of history (in
>>   the sea/cloud of commits) by (1) keeping track of the commit it
>>   currently is at (by recording its ID in the ref used to implement
>>   the branch), (2) allowing you easily record a new commit you
>>   create while you are on it as a child of the current commit (by
>>   allowing the symbolic ref "HEAD" to point the ref used to
>>   implement the branch), (3) keeping the description of the theme of
>>   the particular line of history being developed there (by using
>>   "branch.<name>.description" configuration variable for the branch)
>>   which is incorporated when the branch gets merged to an
>>   integration branch, and (4) keeping track of how the branch has
>>   grown over time (in the reflog for the ref used to implement the
>>   branch).
>>
>> We can limit ourselves to view a "branch" as a narrow subset of a
>> ref that can point at a single commit in the dag of commits, and it
>> can be updated at any time to point another different commit that
>> has no relation to the previous commit.
>
> I think talking too much about the intentions behind branches runs
> the risk of getting into a discussion from Git workflows which IMO
> is definitely out of scope for this document. For example "which is
> incorporated when the branch gets merged to an integration branch" is
> talking about a specific Git workflow.
>
> From my point of view as a Git user one of Git's biggest strengths is its
> flexibility; because branches _can_ be moved to point at a different
> commit at any time in various ways (via `git reset --hard`, `git rebase`, or
> `git commit --amend`), there's a lot of flexibility in how someone can
> choose to use Git, including never using branches at all. 
> (the flexibility is also one of the things that makes Git hard of course :) )
>
> So I'd prefer to keep editorializing about what a branch "means"
> to a minimum.

To immediately contradict myself a bit: after sending this I thought to look through Mark Dominus's great blog posts about Git to see if he has anything to say about this, and I came across this article: https://blog.plover.com/prog/git/branches.html, called "I wish people would stop insisting that Git branches are nothing but refs".

It reminded me that of course in Git the word "branch" often is used to mean "a sequence of commits", for example if I make a branch called `topic` and add 2 commits to it I might say that that "branch" is that sequence of two commits. I think the way Dominus talks about this is very interesting:

	The reason people say this, the disconnection is that the Git software
	doesn't have any formal representation of branches. Conceptually, the
	branch is there; the git commands just don't understand it. This is the
	most important mismatch between the conceptual model and what the Git
	software actually does.

To me the sticky point is that "the branch is these two commits" is an important and useful concept in Git, but it doesn't really _exist_ in Git's data model, because Git only stores a branch as a reference to a commit.

One way I've resolved this in the past is to say something like "you can think about a branch in 3 different ways!" https://wizardzines.com/comics/whats-a-branch/

The idea there is to talk about how a branch might be _conceptually_ "a line of development", but that Git doesn't have anything in its data model to track what the "base" of the line of development is, so any time you want Git to think of a branch as "these 2 commits" you need to give it a way to determine the base.

Show 26 quoted lines

> Right now we have this, which tries to explain a very small amount
> about how branches are used that should apply to almost
> all Git workflows:
>
> "Even though branches and tags both refer to a commit ID, Git treats
> them very differently. Branches are expected to change over time: when
> you make a commit, Git will update your current branch to point to the
> new commit. "
>
>> Once we stop limiting ourselves and explain the purpose of using a
>> "branch", "it can be updated to point any random commit" stops being
>> entirely true.  While the "git branch -f" command can be used to do
>> so, doing so all the time would go against what makes a branch a
>> branch, i.e. to keep track of the process of growing the history,
>> and it is expected that it would be a lot more common for the commit
>> pointed at by the branch ref to move by growing the history with
>> "git commit", refining the history with "git rebase", etc.  But that
>> can only follow if readers understand the branch as more than "just
>> a ref whose name begins with refs/heads/".
>>
>> I am not sure what level the data model description you are writing
>> should be at.  The current description seems to concentrate too
>> narrowly on "a branch is a specialization of a ref" aspect, and
>> while it is not incorrect as a description of a building block of a
>> tool set to implement a workflow, it might be too limiting to form
>> a proper mental model.  I dunno.