[PATCH 1/2] git-checkout.txt: fix incorrect statement about HEAD and index

[PATCH 1/2] git-checkout.txt: fix incorrect statement about HEAD and index

[Matthieu Moy]

The command "git checkout" checks out from the index by default, not
HEAD (the introducing comment were correct, but the detailled
explanation added below were not).

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/git-checkout.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 1a6c19e..0b5485b 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -191,7 +191,7 @@ $ git checkout hello.c            <3>
 +
 <1> switch branch
 <2> take a file out of another commit
-<3> restore hello.c from HEAD of current branch
+<3> restore hello.c from the index
 +
 If you have an unfortunate branch that is named `hello.c`, this
 step would be confused as an instruction to switch to that branch.
-- 
1.6.2.1.427.g061ea

[PATCH 2/2] git-checkout.txt: clarify that <branch> applies when no path is given.

[Matthieu Moy]

Otherwise, the sentence "Defaults to HEAD." can be mis-read to mean
that "git checkout -- hello.c" checks-out from HEAD.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---

This may be a bit too verbose, but I've been biten by this (reading
the doc not carrefully enough, I really thought git checkout would
take HEAD, then I thought it was actually a documentation bug, and
then I realized I miss-read). This patch would have saved me time. But
if other disagree, I won't fight ;-).

 Documentation/git-checkout.txt |    9 +++++++--
 1 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 0b5485b..58bf508 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -126,9 +126,14 @@ the conflicted merge in the specified paths.
 <new_branch>::
 	Name for the new branch.
 
+<tree-ish>::
+	Tree to checkout from (when path are given). If not specified,
+	the index will be used.
+
 <branch>::
-	Branch to checkout; may be any object ID that resolves to a
-	commit.  Defaults to HEAD.
+	Branch to checkout (when no path are given); may be any object
+	ID that resolves to a commit.  Defaults to HEAD.
+
 +
 When this parameter names a non-branch (but still a valid commit object),
 your HEAD becomes 'detached'.
-- 
1.6.2.1.427.g061ea

Re: [PATCH 2/2] git-checkout.txt: clarify that <branch> applies when no path is given.

[Mike Ralphson]

2009/4/6 Matthieu Moy <Matthieu.Moy@imag.fr>:
> Otherwise, the sentence "Defaults to HEAD." can be mis-read to mean
> that "git checkout -- hello.c" checks-out from HEAD.

> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index 0b5485b..58bf508 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -126,9 +126,14 @@ the conflicted merge in the specified paths.
>  <new_branch>::
>        Name for the new branch.
>
> +<tree-ish>::
> +       Tree to checkout from (when path are given). If not specified,
> +       the index will be used.
> +
>  <branch>::
> -       Branch to checkout; may be any object ID that resolves to a
> -       commit.  Defaults to HEAD.
> +       Branch to checkout (when no path are given); may be any object
> +       ID that resolves to a commit.  Defaults to HEAD.
> +

s/path are/paths are/g

Sorry if I come across as picking on your grammar, I think your
documentation improvements are very worthwhile.

Mike

[PATCH 1/2] git-checkout.txt: clarify that <branch> applies when no path is given.

[Matthieu Moy]

Otherwise, the sentence "Defaults to HEAD." can be mis-read to mean
that "git checkout -- hello.c" checks-out from HEAD.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
> s/path are/paths are/g

Right.

I'm not 100% sure about "no paths are given" Vs "no path is given",
but my understanding of english grammar is that since there could have
been several paths, the absence of path is still plural (French would
be singular here).

> Sorry if I come across as picking on your grammar, I think your
> documentation improvements are very worthwhile.

No harm ;-).

 Documentation/git-checkout.txt |    9 +++++++--
 1 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 0b5485b..7eafcdf 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -126,9 +126,14 @@ the conflicted merge in the specified paths.
 <new_branch>::
 	Name for the new branch.
 
+<tree-ish>::
+	Tree to checkout from (when paths are given). If not specified,
+	the index will be used.
+
 <branch>::
-	Branch to checkout; may be any object ID that resolves to a
-	commit.  Defaults to HEAD.
+	Branch to checkout (when no paths are given); may be any object
+	ID that resolves to a commit.  Defaults to HEAD.
+
 +
 When this parameter names a non-branch (but still a valid commit object),
 your HEAD becomes 'detached'.
-- 
1.6.2.2.449.g92961.dirty

[PATCH v2] git-checkout.txt: clarify that <branch> applies when no path is given.

[Matthieu Moy]

Otherwise, the sentence "Defaults to HEAD." can be mis-read to mean
that "git checkout -- hello.c" checks-out from HEAD.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
Sorry, patch v1 was introducing a spurious newline, which broke
asciidoc syntax. This fixes it, but Junio, if you already applied v1,
just remove the empty line after <branch>:: and before +.

 Documentation/git-checkout.txt |    8 ++++++--
 1 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 0b5485b..223ea9c 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -126,9 +126,13 @@ the conflicted merge in the specified paths.
 <new_branch>::
 	Name for the new branch.
 
+<tree-ish>::
+	Tree to checkout from (when paths are given). If not specified,
+	the index will be used.
+
 <branch>::
-	Branch to checkout; may be any object ID that resolves to a
-	commit.  Defaults to HEAD.
+	Branch to checkout (when no paths are given); may be any object
+	ID that resolves to a commit.  Defaults to HEAD.
 +
 When this parameter names a non-branch (but still a valid commit object),
 your HEAD becomes 'detached'.
-- 
1.6.2.2.449.g92961.dirty

Re: [PATCH 1/2] git-checkout.txt: fix incorrect statement about HEAD and index

[Junio C Hamano]

Thanks.  Both patches look good.