Fix wrong filename listing bug in git-ls-tree.

[git.git] / Documentation / tutorial.txt

diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index ad48bb8..36f42e0 100644 (file)
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -432,8 +432,8 @@ message headers, and a few one-liners that actually do the
 commit itself (`git-commit`).
 
 
 commit itself (`git-commit`).
 
 

-Checking it out
----------------
+Inspecting Changes
+------------------

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


@@ -742,7 +742,7 @@ git commit -m 'Some work.' hello
 ------------------------------------------------
 
 Here, we just added another line to `hello`, and we used a shorthand for
 ------------------------------------------------
 
 Here, we just added another line to `hello`, and we used a shorthand for

-both going a `git-update-index hello` and `git commit` by just giving the
+doing both `git-update-index hello` and `git commit` by just giving the

 filename directly to `git commit`. The `-m` flag is to give the
 commit log message from the command line.
 
 filename directly to `git commit`. The `-m` flag is to give the
 commit log message from the command line.
 


@@ -828,7 +828,7 @@ which will very loudly warn you that you're now committing a merge
 (which is correct, so never mind), and you can write a small merge
 message about your adventures in git-merge-land.
 
 (which is correct, so never mind), and you can write a small merge
 message about your adventures in git-merge-land.
 

-After you're done, start up `gitk --all` to see graphically what the
+After you're done, start up `gitk \--all` to see graphically what the

 history looks like. Notice that `mybranch` still exists, and you can
 switch to it, and continue to work with it if you want to. The
 `mybranch` branch will not contain the merge, but next time you merge it
 history looks like. Notice that `mybranch` still exists, and you can
 switch to it, and continue to work with it if you want to. The
 `mybranch` branch will not contain the merge, but next time you merge it


@@ -859,7 +859,12 @@ All of them have plus `+` characters in the first column, which
 means they are now part of the `master` branch. Only the "Some
 work" commit has the plus `+` character in the second column,
 because `mybranch` has not been merged to incorporate these
 means they are now part of the `master` branch. Only the "Some
 work" commit has the plus `+` character in the second column,
 because `mybranch` has not been merged to incorporate these

-commits from the master branch.
+commits from the master branch.  The string inside brackets
+before the commit log message is a short name you can use to
+name the commit.  In the above example, 'master' and 'mybranch'
+are branch heads.  'master~1' is the first parent of 'master'
+branch head.  Please see 'git-rev-parse' documentation if you
+see more complex cases.

 
 Now, let's pretend you are the one who did all the work in
 `mybranch`, and the fruit of your hard work has finally been merged
 
 Now, let's pretend you are the one who did all the work in
 `mybranch`, and the fruit of your hard work has finally been merged


@@ -883,7 +888,7 @@ not actually do a merge. Instead, it just updated the top of
 the tree of your branch to that of the `master` branch. This is
 often called 'fast forward' merge.
 
 the tree of your branch to that of the `master` branch. This is
 often called 'fast forward' merge.
 

-You can run `gitk --all` again to see how the commit ancestry
+You can run `gitk \--all` again to see how the commit ancestry

 looks like, or run `show-branch`, which tells you this.
 
 ------------------------------------------------
 looks like, or run `show-branch`, which tells you this.
 
 ------------------------------------------------


@@ -1356,4 +1361,101 @@ fast forward.  You need to pull and merge those other changes
 back before you push your work when it happens.
 
 
 back before you push your work when it happens.
 
 

+Bundling your work together
+---------------------------
+
+It is likely that you will be working on more than one thing at
+a time.  It is easy to use those more-or-less independent tasks
+using branches with git.
+
+We have already seen how branches work in a previous example,
+with "fun and work" example using two branches.  The idea is the
+same if there are more than two branches.  Let's say you started
+out from "master" head, and have some new code in the "master"
+branch, and two independent fixes in the "commit-fix" and
+"diff-fix" branches:
+
+------------
+$ git show-branch
+! [commit-fix] Fix commit message normalization.
+ ! [diff-fix] Fix rename detection.
+  * [master] Release candidate #1
+---
+ +  [diff-fix] Fix rename detection.
+ +  [diff-fix~1] Better common substring algorithm.
++   [commit-fix] Fix commit message normalization.
+  + [master] Release candidate #1
++++ [diff-fix~2] Pretty-print messages.
+------------
+
+Both fixes are tested well, and at this point, you want to merge
+in both of them.  You could merge in 'diff-fix' first and then
+'commit-fix' next, like this:
+
+------------
+$ git resolve master diff-fix 'Merge fix in diff-fix'
+$ git resolve master commit-fix 'Merge fix in commit-fix'
+------------
+
+Which would result in:
+
+------------
+$ git show-branch
+! [commit-fix] Fix commit message normalization.
+ ! [diff-fix] Fix rename detection.
+  * [master] Merge fix in commit-fix
+---
+  + [master] Merge fix in commit-fix
++ + [commit-fix] Fix commit message normalization.
+  + [master~1] Merge fix in diff-fix
+ ++ [diff-fix] Fix rename detection.
+ ++ [diff-fix~1] Better common substring algorithm.
+  + [master~2] Release candidate #1
++++ [master~3] Pretty-print messages.
+------------
+
+However, there is no particular reason to merge in one branch
+first and the other next, when what you have are a set of truly
+independent changes (if the order mattered, then they are not
+independent by definition).  You could instead merge those two
+branches into the current branch at once.  First let's undo what
+we just did and start over.  We would want to get the master
+branch before these two merges by resetting it to 'master~2':
+
+------------
+$ git reset --hard master~2
+------------
+
+You can make sure 'git show-branch' matches the state before
+those two 'git resolve' you just did.  Then, instead of running
+two 'git resolve' commands in a row, you would pull these two
+branch heads (this is known as 'making an Octopus'):
+
+------------
+$ git pull . commit-fix diff-fix
+$ git show-branch
+! [commit-fix] Fix commit message normalization.
+ ! [diff-fix] Fix rename detection.
+  * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
+---
+  + [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
++ + [commit-fix] Fix commit message normalization.
+ ++ [diff-fix] Fix rename detection.
+ ++ [diff-fix~1] Better common substring algorithm.
+  + [master~1] Release candidate #1
++++ [master~2] Pretty-print messages.
+------------
+
+Note that you should not do Octopus because you can.  An octopus
+is a valid thing to do and often makes it easier to view the
+commit history if you are pulling more than two independent
+changes at the same time.  However, if you have merge conflicts
+with any of the branches you are merging in and need to hand
+resolve, that is an indication that the development happened in
+those branches were not independent after all, and you should
+merge two at a time, documenting how you resolved the conflicts,
+and the reason why you preferred changes made in one side over
+the other.  Otherwise it would make the project history harder
+to follow, not easier.
+

 [ to be continued.. cvsimports ]
 [ to be continued.. cvsimports ]