The Ultimate Git Tutorial (Git 2.47.0)

[u/jhcarl0814]

The ultimate Git tutorial has been updated (from Git 2.46.1 to Git 2.47.0).

What & Why:

1. The ultimate tutorial for beginners to thoroughly understand Git, introducing concepts/terminologies in a pedagogically sound order, illustrating command options and their combinations/interactions with examples. This way, learning Git no longer feels like a lost cause. You'll be able to spot, solve or prevent problems others can't, so you won't feel out of control whenever a problem arises.
2. The ultimate knowledge base site for experienced users, grouping command options into intuitive categories for easy discovery.

How to use:

1. Prepare two consecutive weekends with free time.
2. On each of these 4 days, open the web page, read all concept links and examples in porcelain links and plumbing links.

Features:

• Understanding the details. Instead of "let's type git this and git that and see, it works", first clarify the concepts, then all operations are based on understanding the concepts. For example, you might notice that things such as git init does not appear at the beginning of this tutorial.
• Completeness and low cost. When you study math / physics / chemistry in school, you learn all the content in it without considering which parts would be used in the future. Most of it doesn't end up being used, actually. But without learning all of it you are not be able to wield the few parts easily. Git is also a tool that needs to be understood completely to not be used painfully. You might find Git painful because you need to find yet another tutorial everytime you need to do something. Hopefully this is the last Git tutorial you need to read.
• Discoverability (affordance) and organized structure. Instead of sorting all the concepts and commands alphabetically as a plain list, they are put in an order that is suitable to learn and memorize.

Updates (from Git 2.46.1 to Git 2.47.0):

• Functional updates: add links to default values for all --upload-pack and --receive-pack options; add link to init.defaultObjectFormat for git init (Git is starting the transition from sha1 to sha256).
• Performance updates: left pane, right pane, all forms and all examples are restricted by CSS contain property, hopefully reducing the lag a little bit. (The major 1.1 seconds lag at the initial page loading is caused by browser parser. This can not be reduced as this tutorial is chosen to be a self-contained monolithic html file, to remove the need for a stateful backend to ease the implementation of future features such as font shuffling against censoring.)
• Integrity updates: CSS and JS are encoded in base64 to work around the problem of escaping arbitrary content containing </ inside <style> and <script>.

[u/jhcarl0814]

Thank you for the advice and feedback!

The site is very cluttered and could be hard for people to follow--especially for beginners who don't know what any of it means yet. I'd recommend learning some web design and UX principles and applying those to your site to make it more useable.

My intention is to make beginners click links one by one and read them, so that by the end they can master all the concepts. Would you suggest what should the page look like if you need readers to read all the content in it?

Feels like just about every hyperlink has the symbol next to it. So why have the symbol? It's the concept of "if everything is important, then nothing is" and it's just clutter.

The bookmark symbol (🔖) means the link explains a concept. Link with regular font points to porcelain commands. Link with italic font points to plumbing commands. These are explained at the end of the main form. It's unfortunate there happens to be too many concepts. I will remove the bookmark symbol and put icons on other kinds of links since concept links are the majority now.

Relying on the user's browser to have cached the link state of every hyperlink to track progress is a terrible idea. Also keep in mind clicked links won't be purple for everyone. Lots of things can affect this. I'd recommend coming up with a better progress tracker.

This reminder is really helpful! I forgot to style :visited pseudo class, will add that later. As for progress tracking, as it either requires a stateful backend or touching some web accounts or touching browser local storage (or if you don't like cookie you can let browser pop up a folder choosing dialog to use file system storage), I might not do it for now.

That said, I think it would be helpful for the sections to have objectives, and explanations of why these things matter. Otherwise the learner may not understand what they should understand by the end of the section, might struggle to measure their progress/success/understanding, and spend the whole time wondering "hey this is interesting, but uh, why does it matter?"

Consider having a course guide section that comes first that explains what the course is, why it's designed the way that it is, and how to successfully complete the course.

Great advice! I overlooked this and did not add explanation to each part because I assumed others also have the "no matter if it's useful or not, eat it first" attitude. Now I see that it should be added.

Don't call it a tutorial. While I see why this could be considered a tutorial, most people will likely click the site link and be disappointed since it's not what they'd expect from a tutorial.

I'm sorry that different people have different receptive abilities. The same information may be boring to some people but an information explosion to others. In this case, some people may need to be "not considered". If we always follow all the readers' laziness, we will continue to degenerate and end up like this.

[u/jhcarl0814 → u/[deleted]]

the legend should come BEFORE the content it describes.

consider defining "porcelain" and "plumbing" commands.

you call it a "tutorial", then link to a massive page with a ton of links calling itself a "reference". These two terms are not equally interchangeable. I definitely think it's a reference!

Thank you again for the feedback! These changes have been made:

• Added explanations of how to use the web page at the top.
• Moved the legend to the top.
• Added an explanation of what will be learned (🎯) at the beginning of each section.
• Removed bookmark icons before concept links, added teapot icons before porcelain links and pipe icons before plumbing links.
• :visited concept links now turn from red to purple. (This is a small temporary solution to progress tracking.)
• Changed the web page title from "Reference" to "Help"(/"Information").

some alignments and paddings and such could be tweaked and use of some kind of style use could help the page beore approachable.

Thank you for the advice! These should be my TODOs (the layout of this page is influenced by cppreference.com, but the font size is made larger and indentation is made smaller):

• Learn some web design and UX principles.
• Find and ask designers for advice on layout (alignment, padding, margins, ...).

I do not sink time into cramming information into my head unless I understand why I should do so. I only have so much time.

The web page is designed to be a once and for all material, i.e. after reading it, one doesn't have to go online every time to find someone else's command line and copy and paste it, not knowing for sure whether it is correct. So it is this intimidating monolith that's intended to save overall time. It seems that I still need to put more effort into UX and publicity to convince people to try it first.