I've been working a bit the past week on a guide for a workshop I'll be running in a few months to get research mathematicians productive using just GitHub's UI. [0] So the purpose is not identical by any means. But I'm curious whether it's appropriate that this RedHat guide seems to go straight into "what commands do I run" rather than answering/illustrating "how does Git model the history of a software project's files".
The #1 mistake in trying to teach people Git is jumping right to commands without developing a mental model first. It leads to nothing but confusion down the line, and reliance on copy/paste of snippets and scripts to get anything done. Effective usage of Git depends heavily on having a basic understanding of how it works, moreso than a lot of other tools.
Mental models are famously quasi-impossible to transfer. Almost nobody really groks new concepts with theoretical explanations, practical experience is needed almost immediately
Of course; but if you only get practical experience with no theoretical explanations, you're almost sure to develop a mental model that's going to cause you troubles later on.
Definitely a mistake, though you can explain Git's data model in about 2 minutes.
I would say a bigger mistake is starting with the command line. A good GUI is absolutely instrumental to understanding Git, and it lets you avoid Git's terrible CLI for as long as possible.
1. the git commands map so cleanly to the states
2. there are so many terrible GUI interfaces that try and coddle the developer, really hiding the intent
I think the real problem is the flexibility allows for a lot of totally unintended but "legal" actions, from which it is really hard to recover because it's not your standard workflow.
Yeah I definitely agree on the proliferation of terrible GUIs. As someone else said, pick a good one when teaching.
> the git commands map so cleanly to the states
They absolutely don't. Someone already mentioned the mess of "checkout" and "reset" but that's only half the issue. The naming is a huge issue with learning.
The worst is the "index" which is apparently named after the data structure used to store it. Such a bad name that it's often called the "staging area" instead. But even that is bad. Why isn't it just called the "draft commit"? That immediately tells you what it is.
Another example is reset's soft/mixed/hard. Terrible meaningless names. They might as well have been called 1, 2 and 3.
And there's more! It's not just the mapping and the naming. The actual CLI is stupidly inconsistent too. Flags have wildly different meanings depending on the command. You do the same action in totally different ways depending on insignificant differences (e.g. git reset --hard Vs git branch -f).
I have to look up the command to delete a remote branch every single time I use it because it's just so unintuitive.
I think people love the Git data model (which is great) sooo much that they think they love all of Git.
I disagree. "checkout" does literally 2 unrelated things, one of them destructive with no safety checks. "reset" kind of moves HEAD around, but does a bunch of other stuff in the process. "Rebase" has a lot of magical (albeit useful) behavior involved in determining what exactly gets rebased. Etc.
> there are so many terrible GUI interfaces that try and coddle the developer, really hiding the intent
I agree. The CLI is confusing and occasionally obfuscates the data model, so adding yet another confusing obfuscating layer isn't going to really help. That said, a really good GUI that doesn't try to hide what's going on, would be a useful learning aid.
> A good GUI is absolutely instrumental to understanding Git, and it lets you avoid Git's terrible CLI for as long as possible.
Depends on the user.
If they are already an active user of the Terminal, they should be able to learn the git cli without ever touching a GUI.
The git cli has some warts for sure, and some weird inconsistencies. But with a bit of practice and some good documents about the correct mental model to have, you get used to it and you learn to use it very effectively.
Interesting about starting with the GUI. I can see it being useful in a controlled learning environment where you start with the GUI and gradually transition to the CLI. But if you stay on the GUI too long the student might suffer because they eventually will need to use the CLI, or at least understand its vocabulary, in order to read the documentation and get help from other people.
You should almost certainly talk about the way the history is stored. Both because it is essential to understand how git works, but also, if you drop in some of the mathematics that git uses, the mathematicians will enjoy it more.
[0]: http://jmm2024.clontz.org/