Improve documentation and comments regarding directory traversal API
traversal API has a few potentially confusing properties. These comments clarify a few key aspects and will hopefully make it easier to understand for other newcomers in the future. Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Adam Spiers committed
Dec 27, 2012 at 02:32 UTC
95a68344afcaf229765921c70458ee76add342dc
3 files changed
+37
-6
Documentation/technical/api-directory-listing.txt
+6
-3
@@ -9,8 +9,11 @@ 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. The notable
13
-options are:
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
@@ -39,7 +42,7 @@ options are:
42
If set, recurse into a directory that looks like a git
43
directory. Otherwise it is shown as a directory.
44
42
-The result of the enumeration is left in these fields::
45
+The result of the enumeration is left in these fields:
46
47
`entries[]`::
48
dir.c
+7
-1
@@ -2,6 +2,8 @@
2
* This handles recursive filename detection with exclude
3
* files, index knowledge etc..
4
*
5
+ * See Documentation/technical/api-directory-listing.txt
6
+ *
7
* Copyright (C) Linus Torvalds, 2005-2006
8
* Junio Hamano, 2005-2006
9
*/
@@ -476,6 +478,10 @@ void add_excludes_from_file(struct dir_struct *dir, const char *fname)
478
die("cannot use %s as an exclude file", fname);
479
}
480
481
+/*
482
+ * Loads the per-directory exclude list for the substring of base
483
+ * which has a char length of baselen.
484
+ */
485
static void prep_exclude(struct dir_struct *dir, const char *base, int baselen)
486
{
487
struct exclude_list *el;
@@ -486,7 +492,7 @@ static void prep_exclude(struct dir_struct *dir, const char *base, int baselen)
492
(baselen + strlen(dir->exclude_per_dir) >= PATH_MAX))
493
return; /* too long a path -- ignore */
494
489
- /* Pop the ones that are not the prefix of the path being checked. */
495
+ /* Pop the directories that are not the prefix of the path being checked. */
496
el = &dir->exclude_list[EXC_DIRS];
497
while ((stk = dir->exclude_stack) != NULL) {
498
if (stk->baselen <= baselen &&
dir.h
+24
-2
@@ -1,6 +1,8 @@
1
#ifndef DIR_H
2
#define DIR_H
3
4
+/* See Documentation/technical/api-directory-listing.txt */
5
+
6
#include "strbuf.h"
7
8
struct dir_entry {
@@ -13,6 +15,12 @@ struct dir_entry {
15
#define EXC_FLAG_MUSTBEDIR 8
16
#define EXC_FLAG_NEGATIVE 16
17
18
+/*
19
+ * Each .gitignore file will be parsed into patterns which are then
20
+ * appended to the relevant exclude_list (either EXC_DIRS or
21
+ * EXC_FILE). exclude_lists are also used to represent the list of
22
+ * --exclude values passed via CLI args (EXC_CMDL).
23
+ */
24
struct exclude_list {
25
int nr;
26
int alloc;
@@ -26,9 +34,15 @@ struct exclude_list {
34
} **excludes;
35
};
36
37
+/*
38
+ * The contents of the per-directory exclude files are lazily read on
39
+ * demand and then cached in memory, one per exclude_stack struct, in
40
+ * order to avoid opening and parsing each one every time that
41
+ * directory is traversed.
42
+ */
43
struct exclude_stack {
30
- struct exclude_stack *prev;
31
- char *filebuf;
44
+ struct exclude_stack *prev; /* the struct exclude_stack for the parent directory */
45
+ char *filebuf; /* remember pointer to per-directory exclude file contents so we can free() */
46
int baselen;
47
int exclude_ix;
48
};
@@ -59,6 +73,14 @@ struct dir_struct {
73
#define EXC_DIRS 1
74
#define EXC_FILE 2
75
76
+ /*
77
+ * Temporary variables which are used during loading of the
78
+ * per-directory exclude lists.
79
+ *
80
+ * exclude_stack points to the top of the exclude_stack, and
81
+ * basebuf contains the full path to the current
82
+ * (sub)directory in the traversal.
83
+ */
84
struct exclude_stack *exclude_stack;
85
char basebuf[PATH_MAX];
86
};