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 | |
| 95a68344 AS |
12 | options to the library and to record the paths discovered. A single |
| 13 | `struct dir_struct` is used regardless of whether or not the traversal | |
| 14 | recursively descends into subdirectories. | |
| 15 | ||
| 16 | The notable options are: | |
| 530e741c JH |
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 | ||
| f1a7082f | 23 | `flags`:: |
| 530e741c | 24 | |
| f1a7082f | 25 | A bit-field of options: |
| 530e741c | 26 | |
| f1a7082f | 27 | `DIR_SHOW_IGNORED`::: |
| 530e741c JH |
28 | |
| 29 | The traversal is for finding just ignored files, not unignored | |
| 30 | files. | |
| 31 | ||
| f1a7082f | 32 | `DIR_SHOW_OTHER_DIRECTORIES`::: |
| 530e741c JH |
33 | |
| 34 | Include a directory that is not tracked. | |
| 35 | ||
| f1a7082f | 36 | `DIR_HIDE_EMPTY_DIRECTORIES`::: |
| 530e741c JH |
37 | |
| 38 | Do not include a directory that is not tracked and is empty. | |
| 39 | ||
| f1a7082f | 40 | `DIR_NO_GITLINKS`::: |
| 530e741c JH |
41 | |
| 42 | If set, recurse into a directory that looks like a git | |
| 43 | directory. Otherwise it is shown as a directory. | |
| 44 | ||
| 95a68344 | 45 | The result of the enumeration is left in these fields: |
| 530e741c JH |
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 | ||
| 61 | Calling sequence | |
| 62 | ---------------- | |
| 63 | ||
| c28b3d6e NTND |
64 | Note: index may be looked at for .gitignore files that are CE_SKIP_WORKTREE |
| 65 | marked. If you to exclude files, make sure you have loaded index first. | |
| 66 | ||
| 530e741c JH |
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) |