Re: Checkout tag?

On Sunday, January 22, 2012 at 18:08 CET,
     Jonathan Nieder [off-list ref] wrote:

Magnus Bäck wrote:

quoted

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