From: "Julia Evans" <julia@jvns•ca>
To: "Junio C Hamano" <gitster@pobox•com>
Cc: "D. Ben Knoble" <ben.knoble@gmail•com>,
"Julia Evans" <gitgitgadget@gmail•com>,
git@vger•kernel.org,
"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail•com>,
"Patrick Steinhardt" <ps@pks•im>
Subject: Re: [PATCH v6] doc: add an explanation of Git's data model
Date: Thu, 13 Nov 2025 14:50:13 -0500 [thread overview]
Message-ID: <2265ecb5-b0ba-4a28-904f-186ef5318562@app.fastmail.com> (raw)
In-Reply-To: <xmqqo6p6q32v.fsf@gitster.g>
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.
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.
next prev parent reply other threads:[~2025-11-13 19:50 UTC|newest]
Thread overview: 89+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-10-03 17:34 [PATCH] doc: add a explanation of Git's data model Julia Evans via GitGitGadget
2025-10-03 21:46 ` Kristoffer Haugsbakk
2025-10-06 19:36 ` Julia Evans
2025-10-06 21:44 ` D. Ben Knoble
2025-10-06 21:46 ` Julia Evans
2025-10-06 21:55 ` D. Ben Knoble
2025-10-09 13:20 ` Julia Evans
2025-10-08 9:59 ` Kristoffer Haugsbakk
2025-10-06 3:32 ` Junio C Hamano
2025-10-06 19:03 ` Julia Evans
2025-10-07 12:37 ` Kristoffer Haugsbakk
2025-10-07 16:38 ` Junio C Hamano
2025-10-07 14:32 ` Patrick Steinhardt
2025-10-07 17:02 ` Junio C Hamano
2025-10-07 19:30 ` Julia Evans
2025-10-07 20:01 ` Junio C Hamano
2025-10-07 18:39 ` D. Ben Knoble
2025-10-07 18:55 ` Julia Evans
2025-10-08 4:18 ` Patrick Steinhardt
2025-10-08 15:53 ` Junio C Hamano
2025-10-08 19:06 ` Julia Evans
2025-10-08 13:53 ` [PATCH v2] " Julia Evans via GitGitGadget
2025-10-10 11:51 ` Patrick Steinhardt
2025-10-13 14:48 ` Junio C Hamano
2025-10-14 5:45 ` Patrick Steinhardt
2025-10-14 9:18 ` Julia Evans
2025-10-14 11:45 ` Patrick Steinhardt
2025-10-14 13:39 ` Junio C Hamano
2025-10-14 21:12 ` [PATCH v3] " Julia Evans via GitGitGadget
2025-10-15 6:24 ` Patrick Steinhardt
2025-10-15 15:34 ` Junio C Hamano
2025-10-15 17:20 ` Julia Evans
2025-10-15 20:42 ` Junio C Hamano
2025-10-16 14:21 ` Julia Evans
2025-10-15 19:58 ` Junio C Hamano
2025-10-16 15:19 ` Julia Evans
2025-10-16 16:54 ` Junio C Hamano
2025-10-16 18:59 ` Julia Evans
2025-10-16 20:48 ` Junio C Hamano
2025-10-16 15:24 ` Kristoffer Haugsbakk
2025-10-20 16:37 ` Kristoffer Haugsbakk
2025-10-20 18:01 ` Junio C Hamano
2025-10-27 19:32 ` [PATCH v4] doc: add an " Julia Evans via GitGitGadget
2025-10-27 21:54 ` Junio C Hamano
2025-10-28 20:10 ` Julia Evans
2025-10-28 20:31 ` Junio C Hamano
2025-10-30 20:32 ` [PATCH v5] " Julia Evans via GitGitGadget
2025-10-31 14:44 ` Junio C Hamano
2025-11-03 7:40 ` Patrick Steinhardt
2025-11-03 15:38 ` Junio C Hamano
2025-11-03 19:43 ` Julia Evans
2025-11-04 1:34 ` Junio C Hamano
2025-11-04 15:45 ` Julia Evans
2025-11-04 20:53 ` Junio C Hamano
2025-11-04 21:24 ` Julia Evans
2025-11-04 23:45 ` Junio C Hamano
2025-11-05 0:02 ` Julia Evans
2025-11-05 3:21 ` Ben Knoble
2025-11-05 16:26 ` Julia Evans
2025-11-06 3:07 ` Ben Knoble
2025-10-31 21:49 ` Junio C Hamano
2025-11-03 7:40 ` Patrick Steinhardt
2025-11-03 19:52 ` Julia Evans
2025-11-07 19:52 ` [PATCH v6] " Julia Evans via GitGitGadget
2025-11-07 21:03 ` Junio C Hamano
2025-11-07 21:23 ` Junio C Hamano
2025-11-07 21:40 ` Julia Evans
2025-11-07 23:07 ` Junio C Hamano
2025-11-08 19:43 ` Junio C Hamano
2025-11-09 0:48 ` Ben Knoble
2025-11-09 4:59 ` Junio C Hamano
2025-11-10 15:56 ` Julia Evans
2025-11-11 10:13 ` Junio C Hamano
2025-11-11 13:07 ` Ben Knoble
2025-11-11 15:24 ` Julia Evans
2025-11-12 19:16 ` Junio C Hamano
2025-11-12 22:49 ` Junio C Hamano
2025-11-13 19:50 ` Julia Evans [this message]
2025-11-13 20:07 ` Junio C Hamano
2025-11-13 20:18 ` Julia Evans
2025-11-13 20:34 ` Chris Torek
2025-11-13 23:11 ` Junio C Hamano
2025-11-12 19:53 ` [PATCH v7] " Julia Evans via GitGitGadget
2025-11-12 20:26 ` Junio C Hamano
2025-11-23 2:37 ` Junio C Hamano
2025-12-01 8:14 ` Patrick Steinhardt
2025-12-02 12:25 ` Junio C Hamano
2025-10-09 14:20 ` [PATCH] doc: add a " Julia Evans
2025-10-10 0:42 ` Ben Knoble
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=2265ecb5-b0ba-4a28-904f-186ef5318562@app.fastmail.com \
--to=julia@jvns$(echo .)ca \
--cc=ben.knoble@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=gitster@pobox$(echo .)com \
--cc=kristofferhaugsbakk@fastmail$(echo .)com \
--cc=ps@pks$(echo .)im \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox