Remove incorrect information about HEAD #77

merged 1 commit into from Mar 23, 2013


None yet

3 participants

aschrab commented Mar 20, 2013

The statement that the working directory (aside: "working tree" would be
a more git-like term) will always match the current state of HEAD is
completely incorrect. That would imply that changes to files get in
some way committed as files are saved.

Even the second part of the paragraph is incorrect. Changing HEAD does
not necessarily change the contents of the working tree as in git reset without the --hard option.

pcottle commented Mar 20, 2013

I totally see your point (thanks for the other pull request btw). I guess I was referring to the LGB world when I wrote this sentence, where the user never change files (since it omits the whole staging side of things).

I still think we need some kind of sentence for noobies though, saying something like

Moving HEAD actually changes the files in your working directory, which is why it's so important. You can create branches all over your commit tree, but only once you move HEAD to a new location will your filesystem change.

to really drive it home.

(btw, I added you as a contributor since all your pull requests have been top notch!)

aschrab commented Mar 20, 2013

I agree that a further description of HEAD would be useful, and wasn't really expecting this pull request to be accepted as is but saw it more as a starting point to improving things.

But IMO it absolutely should not say that moving HEAD changes things in the working tree. As I noted in the pull request there are definitely cases where moving head doesn't affect the working tree in any way.

pcottle commented Mar 20, 2013

Yeah, l let me rephrase it -- moving HEAD is how you change things in the working tree. it might not always happen, but that's the start to it :D

aschrab commented Mar 21, 2013

That's definitely an improvement. But, there are common exceptions to that as well such as git checkout someBranch -- fileOne.

pcottle commented Mar 22, 2013

Yeah, that's an exception for sure, but individually staging files is something that is around the git experienced - to - expert level. Right before the git add -p level (imo)

How about

Moving HEAD actually changes the files in your working directory, which is why it's so important. You can create branches all over your commit tree all you want, but moving HEAD to a new location is (usually) the only command that will change your filesystem.

This is tricky, because you want an explanation that's simple enough to help a new user understand, but not obviously wrong to an experienced user. One tactic is to make it clear that you're giving a helpful analogy and not claiming that it's always true. What do you think of this?

First we have to talk about "HEAD." HEAD is the symbolic name for the currently checked out commit -- you can think of it as the starting point for all the file changes you're making in your working tree. When you move HEAD, git takes any changes you've made in the working tree and tries to apply them to the commit that HEAD is now pointing at. Normally HEAD points to a branch name (like bugFix). When you commit, both bugFix and HEAD move together.

@aschrab aschrab Replace incorrect information about HEAD
Avoid stating that changing HEAD alters the working tree.  Although that
is a common next step they are not actually the same action and can be
done independently (e.g. `git reset` without `--hard`).

Also state that committing while on a branch only alters the branch,
without actually changing HEAD; HEAD only gets the new commit because it
points to the branch rather than a specific commit.
aschrab commented Mar 22, 2013

I've updated my branch for this pull request with some wording that I hope will be suitably accessible without giving incorrect information.

@pcottle pcottle merged commit 46d71cd into pcottle:master Mar 23, 2013
pcottle commented Mar 23, 2013

Nice Aaron! Love the wording on this one, and it's still quite concise. I think Don's version is nice too but might give almost too much detail. Merging this bad boy in

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment