- Making a change
- ---------------
-
-Remember how we did the "git-update-cache" on file "a" and then we
-changed "a" afterwards, and could compare the new state of "a" with the
-state we saved in the index file?
-
-Further, remember how I said that "git-write-tree" writes the contents
-of the _index_ file to the tree, and thus what we just committed was in
-fact the _original_ contents of the file "a", not the new ones. We did
-that on purpose, to show the difference between the index state, and the
-state in the working directory, and how they don't have to match, even
-when we commit things.
-
-As before, if we do "git-diff-files -p" in our git-tutorial project,
-we'll still see the same difference we saw last time: the index file
-hasn't changed by the act of committing anything. However, now that we
-have committed something, we can also learn to use a new command:
-"git-diff-cache".
-
-Unlike "git-diff-files", which showed the difference between the index
-file and the working directory, "git-diff-cache" shows the differences
-between a committed _tree_ and the index file. In other words,
-git-diff-cache wants a tree to be diffed against, and before we did the
-commit, we couldn't do that, because we didn't have anything to diff
-against.
-
-But now we can do
-
- git-diff-cache -p HEAD
-
-(where "-p" has the same meaning as it did in git-diff-files), and it
-will show us the same difference, but for a totally different reason.
-Now we're not comparing against the index file, we're comparing against
-the tree we just wrote. It just so happens that those two are obviously
-the same.
-
-"git-diff-cache" also has a specific flag "--cached", which is used to
-tell it to show the differences purely with the index file, and ignore
-the current working directory state entirely. Since we just wrote the
-index file to HEAD, doing "git-diff-cache --cached -p HEAD" should thus
-return an empty set of differences, and that's exactly what it does.
-
-However, our next step is to commit the _change_ we did, and again, to
-understand what's going on, keep in mind the difference between "workign
-directory contents", "index file" and "committed tree". We have changes
-in the working directory that we want to commit, and we always have to
-work through the index file, so the first thing we need to do is to
-update the index cache:
-
- git-update-cache a
-
-(note how we didn't need the "--add" flag this time, since git knew
-about the file already).
-
-Note what happens to the different git-diff-xxx versions here. After
-we've updated "a" in the index, "git-diff-files -p" now shows no
-differences, but "git-diff-cache -p HEAD" still _does_ show that the
-current state is different from the state we committed. In fact, now
-"git-diff-cache" shows the same difference whether we use the "--cached"
-flag or not, since now the index is coherent with the working directory.
-
-Now, since we've updated "a" in the index, we can commit the new
-version. We could do it by writing the tree by hand, and committing the
-tree (this time we'd have to use the "-p HEAD" flag to tell commit that
-the HEAD was the _parent_ fo the new commit, and that this wasn't an
-initial commit any more), but the fact is, git has a simple helper
-script for doing all of the non-initial commits that does all of this
-for you, and starts up an editor to let you write your commit message
-yourself, so let's just use that:
-
- git-commit-script
-
-Write whatever message you want, and all the lines that start with '#'
-will be pruned out, and the rest will be used as the commit message for
-the change. If you decide you don't want to commit anything after all at
-this point (you can continue to edit things and update the cache), you
-can just leave an empty message. Otherwise git-commit-script will commit
-the change for you.
-
-(Btw, current versions of git will consider the change in question to be
-so big that it's considered a whole new file, since the diff is actually
-bigger than the file. So the helpful comments that git-commit-script
-tells you for this example will say that you deleted and re-created the
-file "a". For a less contrieved example, these things are usually more
-obvious).
-
-You've now made your first real git commit. And if you're interested in
-looking at what git-commit-script really does, feel free to investigate:
-it's a few very simple shell scripts to generate the helpful (?) commit
-message headers, and a few one-liners that actually do the commit itself.
-
-
- Checking it out
- ---------------
-
-While creating changes is useful, it's even more useful if you can tell
-later what changed. The most useful command for this is another of the
-"diff" family, namely "git-diff-tree".
-
-git-diff-tree can be given two arbitrary trees, and it will tell you the
-differences between them. Perhaps even more commonly, though, you can
-give it just a single commit object, and it will figure out the parent
-of that commit itself, and show the difference directly. Thus, to get
-the same diff that we've already seen several times, we can now do
-
- git-diff-tree -p HEAD
-
-(again, "-p" means to show the difference as a human-readable patch),
-and it will show what the last commit (in HEAD) actually changed.
-
-More interestingly, you can also give git-diff-tree the "-v" flag, which
-tells it to also show the commit message and author and date of the
-commit, and you can tell it to show a whole series of diffs.
-Alternatively, you can tell it to be "silent", and not show the diffs at
-all, but just show the actual commit message.
-
-In fact, together with the "git-rev-list" program (which generates a
-list of revisions), git-diff-tree ends up being a veritable fount of
-changes. A trivial (but very useful) script called "git-whatchanged" is
-included with git which does exactly this, and shows a log of recent
-activity.
-
-To see the whole history of our pitiful little git-tutorial project, we
-can do
-
- git-whatchanged -p --root HEAD
-
-(the "--root" flag is a flag to git-diff-tree to tell it to show the
-initial aka "root" commit as a diff too), and you will see exactly what
-has changed in the repository over its short history.
-
-With that, you should now be having some incling of what git does, and
-can explore on your own.
-
-[ to be continued.. cvs2git, tagging versions, branches, merging.. ]
+shows a list of all the changes that Bob made since he branched from
+Alice's master branch.
+
+After examing those changes, and possibly fixing things, Alice can
+pull the changes into her master branch:
+
+-------------------------------------
+$ git checkout master
+$ git pull . bob-incoming
+-------------------------------------
+
+The last command is a pull from the "bob-incoming" branch in Alice's
+own repository.
+
+Later, Bob can update his repo with Alice's latest changes using
+
+-------------------------------------
+$ git pull
+-------------------------------------
+
+Note that he doesn't need to give the path to Alice's repository;
+when Bob cloned Alice's repository, git stored the location of her
+repository in the file .git/remotes/origin, and that location is used
+as the default for pulls.
+
+Bob may also notice a branch in his repository that he didn't create:
+
+-------------------------------------
+$ git branch
+* master
+ origin
+-------------------------------------
+
+The "origin" branch, which was created automatically by "git clone",
+is a pristine copy of Alice's master branch; Bob should never commit
+to it.
+
+If Bob later decides to work from a different host, he can still
+perform clones and pulls using the ssh protocol:
+
+-------------------------------------
+$ git clone alice.org:/home/alice/project myrepo
+-------------------------------------
+
+Alternatively, git has a native protocol, or can use rsync or http;
+see gitlink:git-pull[1] for details.
+
+Git can also be used in a CVS-like mode, with a central repository
+that various users push changes to; see gitlink:git-push[1] and
+link:cvs-migration.html[git for CVS users].
+
+Keeping track of history
+------------------------
+
+Git history is represented as a series of interrelated commits. The
+most recent commit in the currently checked-out branch can always be
+referred to as HEAD, and the "parent" of any commit can always be
+referred to by appending a caret, "^", to the end of the name of the
+commit. So, for example,
+
+-------------------------------------
+git diff HEAD^ HEAD
+-------------------------------------
+
+shows the difference between the most-recently checked-in state of
+the tree and the previous state, and
+
+-------------------------------------
+git diff HEAD^^ HEAD^
+-------------------------------------
+
+shows the difference between that previous state and the state two
+commits ago. Also, HEAD~5 can be used as a shorthand for HEAD{caret}{caret}{caret}{caret}{caret},
+and more generally HEAD~n can refer to the nth previous commit.
+Commits representing merges have more than one parent, and you can
+specify which parent to follow in that case; see
+gitlink:git-rev-parse[1].
+
+The name of a branch can also be used to refer to the most recent
+commit on that branch; so you can also say things like
+
+-------------------------------------
+git diff HEAD experimental
+-------------------------------------
+
+to see the difference between the most-recently committed tree in
+the current branch and the most-recently committed tree in the
+experimental branch.
+
+But you may find it more useful to see the list of commits made in
+the experimental branch but not in the current branch, and
+
+-------------------------------------
+git whatchanged HEAD..experimental
+-------------------------------------
+
+will do that, just as
+
+-------------------------------------
+git whatchanged experimental..HEAD
+-------------------------------------
+
+will show the list of commits made on the HEAD but not included in
+experimental.
+
+You can also give commits convenient names of your own: after running
+
+-------------------------------------
+$ git-tag v2.5 HEAD^^
+-------------------------------------
+
+you can refer to HEAD^^ by the name "v2.5". If you intend to share
+this name with other people (for example, to identify a release
+version), you should create a "tag" object, and perhaps sign it; see
+gitlink:git-tag[1] for details.
+
+You can revisit the old state of a tree, and make further
+modifications if you wish, using git branch: the command
+
+-------------------------------------
+$ git branch stable-release v2.5
+-------------------------------------
+
+will create a new branch named "stable-release" starting from the
+commit which you tagged with the name v2.5.
+
+You can reset the state of any branch to an earlier commit at any
+time with
+
+-------------------------------------
+$ git reset --hard v2.5
+-------------------------------------
+
+This will remove all later commits from this branch and reset the
+working tree to the state it had when the given commit was made. If
+this branch is the only branch containing the later commits, those
+later changes will be lost. Don't use "git reset" on a
+publicly-visible branch that other developers pull from, as git will
+be confused by history that disappears in this way.
+
+Next Steps
+----------
+
+Some good commands to explore next:
+
+ * gitlink:git-diff[1]: This flexible command does much more than
+ we've seen in the few examples above.
+
+ * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert
+ series of git commits into emailed patches, and vice versa,
+ useful for projects such as the linux kernel which rely heavily
+ on emailed patches.
+
+ * gitlink:git-bisect[1]: When there is a regression in your
+ project, one way to track down the bug is by searching through
+ the history to find the exact commit that's to blame. Git bisect
+ can help you perform a binary search for that commit. It is
+ smart enough to perform a close-to-optimal search even in the
+ case of complex non-linear history with lots of merged branches.
+
+Other good starting points include link:everyday.html[Everday GIT
+with 20 Commands Or So] and link:cvs-migration.html[git for CVS
+users]. Also, link:core-tutorial.html[A short git tutorial] gives an
+introduction to lower-level git commands for advanced users and
+developers.