path: root/pathspec.h
diff options
authorJunio C Hamano <>2019-12-16 21:08:39 (GMT)
committerJunio C Hamano <>2019-12-16 21:08:39 (GMT)
commit26c816a67de449b3c5284ab97b03aeeeeabbb45c (patch)
tree2cca69d5115269b1c680b1ccd852202e1f7b5862 /pathspec.h
parentf0070a7df98540ebd0ba6ecb7aef4620efe27724 (diff)
parent6c51cb525da47a751b856bba55522ca9d4c24dac (diff)
Merge branch 'hw/doc-in-header'
* hw/doc-in-header: trace2: move doc to trace2.h submodule-config: move doc to submodule-config.h tree-walk: move doc to tree-walk.h trace: move doc to trace.h run-command: move doc to run-command.h parse-options: add link to doc file in parse-options.h credential: move doc to credential.h argv-array: move doc to argv-array.h cache: move doc to cache.h sigchain: move doc to sigchain.h pathspec: move doc to pathspec.h revision: move doc to revision.h attr: move doc to attr.h refs: move doc to refs.h remote: move doc to remote.h and refspec.h sha1-array: move doc to sha1-array.h merge: move doc to ll-merge.h graph: move doc to graph.h and graph.c dir: move doc to dir.h diff: move doc to diff.h and diffcore.h
Diffstat (limited to 'pathspec.h')
1 files changed, 34 insertions, 1 deletions
diff --git a/pathspec.h b/pathspec.h
index a27dc81..454ce36 100644
--- a/pathspec.h
+++ b/pathspec.h
@@ -22,6 +22,11 @@ struct index_state;
#define PATHSPEC_ONESTAR 1 /* the pathspec pattern satisfies GFNM_ONESTAR */
+ * See glossary-context.txt for the syntax of pathspec.
+ * In memory, a pathspec set is represented by "struct pathspec" and is
+ * prepared by parse_pathspec().
+ */
struct pathspec {
int nr;
unsigned int has_wildcard:1;
@@ -73,12 +78,39 @@ struct pathspec {
* Given command line arguments and a prefix, convert the input to
* pathspec. die() if any magic in magic_mask is used.
* Any arguments used are copied. It is safe for the caller to modify
* or free 'prefix' and 'args' after calling this function.
+ *
+ * - magic_mask specifies what features that are NOT supported by the following
+ * code. If a user attempts to use such a feature, parse_pathspec() can reject
+ * it early.
+ *
+ * - flags specifies other things that the caller wants parse_pathspec to
+ * perform.
+ *
+ * - prefix and args come from cmd_* functions
+ *
+ * parse_pathspec() helps catch unsupported features and reject them politely.
+ * At a lower level, different pathspec-related functions may not support the
+ * same set of features. Such pathspec-sensitive functions are guarded with
+ * GUARD_PATHSPEC(), which will die in an unfriendly way when an unsupported
+ * feature is requested.
+ *
+ * The command designers are supposed to make sure that GUARD_PATHSPEC() never
+ * dies. They have to make sure all unsupported features are caught by
+ * parse_pathspec(), not by GUARD_PATHSPEC. grepping GUARD_PATHSPEC() should
+ * give the designers all pathspec-sensitive codepaths and what features they
+ * support.
+ *
+ * A similar process is applied when a new pathspec magic is added. The designer
+ * lifts the GUARD_PATHSPEC restriction in the functions that support the new
+ * magic. At the same time (s)he has to make sure this new feature will be
+ * caught at parse_pathspec() in commands that cannot handle the new magic in
+ * some cases. grepping parse_pathspec() should help.
void parse_pathspec(struct pathspec *pathspec,
unsigned magic_mask,
@@ -95,6 +127,7 @@ void parse_pathspec_file(struct pathspec *pathspec,
const char *prefix,
const char *file,
int nul_term_line);
void copy_pathspec(struct pathspec *dst, const struct pathspec *src);
void clear_pathspec(struct pathspec *);