git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: Rewriting the Git tutorial to cover less content

From
Junio C Hamano <gitster@pobox.com>
Date
Sep 25, 2026, 16:47 UTC
Message-ID
<xmqq7bk9wa4y.fsf@gitster.g>
In-Reply-To
<bd5d9451-ac5a-4274-9a7a-57ae99864fe9@app.fastmail.com>
"Julia Evans" <julia@jvns.ca> writes:
Show 14 quoted lines
> I'm working on a patch series to replace `gittutorial.adoc` with a completely
> rewritten tutorial, since a lot has changed since it was originally written.
> ...
> I'm excited about this direction, I've already gotten some positive feedback from
> test readers, like:
>
>> I can say I liked this tutorial better than any of the other git tutorials I've tried.
>
> and
>
>> I really like the tutorial, it's easy to follow and I learned a lot!
>
> I have some ideas for what to do with `gittutorial-2` too but I'll leave
> that for another discussion.

As long as it does not mean that learners now have to read three documents instead of two (i.e., your replacement, gittutorial.adoc, and gittutorial-2.adoc), I am also excited.

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, 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.

As we reached consensus at the contributors' summit, we should wean ourselves away from the mindset that these tutorial materials can be incrementally polished to match today's needs, so if the plan for 'the rest' is also to write on these topics from the ground up, that would be very good.

Thanks.
Previous: Julia EvansNext: Julia Evans
Message 17 of 23 in “doc: add more AsciiDoc cross-references”
  1. doc: add more AsciiDoc cross-referencesJulia Evans via GitGitGadget, Sep 22, 2026
  2. Junio C HamanoSep 22, 2026
  3. Julia EvansSep 22, 2026
  4. Jeff KingSep 23, 2026
  5. Julia EvansSep 24, 2026
  6. Jeff KingSep 24, 2026
  7. Junio C HamanoSep 24, 2026
  8. Julia EvansSep 24, 2026
  9. Junio C HamanoSep 24, 2026
  10. Jeff KingSep 24, 2026
  11. Jean-Noël AVILAOct 18, 2026
  12. Kristoffer HaugsbakkSep 23, 2026
  13. Jeff KingSep 23, 2026
  14. doc: add more AsciiDoc cross-referencesJulia Evans via GitGitGadget, Sep 25, 2026
  15. Jeff KingSep 25, 2026
  16. Rewriting the Git tutorial to cover less contentJulia Evans, Sep 25, 2026
  17. Junio C HamanoSep 25, 2026
  18. Julia EvansSep 25, 2026
  19. Junio C HamanoSep 25, 2026
  20. Julia EvansSep 25, 2026
  21. Junio C HamanoSep 25, 2026
  22. Julia EvansSep 28, 2026
  23. Junio C HamanoSep 28, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.