[RFD] git glossary: define pathspec

As far as I know we have three lightly incompatible pathspec
implementations:

1. match_pathspec() in dir.c
2. tree_interesting() in tree-walk.c
3. pathspec_matches() in builtin/grep.c

What I describe here is match_pathspec(). What I want is a single
pathspec semantics that all three must follow. Or even better, all
three will become a single impl.

We need to point the differences between the three and see how to
unify them.

sure if #3 can do the same.

directories. Therefore "Documentation" can't match the directory,
while Documentation/ can. This is no problem to #2. It can be solved
with a similar approach to [1], although maybe we can just convert the
index to tree-based structure.

Any other differences?

Also rewording my poor paragraph is welcome.

[1] http://article.gmane.org/gmane.comp.version-control.git/162267
---
 Documentation/glossary-content.txt |   11 +++++++++++
 1 files changed, 11 insertions(+), 0 deletions(-)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 1f029f8..22da1b1 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt

@@ -278,6 +278,17 @@ This commit is referred to as a "merge commit", or sometimes just a
 	of the logical predecessor(s) in the line of development, i.e. its
 	parents.
 
+[[def_pathspec]]pathspec::
+	Pathspec in its simplest form is a literal path to address a
+	file or a blob.
+	Pathspec can end with a slash. Such pathspec is considered a
+	directory prefix and will match everything under matched
+	directory.
+	Pathspec can contain wildcards such as '*', '?'... Such
+	pathspecs, after being matched literally against the entire
+	path, will be matched against the entire path using
+	fnmatch(3).
+
 [[def_pickaxe]]pickaxe::
 	The term <<def_pickaxe,pickaxe>> refers to an option to the diffcore
 	routines that help select changes that add or delete a given text

-- 
1.7.3.2.316.gda8b3

2010/11/29 Nguyễn Thái Ngọc Duy [off-list ref]:

sure if #3 can do the same.
...
index to tree-based structure.

Words disappear mysteriously. That part says

#1 can match a wildcard pattern literally (say "a*" will match the
file named "a*"). This is new to me. I don't know if #3 can do the
same.

#2 can't match wildcards, which is known for some time.

#1 and #3 can match index. The famous index does not have directories,
so "Documentation" matches that directory well in #2, but won't in #1
and #3. "Documentation/" works in all three. [1] in the previous mail
can be used to recreate directories, or we can just move the index to
a tree-based structure.
-- 
Duy

2010/11/29 Nguyễn Thái Ngọc Duy [off-list ref]:

[1] http://article.gmane.org/gmane.comp.version-control.git/162267

Sorry again. Wrong reference. The correct link should be

[1] http://article.gmane.org/gmane.comp.version-control.git/162269
-- 
Duy

Nguyễn Thái Ngọc Duy wrote:

Perhaps worth mentioning that these are path specifiers?

 pathspec::
	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
	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
	pathspec syntax is as follows:

	. any path matches itself
	. the pathspec up to the last slash represents a
	  directory prefix.  The scope of that pathspec is
	  limited to that subtree.
	. the rest of the pathspec is a pattern for the remainder
	  of the pathname.  Paths relative to the directory
	  prefix will be matched against that pattern using fnmatch(3);
	  in particular, '*' and '?' _can_ match directory separators.

	For example, Documentation/*.jpg will match all .jpg files
	in the Documentation subtree,
	including Documentation/chapter_1/figure_1.jpg.

Of course, I am making the semantics up. :)

Hope that helps,
Jonathan