From: Boyd Stephen Smith Jr. <bss@iguanasuicide.net>
Date: Sun, 08 Feb 2009 08:47:36 GMT
Subject: Re: [PATCH] git-show.txt: mention that object path must be relative in EXAMPLES.
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:
> "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.

> > 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/                    \_/