dir.c: provide clear_directory() for reclaiming dir_struct memory
[git/git.git] / Documentation / technical / api-directory-listing.txt
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 The traversal is for finding just ignored files, not unignored
30 files.
31
32 `DIR_SHOW_OTHER_DIRECTORIES`:::
33
34 Include a directory that is not tracked.
35
36 `DIR_HIDE_EMPTY_DIRECTORIES`:::
37
38 Do not include a directory that is not tracked and is empty.
39
40 `DIR_NO_GITLINKS`:::
41
42 If set, recurse into a directory that looks like a git
43 directory. Otherwise it is shown as a directory.
44
45 The result of the enumeration is left in these fields:
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
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
67 * Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0,
68 sizeof(dir))`.
69
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.
77
78 * Set options described in the Data Structure section above.
79
80 * Call `read_directory()`.
81
82 * Use `dir.entries[]`.
83
84 * Call `free_directory()` when none of the contained elements are no longer in use.
85
86 (JC)