| 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. 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:
|
|---|
| 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 (the `*IGNORED*` flags are mutually exclusive):
|
|---|
| 26 |
|
|---|
| 27 | `DIR_SHOW_IGNORED`:::
|
|---|
| 28 |
|
|---|
| 29 | Return just ignored files in `entries[]`, not untracked files.
|
|---|
| 30 |
|
|---|
| 31 | `DIR_SHOW_IGNORED_TOO`:::
|
|---|
| 32 |
|
|---|
| 33 | Similar to `DIR_SHOW_IGNORED`, but return ignored files in `ignored[]`
|
|---|
| 34 | in addition to untracked files in `entries[]`.
|
|---|
| 35 |
|
|---|
| 36 | `DIR_COLLECT_IGNORED`:::
|
|---|
| 37 |
|
|---|
| 38 | Special mode for git-add. Return ignored files in `ignored[]` and
|
|---|
| 39 | untracked files in `entries[]`. Only returns ignored files that match
|
|---|
| 40 | pathspec exactly (no wildcards). Does not recurse into ignored
|
|---|
| 41 | directories.
|
|---|
| 42 |
|
|---|
| 43 | `DIR_SHOW_OTHER_DIRECTORIES`:::
|
|---|
| 44 |
|
|---|
| 45 | Include a directory that is not tracked.
|
|---|
| 46 |
|
|---|
| 47 | `DIR_HIDE_EMPTY_DIRECTORIES`:::
|
|---|
| 48 |
|
|---|
| 49 | Do not include a directory that is not tracked and is empty.
|
|---|
| 50 |
|
|---|
| 51 | `DIR_NO_GITLINKS`:::
|
|---|
| 52 |
|
|---|
| 53 | If set, recurse into a directory that looks like a Git
|
|---|
| 54 | directory. Otherwise it is shown as a directory.
|
|---|
| 55 |
|
|---|
| 56 | The result of the enumeration is left in these fields:
|
|---|
| 57 |
|
|---|
| 58 | `entries[]`::
|
|---|
| 59 |
|
|---|
| 60 | An array of `struct dir_entry`, each element of which describes
|
|---|
| 61 | a path.
|
|---|
| 62 |
|
|---|
| 63 | `nr`::
|
|---|
| 64 |
|
|---|
| 65 | The number of members in `entries[]` array.
|
|---|
| 66 |
|
|---|
| 67 | `alloc`::
|
|---|
| 68 |
|
|---|
| 69 | Internal use; keeps track of allocation of `entries[]` array.
|
|---|
| 70 |
|
|---|
| 71 | `ignored[]`::
|
|---|
| 72 |
|
|---|
| 73 | An array of `struct dir_entry`, used for ignored paths with the
|
|---|
| 74 | `DIR_SHOW_IGNORED_TOO` and `DIR_COLLECT_IGNORED` flags.
|
|---|
| 75 |
|
|---|
| 76 | `ignored_nr`::
|
|---|
| 77 |
|
|---|
| 78 | The number of members in `ignored[]` array.
|
|---|
| 79 |
|
|---|
| 80 | Calling sequence
|
|---|
| 81 | ----------------
|
|---|
| 82 |
|
|---|
| 83 | Note: index may be looked at for .gitignore files that are CE_SKIP_WORKTREE
|
|---|
| 84 | marked. If you to exclude files, make sure you have loaded index first.
|
|---|
| 85 |
|
|---|
| 86 | * Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0,
|
|---|
| 87 | sizeof(dir))`.
|
|---|
| 88 |
|
|---|
| 89 | * To add single exclude pattern, call `add_exclude_list()` and then
|
|---|
| 90 | `add_exclude()`.
|
|---|
| 91 |
|
|---|
| 92 | * To add patterns from a file (e.g. `.git/info/exclude`), call
|
|---|
| 93 | `add_excludes_from_file()` , and/or set `dir.exclude_per_dir`. A
|
|---|
| 94 | short-hand function `setup_standard_excludes()` can be used to set
|
|---|
| 95 | up the standard set of exclude settings.
|
|---|
| 96 |
|
|---|
| 97 | * Set options described in the Data Structure section above.
|
|---|
| 98 |
|
|---|
| 99 | * Call `read_directory()`.
|
|---|
| 100 |
|
|---|
| 101 | * Use `dir.entries[]`.
|
|---|
| 102 |
|
|---|
| 103 | * Call `clear_directory()` when none of the contained elements are no longer in use.
|
|---|
| 104 |
|
|---|
| 105 | (JC)
|
|---|
