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