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 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: 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 (the `*IGNORED*` flags are mutually exclusive): 26 27`DIR_SHOW_IGNORED`::: 28 29 Return just ignored files in `entries[]`, not untracked files. 30 31`DIR_SHOW_IGNORED_TOO`::: 32 33 Similar to `DIR_SHOW_IGNORED`, but return ignored files in `ignored[]` 34 in addition to untracked files in `entries[]`. 35 36`DIR_KEEP_UNTRACKED_CONTENTS`::: 37 38 Only has meaning if `DIR_SHOW_IGNORED_TOO` is also set; if this is set, the 39 untracked contents of untracked directories are also returned in 40 `entries[]`. 41 42`DIR_COLLECT_IGNORED`::: 43 44 Special mode for git-add. Return ignored files in `ignored[]` and 45 untracked files in `entries[]`. Only returns ignored files that match 46 pathspec exactly (no wildcards). Does not recurse into ignored 47 directories. 48 49`DIR_SHOW_OTHER_DIRECTORIES`::: 50 51 Include a directory that is not tracked. 52 53`DIR_HIDE_EMPTY_DIRECTORIES`::: 54 55 Do not include a directory that is not tracked and is empty. 56 57`DIR_NO_GITLINKS`::: 58 59 If set, recurse into a directory that looks like a Git 60 directory. Otherwise it is shown as a directory. 61 62The result of the enumeration is left in these fields: 63 64`entries[]`:: 65 66 An array of `struct dir_entry`, each element of which describes 67 a path. 68 69`nr`:: 70 71 The number of members in `entries[]` array. 72 73`alloc`:: 74 75 Internal use; keeps track of allocation of `entries[]` array. 76 77`ignored[]`:: 78 79 An array of `struct dir_entry`, used for ignored paths with the 80 `DIR_SHOW_IGNORED_TOO` and `DIR_COLLECT_IGNORED` flags. 81 82`ignored_nr`:: 83 84 The number of members in `ignored[]` array. 85 86Calling sequence 87---------------- 88 89Note: index may be looked at for .gitignore files that are CE_SKIP_WORKTREE 90marked. If you to exclude files, make sure you have loaded index first. 91 92* Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0, 93 sizeof(dir))`. 94 95* To add single exclude pattern, call `add_exclude_list()` and then 96 `add_exclude()`. 97 98* To add patterns from a file (e.g. `.git/info/exclude`), call 99 `add_excludes_from_file()` , and/or set `dir.exclude_per_dir`. A 100 short-hand function `setup_standard_excludes()` can be used to set 101 up the standard set of exclude settings. 102 103* Set options described in the Data Structure section above. 104 105* Call `read_directory()`. 106 107* Use `dir.entries[]`. 108 109* Call `clear_directory()` when none of the contained elements are no longer in use. 110 111(JC)