131 comments

[ 3.4 ms ] story [ 220 ms ] thread
I got stuck on the setup stage originally. Its not idiot proof enough - like everything to do with *nix and buddies.
Hey, I think I need to add some more setup instructions. Thanks for your feedback.
Nice. I will definitely show this to people who are new to SCM.

How about adding Linux install instructions? Something like,

  apt-get install git
for Debian based distros.
The tutorial does not mention a Windows GUI for git.

There exists TortoiseGit:

   http://code.google.com/p/tortoisegit/
Thanks, I'll add that one to the list.
One thing that is missing is how to revert your working directory back to a tagged revision. Is that done with checkout?
Moving between refs is almost always done with checkout

    git checkout tag-name
Tags are just a fancy label pointing to a commit so you can use them anywhere you'd use a sha1 or branch name.
I'll add that one to the guide as well. Thanks!
Or, if you don't want to keep untracked files:

    git reset --hard <commit>
Please note that this does more then what the parent suggests doing by "git checkout".

This destroys untracked changes and resets your current branch-pointer to <commit>, removing all the commit-history that comes after <commit>. (You can still recover them from the database, e.g. with "git reflog")

I like it. Good start for beginners. I agree that Linux setup instructions are required. Also how to modify the global config.
A 2-3 line "this is why git is useful" at the top would be probably be helpful.

I'm forwarding this my friends who are yet to be using version control. Good stuff.

Thanks, I'll take this into account for an update!
I don't get this. Sure, the tutorial looks very pretty, but it does not explain any concepts.

"Create a new repository." What is a repository? What do I do with it?

The HEAD is a tree "which points to the last commit you've made". Huh? A tree can point? The one in my garden can't. Also, what's a commit? I thought "commit" was a verb, not a noun.

And so on.

It's nice that people want to make something as complex as git accessible, so I applaud the effort. Nevertheless, this just makes me feel like a moron for not finding it simple. After all, the layout and the pictures make me feel like I should find it simple. But I don't, so it must be me, right? I think it's tutorials like these that keep people on TortoiseSVN.

Thanks for your feedback! I completely understand your point. Maybe it would make sense to make another guide with an intro on Source Control Management systems and link it in the git guide. Currently, you need to have a little bit of knowledge on an SCM. But I will think about it.
Hmm, I'm not sure "having a little knowledge on an SCM" does the trick. Let's assume that I've used subversion for years (which surely is SCM). Therefore, for instance, I know that a repository is something on a server that can hold all relevant for my current team (we'll checkout a subdir for each of subproject). Also, I know that committing means sending a change to the server. I also know that I can lock a file and then nobody else can commit it, handy!

The meaning of nearly all SCM-related terms in your tutorial are highly git-specific. Making an SCM intro does not really help that. You need to make a git intro.

Yes, you might be right on this. I will think about it. If you have links where something like this can be found, i would appreciate it. Thanks!
Hi, shameless plug but I've found people enjoyed these two guides on traditional version control and distributed version control:

http://betterexplained.com/articles/a-visual-guide-to-versio...

http://betterexplained.com/articles/intro-to-distributed-ver...

One technique I use is trying to explain the underlying concepts using analogies to what people already know. Most people are familiar with using "Save as..." to create MyResumeOct2010.doc, MyResumeFinal_v1.doc, MyResumeFinal_REALLY.doc, etc. Version control is like a beefed up, automatic "Save as...". You can jump to any version without a mess of different files.

Distributed version control lets you "peel off" individual changes and send them to anyone. If you are making a shopping list with 3 people, you can "peel off" the items that Alice, Bob and Charlie added and put them on your own list.

Once the concepts are clear, you can give them proper names (diffs, revisions, commits, etc.) and things start to click. Anyway, that's what I've found helpful, good luck!

