Re: Checkout tag?

From: Magnus Bäck <magnus.back@sonyericsson.com>
Date: Jan 22, 2012, 17:33 UTC
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:

Show 20 quoted lines

> 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.

Show 21 quoted lines

> 	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