▲ 665 points
back
129 comments
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.
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.
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.
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).
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.
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.
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.
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...
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).
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.
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.
Make a tutorial that follows the workflow of a bad developer, and you can get a lot of people on board. Show us how to undo terrible mistakes. Show us how to work with other bad developers and working with their terrible mistakes.
To get people on board with Git, you gotta show that anyone can use it, efficiently. That's how you get the most number of people to adopt - when they can easily see themselves using and trusting Git.
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.
Hey pixeldude, there's a lot of negative feedback on here that seems pretty hostile in tone. Don't let it get you down. It's not perfect yet, but you're writing something that I specifically wanted to give others at multiple points in the past.
Some constructive criticism: don't align=center absolutely everything, it makes it difficult to read larger sections of text. If everything is centered, then nothing is centered.
Why not just download Eric Sink's "Version Control by Example" ? http://www.ericsink.com/vcbe/
The book is free or can be purchased and explains both git and Mercurial with similar examples. We use it at our office to get novices up to speed on source control.
"There's just one thing, Dude. Do you have to use so many cuss words?" -- Big Lebowski
Joking aside, there is really no need to ruin a great guide by swearing in the subtitle.
I'm not sure I'll ever understand why developers think they need to swear in articles. In this instance, is it because the author is writing in nerd (addressing a seemingly technical concept) and needs to show his article has some universal accessibility by using one of the most understood terms for excrement in the subtitle?
I mean, I'm glad he warned me there is no deep poop in the subtitle because I won't read ANYTHING that has deep doo-doo in it.
Show some maturity: s/shit/stuff (that'd be Sed for replace the word 'shit' with the word 'stuff')
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.
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
The tutorial does not mention a Windows GUI for git.
There exists TortoiseGit:
http://code.google.com/p/tortoisegit/It is neither helpful to an expert, nor to a beginner. A beginner will have no clue what the article is talking, like tree etc. An expert cannot really use this as a quick reference or something. Looks flashy, but is it anything more?
I would recommend http://gitimmersion.com/
How hard is git that we apparently have needed a new "getting started with git" guide every week for the last 3 years?
I think git is not easy to use, and the proof of that is that at least once a month there is a "how to use git" tutorial on the front-page of HN.
I'm not saying git is a totally bad system, but I disagree with people who think git is easy to use.
You don't see thousands of tutorials on the web, and tutorials hitting the HN frontpage on "How to use Subversion", "My personal Subversion workflow", "My .bashrc file containing my aliases for Subversion". I assert the reason is, that they are not necessary (and not, for example, that nobody uses Subversion, or nobody who reads HN uses Subversion.)
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.
It looks like a lot of people have a case of the Mondays today. Seriously, these are about the number of commands I had sketched out when first starting on GIT, which I assume is your audience. I do have to say that I get a little tripped up between trying to use page-down and having to position the page. A full page side-swipe presentation format would work well here.
I think this guide needs some general explanation of what git is, and what the thinking behind it is (like here: http://progit.org/book/ch1-3.html).
Of course you can get started with this guide, but you have no clue what you are doing. It's learning by following the recipe versus learning by understanding.
I have found gitimmersion (1) to be really useful for beginners.
One thing that is missing is how to revert your working directory back to a tagged revision. Is that done with checkout?
I just wrote a post about my even simpler system for using git for people who know SVN/CVS: Teach yourself git in 2 minutes http://www.jperla.com/blog/post/teach-yourself-git-in-2-minu...
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.
I love this, and I've bookmarked it to email it around when I need to, but I'd love to read something that simplifies setting up git on the server side as a central location for repositories.
But that aside, coming from SVN it makes sense to me, and I've played around with git without really reading into it too much. It's of added interest because deployment and branching seems much less of a hassle with git than with svn.
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.
This community gets to me on occasion, parallel to that meme with the asian father saying 'Why you no get A+'?
I know what git is. I know what source control is. To my knowledge toolbox, you just added an explanation of how a git commit->master is different than a push->remote server. Mission accomplished. Win. Author, please continue executing your work and making this world a better place.
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 like it. Good start for beginners. I agree that Linux setup instructions are required. Also how to modify the global config.
I got stuck on the setup stage originally. Its not idiot proof enough - like everything to do with *nix and buddies.
Here I summarized major differences between Subversion and Git -- I wrote this just to avoid explaining the same things to my customers. I hope someone finds it useful:
http://txlab.wordpress.com/2011/12/02/moving-from-subversion...
Although I already learned how to get started in git "the hard way", I think this guide is really helpful for beginners. I know I would have appreciated it. As a matter of fact, the first repo I pushed to github was a guide on how to do do stuff in github =D
In the example where you `git checkout -b feature_x`, I believe you also want to `git merge feature_x` after you `git checkout master`, as the `-d` flag on `git branch -d feature_x` will only delete the branch if it's been merged.
For me the best Git guide is John Wiegley's "Git from the bottom up" @ http://newartisans.com/2008/04/git-from-the-bottom-up/
Completely off-topic, but what tool did you use to create those diagrams?
Please add Git Extensions ( http://code.google.com/p/gitextensions/).
It's the best Windows Git client I've found so far.
It's weird it says "create a new branch named "feature_x" and switch to it using ..." but it doesn't give you the command to create the branch.
Is that a "bug"?
Using gitx (http://gitx.frim.nl/) really helped me grasp some of the concepts you talk about.
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.
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.
What's the point of including instructions for downloading git for MacOSX, when it's already installed in the system by default?
Isn't pull bad for some reason? I thought you were supposed to use fetch and merge separately. I can't remember why though.
Thanks in the name of all visual impaired, but for 30px font is simply to large for me to read.
The biggest problem with Git is the insistence of using command line. Just so you know, when you install the software it provides a simple GUI where you can, you know, click on buttons instead of memorizing commands.