I don't know if they are necessarily Git specific, but probably are distributed version control system specific. For example the concept that committing would record your changes to the local repository wouldn't make any sense to a Subversion user, but would make a lot of sense to say a user of Mercurial.
(comment deleted)
I found this guide very useful, so thanks for making it. :) I've used SVN, Mercurial, and git before, so knowing those made this easy to digest. Plus it covers stuff about git I never knew existed, like gitk. So cool!
As someone who is used to SVN and Mercurial, I found this pretty useful. The author's going to have to decide what the intended audience is - people who have never used SCM, or people who are considering switching from another SCM (probably SVN).
I agree with you in general, but I feel like you take a wrong perspective of it.

The author takes a top-down approach to teaching, which basically means that he thought about this tutorial from his perspective, someone that was already intimately familiar with the details. This, as you pointed out, is wrong. If this is a tutorial for beginners, you need to have some explanation of what "checking-out" means, what "trees" are, etc. If this tutorial is for advanced users, however, its too sparse to give any new information. So in the end, the tutorial is pretty, but helps neither advanced users nor beginners.

I feel like the examples you give, however, are inefficient for a guide as well -- at what point do we start making assumptions about the reader? For example, you give the example that a beginner might not understand trees, but how do we know they understand anything? Do we believe they don't know trees, but do know how to program, and if so, to what level? Do we assume they are proficient in the terminal, and can even install git if it is not already present? The problem with your approach is that it seems like there's never a point at which we stop.

When I learned a new romantic language (Spanish), we didn't start all the way at the beginning with the alphabet, nor did we try to explain conjugation, past participles. We started with simple phrases -- "Hello", "How are you", "The weather outside is nice", without a real understanding of why we said them. Then, over the years, we peel back the onions of why phrases were the way they were -- Adios (goodbye) was a combined form "A dios"--to the gods. But you shouldn't try to teach that from the onset as you'll overwhelm the learner -- you just continually add on layers until they discover themselves.

Similarly, I feel like for this scenario, a tutorial should set up a scenario that fits the commands perfectly -- don't explain why we use git commit -m, have the first user just go through a few scenarios where they just do it. Then, as they learn, build advanced git tutorials that add on layers, so suddenly they start to uncover all the nuances that git has to offer.

Now, granted, that doesn't extend itself to a "simple guide" if you will, but I feel that these iterative examples that let you think are much better.

(comment deleted)
Coming from my perspective (I'm familiar with the concepts of version control, and and a good enough high level understanding of it, but I don't know how to use git and it's commands), I found this very useful and informative. I suppose you could break down knowledge of git into 2 types, WHAT it does, and HOW to use it. I think this tutorial fails at the first part (or doesn't care about it) but is tremendously useful for the second part. It's just a good starting point for someone like me, who knows what it is, but doesn't know how to use it yet.
If you want to learn, get that version control book by Erik Sink. And like other best things in life, it's free (including shipping).
Presumably I know why I want to use git before I look at this guide. Also, I know what a repository is (in the English sense), but just in case, I typed define repository into google: "A place, building, or receptacle where things are or may be stored." Now "Create a new repository" really is dead simple.

The term commit and it's function are made clear in the "add and commit" section. Perhaps the order of "trees" and "add and commit" should be switched, but this hardly makes the guide unusable.

If in doubt, type the commands and see what happens. And, at the very very least, the article is titled "git - the simple guide", not "version control terminology - the simple guide".

Perhaps not everyone is the intended audience, and perhaps some people could supplement this guide with additional reading. I've never used git, and I found this guide clear and useful.

Indeed. I've been using source control of various flavors for 15 years now, and that "Trees" section is completely unparseable by me. Why are there 3 of them? Why do I care that there are 3 of them? What do I use them for? If I don't use them all directly, why are we talking about them?

Further, why are we talking in terms of the actual command-line commands? Surely a version control system as popular as this has tools at least as good as TortoiseSVN so that I don't have to actually type commands into a command prompt like some bearded guy from the '70s. I'd much prefer you tell me the name of the popular Windows/Mac client and walk me through the workflow I'll actually use on a day-to-day basis.

> I don't have to actually type commands into a command prompt like some bearded guy from the '70s

Really? I mean, really?

