pathspec: move doc to pathspec.h
Move the documentation from Documentation/technical/api-setup.txt to pathspec.h as it's easier for the developers to find the usage information beside the code instead of looking for it in another doc file. Also documentation/technical/api-setup.txt is removed because the information it has is now redundant and it'll be hard to keep it up to date and synchronized with the documentation in the header file. Signed-off-by: Heba Waly <heba.waly@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Heba Waly committed
Nov 17, 2019 at 21:04 UTC
19ef3ddd36cdd426c35523a420c78e13a36b6f99
2 files changed
+34
-48
Documentation/technical/api-setup.txt
deleted
-47
@@ -1,47 +0,0 @@
1
-setup API
2
-=========
3
-
4
-Talk about
5
-
6
-* setup_git_directory()
7
-* setup_git_directory_gently()
8
-* is_inside_git_dir()
9
-* is_inside_work_tree()
10
-* setup_work_tree()
11
-
12
-(Dscho)
13
-
14
-Pathspec
15
---------
16
-
17
-See glossary-context.txt for the syntax of pathspec. In memory, a
18
-pathspec set is represented by "struct pathspec" and is prepared by
19
-parse_pathspec(). This function takes several arguments:
20
-
21
-- magic_mask specifies what features that are NOT supported by the
22
- following code. If a user attempts to use such a feature,
23
- parse_pathspec() can reject it early.
24
-
25
-- flags specifies other things that the caller wants parse_pathspec to
26
- perform.
27
-
28
-- prefix and args come from cmd_* functions
29
-
30
-parse_pathspec() helps catch unsupported features and reject them
31
-politely. At a lower level, different pathspec-related functions may
32
-not support the same set of features. Such pathspec-sensitive
33
-functions are guarded with GUARD_PATHSPEC(), which will die in an
34
-unfriendly way when an unsupported feature is requested.
35
-
36
-The command designers are supposed to make sure that GUARD_PATHSPEC()
37
-never dies. They have to make sure all unsupported features are caught
38
-by parse_pathspec(), not by GUARD_PATHSPEC. grepping GUARD_PATHSPEC()
39
-should give the designers all pathspec-sensitive codepaths and what
40
-features they support.
41
-
42
-A similar process is applied when a new pathspec magic is added. The
43
-designer lifts the GUARD_PATHSPEC restriction in the functions that
44
-support the new magic. At the same time (s)he has to make sure this
45
-new feature will be caught at parse_pathspec() in commands that cannot
46
-handle the new magic in some cases. grepping parse_pathspec() should
47
-help.
pathspec.h
+34
-1
@@ -22,6 +22,11 @@ struct index_state;
22
23
#define PATHSPEC_ONESTAR 1 /* the pathspec pattern satisfies GFNM_ONESTAR */
24
25
+/**
26
+ * See glossary-context.txt for the syntax of pathspec.
27
+ * In memory, a pathspec set is represented by "struct pathspec" and is
28
+ * prepared by parse_pathspec().
29
+ */
30
struct pathspec {
31
int nr;
32
unsigned int has_wildcard:1;
@@ -73,18 +78,46 @@ struct pathspec {
78
*/
79
#define PATHSPEC_LITERAL_PATH (1<<6)
80
76
-/*
81
+/**
82
* Given command line arguments and a prefix, convert the input to
83
* pathspec. die() if any magic in magic_mask is used.
84
*
85
* Any arguments used are copied. It is safe for the caller to modify
86
* or free 'prefix' and 'args' after calling this function.
87
+ *
88
+ * - magic_mask specifies what features that are NOT supported by the following
89
+ * code. If a user attempts to use such a feature, parse_pathspec() can reject
90
+ * it early.
91
+ *
92
+ * - flags specifies other things that the caller wants parse_pathspec to
93
+ * perform.
94
+ *
95
+ * - prefix and args come from cmd_* functions
96
+ *
97
+ * parse_pathspec() helps catch unsupported features and reject them politely.
98
+ * At a lower level, different pathspec-related functions may not support the
99
+ * same set of features. Such pathspec-sensitive functions are guarded with
100
+ * GUARD_PATHSPEC(), which will die in an unfriendly way when an unsupported
101
+ * feature is requested.
102
+ *
103
+ * The command designers are supposed to make sure that GUARD_PATHSPEC() never
104
+ * dies. They have to make sure all unsupported features are caught by
105
+ * parse_pathspec(), not by GUARD_PATHSPEC. grepping GUARD_PATHSPEC() should
106
+ * give the designers all pathspec-sensitive codepaths and what features they
107
+ * support.
108
+ *
109
+ * A similar process is applied when a new pathspec magic is added. The designer
110
+ * lifts the GUARD_PATHSPEC restriction in the functions that support the new
111
+ * magic. At the same time (s)he has to make sure this new feature will be
112
+ * caught at parse_pathspec() in commands that cannot handle the new magic in
113
+ * some cases. grepping parse_pathspec() should help.
114
*/
115
void parse_pathspec(struct pathspec *pathspec,
116
unsigned magic_mask,
117
unsigned flags,
118
const char *prefix,
119
const char **args);
120
+
121
void copy_pathspec(struct pathspec *dst, const struct pathspec *src);
122
void clear_pathspec(struct pathspec *);
123