Re: [PATCH 0/3] [doc] Remove gittutorial-2

From: Julia Evans <julia@jvns.ca>
Date: Sep 29, 2026, 10:42 UTC
Message-ID: <8a5b742a-3f11-4bfa-954b-ffdd839b6d43@app.fastmail.com>
In-Reply-To: <xmqq5wzojy31.fsf@gitster.g>

> Is this the "two series" approach you mentioned earlier?

The idea is that:

1. we delete gittutorial-2 (this series)
2. we delete gittutorial
3. we add a new gittutorial

We could also combine #2 and #3 into a single series. I don't feel strongly about that and it might (as you mention below) be better to wait to delete gittutorial until we have a replacement ready to go.

Show 11 quoted lines

> There is no need to ensure that the new document that replaces the
> old one covers everything the old one did.  After all, giving us a
> clean slate and letting us choose what to cover (and, more
> importantly, what not to cover) with fresh eyes to match the needs
> of today's world is the whole point of redoing the tutorial
> document.
>
> So I personally feel it is OK to remove the old one, without
> promising or even hinting at what in the new one that replaces it.
> But we would want to see its replacement in the not-so-distant
> future.

I'm not planning to replace gittutorial-2 since the material in it is already covered by gitdatamodel and gitcore-tutorial. Let me know if you disagree!

Show 5 quoted lines

> Also, we may want to decide what to do with gittutorial.  It is
> short and reasonably sweet.  One old-fashioned thing that does not
> exactly match today's prevalent usage patterns may be that it starts
> tracking a new project from a tarball, but other than that, it may
> not hurt to keep it around.  I do not know.

We definitely want a tutorial that covers `git init`, `git add`, `git commit`, etc. Any replacement would definitely cover those topics, but I don't see the value of having 2 such tutorials. Why do you think it would be valuable to keep it around? It seems like it would cause a lot of confusion to me.