Absolutely. I am aware that lots of developers seem to like the command line, but I can't for the life of me understand why. I think visually, so looking at a visual interface such as Windows Explorer is several orders of magnitude more productive than fiddling around with cd/ls to give me a picture of what's going on. Once I find what I'm looking for, I'd much prefer to right click on it and get on with my day than open up a terminal, type out a path, then try to remember some archaic command syntax.

As I say, lots of programmers claim to be more productive from the command line than they are in a visual interface. It doesn't make much sense to try to dispute that, but I still find it quite baffling.

Well, as a bearded guy from the 2010's, I prefer the command line to visual interfaces for the same reason I prefer C to LabVIEW.
I don't think it's a matter of programmers being productive per se. The greatest benefits of command line are the ability to easily store, share and reproduce actions. It's just text. You don't need screenshots to explain something, and everything is scriptable.
Note that source control in particular is particularly amenable to the command line, since the output of source control commands is blobs of text that refers to text files on disk; grepping around in it and wanting to access, process, or modify those files by name is a common operation.
I'm not sure I agree with that; I mean I use TortoiseSVN and before that TortoiseCVS as my main interface to version control, and have done for the last 10 years. It works perfectly and I don't feel I'm missing the command-line at all.

(A goal of Subversion was that its command-line commands produce output which is both easily parsable by humans and machines. But still, I never use it.)

>am aware that lots of developers seem to like the command line, but I can't for the life of me understand why.

I used to think exactly like this. It takes a while to get used to the CLI workflow, you only start to reap its benefits once you've gained a solid understanding of unix and also developed the autonomy to select the right CLI tools (e.g. tmux, zsh, vim, git) which creates synergy at every tier of your development stack.

I have written software on Windows and Linux, and when it comes to most tasks related to software development, GUIs tend to get in the way. GUIs are useful at first because all your options are laid out before you, but the complexity increases since the functionality of the entire system must be abstracted through a visual interface.

do you write your programs in sharepoint designer, too? ;)
>I don't have to actually type commands into a command prompt like some bearded guy from the '70s

Really? I mean, really?

Kids today!

> Further, why are we talking in terms of the actual command-line commands? (...) I'd much prefer you tell me the name of the popular Windows/Mac client and walk me through the workflow I'll actually use on a day-to-day basis.

