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 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 45The 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 61Calling sequence 62---------------- 63 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 67* Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0, 68 sizeof(dir))`. 69 70* Call `add_exclude()` to add single exclude pattern, 71 `add_excludes_from_file()` to add patterns from a file 72 (e.g. `.git/info/exclude`), and/or set `dir.exclude_per_dir`. A 73 short-hand function `setup_standard_excludes()` can be used to set up 74 the standard set of exclude settings. 75 76* Set options described in the Data Structure section above. 77 78* Call `read_directory()`. 79 80* Use `dir.entries[]`. 81 82(JC)