From: "Julia Evans" <julia@jvns•ca>
To: "Junio C Hamano" <gitster@pobox•com>,
"Julia Evans" <gitgitgadget@gmail•com>
Cc: git@vger•kernel.org
Subject: Re: [PATCH 2/5] doc: git-add: start man page with an example
Date: Tue, 12 Aug 2025 17:40:19 -0400 [thread overview]
Message-ID: <152d47a3-7744-476a-8ab8-43b7b52b67ea@app.fastmail.com> (raw)
In-Reply-To: <xmqqbjoks19f.fsf@gitster.g>
> But isn't it the source of the most end-user confusion that they
> cannot wean themselves off of the diff/patch worldview?
To me it feels very contextual! My impression is that what's important for Git
users is to be able to think about commits as diffs in some contexts, and as
snapshots in other contexts. For example with `git rebase` I'm usually thinking
of my commits as diffs, but it's very helpful to me to think of a merge commit
as a snapshot, because the merge commit does not have to be a "combination" of
the two sides of the merge, it can have arbitrary extra content.
> Wouldn't "add file X" confuse folks who still remember how other
> SCMs before Git operated (i.e. "file X is now known, so if I make
> further changes to X next 'commit' command will record it") into
> thinking that Git would do the same?
The point about Subversion is interesting: I would expect that most
people learning about Git's data model in 2025 have never used
Subversion.
So while I think it's extremely important to make accurate statements
while talking about Git (and I think it's very possible that this description
is not accurate enough!), I do not think it's so important to specifically
target misconceptions that users coming from Subversion/CVS
may have.
>> +By default, `git commit` only commits changes that you've added to the
>> +index. For example, if you've edited `file.c` and want to commit your
>> +changes, you can run:
>> +
>> + git add file.c
>> + git commit
>
> What happens when you did "edit && add && edit && add"? It commits
> the two changes you added to the index? I do not think it is
> productive to hide the fact that you are preparing a snapshot of the
> "next commit" in the index (or "staging the contents for the next
> commit in the staging area") with various forms "git add", including
> "git add -p".
It could! It's easy for me to imagine a world where the index
stores an ordered list of diffs, which are applied as patches in
series when I commit. I guess you'd need some sort of
patch + patch + patch + diff workflow to generate the final diff,
but to me that doesn't feel so different from what Git is actually doing in
practice.
In any case, I'll think more about whether I think this is really
an accurate description. I'm always especially interested in the practical
consequences of having misconceptions about Git: for example (and maybe I'm
convincing myself to change my position here!) with `git mv` I think it can
become relevant pretty quickly that commits are snapshots, because if
you move a file and edit it then Git can't always accurately guess that you
intended to "move" the file rather than delete the file and create a new one.
I'd like to be able to have a similarly practical example of why it's important
to think of commits as snapshots in the context of `git add` but I haven't quite
found the right one yet. I've noticed that people will often sort of "reject"
information that does not fit their mental models, and I think "commits are
snapshots, this is important in this context because of
<specific practical consequence>" is much more convincing than just
"commits are snapshots".
next prev parent reply other threads:[~2025-08-12 21:40 UTC|newest]
Thread overview: 59+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-08-12 20:07 [PATCH 0/5] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-08-12 20:07 ` [PATCH 1/5] doc: git-add: remove options from SYNOPSIS Julia Evans via GitGitGadget
2025-08-12 20:41 ` Junio C Hamano
2025-08-13 16:58 ` Julia Evans
2025-08-13 20:47 ` Jean-Noël AVILA
2025-08-12 20:07 ` [PATCH 2/5] doc: git-add: start man page with an example Julia Evans via GitGitGadget
2025-08-12 21:01 ` Junio C Hamano
2025-08-12 21:40 ` Julia Evans [this message]
2025-08-12 22:12 ` Junio C Hamano
2025-08-12 22:45 ` Julia Evans
2025-08-13 17:22 ` D. Ben Knoble
2025-08-14 0:41 ` Junio C Hamano
2025-08-14 2:59 ` Julia Evans
2025-08-15 5:38 ` Junio C Hamano
2025-08-12 20:07 ` [PATCH 3/5] doc: git-add: simplify discussion of ignored files Julia Evans via GitGitGadget
2025-08-13 17:24 ` D. Ben Knoble
2025-08-12 20:07 ` [PATCH 4/5] doc: git-add: make explanation less dry Julia Evans via GitGitGadget
2025-08-12 20:07 ` [PATCH 5/5] doc: git-add: explain inconsistent terminology Julia Evans via GitGitGadget
2025-08-12 20:51 ` Chris Torek
2025-08-12 21:36 ` Junio C Hamano
2025-08-12 21:43 ` Julia Evans
2025-08-13 23:20 ` [PATCH v2 0/4] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-08-13 23:20 ` [PATCH v2 1/4] doc: git-add: start man page with an example Julia Evans via GitGitGadget
2025-08-15 0:38 ` Junio C Hamano
2025-08-15 13:34 ` Jean-Noël AVILA
2025-08-15 16:33 ` Junio C Hamano
2025-08-17 18:37 ` Jean-Noël AVILA
2025-08-19 20:01 ` Julia Evans
2025-08-13 23:20 ` [PATCH v2 2/4] doc: git-add: simplify discussion of ignored files Julia Evans via GitGitGadget
2025-08-14 0:59 ` D. Ben Knoble
2025-08-14 22:10 ` Junio C Hamano
2025-08-13 23:20 ` [PATCH v2 3/4] doc: git-add: make explanation less dry Julia Evans via GitGitGadget
2025-08-14 22:22 ` Junio C Hamano
2025-08-15 16:10 ` Julia Evans
2025-08-15 18:25 ` D. Ben Knoble
2025-08-15 20:01 ` Junio C Hamano
2025-08-16 14:15 ` D. Ben Knoble
2025-08-15 19:47 ` Junio C Hamano
2025-08-19 12:57 ` Julia Evans
2025-08-21 20:36 ` Jean-Noël AVILA
2025-08-13 23:20 ` [PATCH v2 4/4] doc: git-add: explain inconsistent terminology Julia Evans via GitGitGadget
2025-08-14 22:49 ` Junio C Hamano
2025-08-19 20:09 ` Julia Evans
2025-08-19 20:46 ` [PATCH v3 0/3] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-08-19 20:46 ` [PATCH v3 1/3] Git 2.51 Junio C Hamano via GitGitGadget
2025-08-19 21:06 ` rsbecker
2025-08-19 21:37 ` Junio C Hamano
2025-08-19 21:44 ` D. Ben Knoble
2025-08-19 21:48 ` Julia Evans
2025-08-19 21:49 ` rsbecker
2025-08-19 20:46 ` [PATCH v3 2/3] doc: git-add: clarify intro & add an example Julia Evans via GitGitGadget
2025-08-21 20:08 ` Junio C Hamano
2025-08-22 20:37 ` Julia Evans
2025-08-19 20:46 ` [PATCH v3 3/3] doc: git-add: simplify discussion of ignored files Julia Evans via GitGitGadget
2025-08-21 20:09 ` Junio C Hamano
2025-08-29 11:55 ` [PATCH v4 0/2] doc: git-add: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-08-29 11:55 ` [PATCH v4 1/2] doc: git-add: clarify intro & add an example Julia Evans via GitGitGadget
2025-08-29 11:55 ` [PATCH v4 2/2] doc: git-add: simplify discussion of ignored files Julia Evans via GitGitGadget
2025-08-29 17:11 ` [PATCH v4 0/2] doc: git-add: clarify DESCRIPTION section Junio C Hamano
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=152d47a3-7744-476a-8ab8-43b7b52b67ea@app.fastmail.com \
--to=julia@jvns$(echo .)ca \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=gitster@pobox$(echo .)com \
/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