8 ms·

A visual Git reference

238 points by dennis_vartan 14y ago

drek 14y ago
Awesome! Very clear and well-written reference. I wish someone would make a reference like this for remote branches and repos, I always keep forgetting commands for setting upstream branches, checking out remote branches and having them tracked, etc.
zephjc 14y ago
This is cool, but every diagram I've seen for git history uses arrows pointing to the past instead of the future, which is a bit confusing.
- praptak 14y ago
  It represents the actual way commits are represented. Past commits cannot be modified to add children (this would change their hashes) so new commits contain references to parents. Changing this in diagrams would create even greater confusion later on.
- megrimlock 14y ago
  The arrows do not represent time. Instead, they reflect the way git represents the commits internally. Each commit is a set of changes to some starting state, identified by the arrow. You could think of it like a citation in a paper that mentions and then extends some earlier findings.
- kisielk 14y ago
  Just think of it as a commit having a pointer to its parent.
  - erso 14y ago
    This, in addition to knowing that a commit may have multiple parents (a merge commit, for example).
- erso 14y ago
  kisielk got it right, but to add: A commit knows about its history via its parent(s), thus the arrow pointing to the parent. As far as I know no commit can (or for that matter should) know about its descendants. Does that help?
endeavor 14y ago
Very nice set of diagrams. But every time I see something this I have to ask myself again why I'm just not using CVS (or SVN, i.e. a simpler tool).
- aidenn0 14y ago
  Because experience shows that on any sufficiently long-running project, you're going to need some of the power that CVS/SVN don't have.
- columbo 14y ago
  My opinion in the svn vs git debate: Unless you are working across multiple groups with developers in different time zones and a choppy set of releases you'll see almost no benefit from git. However, if you are in that situation the benefits are large and immediate.
  - qznc 14y ago
    I love git even for personal single-developer projects.
    - columbo 14y ago
      I do too. I'm just saying the smaller the project the more the benefits tend to lean towards personal preference over empirical evidence.
      - Ralith 14y ago
        I think eliminating the need to set up a SVN repository for very small projects is a major boon.
  - rimantas 14y ago
    Well, if you enjoy 'log' pulling info over the network (slowly), .svn in every single folder, barely useable branching, no reabase, no stach, no… well maybe you have the point. Otherwise not even comparable. When I first saw Linus' talk on git where he was very harsh toward SVN uers I thought "WTF". Then I tried git and had to admit that the man was right.
mukaiji 14y ago
Excellent stuff. Maybe one quick feedback would be to show actual terminal examples to complement what's in the paragraphs.
kevinsd 14y ago
A nice example that good tech reference doesn't need much stylistic formatting :)
erso 14y ago
This 'reference' is, at best, full of inaccuracies and incorrect terminology, with diagrams that are overly complicated and ridiculous. For example: http://marklodato.github.com/visual-git-guide/merge.svg http://marklodato.github.com/visual-git-guide/merge.svg. What the fuck? This guide will only make your understanding of Git worse. It uses incorrect terminology to mislead what Git is actually doing in a number of situations, starting with the first sentence of the first section: The four commands above copy files between the working directory, the stage (also called the index), and the history (in the form of commits). Git doesn't care about files, but changesets so this should raise a red flag with anyone with even a passing knowledge of how Git works. This is either a fundamental flaw in the understanding of how Git works by the OP or intentionally misleading wording. In the Commit section, the OP writes: It then points the current branch to this new commit. I don't like this wording because it makes it seem like a branch is something other than a reference to a particular commit (which is available in .git/refs/heads). Really, any reference to "current branch" should be replaced by HEAD, because the current branch is nothing other than HEAD, and HEAD of course is just a commit. In the Checkout section, the OP writes: The checkout command is used to copy files from the history (or stage) to the working directory, and to optionally switch branches. This is blatantly false. `git checkout` doesn't "copy files"; it may move HEAD or it may get rid of any changes in the working directory, and in doing so may change the state of the files within the local repo. In the Committing with a Detached HEAD section, the OP writes: Once you check out something else, say master, the commit is (presumably) no longer referenced by anything else, and gets lost. This is only partly true. The commit still remains in the reflog and can be retrieved up to the point that garbage collection is run. It's incorrect to tell someone their commits are lost as soon as they `git checkout` another treeish. This guide should be binned in favor of EdgeCase's Git Immersion (http://gitimmersion.com/ http://gitimmersion.com/) and Scott Chacon's Pro Git (http://www.git-scm.com/book http://www.git-scm.com/book).
- kschrader 14y ago
  Perhaps you (or someone else with a better understanding of git) can fork https://github.com/MarkLodato/visual-git-guide https://github.com/MarkLodato/visual-git-guide and clean it up then. I think that it would be interesting to reread this after it's been worked over by someone to better represent the way that Git actually works.
