Re: [PATCH v3 0/2] doc: add new git tutorial
- From
Julia Evans <julia@jvns.ca>
- Date
- Oct 27, 2026, 18:31 UTC
- Message-ID
- <DEC4FB30-2262-4006-9704-693D099D41B5@jvns.ca>
- In-Reply-To
- <A48F72E1-8686-453E-91EC-674BD92CA1E5@gmail.com>
Show 48 quoted lines
> On Oct 27, 2026, at 11:19 AM, Ben Knoble <ben.knoble@gmail.com> wrote: > >> >> Le 27 oct. 2026 à 10:30, Julia Evans <julia@jvns.ca> a écrit : >> >> >> >> On Fri, Oct 23, 2026, at 2:01 PM, Ben Knoble wrote: >>>>> Le 23 oct. 2026 à 11:17, Julia Evans via GitGitGadget <gitgitgadget@gmail.com> a écrit : >>>> >>>> So far we've gotten 112 comments from 30ish beta testers who have tried to >>>> learn Git for the first using this tutorial. Most of them were able to >>>> finish it successfully. By far the most common piece of feedback was that >>>> people want to learn more about collaboration and branching. I've written a >>>> draft of a tutorial on branching, but this is already quite a lot of words >>>> so definitely we can't cover it in this series. >>>> >>>> I don't know if it's possible to get this merged quickly, but if it were I >>>> think it would be amazing since people are so eager for a tutorial on >>>> branching. If we spend a huge amount of time revising this I think there's a >>>> real risk I'll run out of funding before we have time to write about >>>> branching. Ideally I think it would be great if we could merge a "good >>>> enough" version and then have a way on the website for users to give >>>> feedback on it, so that we can later incorporate that feedback and >>>> iteratively make it better over time. >>>> >>>> Thanks to Paula, Agavi, Ken Wells, Michael / Chgowiz, Ishmaeel, and all 20 >>>> or so other test readers. >>>> >>>> changes in v3: (v2 was the "first" real version since v1 was a WIP) >>>> >>>> * Say that the tutorial supports any version above 2.23.0, when git switch >>>> was introduced, since the next part of the tutorial on branches will use >>>> git switch >>>> * Mention that on Windows the tutorial will work best in Git Bash for and >>>> it might need adapting for PowerShell. (thanks to Ben) >>>> * Add a warning about how Git can dump you into vi, how to handle that >>>> situation, and how to write a longer commit message. I tried to strike a >>>> balance between lightly suggesting that it might be good to write longer >>>> commit messages, while making it clear that you can just use -m"" if >>>> you're not ready to navigate the world of editor configuration. I don't >>>> think we can use Pro Git here though since it's a bit outdated. (thanks >>>> to Ben) >>> >>> I noticed some discussion in Discord about the main text being out of date, >>> but while the appendix makes copious references to editors >>> that have fallen out of style I think it also covers common cases >>> like VS Code and so on.
Yeah I now see that’s a great list, I’ll add a link. I wonder if at some point in the future it would make sense to manage this list in Git (like with merge tools) but that’s out of scope :)
> ;) long emails?
Yes, I really need to start using Apple Mail more consistently. The Fastmail web UI I’ve been using really doesn’t work for these emails :)
Show 25 quoted lines
>>>> ++ >>>> ++Warning about terminal text editors >>>> ++----------------------------------- >>>> ++ >>>> ++If you run `git commit` without any arguments, Git will open a >>>> ++text editor in the terminal for you to use to edit your commit message. >>>> ++This lets you write a longer commit message with more details. >>>> ++By default, Git uses the `vi` text editor, which is extremely difficult >>> >>> Personally, I’d drop « extremely » here to avoid casting a judgement? >> >> The goal isn't to judge vim (I love vim!), it's to make sure people who aren't >> familiar with it know that it's not a good idea to try to figure out how to use it >> in the middle of a tutorial on how to use Git. >> >> It's almost impossible for me to imagine someone successfully learning vim >> when they're unexpectedly put into it for the first time. > > I too love Vim, and I agree. (Well, I sort of did learn both at > the same time, but I had a lot of free time as a first-semester > freshman in college…). > > Anyway, I think since the goal is not to judge, I’d still consider dropping > « extremely », but it’s your call! >
I’ll think about it! Maybe we can briefly explain what it is about vim that makes it so difficult (like "Some signs that you're trapped in `vi`: suddenly typing doesn’t work anymore…”) and take a more “show don’t tell” approach.
Show 17 quoted lines
>>>> ++2. Run `git config --global core.editor YOUR_PREFERRED_EDITOR` >>> >>> This is probably ok for now. Long term I encourage folks to set >>> EDITOR and/or VISUAL environment variables, so all >>> programs know what to do, but shell configuration is way >>> off-topic here :) >> >> Yeah. It also depends on whether the user is planning to use a terminal >> editor at all, I think some folks will choose to use their IDE integration to >> work with Git and so setting EDITOR might never become relevant in >> that case. > > Well, if they use their IDE’s integrated terminal and run a command > that looks at either variable… ;) Although I wonder if some set > those variables in such terminals automatically? > > Regardless, I’ll let this one go as it’s off-topic as I said ‘:D