undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve documentation and comments regarding directory traversal API

Browse Source 
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>
This commit is contained in:
Adam Spiers 2012-12-27 02:32:21 +00:00 committed by Junio C Hamano
parent f1a7082f2a
commit 95a68344af
3 changed files with 37 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
Documentation/technical/api-directory-listing.txt
View File

@ -9,8 +9,11 @@ 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:
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`::
@ -39,7 +42,7 @@ options are:
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::
The result of the enumeration is left in these fields:
`entries[]`::

8
dir.c
View File

@ -2,6 +2,8 @@
* This handles recursive filename detection with exclude
* files, index knowledge etc..
*
* See Documentation/technical/api-directory-listing.txt
*
* Copyright (C) Linus Torvalds, 2005-2006
* Junio Hamano, 2005-2006
*/
@ -476,6 +478,10 @@ void add_excludes_from_file(struct dir_struct *dir, const char *fname)
die("cannot use %s as an exclude file", fname);
}
/*
* Loads the per-directory exclude list for the substring of base
* which has a char length of baselen.
*/
static void prep_exclude(struct dir_struct *dir, const char *base, int baselen)
{
struct exclude_list *el;
@ -486,7 +492,7 @@ static void prep_exclude(struct dir_struct *dir, const char *base, int baselen)
(baselen + strlen(dir->exclude_per_dir) >= PATH_MAX))
return; /* too long a path -- ignore */
/* Pop the ones that are not the prefix of the path being checked. */
/* Pop the directories that are not the prefix of the path being checked. */
el = &dir->exclude_list[EXC_DIRS];
while ((stk = dir->exclude_stack) != NULL) {
if (stk->baselen <= baselen &&

26
dir.h
View File

@ -1,6 +1,8 @@
#ifndef DIR_H
#define DIR_H
/* See Documentation/technical/api-directory-listing.txt */
#include "strbuf.h"
struct dir_entry {
@ -13,6 +15,12 @@ struct dir_entry {
#define EXC_FLAG_MUSTBEDIR 8
#define EXC_FLAG_NEGATIVE 16
/*
* Each .gitignore file will be parsed into patterns which are then
* appended to the relevant exclude_list (either EXC_DIRS or
* EXC_FILE). exclude_lists are also used to represent the list of
* --exclude values passed via CLI args (EXC_CMDL).
*/
struct exclude_list {
int nr;
int alloc;
@ -26,9 +34,15 @@ struct exclude_list {
} **excludes;
};
/*
* The contents of the per-directory exclude files are lazily read on
* demand and then cached in memory, one per exclude_stack struct, in
* order to avoid opening and parsing each one every time that
* directory is traversed.
*/
struct exclude_stack {
struct exclude_stack *prev;
char *filebuf;
struct exclude_stack *prev; /* the struct exclude_stack for the parent directory */
char *filebuf; /* remember pointer to per-directory exclude file contents so we can free() */
int baselen;
int exclude_ix;
};
@ -59,6 +73,14 @@ struct dir_struct {
#define EXC_DIRS 1
#define EXC_FILE 2
/*
* Temporary variables which are used during loading of the
* per-directory exclude lists.
*
* exclude_stack points to the top of the exclude_stack, and
* basebuf contains the full path to the current
* (sub)directory in the traversal.
*/
struct exclude_stack *exclude_stack;
char basebuf[PATH_MAX];
};