dir: add commentary explaining match_pathspec_item's return value
The way match_pathspec_item() handles names and pathspecs with trailing slash characters, in conjunction with special options like DO_MATCH_DIRECTORY and DO_MATCH_LEADING_PATHSPEC were non-obvious, and broken until this patch series. Add a table in a comment explaining the intent of how these work. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Elijah Newren committed
Sep 17, 2019 at 09:34 UTC
29b577b96082d87b7237fdc57bf95cfe0914c53d
1 file changed
+19
-8
dir.c
+19
-8
@@ -276,16 +276,27 @@ static int do_read_blob(const struct object_id *oid, struct oid_stat *oid_stat,
276
#define DO_MATCH_LEADING_PATHSPEC (1<<2)
277
278
/*
279
- * Does 'match' match the given name?
280
- * A match is found if
279
+ * Does the given pathspec match the given name? A match is found if
280
*
282
- * (1) the 'match' string is leading directory of 'name', or
283
- * (2) the 'match' string is a wildcard and matches 'name', or
284
- * (3) the 'match' string is exactly the same as 'name'.
281
+ * (1) the pathspec string is leading directory of 'name' ("RECURSIVELY"), or
282
+ * (2) the pathspec string has a leading part matching 'name' ("LEADING"), or
283
+ * (3) the pathspec string is a wildcard and matches 'name' ("WILDCARD"), or
284
+ * (4) the pathspec string is exactly the same as 'name' ("EXACT").
285
*
286
- * and the return value tells which case it was.
286
+ * Return value tells which case it was (1-4), or 0 when there is no match.
287
*
288
- * It returns 0 when there is no match.
288
+ * It may be instructive to look at a small table of concrete examples
289
+ * to understand the differences between 1, 2, and 4:
290
+ *
291
+ * Pathspecs
292
+ * | a/b | a/b/ | a/b/c
293
+ * ------+-----------+-----------+------------
294
+ * a/b | EXACT | EXACT[1] | LEADING[2]
295
+ * Names a/b/ | RECURSIVE | EXACT | LEADING[2]
296
+ * a/b/c | RECURSIVE | RECURSIVE | EXACT
297
+ *
298
+ * [1] Only if DO_MATCH_DIRECTORY is passed; otherwise, this is NOT a match.
299
+ * [2] Only if DO_MATCH_LEADING_PATHSPEC is passed; otherwise, not a match.
300
*/
301
static int match_pathspec_item(const struct index_state *istate,
302
const struct pathspec_item *item, int prefix,
@@ -353,7 +364,7 @@ static int match_pathspec_item(const struct index_state *istate,
364
item->nowildcard_len - prefix))
365
return MATCHED_FNMATCH;
366
356
- /* Perform checks to see if "name" is a super set of the pathspec */
367
+ /* Perform checks to see if "name" is a leading string of the pathspec */
368
if (flags & DO_MATCH_LEADING_PATHSPEC) {
369
/* name is a literal prefix of the pathspec */
370
int offset = name[namelen-1] == '/' ? 1 : 0;