How Git Works by Julia Evans

" Hello!

I am so happy that the Korean translation of 《How Git Works》 has been published. Although I cannot read Korean, looking at the design and quality of the translation, I felt that it was made truly beautifully.

I hope this little zine helps you understand and use Git with more confidence.

Enjoy reading! "

— Julia Evans

Hello. We are BFS (Byte Freaks Studio). 🎲
After reading Julia's greeting, you might have a question.

Why did Julia decide to create this zine?

Git is a tool used daily by countless developers around the world, but at the same time, it is also the tool that many people find most difficult. Julia also focused on that point, and those reflections eventually led to the creation of 《How Git Works》.

The following text is a blog post written by Julia herself at the time of the publication of 《How Git Works》. I am introducing it in Korean as I believe it is a piece that allows for a deeper understanding of the core problems this zine aimed to address and what it intended to convey.

Please enjoy reading. 🎲

Hello!

It feels like I've been talking about nothing but Git on this blog for months. Finally, the Git Zine is complete! It was published last Friday.

Who is this zine for?

I wrote this zine for people who have been using Git for years but are still afraid of it. I always think the same thing: it really sucks to have to be afraid of a tool you use every day for work! I want people to be able to use Git with confidence.

The goal of this zine is as follows:

• Explain that Git concepts which may feel scary at first (for example, the "detached HEAD state") are actually quite simple once you understand what is really happening.

• Point out specific areas in Git where you need to be especially careful. For example, stash is one of the features where it's easiest to lose your work, and once a problem occurs, recovery is extremely cumbersome. That's why I tend not to use stash very often.

• Correcting widespread misconceptions about core Git concepts such as commit, branch, and merge

Why on earth is Git so confusing?

Writing this zine was much harder than I expected. When I started writing, I had already been using Git quite confidently for 10 years. As a result, I could hardly remember what it was like back when I used to struggle with Git.

But thanks to Marie and the many people on Mastodon who shared their thoughts on Git, I eventually came to see once again that there are so many parts of Git that are unintuitive, misleading, or just plain confusing.

For example, things like these.

• Confusing terms (expressions like "fast-forward", "reference", "remote-tracking branch")

• Misleading messages (for example, the message Your branch is up to date with 'origin/main' does not necessarily mean it is actually synchronized with the main branch of the remote repository)

• Output results that do not provide sufficient information (for example, even now, when I look at merge conflicts, there are times when I cannot immediately tell which code came from which branch)

• Insufficient guidance regarding diverged branches (for example, when you run git pull and the local and remote branches have diverged, Git does not explain very kindly how to handle this situation)

• Inconsistent behaviors (for example, while the reflog almost always operates in an append-only manner, the stash is an exception; running git stash drop actually deletes the existing entry)

The more I hear about how confused people feel about Git, the clearer it becomes that Git is a tool whose internal logic is not easily understood simply by trying it out.

You eventually get used to Git's quirks

Reading this far, Git might sound like a truly terrible tool. You might even wonder, "Who on earth would use something like this?"

However, my experience is a bit different. Once I understood what those strange error messages Git spits out actually mean, most situations became quite routine.

For example, let's say you encountered the following error.

failed to push some refs to 'github.com/wizard-zines-site'

Then I think, "Ah, someone must have pushed changes to the main branch since I last did a git pull." Then I run git pull --rebase to bring in the changes and continue with what I was doing. It usually takes about 10 seconds.

Or you might see a warning like this.

You are in 'detached HEAD' state

In that case, you can simply run git checkout mybranch before you continue writing your code. It's not a big deal.

For me, and for many people I talk to about Git, its peculiar expressions have become so familiar that we sometimes even forget why someone would find them difficult in the first place.

How deep should we go into Git's internal structure?

One of the things I agonized over most while writing this Zine was how much of the inside of the .git directory I should explain.

In the end, we decided to include a page covering Git's internal structure ("Exploring the .git folder"), but overall, we chose to focus more on the behaviors you actually see when using Git and the reasons why Git sometimes acts unexpectedly.

There are two reasons for this.

One is because there are already many excellent resources available that explain Git's internal structure.

