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. The notable 13options are: 14 15`exclude_per_dir`:: 16 17 The name of the file to be read in each directory for excluded 18 files (typically `.gitignore`). 19 20`collect_ignored`:: 21 22 Include paths that are to be excluded in the result. 23 24`show_ignored`:: 25 26 The traversal is for finding just ignored files, not unignored 27 files. 28 29`show_other_directories`:: 30 31 Include a directory that is not tracked. 32 33`hide_empty_directories`:: 34 35 Do not include a directory that is not tracked and is empty. 36 37`no_gitlinks`:: 38 39 If set, recurse into a directory that looks like a git 40 directory. Otherwise it is shown as a directory. 41 42The result of the enumeration is left in these fields:: 43 44`entries[]`:: 45 46 An array of `struct dir_entry`, each element of which describes 47 a path. 48 49`nr`:: 50 51 The number of members in `entries[]` array. 52 53`alloc`:: 54 55 Internal use; keeps track of allocation of `entries[]` array. 56 57 58Calling sequence 59---------------- 60 61* Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0, 62 sizeof(dir))`. 63 64* Call `add_exclude()` to add single exclude pattern, 65 `add_excludes_from_file()` to add patterns from a file 66 (e.g. `.git/info/exclude`), and/or set `dir.exclude_per_dir`. A 67 short-hand function `setup_standard_excludes()` can be used to set up 68 the standard set of exclude settings. 69 70* Set options described in the Data Structure section above. 71 72* Call `read_directory()`. 73 74* Use `dir.entries[]`. 75 76(JC)