]>
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 | |
f1a7082f | 25 | A bit-field of options: |
530e741c | 26 | |
f1a7082f | 27 | `DIR_SHOW_IGNORED`::: |
530e741c JH |
28 | |
29 | The traversal is for finding just ignored files, not unignored | |
30 | files. | |
31 | ||
f1a7082f | 32 | `DIR_SHOW_OTHER_DIRECTORIES`::: |
530e741c JH |
33 | |
34 | Include a directory that is not tracked. | |
35 | ||
f1a7082f | 36 | `DIR_HIDE_EMPTY_DIRECTORIES`::: |
530e741c JH |
37 | |
38 | Do not include a directory that is not tracked and is empty. | |
39 | ||
f1a7082f | 40 | `DIR_NO_GITLINKS`::: |
530e741c JH |
41 | |
42 | If set, recurse into a directory that looks like a git | |
43 | directory. Otherwise it is shown as a directory. | |
44 | ||
95a68344 | 45 | The result of the enumeration is left in these fields: |
530e741c JH |
46 | |
47 | `entries[]`:: | |
48 | ||
49 | An array of `struct dir_entry`, each element of which describes | |
50 | a path. | |
51 | ||
52 | `nr`:: | |
53 | ||
54 | The number of members in `entries[]` array. | |
55 | ||
56 | `alloc`:: | |
57 | ||
58 | Internal use; keeps track of allocation of `entries[]` array. | |
59 | ||
60 | ||
61 | Calling sequence | |
62 | ---------------- | |
63 | ||
c28b3d6e NTND |
64 | Note: index may be looked at for .gitignore files that are CE_SKIP_WORKTREE |
65 | marked. If you to exclude files, make sure you have loaded index first. | |
66 | ||
530e741c JH |
67 | * Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0, |
68 | sizeof(dir))`. | |
69 | ||
c082df24 AS |
70 | * To add single exclude pattern, call `add_exclude_list()` and then |
71 | `add_exclude()`. | |
72 | ||
73 | * To add patterns from a file (e.g. `.git/info/exclude`), call | |
74 | `add_excludes_from_file()` , and/or set `dir.exclude_per_dir`. A | |
75 | short-hand function `setup_standard_excludes()` can be used to set | |
76 | up the standard set of exclude settings. | |
530e741c JH |
77 | |
78 | * Set options described in the Data Structure section above. | |
79 | ||
80 | * Call `read_directory()`. | |
81 | ||
82 | * Use `dir.entries[]`. | |
83 | ||
270be816 AS |
84 | * Call `free_directory()` when none of the contained elements are no longer in use. |
85 | ||
530e741c | 86 | (JC) |