Re: Rewriting the Git tutorial to cover less content
- From
Julia Evans <julia@jvns.ca>
- Date
- Sep 25, 2026, 17:25 UTC
- Message-ID
- <4c9f0480-768a-48ba-9753-b4d34188b1a1@app.fastmail.com>
- In-Reply-To
- <xmqq7bk9wa4y.fsf@gitster.g>
Show 6 quoted lines
> Omitting some material that is covered in the current tutorial from > the new one would mean that the topics covered by the remainder of > the current tutorial have to be sifted into three buckets: one that > is to be discarded because it is no longer useful to the target > audience, another that needs to be described somewhere in our > documentation set, and the rest that need to be taught elsewhere,
I do think there's a cost to keeping guides around that are outdated and difficult for users to understand.
For example right now `man git` says:
> See gittutorial(7) to get started, then see giteveryday(7) for > a useful minimum set of commands.
This is a nice friendly statement, but in my opinion `gittutorial` and `giteveryday` really do not live up to what it promises, and I think it undermines trust in the documentation.
> though that may be beyond the scope of the project documentation > and better left to other projects that produce "books on Git". It > is somewhat unclear from your description what your plan is to cover > other topics that should still be taught.
I see a couple of possible strategies.
* We can write new guides which are clearer * We can link to outside resources (via https://git-scm.com/learn) which we think do a good job. Right now that page is pretty out of date and it would be very easy to improve.
I think a mix of both is probably most realistic right now.