magic pathspec: add tentative ":/path/from/top/level" pathspec support

Support ":/" magic string that can be prefixed to a pathspec element to
say "this names the path from the top-level of the working tree", when
you are in the subdirectory.

For example, you should be able to say:

    $ edit Makefile ;# top-level
    $ cd Documentation
    $ edit git.txt ;# in the subdirectory

and then do one of three things, still inside the subdirectory:

    $ git add -u .  ;# add only Documentation/git.txt
    $ git add -u :/ ;# add everything, including paths outside Documentation
    $ git add -u    ;# whatever the default setting is.

To truly support magic pathspec, the API needs to be restructured so that
get_pathspec() and init_pathspec() are unified into one call.  Currently,
the former just prefixes the user supplied pathspec with the current
subdirectory path, and the latter takes the output from the former and
pre-parses them into a bit richer structure for easier handling.  They
should become a single API function that takes the current subdirectory
path and the remainder of argv[] (after parsing --options and revision
arguments from the command line) and returns an array of parsed pathspec
elements, and "magic" should become attributes of struct pathspec_item.

This patch implements only "top" magic because it can be hacked into the
system without such a refactoring.

The syntax for magic pathspec prefix is designed to be extensible yet
simple to type to invoke a simple magic like "from the top".  The parser
for the magic prefix is hooked into get_pathspec() function in this patch,
and it needs to be moved when we refactor the API.

But we have to start from somewhere.

Signed-off-by: Junio C Hamano <gitster@pobox.com>

1 files changed, 30 insertions, 1 deletions

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 33716a31d0..e51d7e60eb 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -277,7 +277,8 @@ This commit is referred to as a "merge commit", or sometimes just a
        Pattern used to specify paths.
 +
 Pathspecs are used on the command line of "git ls-files", "git
-ls-tree", "git grep", "git checkout", and many other commands to
+ls-tree", "git add", "git grep", "git diff", "git checkout",
+and many other commands to
 limit the scope of operations to some subset of the tree or
 worktree.  See the documentation of each command for whether
 paths are relative to the current directory or toplevel.  The
@@ -296,6 +297,34 @@ For example, Documentation/*.jpg will match all .jpg files
 in the Documentation subtree,
 including Documentation/chapter_1/figure_1.jpg.
 
++
+A pathspec that begins with a colon `:` has special meaning.  In the
+short form, the leading colon `:` is followed by zero or more "magic
+signature" letters (which optionally is terminated by another colon `:`),
+and the remainder is the pattern to match against the path. The optional
+colon that terminates the "magic signature" can be omitted if the pattern
+begins with a character that cannot be a "magic signature" and is not a
+colon.
++
+In the long form, the leading colon `:` is followed by a open
+parenthesis `(`, a comma-separated list of zero or more "magic words",
+and a close parentheses `)`, and the remainder is the pattern to match
+against the path.
++
+The "magic signature" consists of an ASCII symbol that is not
+alphanumeric.
++
+--
+top `/`;;
+	The magic word `top` (mnemonic: `/`) makes the pattern match
+	from the root of the working tree, even when you are running
+	the command from inside a subdirectory.
+--
++
+Currently only the slash `/` is recognized as the "magic signature",
+but it is envisioned that we will support more types of magic in later
+versions of git.
+
 [[def_parent]]parent::
 	A <<def_commit_object,commit object>> contains a (possibly empty) list
 	of the logical predecessor(s) in the line of development, i.e. its