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

Re: Rewriting the Git tutorial to cover less content

From
Julia Evans <julia@jvns.ca>
Date
Sep 25, 2026, 19:22 UTC
Message-ID
<17c46e4e-a4f6-433e-8eea-c1e4eb28fdfd@app.fastmail.com>
In-Reply-To
<xmqqh5jdur4c.fsf@gitster.g>
On Fri, Sep 25, 2026, at 2:23 PM, Junio C Hamano wrote:
Show 22 quoted lines
> "Julia Evans" <julia@jvns.ca> writes:
>
>>> 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, ...
>
> Yes, it outlived its time and the world has moved on.
>
>> 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.
>
> Whatever we do, it is not enough that new guides are more clear than
> the current one.  The goal should be that it also is sufficient to
> replace the current one. 

I don't understand what you mean by "replace the current one". Some interpretations I can imagine:

1. The documentation remains internally consistent, like if it says
   "see <page> for <information>", then the information is in fact on that page
2. Any information explained in a guide must always be explained a
    in some guide in the future
3. We should aim to make guides more _useful_ over time: on average,
    a user reading the new version of the guide should come away having
    learned more relevant-to-them information about Git than with the
    old guide.
4. The original intent of a guide needs to be maintained.

I imagine everyone agrees that #1 is important. I spend most of my time thinking about how to do a good job of #3.

> I do not know if we have bandwidth to keep external links fresh, and
> having a set of links to stale pages ourselves may hurt more than
> help.

We've had a list of links like this since 2013, at https://git-scm.com/doc/ext. It definitely has broken links and it would be pretty easy to update some of them once, which would help in the short term.

Previous: Junio C HamanoNext: Junio C Hamano
Message 20 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.