dir: move doc to dir.h
Move the documentation from Documentation/technical/api-directory-listing.txt to dir.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-directory-listing.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 files. 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
266f03eccd36b84c88206aa6d18b163223294229
3 files changed
+114
-137
Documentation/technical/api-directory-listing.txt
deleted
-130
@@ -1,130 +0,0 @@
1
-directory listing API
2
-=====================
3
-
4
-The directory listing API is used to enumerate paths in the work tree,
5
-optionally taking `.git/info/exclude` and `.gitignore` files per
6
-directory into account.
7
-
8
-Data structure
9
---------------
10
-
11
-`struct dir_struct` structure is used to pass directory traversal
12
-options to the library and to record the paths discovered. A single
13
-`struct dir_struct` is used regardless of whether or not the traversal
14
-recursively descends into subdirectories.
15
-
16
-The notable options are:
17
-
18
-`exclude_per_dir`::
19
-
20
- The name of the file to be read in each directory for excluded
21
- files (typically `.gitignore`).
22
-
23
-`flags`::
24
-
25
- A bit-field of options:
26
-
27
-`DIR_SHOW_IGNORED`:::
28
-
29
- Return just ignored files in `entries[]`, not untracked
30
- files. This flag is mutually exclusive with
31
- `DIR_SHOW_IGNORED_TOO`.
32
-
33
-`DIR_SHOW_IGNORED_TOO`:::
34
-
35
- Similar to `DIR_SHOW_IGNORED`, but return ignored files in
36
- `ignored[]` in addition to untracked files in
37
- `entries[]`. This flag is mutually exclusive with
38
- `DIR_SHOW_IGNORED`.
39
-
40
-`DIR_KEEP_UNTRACKED_CONTENTS`:::
41
-
42
- Only has meaning if `DIR_SHOW_IGNORED_TOO` is also set; if this is set, the
43
- untracked contents of untracked directories are also returned in
44
- `entries[]`.
45
-
46
-`DIR_SHOW_IGNORED_TOO_MODE_MATCHING`:::
47
-
48
- Only has meaning if `DIR_SHOW_IGNORED_TOO` is also set; if
49
- this is set, returns ignored files and directories that match
50
- an exclude pattern. If a directory matches an exclude pattern,
51
- then the directory is returned and the contained paths are
52
- not. A directory that does not match an exclude pattern will
53
- not be returned even if all of its contents are ignored. In
54
- this case, the contents are returned as individual entries.
55
-+
56
-If this is set, files and directories that explicitly match an ignore
57
-pattern are reported. Implicitly ignored directories (directories that
58
-do not match an ignore pattern, but whose contents are all ignored)
59
-are not reported, instead all of the contents are reported.
60
-
61
-`DIR_COLLECT_IGNORED`:::
62
-
63
- Special mode for git-add. Return ignored files in `ignored[]` and
64
- untracked files in `entries[]`. Only returns ignored files that match
65
- pathspec exactly (no wildcards). Does not recurse into ignored
66
- directories.
67
-
68
-`DIR_SHOW_OTHER_DIRECTORIES`:::
69
-
70
- Include a directory that is not tracked.
71
-
72
-`DIR_HIDE_EMPTY_DIRECTORIES`:::
73
-
74
- Do not include a directory that is not tracked and is empty.
75
-
76
-`DIR_NO_GITLINKS`:::
77
-
78
- If set, recurse into a directory that looks like a Git
79
- directory. Otherwise it is shown as a directory.
80
-
81
-The result of the enumeration is left in these fields:
82
-
83
-`entries[]`::
84
-
85
- An array of `struct dir_entry`, each element of which describes
86
- a path.
87
-
88
-`nr`::
89
-
90
- The number of members in `entries[]` array.
91
-
92
-`alloc`::
93
-
94
- Internal use; keeps track of allocation of `entries[]` array.
95
-
96
-`ignored[]`::
97
-
98
- An array of `struct dir_entry`, used for ignored paths with the
99
- `DIR_SHOW_IGNORED_TOO` and `DIR_COLLECT_IGNORED` flags.
100
-
101
-`ignored_nr`::
102
-
103
- The number of members in `ignored[]` array.
104
-
105
-Calling sequence
106
-----------------
107
-
108
-Note: index may be looked at for .gitignore files that are CE_SKIP_WORKTREE
109
-marked. If you to exclude files, make sure you have loaded index first.
110
-
111
-* Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0,
112
- sizeof(dir))`.
113
-
114
-* To add single exclude pattern, call `add_pattern_list()` and then
115
- `add_pattern()`.
116
-
117
-* To add patterns from a file (e.g. `.git/info/exclude`), call
118
- `add_patterns_from_file()` , and/or set `dir.exclude_per_dir`. A
119
- short-hand function `setup_standard_excludes()` can be used to set
120
- up the standard set of exclude settings.
121
-
122
-* Set options described in the Data Structure section above.
123
-
124
-* Call `read_directory()`.
125
-
126
-* Use `dir.entries[]`.
127
-
128
-* Call `clear_directory()` when none of the contained elements are no longer in use.
129
-
130
-(JC)
dir.c
-2
@@ -2,8 +2,6 @@
2
* This handles recursive filename detection with exclude
3
* files, index knowledge etc..
4
*
5
- * See Documentation/technical/api-directory-listing.txt
6
- *
5
* Copyright (C) Linus Torvalds, 2005-2006
6
* Junio Hamano, 2005-2006
7
*/
dir.h
+114
-5
@@ -1,11 +1,44 @@
1
#ifndef DIR_H
2
#define DIR_H
3
4
-/* See Documentation/technical/api-directory-listing.txt */
5
-
4
#include "cache.h"
5
#include "strbuf.h"
6
7
+/**
8
+ * The directory listing API is used to enumerate paths in the work tree,
9
+ * optionally taking `.git/info/exclude` and `.gitignore` files per directory
10
+ * into account.
11
+ */
12
+
13
+/**
14
+ * Calling sequence
15
+ * ----------------
16
+ *
17
+ * Note: The index may be checked for .gitignore files that are
18
+ * CE_SKIP_WORKTREE marked. If you want to exclude files, make sure you have
19
+ * loaded the index first.
20
+ *
21
+ * - Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0,
22
+ * sizeof(dir))`.
23
+ *
24
+ * - To add single exclude pattern, call `add_pattern_list()` and then
25
+ * `add_pattern()`.
26
+ *
27
+ * - To add patterns from a file (e.g. `.git/info/exclude`), call
28
+ * `add_patterns_from_file()` , and/or set `dir.exclude_per_dir`. A
29
+ * short-hand function `setup_standard_excludes()` can be used to set
30
+ * up the standard set of exclude settings.
31
+ *
32
+ * - Set options described in the Data Structure section above.
33
+ *
34
+ * - Call `read_directory()`.
35
+ *
36
+ * - Use `dir.entries[]`.
37
+ *
38
+ * - Call `clear_directory()` when none of the contained elements are no longer in use.
39
+ *
40
+ */
41
+
42
struct dir_entry {
43
unsigned int len;
44
char name[FLEX_ARRAY]; /* more */
@@ -144,25 +177,101 @@ struct untracked_cache {
177
unsigned int use_fsmonitor : 1;
178
};
179
180
+/**
181
+ * structure is used to pass directory traversal options to the library and to
182
+ * record the paths discovered. A single `struct dir_struct` is used regardless
183
+ * of whether or not the traversal recursively descends into subdirectories.
184
+ */
185
struct dir_struct {
148
- int nr, alloc;
149
- int ignored_nr, ignored_alloc;
186
+
187
+ /* The number of members in `entries[]` array. */
188
+ int nr;
189
+
190
+ /* Internal use; keeps track of allocation of `entries[]` array.*/
191
+ int alloc;
192
+
193
+ /* The number of members in `ignored[]` array. */
194
+ int ignored_nr;
195
+
196
+ int ignored_alloc;
197
+
198
+ /* bit-field of options */
199
enum {
200
+
201
+ /**
202
+ * Return just ignored files in `entries[]`, not untracked files.
203
+ * This flag is mutually exclusive with `DIR_SHOW_IGNORED_TOO`.
204
+ */
205
DIR_SHOW_IGNORED = 1<<0,
206
+
207
+ /* Include a directory that is not tracked. */
208
DIR_SHOW_OTHER_DIRECTORIES = 1<<1,
209
+
210
+ /* Do not include a directory that is not tracked and is empty. */
211
DIR_HIDE_EMPTY_DIRECTORIES = 1<<2,
212
+
213
+ /**
214
+ * If set, recurse into a directory that looks like a Git directory.
215
+ * Otherwise it is shown as a directory.
216
+ */
217
DIR_NO_GITLINKS = 1<<3,
218
+
219
+ /**
220
+ * Special mode for git-add. Return ignored files in `ignored[]` and
221
+ * untracked files in `entries[]`. Only returns ignored files that match
222
+ * pathspec exactly (no wildcards). Does not recurse into ignored
223
+ * directories.
224
+ */
225
DIR_COLLECT_IGNORED = 1<<4,
226
+
227
+ /**
228
+ * Similar to `DIR_SHOW_IGNORED`, but return ignored files in
229
+ * `ignored[]` in addition to untracked files in `entries[]`.
230
+ * This flag is mutually exclusive with `DIR_SHOW_IGNORED`.
231
+ */
232
DIR_SHOW_IGNORED_TOO = 1<<5,
233
+
234
DIR_COLLECT_KILLED_ONLY = 1<<6,
235
+
236
+ /**
237
+ * Only has meaning if `DIR_SHOW_IGNORED_TOO` is also set; if this is
238
+ * set, the untracked contents of untracked directories are also
239
+ * returned in `entries[]`.
240
+ */
241
DIR_KEEP_UNTRACKED_CONTENTS = 1<<7,
242
+
243
+ /**
244
+ * Only has meaning if `DIR_SHOW_IGNORED_TOO` is also set; if this is
245
+ * set, returns ignored files and directories that match an exclude
246
+ * pattern. If a directory matches an exclude pattern, then the
247
+ * directory is returned and the contained paths are not. A directory
248
+ * that does not match an exclude pattern will not be returned even if
249
+ * all of its contents are ignored. In this case, the contents are
250
+ * returned as individual entries.
251
+ *
252
+ * If this is set, files and directories that explicitly match an ignore
253
+ * pattern are reported. Implicitly ignored directories (directories that
254
+ * do not match an ignore pattern, but whose contents are all ignored)
255
+ * are not reported, instead all of the contents are reported.
256
+ */
257
DIR_SHOW_IGNORED_TOO_MODE_MATCHING = 1<<8,
258
+
259
DIR_SKIP_NESTED_GIT = 1<<9
260
} flags;
261
+
262
+ /* An array of `struct dir_entry`, each element of which describes a path. */
263
struct dir_entry **entries;
264
+
265
+ /**
266
+ * used for ignored paths with the `DIR_SHOW_IGNORED_TOO` and
267
+ * `DIR_COLLECT_IGNORED` flags.
268
+ */
269
struct dir_entry **ignored;
270
165
- /* Exclude info */
271
+ /**
272
+ * The name of the file to be read in each directory for excluded files
273
+ * (typically `.gitignore`).
274
+ */
275
const char *exclude_per_dir;
276
277
/*