Re: What I miss from Cogito...

Theodore Tso [off-list ref] writes:

       git-checkout - Checkout and switch to a branch

At the very least, will you admit that the summary in the man page is
perhaps just a wee bit misleading?

It's not "wee bit misleading" but it just is outright stale.

Back then, before people realized the operation "to check out the path out
of index or tree-ish" belongs naturally to a command whose name is
"checkout", "to check out the named branch or a commit" was the only thing
that you could do with the command.  The one-line description you quoted
above reflects that history.

Patches very much welcome; I did not notice it was kept stale.

For a while now, git-checkout has been more powerful than the man-page
summary would suggest (the main text does describe the new features),
so update the summary to hopefully better reflect the current
functionality.

Signed-off-by: Julian Phillips <redacted>
---

On Sun, 23 Mar 2008, Junio C Hamano wrote:

Theodore Tso [off-list ref] writes:

quoted

       git-checkout - Checkout and switch to a branch

At the very least, will you admit that the summary in the man page is
perhaps just a wee bit misleading?

It's not "wee bit misleading" but it just is outright stale.

Back then, before people realized the operation "to check out the path out
of index or tree-ish" belongs naturally to a command whose name is
"checkout", "to check out the named branch or a commit" was the only thing
that you could do with the command.  The one-line description you quoted
above reflects that history.

Patches very much welcome; I did not notice it was kept stale.

Something like this perhaps?

 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 4014e72..1b8caf1 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt

@@ -3,7 +3,7 @@ git-checkout(1)
 
 NAME
 ----
-git-checkout - Checkout and switch to a branch
+git-checkout - Checkout/update/refresh items in the working tree
 
 SYNOPSIS
 --------

-- 
1.5.4.4

Julian Phillips [off-list ref] writes:

Hmm.

The glossary may be a good place to define what the verb "checkout" means.
I think using that defined word without adding "/update/refresh" to
muddy its meaning would be more appropriate, after we establish what
"checkout" means in the glossary.

So how about saying "Check out a whole branch, or paths to the work tree"
or something like that?

For a while now, git-checkout has been more powerful than the man-page
summary would suggest (the main text does describe the new features),
so update the summary to hopefully better reflect the current
functionality.  Also update the glossary description of the word checkout.

Signed-off-by: Julian Phillips <redacted>
---
On Mon, 24 Mar 2008, Junio C Hamano wrote:

Julian Phillips [off-list ref] writes:

quoted

diff --git a/Documentation/git-checkout.txt

b/Documentation/git-checkout.txt

quoted

index 4014e72..1b8caf1 100644

--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt

@@ -3,7 +3,7 @@ git-checkout(1)

 NAME
 ----
-git-checkout - Checkout and switch to a branch
+git-checkout - Checkout/update/refresh items in the working tree

Hmm.

The glossary may be a good place to define what the verb "checkout" means.
I think using that defined word without adding "/update/refresh" to
muddy its meaning would be more appropriate, after we establish what
"checkout" means in the glossary.

So how about saying "Check out a whole branch, or paths to the work tree"
or something like that?

Ok, so more like this?  I've updated the glossary entry for checkout too,
though I'm thinking that there ought to be a clearer way to explain it ...

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

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 4014e72..e11cddb 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt

@@ -3,7 +3,7 @@ git-checkout(1)
 
 NAME
 ----
-git-checkout - Checkout and switch to a branch
+git-checkout - Checkout a branch or paths to the working tree
 
 SYNOPSIS
 --------

diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt
index ab4caf4..51b6353 100644
--- a/Documentation/glossary.txt
+++ b/Documentation/glossary.txt

@@ -45,9 +45,12 @@ GIT Glossary
 	"changesets" with git.
 
 [[def_checkout]]checkout::
-	The action of updating the <<def_working_tree,working tree>> to a
-	<<def_revision,revision>> which was stored in the
-	<<def_object_database,object database>>.
+	The action of updating all or part of the
+	<<def_working_tree,working tree>> with a <<def_tree_object,tree object>>
+	or <<def_blob_object,blob>> from the
+	<<def_object_database,object database>>, and updating the
+	<<def_index,index>> and <<def_HEAD,HEAD>> if the whole working tree has
+	been pointed at a new <<def_branch,branch>>.
 
 [[def_cherry-picking]]cherry-picking::
 	In <<def_SCM,SCM>> jargon, "cherry pick" means to choose a subset of

-- 
1.5.4.4