Documentation/technical/api-directory-listing.txt

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