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:

DIR_SHOW_IGNORED

Return just ignored files in entries[], not untracked files. This flag is mutually exclusive with DIR_SHOW_IGNORED_TOO.

DIR_SHOW_IGNORED_TOO

Similar to DIR_SHOW_IGNORED, but return ignored files in ignored[] in addition to untracked files in entries[]. This flag is mutually exclusive with DIR_SHOW_IGNORED.

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_SHOW_IGNORED_TOO_MODE_MATCHING

Only has meaning if DIR_SHOW_IGNORED_TOO is also set; if this is set, returns ignored files and directories that match an exclude pattern. If a directory matches an exclude pattern, then the directory is returned and the contained paths are not. A directory that does not match an exclude pattern will not be returned even if all of its contents are ignored. In this case, the contents are returned as individual entries.

If this is set, files and directories that explicity match an ignore pattern are reported. Implicity ignored directories (directories that do not match an ignore pattern, but whose contents are all ignored) are not reported, instead all of the contents are reported.

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)