Problems in Git

Primary Links To Website

Glossary
Command Overview {{Incomplete}}

Too Many Unclear Terms (The Staging Index Example)
Is a Staging Area Part of a Repository?
Demystifying Remotes
What is "Tracking"?

Note: "Command Overview" is unavailable at the moment, and I don't know when it will be published. It took a very long time for me to deep dive into Git terminology, create the glossary, and write the four articles that are currently available. I also had work, school, family obligations, and other private issues that needed to be dealt with. At some point, I decided to stop work on the "Command Overview" (which was the least developed because it required the glossary) and focus on the other links made available to you. Maybe a long time from now, I'll get around to publishing the "Command Overview".

Introduction

Git documentation has some serious problems.

I tried to learn Git on my own and for a long time, I found simple concepts in Git difficult to grasp despite leafing through what I thought was the official documentation. Apparently, I'm not the only one.

Some people know they don't understand Git. Some people think they understand Git but don't. And a very, very small percentage of people actually understand it. For the most part, it's the blind leading the blind.

I'm not naive nor conceited. I am not in that small percentage that knows Git and this documentation won't be perfect either. Actually, based on what I've learned, no documentation can ever be perfect anymore. I'm just one of the rare people who will admit that.

This isn't the typical documentation you'll find elsewhere. What I've written will either help untangle the knot of misconceptions floating around out there, or at least clear up some questions some of you have.

Target Audience

My target audience is geared for the newbie and the casual Git user.

If you're completely new to Git and don't know how to add a branch, this documentation isn't for you yet. There are lots articles out there that describe how to do this. Atlassian has some good stuff. Look at my stuff again in a month.

If you know how to add branches and do commits, but you don't understand why it's so hard to understand the difference between a "tracking branch" and a "remote-tracking branch", then this is the right place for you.

If you don't know that "remote reference" has two very opposite definitions or if you don't know that "remote" has five different definitions, then this is the right place for you.

If you're advanced enough where Git is just a bunch of "blobs" and "tree objects" to you, then you're probably in the wrong place... except if you want to rewrite Git documentation so the everyday user can understand it, then I want you to take any ideas from here that you think is worthy to be taken.

Links to Official Git Documentation

The Links

Official Git Website
Git Glossary
Git Reference
Git Man Pages
Git Manual (For advanced users of Git)
Pro Git, 2nd Edition
Official Source Code for Git documentation
Git Glossary
Git Manual
Git Wiki

Note: The information in my website primarily pulls information from the Git glossary, Git man pages, and Pro Git.

Is Pro Git Considered Official Documentation?

Pro Git is the first thing recommended to most new Git users because it's free and instructive about how Git works. The official Git website even contains very prominent links to the Pro Git book. What is strange is a lot of people consider Pro Git not official documentation.

Supposedly, official documentation is considered only to be what is found in the Git repository. The Git glossary and Git manual (for advanced users) can be found in there, so those two items seem to qualify.

Pro Git, however, is not found in the repository. For many people in the Git community, that makes the Pro Git book not official.

I disagree. On the official Git website, there seems to be a clear distinction between the documentation link (which contains links to man pages, Pro Git, and videos) and "external links".

Let me be frank: if Pro Git is not included, then the official Git documentation is beyond awful. In a water cooler conversation (but not on this website), I might argue that the official documentation lands in the territory where "it's better not to have the official documentation". It is so incomplete and so disorganized that it misleads and misinforms users. (Want a quick example? Remote-tracking reference is used in the man pages, doesn't exist in the Git glossary, and is a term that shouldn't exist.)

As much as I dislike Pro Git, it is the closest official source of information new comers and casual users have to make any sense out of the madness. For this reason, I lean heavily on Pro Git and include it in my analysis throughout this website.

How Well Does Anyone Know Git?

So, you can clone a repository, but what does cloning do exactly?

One of the things I learned is that cloning automatically creates a "tracking branch". If I wanted to create or delete a tracking branch without cloning, why are there no explicit commands to view, create, edit, and delete tracking branches? I'll give you some hints:

As I dug deeper, things didn't get better. Why does the exact same git checkout <branchName> command sometimes a create a tracking branch and sometimes not -- even when the parameters on the command line are exactly the same? {{TODO: Verify this is correct and add hint}}

If a remote branch refers to a branch on a remote repository, does a remote-tracking branch represent a tracking branch stored on a remote repository?

Hint: Tracking branch and remote-tracking branch are both stored in the local repository.

Does "remote reference" refer a reference that exists in an external repository or a reference that exists in a local repository?

Hint: "Remote Reference" has two different official definitions.

Does "remote" refer to a remote repository or to a tracked repository?

Hint: "Remote" has five different official definitions. And although "tracked repository" is one of those official definitions, "tracked repository" isn't a real term.

Is a remote-tracking branch a local reference or a remote reference?

Hint: According to Pro Git, it's both a local reference and a remote reference.

For a long time, it seemed every question opened up a series of new questions and led down a darker path.

I found definitions and explanations for topics are wildly different not only in unofficial Git documentation, but also in official Git documentation. There is a lot of incorrect, misleading, and contradicting information out there. It was clear that I was far from the only confused person.

After an embarrassingly high amount of time, I finally began to understand why some things were unclear and where the pitfalls were. Very slowly, I was able to pull the seemingly disparate information back together into the documentation you are now reading. Git is a really good program, but the historical baggage makes it difficult for new comers and casual users to use more than a simple few commands in Git.

Nevertheless, with the right information, I believe newcomers and casual users can utilize Git like a professional on the command line without the headaches I got. My documentation isn't the start and it isn't the end of the Git learning process, but I believe it can be a good resource.

And maybe, with some luck, the Git team can look at my work and make better documentation. (I'm hopeful. We're all on the same side, after all.)

Copyright and License

Creative Commons License

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

Personal Note

It's my goal to improve Git documentation. Sharing what I created and letting others build upon it is my ultimate goal.

I haven't decided yet if I want to release this under a CC0 public domain license, so I went with the Creative Commons license as a start.