]>
Commit | Line | Data |
---|---|---|
530e741c JH |
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 | |
95a68344 AS |
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: | |
530e741c JH |
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 | ||
f1a7082f | 23 | `flags`:: |
530e741c | 24 | |
1b2bc391 | 25 | A bit-field of options: |
530e741c | 26 | |
f1a7082f | 27 | `DIR_SHOW_IGNORED`::: |
530e741c | 28 | |
1b2bc391 JM |
29 | Return just ignored files in `entries[]`, not untracked |
30 | files. This flag is mutually exclusive with | |
31 | `DIR_SHOW_IGNORED_TOO`. | |
0aaf62b6 KB |
32 | |
33 | `DIR_SHOW_IGNORED_TOO`::: | |
34 | ||
1b2bc391 JM |
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`. | |
0aaf62b6 | 39 | |
fb898888 SL |
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 | ||
1b2bc391 JM |
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 | + | |
c30d4f1b | 56 | If this is set, files and directories that explicitly match an ignore |
928f0ab4 | 57 | pattern are reported. Implicitly ignored directories (directories that |
1b2bc391 JM |
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 | ||
0aaf62b6 KB |
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. | |
530e741c | 67 | |
f1a7082f | 68 | `DIR_SHOW_OTHER_DIRECTORIES`::: |
530e741c JH |
69 | |
70 | Include a directory that is not tracked. | |
71 | ||
f1a7082f | 72 | `DIR_HIDE_EMPTY_DIRECTORIES`::: |
530e741c JH |
73 | |
74 | Do not include a directory that is not tracked and is empty. | |
75 | ||
f1a7082f | 76 | `DIR_NO_GITLINKS`::: |
530e741c | 77 | |
2de9b711 | 78 | If set, recurse into a directory that looks like a Git |
530e741c JH |
79 | directory. Otherwise it is shown as a directory. |
80 | ||
95a68344 | 81 | The result of the enumeration is left in these fields: |
530e741c JH |
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 | ||
0aaf62b6 KB |
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. | |
530e741c JH |
104 | |
105 | Calling sequence | |
106 | ---------------- | |
107 | ||
c28b3d6e NTND |
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 | ||
530e741c JH |
111 | * Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0, |
112 | sizeof(dir))`. | |
113 | ||
c082df24 AS |
114 | * To add single exclude pattern, call `add_exclude_list()` and then |
115 | `add_exclude()`. | |
116 | ||
117 | * To add patterns from a file (e.g. `.git/info/exclude`), call | |
118 | `add_excludes_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. | |
530e741c JH |
121 | |
122 | * Set options described in the Data Structure section above. | |
123 | ||
124 | * Call `read_directory()`. | |
125 | ||
126 | * Use `dir.entries[]`. | |
127 | ||
368aa529 | 128 | * Call `clear_directory()` when none of the contained elements are no longer in use. |
270be816 | 129 | |
530e741c | 130 | (JC) |