And the other reason is that I felt that even after reading such materials, it is not as easy as one might think to understand how they connect to the actual phenomena seen in the Git user interface.

For example, explanations regarding Git's remote repositories are easy to find. Some documents explain it as follows:

Remote-tracking branches [...] remind you where the branches in your remote repositories were the last time you connected to them.

But even after reading this explanation, the following message displayed in git status

Your branch is up to date with 'origin/main'

it does not necessarily mean you will naturally understand that it isn't completely synchronized with the main branch of the remote repository.

So, in this zine, rather than explaining Git's internal structure first, I focused on the behaviors you actually encounter while using Git and aimed to explain the principles of how those behaviors work internally.

Actually, I really like Git

In this article, I have shared quite a few critical stories about Git. However, I only write zines about the technologies I love. Git is no exception.

There are many reasons why I like Git.

• It's fast!

• Backward compatibility is excellent. The Git knowledge I learned 10 years ago is still almost entirely valid today.

• There are so many great Git hosting services available for free. (GitHub! GitLab! and many others!) Thanks to them, I can easily back up my code.

• Simple workflows are truly simple. When working on a project alone, repeating just git commit -am 'whatever' and git push works perfectly fine most of the time.

• Most of Git's internal files are fairly simple text files. (Or there are versions that can be viewed in text format.) So it gives you the feeling that you can understand what's going on inside at any time if needed.

I hope this zine helps you come to love Git at least a little bit.

People who helped create this Zine

I don't make these zines alone!

I worked with Marie Claire LeBlanc Flanagan every morning for eight months, thinking about how to explain Git more clearly. Vladimir Kašiković worked on the cover, and Gersande La Flèche handled the proofreading. James Coglan, the author of 《Building Git》, provided the technical review, and Lee, the operations manager, helped with text transcription as well as countless other tasks. My partner Kamal, as always, read the drafts and pointed out awkward parts, and I also had many great conversations about Git with Marco Rogers.

Finally, I would like to express my gratitude to the beta readers. This time, a whopping 66 beta readers participated, which was the largest number ever! They left hundreds of comments on what was confusing, what they learned for the first time, and which of my jokes were actually funny.

It is never easy to hear that a page I thought I had explained clearly was actually very confusing. However, because I was able to discover and fix those issues before the final publication, this zine could become a much better final product.

Thank you

As always, I would like to express my sincere gratitude to everyone who has purchased my zines over the years. I was able to come this far thanks to your constant support.

And thank you to the more than 1,000 people who purchased this zine in just 3 days after its release!!!

Thanks to you, this zine set a record for the most copies sold in a single day in Wizard Zines history. It’s truly amazing, and I am deeply moved.

BFS(Byte Freaks Studio)

Did you enjoy reading Julia's post?

The most impressive part of this piece was that Julia didn't stop at simply criticizing the inconveniences of Git. Git is difficult. Sometimes it's strange, some messages are hard to understand, and certain behaviors are unintuitive. However, Julia asked the question, "Why is Git like this?" and then proceeded to step-by-step analyze and explain the reasons why Git is so difficult to understand.

Another thing that was impressive was the perspective on Git learning materials.

There are already many excellent resources available that explain the internal structure of Git. However, even after reading such materials, many people are often left wondering, "So why is Git behaving like this right now?" when they actually start using it in the terminal.

There is a larger gap than one might think between Git's internal principles and the user interface that actual users encounter. Many of you have likely had a similar experience: feeling like you understand it after reading parts of a thick book on Git, only to become flustered again when you encounter an error message during actual work.

We highly appreciated how Julia pinpointed that exact gap. Above all, this sentence particularly resonated with us.

You are in 'detached HEAD' state

If you are a developer, you have likely hesitated at least once after seeing this message.

"What does this mean?" "What should I do now?" "If I touch the wrong thing, will something break?"

I have also had similar concerns as you. That is why I felt this book is less about trying to explain everything about Git, and more about helping you understand why Git behaves the way it does.

And as that understanding builds, Git becomes a tool that is a little less unfamiliar and a little less intimidating. I hope that through 《How Git Works》, you too will come to understand Git a bit more and fear it a bit less.

— BFS 🎲