path: root/dir-iterator.h
diff options
authorMatheus Tavares <>2019-07-10 23:58:59 (GMT)
committerJunio C Hamano <>2019-07-11 20:52:15 (GMT)
commit3012397e0327f5e4dfd1d1183a792268429744ae (patch)
tree79faf55ec5f3ce158864c809e309cc3fa5a0da17 /dir-iterator.h
parentc9bba372ed9ee0c5ea1a4037c3c723a6c31f5921 (diff)
dir-iterator: refactor state machine model
dir_iterator_advance() is a large function with two nested loops. Let's improve its readability factoring out three functions and simplifying its mechanics. The refactored model will no longer depend on level.initialized and level.dir_state to keep track of the iteration state and will perform on a single loop. Also, dir_iterator_begin() currently does not check if the given string represents a valid directory path. Since the refactored model will have to stat() the given path at initialization, let's also check for this kind of error and make dir_iterator_begin() return NULL, on failures, with errno appropriately set. And add tests for this new behavior. Improve documentation at dir-iteration.h and code comments at dir-iterator.c to reflect the changes and eliminate possible ambiguities. Finally, adjust refs/files-backend.c to check for now possible dir_iterator_begin() failures. Original-patch-by: Daniel Ferreira <> Signed-off-by: Matheus Tavares <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'dir-iterator.h')
1 files changed, 11 insertions, 6 deletions
diff --git a/dir-iterator.h b/dir-iterator.h
index 970793d..9b4cb7a 100644
--- a/dir-iterator.h
+++ b/dir-iterator.h
@@ -8,18 +8,22 @@
* Iterate over a directory tree, recursively, including paths of all
* types and hidden paths. Skip "." and ".." entries and don't follow
- * symlinks except for the original path.
+ * symlinks except for the original path. Note that the original path
+ * is not included in the iteration.
* Every time dir_iterator_advance() is called, update the members of
* the dir_iterator structure to reflect the next path in the
* iteration. The order that paths are iterated over within a
- * directory is undefined, but directory paths are always iterated
- * over before the subdirectory contents.
+ * directory is undefined, directory paths are always given before
+ * their contents.
* A typical iteration looks like this:
* int ok;
- * struct iterator *iter = dir_iterator_begin(path);
+ * struct dir_iterator *iter = dir_iterator_begin(path);
+ *
+ * if (!iter)
+ * goto error_handler;
* while ((ok = dir_iterator_advance(iter)) == ITER_OK) {
* if (want_to_stop_iteration()) {
@@ -59,8 +63,9 @@ struct dir_iterator {
- * Start a directory iteration over path. Return a dir_iterator that
- * holds the internal state of the iteration.
+ * Start a directory iteration over path. On success, return a
+ * dir_iterator that holds the internal state of the iteration.
+ * In case of failure, return NULL and set errno accordingly.
* The iteration includes all paths under path, not including path
* itself and not including "." or ".." entries.