projects / thirdparty / git.git / blame
| Commit | Line | Data |
|---|---|---|
| 530e741c JH |
1 | directory listing API |
| 2 | ===================== | |
| 3 | ||
| 4 | The directory listing API is used to enumerate paths in the work tree, | |
| 5 | optionally taking `.git/info/exclude` and `.gitignore` files per | |
| 6 | directory into account. | |
| 7 | ||
| 8 | Data structure | |
| 9 | -------------- | |
| 10 | ||
| 11 | `struct dir_struct` structure is used to pass directory traversal | |
| 12 | options to the library and to record the paths discovered. The notable | |
| 13 | options 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 | ||
| 42 | The 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 | ||
| 58 | Calling sequence | |
| 59 | ---------------- | |
| 60 | ||
| c28b3d6e NTND |
61 | Note: index may be looked at for .gitignore files that are CE_SKIP_WORKTREE |
| 62 | marked. If you to exclude files, make sure you have loaded index first. | |
| 63 | ||
| 530e741c JH |
64 | * Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0, |
| 65 | sizeof(dir))`. | |
| 66 | ||
| 67 | * Call `add_exclude()` to add single exclude pattern, | |
| 68 | `add_excludes_from_file()` to add patterns from a file | |
| 69 | (e.g. `.git/info/exclude`), and/or set `dir.exclude_per_dir`. A | |
| 70 | short-hand function `setup_standard_excludes()` can be used to set up | |
| 71 | the standard set of exclude settings. | |
| 72 | ||
| 73 | * Set options described in the Data Structure section above. | |
| 74 | ||
| 75 | * Call `read_directory()`. | |
| 76 | ||
| 77 | * Use `dir.entries[]`. | |
| 78 | ||
| 79 | (JC) |