Subject: Re: [PATCH 0/3] Support relative path in <blah>:path syntax

From: Nguyen Thai Ngoc Duy <[email-masked]>
Date: Thu, 18 Nov 2010 08:47:01 +0700

On Wed, Nov 17, 2010 at 09:54:08AM -0800, Junio C Hamano wrote:
> Nguyễn Thái Ngọc Duy  <[email-masked]> writes:
> 
> > Sorry Jonathan I lied. I did not pick up your fast-import changes.
> > Could not find how to test it. And it seems fast-import only cares
> > about commits, not the target audience of this syntax.
> >
> > Document is not updated because I think it's intuitive enough.
> 
> When you say <tree>:<path>, you would intuitively expect that the path is
> relative to <tree>, but this patch deliberately breaks (in a good way)
> that expectation by introducing a magic token "./".  Once you know that
> "./" magic _exists_, it is obvious what it means, but people may not even
> imagine that such a magic may exist in the first place (certainly old
> timers won't), and would not know what the magic token is if you do not
> tell them.
> 
> It needs to be documented.

OK. How about this, squashing in the last patch of this series?

--8<--
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 3d4b79c..3fc3e8b 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -121,6 +121,10 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
   ':path' (with an empty part before the colon, e.g. `:README`)
   is a special case of the syntax described next: content
   recorded in the index at the given path.
+  A path starting with './' or '../' is relative to current working directory.
+  The given path will be converted to be relative to working tree's root directory.
+  This is most useful to address a blob or tree from a commit or tree that has
+  the same tree structure with the working tree.
 
 * A colon, optionally followed by a stage number (0 to 3) and a
   colon, followed by a path (e.g. `:0:README`); this names a blob object in the
--8<--