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

On Wed, Nov 17, 2010 at 09:54:08AM -0800, Junio C Hamano wrote:

Nguyễn Thái Ngọc Duy  [off-list ref] writes:

quoted

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