205guy 14y ago
Not cool, or even HN worthy, it's just good documentation (assuming it's accurate). Tech writers (assuming they're good) can help a lot.

238 points by dennis_vartan 14y ago

drek 14y ago

Awesome! Very clear and well-written reference. I wish someone would make a reference like this for remote branches and repos, I always keep forgetting commands for setting upstream branches, checking out remote branches and having them tracked, etc.

zephjc 14y ago

This is cool, but every diagram I've seen for git history uses arrows pointing to the past instead of the future, which is a bit confusing.

praptak 14y ago
It represents the actual way commits are represented. Past commits cannot be modified to add children (this would change their hashes) so new commits contain references to parents. Changing this in diagrams would create even greater confusion later on.
megrimlock 14y ago
The arrows do not represent time. Instead, they reflect the way git represents the commits internally. Each commit is a set of changes to some starting state, identified by the arrow. You could think of it like a citation in a paper that mentions and then extends some earlier findings.
kisielk 14y ago
Just think of it as a commit having a pointer to its parent.
- erso 14y ago
  This, in addition to knowing that a commit may have multiple parents (a merge commit, for example).
erso 14y ago
kisielk got it right, but to add: A commit knows about its history via its parent(s), thus the arrow pointing to the parent. As far as I know no commit can (or for that matter should) know about its descendants. Does that help?

endeavor 14y ago

Very nice set of diagrams. But every time I see something this I have to ask myself again why I'm just not using CVS (or SVN, i.e. a simpler tool).

aidenn0 14y ago
Because experience shows that on any sufficiently long-running project, you're going to need some of the power that CVS/SVN don't have.
columbo 14y ago
My opinion in the svn vs git debate: Unless you are working across multiple groups with developers in different time zones and a choppy set of releases you'll see almost no benefit from git. However, if you are in that situation the benefits are large and immediate.
- qznc 14y ago
  I love git even for personal single-developer projects.
  - columbo 14y ago
    I do too. I'm just saying the smaller the project the more the benefits tend to lean towards personal preference over empirical evidence.
    - Ralith 14y ago
      I think eliminating the need to set up a SVN repository for very small projects is a major boon.
- rimantas 14y ago
  Well, if you enjoy 'log' pulling info over the network (slowly), .svn in every single folder, barely useable branching, no reabase, no stach, no… well maybe you have the point. Otherwise not even comparable. When I first saw Linus' talk on git where he was very harsh toward SVN uers I thought "WTF". Then I tried git and had to admit that the man was right.

mukaiji 14y ago

Excellent stuff. Maybe one quick feedback would be to show actual terminal examples to complement what's in the paragraphs.

kevinsd 14y ago

A nice example that good tech reference doesn't need much stylistic formatting :)

erso 14y ago

This 'reference' is, at best, full of inaccuracies and incorrect terminology, with diagrams that are overly complicated and ridiculous. For example: http://marklodato.github.com/visual-git-guide/merge.svg http://marklodato.github.com/visual-git-guide/merge.svg. What the fuck? This guide will only make your understanding of Git worse. It uses incorrect terminology to mislead what Git is actually doing in a number of situations, starting with the first sentence of the first section: The four commands above copy files between the working directory, the stage (also called the index), and the history (in the form of commits). Git doesn't care about files, but changesets so this should raise a red flag with anyone with even a passing knowledge of how Git works. This is either a fundamental flaw in the understanding of how Git works by the OP or intentionally misleading wording. In the Commit section, the OP writes: It then points the current branch to this new commit. I don't like this wording because it makes it seem like a branch is something other than a reference to a particular commit (which is available in .git/refs/heads). Really, any reference to "current branch" should be replaced by HEAD, because the current branch is nothing other than HEAD, and HEAD of course is just a commit. In the Checkout section, the OP writes: The checkout command is used to copy files from the history (or stage) to the working directory, and to optionally switch branches. This is blatantly false. `git checkout` doesn't "copy files"; it may move HEAD or it may get rid of any changes in the working directory, and in doing so may change the state of the files within the local repo. In the Committing with a Detached HEAD section, the OP writes: Once you check out something else, say master, the commit is (presumably) no longer referenced by anything else, and gets lost. This is only partly true. The commit still remains in the reflog and can be retrieved up to the point that garbage collection is run. It's incorrect to tell someone their commits are lost as soon as they `git checkout` another treeish. This guide should be binned in favor of EdgeCase's Git Immersion (http://gitimmersion.com/ http://gitimmersion.com/) and Scott Chacon's Pro Git (http://www.git-scm.com/book http://www.git-scm.com/book).

kschrader 14y ago
Perhaps you (or someone else with a better understanding of git) can fork https://github.com/MarkLodato/visual-git-guide https://github.com/MarkLodato/visual-git-guide and clean it up then. I think that it would be interesting to reread this after it's been worked over by someone to better represent the way that Git actually works.

205guy 14y ago

Not cool, or even HN worthy, it's just good documentation (assuming it's accurate). Tech writers (assuming they're good) can help a lot.