To be perfectly clear, the command line tools ARE the popular client. The only widely used GUI I'm aware of is the one specific to Github. There are others but they generally expect you to be familiar with the command line workflow. Perhaps this is because Git is easily integrated into IDEs in a way that makes sense for that particular IDE; perhaps it's because the command line interface is actually very good, with features like spelling suggestions (if you've mistyped a command name) and autocompletion scripts (sort of like IntelliSense).

By the way, I can't speak for Windows users but the overwhelming majority of Mac and Linux developers are well aware that their shiny GUIs are thin layers over the gross 70s Unix parts underneath. In this world there's no stigma concerning beards or the 70s, and your dismissal of the command line comes across as backwards and absurd. It's a bit like badmouthing non-Hollywood filmmakers because a lot of them work in foreign languages and you "don't want to read some German thing for four hours" when you go to the movies.

To be honest, if you're going to use Git you probably need to at least become familiar with the vocabulary of the command line interface, even if you never use it. This is because so much of the documentation (including unofficial tutorials) and even interfaces of most of the GUI clients are set up to use the same words. This is actually basically a good thing, I think, because it means that switching from one GUI client to another isn't a big deal.

Furthermore, it's possible that the real reason so much of the unofficial Git docs just talk about the command line rather than point you at a GUI client (except for documentation for those clients themselves of course) is that the Git GUI clients are still under so much development and in some cases are really lacking basic features (for instance, last I checked, the TortoiseGit client did not support any way of interacting with the index/staging area, which is a pretty important part of Git).

I think the parting words of the tutorial "Git from the bottom up" described Git as a library for building a version control system, or something like that, and suggested that we have only just begun to see what people can do with it. I kind of like that idea, that maybe it's possible to bury the complexity of Git underneath a really high level interface, although I don't think that I would actually use it. Git's complicated but it's definitely not rocket science. Plus I generally prefer the command line.

Yes. But I think it mainly is a guide for starters with git. It is not supposed to be a full-on guide for source code management.
Your feedback is probably exactly what the project needs in order to become a better introductory guide. As such, I'm surprised the site doesn't include an obvious link to the GitHub repo/issues [1] so that people who have not been enlightened, or want to contribute better explanations, can share what needs to be clarified.

[1] https://github.com/rogerdudler/git-guide

I've added the link on the site. Thanks for the hint!
looks like this is a list of "how to" instructions than why use git. take it for what it is.

I actually have used both tortoiseSVN and git, and I'm actually in love with git!

you should give it a try.

If you want an easier/more clear guide that the one linked, follow their first-time use tutorial. Learning how it works is as simple as installing it and running their tutorial; it wouldn't take you more than 15 minutes.

Again, as a beginner, I would tell you that I find git very simple and effective and would strongly encourage you to check it out. Glancing at your profile and comments, I think you'd find it very easy: http://help.github.com/

Here is an image that might clear up some of your questions: http://en.wikipedia.org/wiki/File:Git_data_flow_simplified.s...

Please could you fix pagination so that page down works correctly? (Other sites that use the same format have it working)
I don't understand; you want page down to go to the next "block"? That would be neat. I'm asking because pagedown seems to "work" as expected on my browser (scrolls down one viewport-height).
Yes, next block. (If I remember which other sites do this resolution independently, I'll update my post)
Completely off-topic, but what tool did you use to create those diagrams?
These are hand-made drawings done with a Wacom Intuos Graphic Tablet.
It so happens that I started using git just 2 days ago. Reading the git help was pretty useful, but I didn't want to spend a week reading pro git(the ebook). This tutorial is pretty useful to get someone quickly up and running, and certainly a better alternative than spending my time learning git (not that I won't study the details as I go along) rather than the actual project.
I would advice you to read "Pro Git".
You should mention the "git gui" command alongside gitk. It's a really great way to see the changes in your working tree, stage files into the index, and finally commit. You can even right click on hunks in the diff and select "Stage Hunk for Commit" to stage just parts of a file. Generally I'm a command-line person but git gui is a lot easier to use than "git add -i" Also, git novices whom I know have generally reacted well to git gui.
I particularly like "Stage Line for Commit".
I am a designer first and fiddle with programming second. Although I use GIT I am no expertert in it and actually this tutorial made a few things fall in place for me.

So for what it's worth, thanks.

The idea is nice, but the implementation is crap.

I don't use git but I'd like to. I guess I'm the target market in a sense. The key to simplifying a tutorial is removal of jargon. Just tell it like it is.

FYI: This is the line at which I closed the tab: "checkout a repository" - wtf. I don't know what a repository is and now I'm checking it out? is checkout a typo? maybe it should be check-out? either way, I have no way of knowing and confusion has set in. Unfortunately, tab is closed.

Really? You don't know what a repository is? Or are you just being hypothetically ignorant?

I believe that somebody googling git usage is going to be a little bit conversant in the topic of version control.

Well, we use Git at my work, and I have a vague idea of what a repository is... But not really.

I also have to say this:

> I believe that somebody googling git usage is going to be a little bit conversant in the topic of version control.

So you seriously believe somebody trying to learn about version control will already know about version control?

Well, you proved me wrong, but a few minutes ago I did believe someone googling about git would know something about version control.

For the same reason that I believe someone googling about haskell or erlang probably knows something about programming.

Also someone googling about recursion probably knows something about recursion (e.g. that he is googling for it).
Really. For me a repository is somewhere I might leave something...storage...like dropbox maybe? I don't know what it means in the github jargon sense. I have no idea what version control is specifically, but again, I guess it is v1.0 v2.0 etc.
I'm sorry for my attitude. There were some other posts that were doing the hypothetical thing and I guess I was having an allergic reaction.

I forget that this site is about startups and not specifically programmers or people with a heavy IT background.

It's my fault and I apologize.

It is very much like dropbox, in that a repository is a special purpose folder that the git application can run against.

One difference is that you can have multiple of these folders, not only on your local machine but also on remote servers.

So let me see if I get this right.

A repository is like a slave folder to a master folder, when the master folder is updated (the github folder) the contents are automatically copied to all repositories. In this way, it saves from having to update all folders manually and keeps everything in one place, with only one thing needing changes, which then propogate automatically to where they are needed?

Any idea what version control is?

i use git and here's an example.

you can think of a repository as a git-aware folder of code. if you go into your My_Documents folder, type `git init`, it's now a repository. if you click New Repository on github.com, navigate back to your local My_Documents repo, type `git remote add my_github_repo git@github.com:brador/my_documents.git`, you can then push your local repo into that repo with `git push my_github_repo` from your local repo. or if someone else commits to my_github_repo, you can pull changes downstream with `git pull my_github_repo`. git will check repos against eachother for conflicts.

i don't think a "master folder" really makes sense. if you're developing an app, you generally start with that local git init repo, and then you may push it to github. but then you may delete that local repo or go to another computer and type `git clone git@githjub.com:brador/my_documents.git` and it creates a local repo that you can resume working on. i think the point of decentralized version control like git is that there doesn't need to be a master repository. you can always merge repositories into eachother.

Thanks, that explanation actually makes quite a lot of sense!
"checkout a repository"

I see this pattern all the time where people use the single-word noun form as the verb. It should be "check out" in that instance.

What's the point of including instructions for downloading git for MacOSX, when it's already installed in the system by default?
I don't think Git ships with OS X, does it? I think it's bundled with XCode but not with the base OS.

http://apple.stackexchange.com/questions/18470/why-is-git-no...

Quite possibly; all of the Macs I have on hand already have Xcode installed so I can't check. But I don't think that's a big issue; if you're developing software you're almost certainly going to want to install Xcode and all the accompanying dev tools anyway.
What is that font and why does it look awful on Windows?
It's a Google Web Font. I'll check that later. Thanks for the hint!
The giant font doesn't make it any easier to understand. Stuff like 'your local repository consists of three "trees" maintained by git' only makes sense to people who already know how git works.
I'm always happy about better wording. Any ideas?
I think the problem is that the guide doesn't explain the vocabulary it uses at all. There are programmers (and definitely non-programmers) who might not have heard the word "tree" used to describe a directory filled with files and other directories. It's immediately clear once it's explained, and the guide even has little drawings that look like a directory tree, but for people new to version control and people who have used CVS or SVN this use of the word might be foreign. The same with "commit" since someone coming from another system has a different idea of what that means and someone new to version control has no idea.

Honestly, I'm not even sure you need to talk about "trees". The first chapter of Pro Git doesn't mention them at all, and this section describes the working dir, the index and HEAD without using the word: http://progit.org/book/ch1-3.html Instead he talks about "snapshots" and "stages".

I found it pretty helpful with the use of the word "tree" (got it from http://progit.org/). But I definitely need to add some kind of glossary to the page.
Exactly. You can use a big happy font, but when step 2 tells me to create a "repository" and I'm already stuck.... well, that's a problem.

A repository for what? Is this a folder on my computer somewhere? Should I be moving code into this folder? No idea.

In order to make this tutorial helpful, why not take a simple project and get it working under Git?

For example, let's say right now I have a folder that consists of a single source code file like testapp.php, a README.txt, and then a content folder with some images in it. How can I take this mini project and start using Git to manage my code?

I'm seriously that "beginner" when it comes to Git. I do not understand it at all. Maybe I'm not your audience. This tutorial was FAR from simple IMO.

Thanks for putting this together, it looks great. I should mention that the word "shit" in the title of this will make it challenging for me to share this with many professional colleagues.
Mac OS X Lion ships with Git by default. So no need to download Git for that platform.

Also, brew is a better choice for installing and keeping git up to date.

I wish git (and mercurial for that matter) could properly backup large files. I have some sql files > 100MB that I can't check into source control.
Why not?

edit: I use git for game development, and we check in some big asset files (uncompressed .wav music tracks etc.). As long as these don't change too often, the repo stays manageable. Up to 10gigs is still a reasonable repository size IMO.

Having used SVN, and in the process of starting a new job where they use GIT, this actually helped quite a bit. It was quite timely for me.