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: 26 27`DIR_SHOW_IGNORED`::: 28 29 Return just ignored files in `entries[]`, not untracked 30 files. This flag is mutually exclusive with 31 `DIR_SHOW_IGNORED_TOO`. 32 33`DIR_SHOW_IGNORED_TOO`::: 34 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`. 39 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 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+ 56If this is set, files and directories that explicitly match an ignore 57pattern are reported. Implicitly ignored directories (directories that 58do not match an ignore pattern, but whose contents are all ignored) 59are not reported, instead all of the contents are reported. 60 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. 67 68`DIR_SHOW_OTHER_DIRECTORIES`::: 69 70 Include a directory that is not tracked. 71 72`DIR_HIDE_EMPTY_DIRECTORIES`::: 73 74 Do not include a directory that is not tracked and is empty. 75 76`DIR_NO_GITLINKS`::: 77 78 If set, recurse into a directory that looks like a Git 79 directory. Otherwise it is shown as a directory. 80 81The result of the enumeration is left in these fields: 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 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. 104 105Calling sequence 106---------------- 107 108Note: index may be looked at for .gitignore files that are CE_SKIP_WORKTREE 109marked. If you to exclude files, make sure you have loaded index first. 110 111* Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0, 112 sizeof(dir))`. 113 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. 121 122* Set options described in the Data Structure section above. 123 124* Call `read_directory()`. 125 126* Use `dir.entries[]`. 127 128* Call `clear_directory()` when none of the contained elements are no longer in use. 129 130(JC)