dir.c: provide clear_directory() for reclaiming dir_struct memory
[git/git.git] / Documentation / technical / api-directory-listing.txt
CommitLineData
530e741c
JH
1directory listing API
2=====================
3
4The directory listing API is used to enumerate paths in the work tree,
5optionally taking `.git/info/exclude` and `.gitignore` files per
6directory into account.
7
8Data structure
9--------------
10
11`struct dir_struct` structure is used to pass directory traversal
95a68344
AS
12options to the library and to record the paths discovered. A single
13`struct dir_struct` is used regardless of whether or not the traversal
14recursively descends into subdirectories.
15
16The 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 45The 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
61Calling sequence
62----------------
63
c28b3d6e
NTND
64Note: index may be looked at for .gitignore files that are CE_SKIP_WORKTREE
65marked. 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)