From: Magnus Bäck <magnus.back@sonyericsson.com>
Date: Sun, 22 Jan 2012 17:33:52 GMT
Subject: Re: Checkout tag?
Message-ID: <20120122173352.GA1068@jpl.local>
In-Reply-To: <20120122170800.GA29215@burratino>

On Sunday, January 22, 2012 at 18:08 CET,
     Jonathan Nieder <jrnieder@gmail.com> wrote:

> Magnus Bäck wrote:
> 
> > Looking at an up to date Git 1.7.9-rc2 man page, it still seems
> > slightly inconsistent with itself. The synopsis at the top says
> >
> >       git checkout [-p|--patch] [<tree-ish>] [--] [<paths>...]
> >
> > while the text in the DESCRIPTION section says
> >
> >       git checkout [-p|--patch] [<tree-ish>] [--] <pathspec>...
> 
> Hmm, my copy says:
> 
> 	SYNOPSIS
> 
> 	git checkout [-q] [-f] [-m] [<branch>]
> 	git checkout [-q] [-f] [-m] [--detach] [<commit>]
> 	git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
> 	git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
> 	git checkout [-p|--patch] [<tree-ish>] [--] [<paths>...]

Perhaps I wasn't clear -- I didn't mean that the synopsis *only* listed
the form in my original quote above.

> 	DESCRIPTION
> 
> 	... overview ...
> 
> 	git checkout [<branch>], git checkout -b|-B <new_branch> [<start point>],
> 	git checkout [--detach] [<commit>]
> 
> 		This form switches branches by updating the index, working
> 		tree, and HEAD...
> 
> 	git checkout [-p|--patch] [<tree-ish>] [--] <pathspec>...
> 
> 		When <paths> or --patch are given, git checkout does not
> 		switch branches. It updates the named paths...
> 
> So in the synopsis it lists five forms, and in the description section
> it lists two forms, the first of which has three variants.
> 
> It's not immediately obvious to me which inconsistency you are
> pointing to as a source of confusion.  Could you elaborate,
> preferably with suggested wording for a fix?

I simply meant that

   git checkout [-p|--patch] [<tree-ish>] [--] [<paths>...]
   git checkout [-p|--patch] [<tree-ish>] [--] <pathspec>...

aren't identical even though I assume they describe the exact same
scenario. The first command synopsis makes it clear that paths are
optional while the second indicates that at least one path must be
specified (unless "..." means "zero, one, or more occurences").
Also, "paths" != "pathspec".

> If you can do so in the form of a patch, all the better. ;-)

Sure, but it won't be during the coming week. Not that the patch is
terribly difficult to prepare but because I need legal approval to
submit it, and it's not clear I'll have time to deal with all that
during my last week at work.

-- 
Magnus Bäck                   Opinions are my own and do not necessarily
SW Configuration Manager      represent the ones of my employer, etc.
Sony Ericsson