From 95a68344afcaf229765921c70458ee76add342dc Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Thu, 27 Dec 2012 02:32:21 +0000 Subject: 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 Signed-off-by: Junio C Hamano --- dir.h | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) (limited to 'dir.h') diff --git a/dir.h b/dir.h index f5c89e3b8..e0869bca2 100644 --- a/dir.h +++ b/dir.h @@ -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]; }; -- cgit v1.2.1 From 840fc334e98e89e28039f85c3eff0caab5f20eb3 Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Thu, 27 Dec 2012 02:32:22 +0000 Subject: dir.c: rename cryptic 'which' variable to more consistent name 'el' is only *slightly* less cryptic, but is already used as the variable name for a struct exclude_list pointer in numerous other places, so this reduces the number of cryptic variable names in use by one :-) Signed-off-by: Adam Spiers Signed-off-by: Junio C Hamano --- dir.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'dir.h') diff --git a/dir.h b/dir.h index e0869bca2..680c1eb6e 100644 --- a/dir.h +++ b/dir.h @@ -127,11 +127,11 @@ extern int path_excluded(struct path_exclude_check *, const char *, int namelen, extern int add_excludes_from_file_to_list(const char *fname, const char *base, int baselen, - char **buf_p, struct exclude_list *which, int check_index); + char **buf_p, struct exclude_list *el, int check_index); extern void add_excludes_from_file(struct dir_struct *, const char *fname); extern void parse_exclude_pattern(const char **string, int *patternlen, int *flags, int *nowildcardlen); extern void add_exclude(const char *string, const char *base, - int baselen, struct exclude_list *which); + int baselen, struct exclude_list *el); extern void free_excludes(struct exclude_list *el); extern int file_exists(const char *); -- cgit v1.2.1 From 9013089c4a841bf17bcc8e2510a86ceecac29ffd Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Thu, 27 Dec 2012 02:32:23 +0000 Subject: dir.c: rename path_excluded() to is_path_excluded() Start adopting clearer names for exclude functions. This 'is_*' naming pattern for functions returning booleans was agreed here: http://thread.gmane.org/gmane.comp.version-control.git/204661/focus=204924 Signed-off-by: Adam Spiers Signed-off-by: Junio C Hamano --- dir.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'dir.h') diff --git a/dir.h b/dir.h index 680c1eb6e..c59bad885 100644 --- a/dir.h +++ b/dir.h @@ -123,7 +123,7 @@ struct path_exclude_check { }; extern void path_exclude_check_init(struct path_exclude_check *, struct dir_struct *); extern void path_exclude_check_clear(struct path_exclude_check *); -extern int path_excluded(struct path_exclude_check *, const char *, int namelen, int *dtype); +extern int is_path_excluded(struct path_exclude_check *, const char *, int namelen, int *dtype); extern int add_excludes_from_file_to_list(const char *fname, const char *base, int baselen, -- cgit v1.2.1 From 0795805053ad89a24954684fca2e69fea2bf50b9 Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Thu, 27 Dec 2012 02:32:24 +0000 Subject: dir.c: rename excluded_from_list() to is_excluded_from_list() Continue adopting clearer names for exclude functions. This 'is_*' naming pattern for functions returning booleans was discussed here: http://thread.gmane.org/gmane.comp.version-control.git/204661/focus=204924 Also adjust their callers as necessary. Signed-off-by: Adam Spiers Signed-off-by: Junio C Hamano --- dir.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'dir.h') diff --git a/dir.h b/dir.h index c59bad885..554f87a5f 100644 --- a/dir.h +++ b/dir.h @@ -98,8 +98,8 @@ extern int within_depth(const char *name, int namelen, int depth, int max_depth) extern int fill_directory(struct dir_struct *dir, const char **pathspec); extern int read_directory(struct dir_struct *, const char *path, int len, const char **pathspec); -extern int excluded_from_list(const char *pathname, int pathlen, const char *basename, - int *dtype, struct exclude_list *el); +extern int is_excluded_from_list(const char *pathname, int pathlen, const char *basename, + int *dtype, struct exclude_list *el); struct dir_entry *dir_add_ignored(struct dir_struct *dir, const char *pathname, int len); /* -- cgit v1.2.1 From 6d24e7a807922a5fbf1aa4d42f66e4f0a0aaa141 Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Thu, 27 Dec 2012 02:32:25 +0000 Subject: dir.c: rename excluded() to is_excluded() Continue adopting clearer names for exclude functions. This is_* naming pattern for functions returning booleans was discussed here: http://thread.gmane.org/gmane.comp.version-control.git/204661/focus=204924 Signed-off-by: Adam Spiers Signed-off-by: Junio C Hamano --- dir.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'dir.h') diff --git a/dir.h b/dir.h index 554f87a5f..d68a9971c 100644 --- a/dir.h +++ b/dir.h @@ -113,8 +113,8 @@ extern int match_pathname(const char *, int, const char *, int, int, int); /* - * The excluded() API is meant for callers that check each level of leading - * directory hierarchies with excluded() to avoid recursing into excluded + * The is_excluded() API is meant for callers that check each level of leading + * directory hierarchies with is_excluded() to avoid recursing into excluded * directories. Callers that do not do so should use this API instead. */ struct path_exclude_check { -- cgit v1.2.1 From a35341a86ecf354d46cf326ed9e0ffbceb54309d Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Thu, 27 Dec 2012 02:32:28 +0000 Subject: dir.c: refactor is_path_excluded() In a similar way to the previous commit, this extracts a new helper function last_exclude_matching_path() which return the last exclude_list element which matched, or NULL if no match was found. is_path_excluded() becomes a wrapper around this, and just returns 0 or 1 depending on whether any matching exclude_list element was found. This allows callers to find out _why_ a given path was excluded, rather than just whether it was or not, paving the way for a new git sub-command which allows users to test their exclude lists from the command line. Signed-off-by: Adam Spiers Signed-off-by: Junio C Hamano --- dir.h | 3 +++ 1 file changed, 3 insertions(+) (limited to 'dir.h') diff --git a/dir.h b/dir.h index d68a9971c..dcb1ad3d3 100644 --- a/dir.h +++ b/dir.h @@ -119,10 +119,13 @@ extern int match_pathname(const char *, int, */ struct path_exclude_check { struct dir_struct *dir; + struct exclude *exclude; struct strbuf path; }; extern void path_exclude_check_init(struct path_exclude_check *, struct dir_struct *); extern void path_exclude_check_clear(struct path_exclude_check *); +extern struct exclude *last_exclude_matching_path(struct path_exclude_check *, const char *, + int namelen, int *dtype); extern int is_path_excluded(struct path_exclude_check *, const char *, int namelen, int *dtype); -- cgit v1.2.1 From f61988125130ac091bfb69bda5d62b0ad8f054c4 Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Thu, 27 Dec 2012 02:32:29 +0000 Subject: dir.c: rename free_excludes() to clear_exclude_list() It is clearer to use a 'clear_' prefix for functions which empty and deallocate the contents of a data structure without freeing the structure itself, and a 'free_' prefix for functions which also free the structure itself. http://article.gmane.org/gmane.comp.version-control.git/206128 Signed-off-by: Adam Spiers Signed-off-by: Junio C Hamano --- dir.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'dir.h') diff --git a/dir.h b/dir.h index dcb1ad3d3..5664ba8c6 100644 --- a/dir.h +++ b/dir.h @@ -135,7 +135,7 @@ extern void add_excludes_from_file(struct dir_struct *, const char *fname); extern void parse_exclude_pattern(const char **string, int *patternlen, int *flags, int *nowildcardlen); extern void add_exclude(const char *string, const char *base, int baselen, struct exclude_list *el); -extern void free_excludes(struct exclude_list *el); +extern void clear_exclude_list(struct exclude_list *el); extern int file_exists(const char *); extern int is_inside_dir(const char *dir); -- cgit v1.2.1