diff options
author | Junio C Hamano <gitster@pobox.com> | 2019-12-17 00:08:39 +0300 |
---|---|---|
committer | Junio C Hamano <gitster@pobox.com> | 2019-12-17 00:08:39 +0300 |
commit | 26c816a67de449b3c5284ab97b03aeeeeabbb45c (patch) | |
tree | 2cca69d5115269b1c680b1ccd852202e1f7b5862 /pathspec.h | |
parent | f0070a7df98540ebd0ba6ecb7aef4620efe27724 (diff) | |
parent | 6c51cb525da47a751b856bba55522ca9d4c24dac (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')
-rw-r--r-- | pathspec.h | 35 |
1 files changed, 34 insertions, 1 deletions
diff --git a/pathspec.h b/pathspec.h index a27dc81ba2..454ce364fa 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 { */ #define PATHSPEC_LITERAL_PATH (1<<6) -/* +/** * 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 *); |