[PATCH] Attempt to make git-checkout man page a bit more clear.

[Sean <seanlkml@sympatico.ca>]

Signed-off-by: Sean Estabrooks <seanlkml@sympatico.ca>
---
 Documentation/git-checkout.txt |   40 +++++++++++++++++++++++++++-------------
 1 files changed, 27 insertions(+), 13 deletions(-)


A recent question on another list, quoted below, shows a
new git user getting stuck on something pretty simple:

>> I'm after all the source of the drm 2.3.0 release.
>>
>> How do I use git to get all the source that drm-2.3.0 tags?
>> I need the kernel drivers as well as the user land code
>> so the tarball is no use to me.
>>
>> All the git docs tell me how to create a tag, but I have not
>> found a single use show how to get a tree of files that correspond
>> to a tag.

Hopefully this patch is accurate and would help a bit.

Sean


diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index fbdbadc..97c3afe 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -8,23 +8,29 @@ git-checkout - Checkout and switch to a branch
 SYNOPSIS
 --------
 [verse]
-'git-checkout' [-f] [-b <new_branch> [-l]] [-m] [<branch>]
+'git-checkout' [-f] [-m] <branch>
+'git-checkout' [-f] [-b <new_branch> [-l]] [-m] [<commit-ish>]
 'git-checkout' [-m] [<branch>] <paths>...
 
 DESCRIPTION
 -----------
 
-When <paths> are not given, this command switches branches by
-updating the index and working tree to reflect the specified
-branch, <branch>, and updating HEAD to be <branch> or, if
-specified, <new_branch>.  Using -b will cause <new_branch> to
-be created.
-
-When <paths> are given, this command does *not* switch
-branches.  It updates the named paths in the working tree from
-the index file (i.e. it runs `git-checkout-index -f -u`).  In
-this case, `-f` and `-b` options are meaningless and giving
-either of them results in an error.  <branch> argument can be
+Checkout the given branch, populating your working tree with its
+contents.  In the first form listed above, this command only
+allows you to checkout an existing branch, not an arbitrary point
+from the history.  You can use the git-branch command to create
+such branches.
+
+The second form of the command allows you to create a new branch
+and check it out in one step.  You specify the new branch name
+with the "-b" option, followed by a reference to the commit that
+will become the HEAD of the new branch.  Note that you can specify
+this commit by tag name, an existing branch name, or any other
+reference specification git allows.
+
+With the third form, this command does *not* switch branches.
+Instead, it replaces the contents of the named paths in your
+working tree from the index.  Here, the <branch> argument can be
 used to specify a specific tree-ish to update the index for the
 given paths before updating the working tree.
 
@@ -32,7 +38,8 @@ given paths before updating the working tree.
 OPTIONS
 -------
 -f::
-	Force a re-read of everything.
+	Force a switch to the given branch even when uncommitted
+	changes in your working tree will be lost as a result.
 
 -b::
 	Create a new branch named <new_branch> and start it at
@@ -92,6 +99,13 @@ You should instead write:
 $ git checkout -- hello.c
 ------------
 
+. To create a branch based on the contents marked by a given tag
+and check it out in a single step:
++
+------------
+$ git checkout -b newbranch tag1.2.3
+------------
+
 . After working in a wrong branch, switching to the correct
 branch would be done using:
 +
-- 
1.4.4.2.g8336