

A visual Git reference - dennis_vartan
http://marklodato.github.com/visual-git-guide/index-en.html

======
erso
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>. 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/>) and Scott Chacon's Pro Git (<http://www.git-
scm.com/book>).

~~~
pokeylope
I disagree on most of your points.

> 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.

Git absolutely cares about files. It cares about commits too, but a commit is
mostly just a set of files with a pointer to its parent. The commands being
discussed operate on individual files except for commit, which operates on the
entire index (which is, conceptually, a snapshot of file).

> 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.

I don't understand your objection to this phrasing. A branch is a pointer to a
commit; the statement talks about changing which commit the branch points to.
I don't see where it implies anything else about what a branch is. As for
"current branch"/"HEAD", using HEAD is more precise in terms of the actual
implementation, but "current branch" is just as accurate and more (new-)user
friendly. The author does discuss the relationship between the two prior to
that point: "The current branch is identified by the special reference HEAD,
which is "attached" to that branch."

> 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.

When used as "git checkout <ref>", this is correct, but that is not what the
author is talking about. "git checkout <ref> <file>" or "git checkout --
<file>" does exactly what the author describes, copying files from the given
commit or index to the working directory.

> 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.

Only partly true, but true enough. The commit isn't irretrievably lost, but
the reflog falls more under "advanced usage"; certainly a git beginner
shouldn't be making detached commits and relying on the reflog to get back to
them.

~~~
erso
> Git absolutely cares about files.

In a sense. A commit is not a set of files, it is one or more blobs and one or
more trees (which may in turn point to one or more blobs or trees.) A blob
does refer to a file, both in content and location, but it's the blob that
matters. The OP speaks of the files on disk, which Git doesn't copy around.
Git does, however, change the state of the working directory to that which
matches the trees referenced in the commit. What I don't like about this is
that it tries to make it seem like the files on disk matter in a way that they
don't from Git's perspective.

> I don't understand your objection to this phrasing.

I had a chat with a coworker and he agreed that my distaste with the "current
branch" terminology is perhaps misplaced.

> When used as "git checkout <ref>", this is correct, but that is not what the
> author is talking about. "git checkout <ref> <file>" or "git checkout --
> <file>" does exactly what the author describes, copying files from the given
> commit or index to the working directory.

Of course, the files that are being copied are not the files that the OP is
talking about. The files being copied are the trees and blobs, not the files
in the working directory. The effective result is the same, but thinking in
files on disk will not improve one's knowledge of Git.

> Only partly true, but true enough. The commit isn't irretrievably lost, but
> the reflog falls more under "advanced usage"; certainly a git beginner
> shouldn't be making detached commits and relying on the reflog to get back
> to them.

Shunning the reflog doesn't do anyone any good. The OP not even mentioning the
reflog is in poor taste, and makes the statement in the guide untrue.

I did a bit of research into the reflog after some questions arose and should
update my prior comment about it to say: Any commit that Git determines to be
unreachable (a list of which that you can see with `git fsck --unreachable`)
will only be removed from the reflog after both the reflog's unreachable
expiration time has passed (by default, 30 days for unreachable) and `git gc`
has ran. At the very least, without mentioning the reflog, the OP should state
that unreachable commits will remain for 30 days.

------
drek
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.

------
endeavor
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).

~~~
columbo
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.

~~~
rimantas
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.

~~~
mhewett
Since Subversion 1.7 (2nd half of 2011) it keeps only one .svn folder in the
root folder.

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

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

------
zephjc
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.

~~~
kisielk
Just think of it as a commit having a pointer to its parent.

~~~
erso
This, in addition to knowing that a commit may have multiple parents (a merge
commit, for example).

------
205guy
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.

