Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Remove incorrect information about HEAD #77

Merged
merged 1 commit into from

3 participants

@aschrab
Collaborator

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
Owner

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
Collaborator

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
Owner

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
Collaborator

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

@pcottle
Owner

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.
@donkirkby
Collaborator

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.
36ad66e
@aschrab
Collaborator

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
@pcottle
Owner

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
Commits on Mar 22, 2013
  1. @aschrab

    Replace incorrect information about HEAD

    aschrab authored
    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.
This page is out of date. Refresh to see the latest.
Showing with 3 additions and 3 deletions.
  1. +3 −3 src/levels/rampup/1.js
View
6 src/levels/rampup/1.js
@@ -34,11 +34,11 @@ exports.level = {
"markdowns": [
"## HEAD",
"",
- "First we have to talk about \"HEAD.\" HEAD is the symbolic name for the currently checked out commit -- it's essentially what commit you're working on top of.",
+ "First we have to talk about \"HEAD\". HEAD is the symbolic name for the currently checked out commit -- it's essentially what commit you're working on top of.",
"",
- "The working directory will always match the current state of HEAD, so by moving HEAD, you actually change the contents of your directory.",
+ "HEAD always points to the most recent commit which is reflected in the working tree. Most git commands which make changes to the working tree will start by changing HEAD.",
"",
- "Normally HEAD points to a branch name (like `bugFix`). When you commit, both bugFix and HEAD move together"
+ "Normally HEAD points to a branch name (like bugFix). When you commit, the status of bugFix is altered and this change is visible through HEAD."
]
}
},
Something went wrong with that request. Please try again.