# directory listing API

The directory listing API is used to enumerate paths in the work tree, optionally taking `.git/info/exclude` and `.gitignore` files per directory into account.

## Data structure

`struct dir_struct` structure is used to pass directory traversal options to the library and to record the paths discovered. A single `struct dir_struct` is used regardless of whether or not the traversal recursively descends into subdirectories.

The notable options are:

`exclude_per_dir`

  The name of the file to be read in each directory for excluded files (typically `.gitignore`).

`flags`

  A bit-field of options (the `*IGNORED*` flags are mutually exclusive):

  `DIR_SHOW_IGNORED`

    Return just ignored files in `entries[]`, not untracked files.

  `DIR_SHOW_IGNORED_TOO`

    Similar to `DIR_SHOW_IGNORED`, but return ignored files in `ignored[]` in addition to untracked files in `entries[]`.

  `DIR_SHOW_IGNORED_DIRECTORY`

    (EXPERIMENTAL) If this is set, non-empty directories that match an ignore pattern are returned. The individual files contained in ignored directories are not included.

  `DIR_KEEP_UNTRACKED_CONTENTS`

    Only has meaning if `DIR_SHOW_IGNORED_TOO` is also set; if this is set, the untracked contents of untracked directories are also returned in `entries[]`.

  `DIR_COLLECT_IGNORED`

    Special mode for git-add. Return ignored files in `ignored[]` and untracked files in `entries[]`. Only returns ignored files that match pathspec exactly (no wildcards). Does not recurse into ignored directories.

  `DIR_SHOW_OTHER_DIRECTORIES`

    Include a directory that is not tracked.

  `DIR_HIDE_EMPTY_DIRECTORIES`

    Do not include a directory that is not tracked and is empty.

  `DIR_NO_GITLINKS`

    If set, recurse into a directory that looks like a Git directory. Otherwise it is shown as a directory.

The result of the enumeration is left in these fields:

`entries[]`

  An array of `struct dir_entry`, each element of which describes a path.

`nr`

  The number of members in `entries[]` array.

`alloc`

  Internal use; keeps track of allocation of `entries[]` array.

`ignored[]`

  An array of `struct dir_entry`, used for ignored paths with the `DIR_SHOW_IGNORED_TOO` and `DIR_COLLECT_IGNORED` flags.

`ignored_nr`

  The number of members in `ignored[]` array.

## Calling sequence

Note: index may be looked at for .gitignore files that are CE_SKIP_WORKTREE marked. If you to exclude files, make sure you have loaded index first.

- Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0, sizeof(dir))`.

- To add single exclude pattern, call `add_exclude_list()` and then `add_exclude()`.

- To add patterns from a file (e.g. `.git/info/exclude`), call `add_excludes_from_file()` , and/or set `dir.exclude_per_dir`. A short-hand function `setup_standard_excludes()` can be used to set up the standard set of exclude settings.

- Set options described in the Data Structure section above.

- Call `read_directory()`.

- Use `dir.entries[]`.

- Call `clear_directory()` when none of the contained elements are no longer in use.

(JC)