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

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

[Sean]

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

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

[Junio C Hamano]

Sean <seanlkml@sympatico.ca> writes:

> 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] [-m] <branch>
> +'git-checkout' [-f] [-b <new_branch> [-l]] [-m] [<commit-ish>]
>  'git-checkout' [-m] [<branch>] <paths>...
>  
>  DESCRIPTION
>  -----------
> ...
> +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.

The 'restore from arbitrary tree-ish' form does not take -m as
far as I know.

Although it might be interesting to do a single-file three-way
merge, I do not think the command is _checkout_ anymore once it
starts doing that.

That is:

	$ git checkout -f master
	$ edit file.c
        $ git that-funny-command next file.c

would steal the version of file.c from 'next', and merge the
change your locally did on top of 'master', and put it in your
working tree and in the index.  Technically I can explain how
that work (and how it could be implemented -- which is trivial),
but I cannot explain what that operation _means_.

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

[Sean]

On Wed, 20 Dec 2006 23:47:42 -0800
Junio C Hamano <junkio@cox.net> wrote:

> The 'restore from arbitrary tree-ish' form does not take -m as
> far as I know.
> 
> Although it might be interesting to do a single-file three-way
> merge, I do not think the command is _checkout_ anymore once it
> starts doing that.

Yeah, I should have caught that.  As well, your explanation makes me
wonder if it makes sense to change <branch> in the third form to
<tree-ish> ?  Would you like an updated patch or will you just make
the touch up(s) yourself?

Sean

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

[Jakub Narebski]

Sean wrote:

> On Wed, 20 Dec 2006 23:47:42 -0800
> Junio C Hamano <junkio@cox.net> wrote:
> 
>> The 'restore from arbitrary tree-ish' form does not take -m as
>> far as I know.
>> 
>> Although it might be interesting to do a single-file three-way
>> merge, I do not think the command is _checkout_ anymore once it
>> starts doing that.
> 
> Yeah, I should have caught that.  As well, your explanation makes me
> wonder if it makes sense to change <branch> in the third form to
> <tree-ish> ?  Would you like an updated patch or will you just make
> the touch up(s) yourself?

Better not, because if I remember correctly

  $ git checkout [--] <paths>...

would replace the contents of the named paths in your
working tree from the index, while

  $ git checkout <commit-ish> [--] <paths>...

would replace the contents of the named paths in your
working tree from the given commit (given branch, perhaps given
tree-ish).
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git