dir.c: improve docs for match_pathspec() and match_pathspec_depth()
Fix a grammatical issue in the description of these functions, and make it more obvious how and why seen[] can be reused across multiple invocations. Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Adam Spiers committed
Jan 6, 2013 at 16:58 UTC
52ed1894b04e7664feaee85c0f14360b415a755c
2 files changed
+32
-12
dir.c
+26
-12
@@ -167,12 +167,19 @@ static int match_one(const char *match, const char *name, int namelen)
167
}
168
169
/*
170
- * Given a name and a list of pathspecs, see if the name matches
171
- * any of the pathspecs. The caller is also interested in seeing
172
- * all pathspec matches some names it calls this function with
173
- * (otherwise the user could have mistyped the unmatched pathspec),
174
- * and a mark is left in seen[] array for pathspec element that
175
- * actually matched anything.
170
+ * Given a name and a list of pathspecs, returns the nature of the
171
+ * closest (i.e. most specific) match of the name to any of the
172
+ * pathspecs.
173
+ *
174
+ * The caller typically calls this multiple times with the same
175
+ * pathspec and seen[] array but with different name/namelen
176
+ * (e.g. entries from the index) and is interested in seeing if and
177
+ * how each pathspec matches all the names it calls this function
178
+ * with. A mark is left in the seen[] array for each pathspec element
179
+ * indicating the closest type of match that element achieved, so if
180
+ * seen[n] remains zero after multiple invocations, that means the nth
181
+ * pathspec did not match any names, which could indicate that the
182
+ * user mistyped the nth pathspec.
183
*/
184
int match_pathspec(const char **pathspec, const char *name, int namelen,
185
int prefix, char *seen)
@@ -239,12 +246,19 @@ static int match_pathspec_item(const struct pathspec_item *item, int prefix,
246
}
247
248
/*
242
- * Given a name and a list of pathspecs, see if the name matches
243
- * any of the pathspecs. The caller is also interested in seeing
244
- * all pathspec matches some names it calls this function with
245
- * (otherwise the user could have mistyped the unmatched pathspec),
246
- * and a mark is left in seen[] array for pathspec element that
247
- * actually matched anything.
249
+ * Given a name and a list of pathspecs, returns the nature of the
250
+ * closest (i.e. most specific) match of the name to any of the
251
+ * pathspecs.
252
+ *
253
+ * The caller typically calls this multiple times with the same
254
+ * pathspec and seen[] array but with different name/namelen
255
+ * (e.g. entries from the index) and is interested in seeing if and
256
+ * how each pathspec matches all the names it calls this function
257
+ * with. A mark is left in the seen[] array for each pathspec element
258
+ * indicating the closest type of match that element achieved, so if
259
+ * seen[n] remains zero after multiple invocations, that means the nth
260
+ * pathspec did not match any names, which could indicate that the
261
+ * user mistyped the nth pathspec.
262
*/
263
int match_pathspec_depth(const struct pathspec *ps,
264
const char *name, int namelen,
dir.h
+6
@@ -116,6 +116,12 @@ struct dir_struct {
116
char basebuf[PATH_MAX];
117
};
118
119
+/*
120
+ * The ordering of these constants is significant, with
121
+ * higher-numbered match types signifying "closer" (i.e. more
122
+ * specific) matches which will override lower-numbered match types
123
+ * when populating the seen[] array.
124
+ */
125
#define MATCHED_RECURSIVELY 1
126
#define MATCHED_FNMATCH 2
127
#define MATCHED_EXACTLY 3