Re: [PATCH] git-show.txt: mention that object path must be relative in EXAMPLES.

From: Boyd Stephen Smith Jr. <bss@iguanasuicide.net>
Date: Feb 8, 2009, 08:47 UTC
Message-ID: <200902080247.44151.bss@iguanasuicide.net>
In-Reply-To: <87skmpxt5g.fsf@jondo.cante.net>

On Sunday 08 February 2009 01:52:11 Jari Aalto wrote:

Show 16 quoted lines

> "Boyd Stephen Smith Jr." <bss@iguanasuicide.net> writes:
> > On Saturday 07 February 2009 17:31:47 Jakub Narebski wrote:
> >> Jari Aalto <jari.aalto@cante.net> writes:
> >> > +	`next`. *Note:* the 'object' path must always be relative to git
> >> > +	project root.
> >> Actually that is not exactly true.  In the <tree-ish>:<path> the
> >> 'object' path must be always relative to <tree-ish), in this case
> >> to "next~10", which means relative to project root at given commit
> >> (important in case of subtree merge).
> > Also important if one of your commits moves everything into a
> > subdirectory in preparation for adding new top-level directories.
> >
> > So, I think better additional text would simply be:
> > *Note:* the path is interpreted relative to the tree-ish.
>
> Changed, See below.

Thanks.

Show 12 quoted lines

> > A example of what not to do is probably not useful in this case.
>
> It is important to give examples. This is a common mistake:
>
>     $ cd todir
>     $ ls file.txt
>     file.txt
>
>     $ git show 8b2de93:file.txt
>
>     fatal: ambiguous argument '8b2de93:file.txt':
>     unknown revision or path not in the working tree.

I agree with both of your statements. I'm just not sure about the wisdom of giving an example of what *not* to do. There's a lot more incorrect invocations of git there there are correct invocations. Perhaps an example that illustrated to the user how the "unintuitive" behavior was *useful* would be better.

> The path is in working tree from user's point of view

No. At least, not from a right-thinking user's point of view. The phrase "working tree" has a very specific meaning in git, it is not "the current directory".

> Not intuitive if you're
> deep/in/the/directory/hierarchy

I'm not sure "not intuitive" is a useful metric. Different people simply expect different results. HCI studies are hard; we shouldn't assume we can guess their results so easily.

Even with my objections above, I'm still slightly positive toward the patch as is.

-- 
Boyd Stephen Smith Jr.                   ,= ,-_-. =.
bss@iguanasuicide.net                   ((_/)o o(\_))
ICQ: 514984 YM/AIM: DaTwinkDaddy         `-'(. .)`-'
http://iguanasuicide.net/                    \_/