path: root/Documentation/technical/api-directory-listing.txt
diff options
authorJunio C Hamano <>2007-11-25 07:48:04 (GMT)
committerJunio C Hamano <>2007-12-15 06:29:38 (GMT)
commit530e741c726a612d78de21957d531dd2215483b4 (patch)
tree52cc876e8da8eb90edfabb1f85159d065a78bc91 /Documentation/technical/api-directory-listing.txt
parentfa4701601a62664a9246a211c5d26f238820737e (diff)
Start preparing the API documents.
Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/technical/api-directory-listing.txt')
1 files changed, 76 insertions, 0 deletions
diff --git a/Documentation/technical/api-directory-listing.txt b/Documentation/technical/api-directory-listing.txt
new file mode 100644
index 0000000..5bbd18f
--- /dev/null
+++ b/Documentation/technical/api-directory-listing.txt
@@ -0,0 +1,76 @@
+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. The notable
+options are:
+ The name of the file to be read in each directory for excluded
+ files (typically `.gitignore`).
+ Include paths that are to be excluded in the result.
+ The traversal is for finding just ignored files, not unignored
+ files.
+ Include a directory that is not tracked.
+ Do not include a directory that is not tracked and is empty.
+ 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::
+ An array of `struct dir_entry`, each element of which describes
+ a path.
+ The number of members in `entries[]` array.
+ Internal use; keeps track of allocation of `entries[]` array.
+Calling sequence
+* Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0,
+ sizeof(dir))`.
+* Call `add_exclude()` to add single exclude pattern,
+ `add_excludes_from_file()` to add patterns from a file
+ (e.g. `.git/info/exclude`), 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[]`.