Merge pull request #3402 from ethomson/faster_diff

Provide path matching in the iterators (for faster diffs)

19 files changed, 1442 insertions, 338 deletions

diff --git a/include/git2/diff.h b/include/git2/diff.h
index 0abbc7f06..a0f6db350 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -129,8 +129,12 @@ typedef enum {
 	 */
 	GIT_DIFF_INCLUDE_CASECHANGE = (1u << 11),
 
-	/** If the pathspec is set in the diff options, this flags means to
-	 *  apply it as an exact match instead of as an fnmatch pattern.
+	/** If the pathspec is set in the diff options, this flags indicates
+	 *  that the paths will be treated as literal paths instead of
+	 *  fnmatch patterns.  Each path in the list must either be a full
+	 *  path to a file or a directory.  (A trailing slash indicates that
+	 *  the path will _only_ match a directory).  If a directory is
+	 *  specified, all children will be included.
 	 */
 	GIT_DIFF_DISABLE_PATHSPEC_MATCH = (1u << 12),
 
diff --git a/src/checkout.c b/src/checkout.c
index 4b3acbcce..de48c9e01 100644
--- a/src/checkout.c
+++ b/src/checkout.c
@@ -2471,11 +2471,12 @@ int git_checkout_iterator(
 {
 	int error = 0;
 	git_iterator *baseline = NULL, *workdir = NULL;
+	git_iterator_options baseline_opts = GIT_ITERATOR_OPTIONS_INIT,
+		workdir_opts = GIT_ITERATOR_OPTIONS_INIT;
 	checkout_data data = {0};
 	git_diff_options diff_opts = GIT_DIFF_OPTIONS_INIT;
 	uint32_t *actions = NULL;
 	size_t *counts = NULL;
-	git_iterator_flag_t iterflags = 0;
 
 	/* initialize structures and options */
 	error = checkout_data_init(&data, target, opts);
@@ -2499,25 +2500,30 @@ int git_checkout_iterator(
 
 	/* set up iterators */
 
-	iterflags = git_iterator_ignore_case(target) ?
+	workdir_opts.flags = git_iterator_ignore_case(target) ?
 		GIT_ITERATOR_IGNORE_CASE : GIT_ITERATOR_DONT_IGNORE_CASE;
+	workdir_opts.flags |= GIT_ITERATOR_DONT_AUTOEXPAND;
+	workdir_opts.start = data.pfx;
+	workdir_opts.end = data.pfx;
 
 	if ((error = git_iterator_reset(target, data.pfx, data.pfx)) < 0 ||
 		(error = git_iterator_for_workdir_ext(
 			&workdir, data.repo, data.opts.target_directory, index, NULL,
-			iterflags | GIT_ITERATOR_DONT_AUTOEXPAND,
-			data.pfx, data.pfx)) < 0)
+			&workdir_opts)) < 0)
 		goto cleanup;
 
+	baseline_opts.flags = git_iterator_ignore_case(target) ?
+		GIT_ITERATOR_IGNORE_CASE : GIT_ITERATOR_DONT_IGNORE_CASE;
+	baseline_opts.start = data.pfx;
+	baseline_opts.end = data.pfx;
+
 	if (data.opts.baseline_index) {
 		if ((error = git_iterator_for_index(
-				&baseline, data.opts.baseline_index,
-				iterflags, data.pfx, data.pfx)) < 0)
+				&baseline, data.opts.baseline_index, &baseline_opts)) < 0)
 			goto cleanup;
 	} else {
 		if ((error = git_iterator_for_tree(
-				&baseline, data.opts.baseline,
-				iterflags, data.pfx, data.pfx)) < 0)
+				&baseline, data.opts.baseline, &baseline_opts)) < 0)
 			goto cleanup;
 	}
 
@@ -2625,7 +2631,7 @@ int git_checkout_index(
 		return error;
 	GIT_REFCOUNT_INC(index);
 
-	if (!(error = git_iterator_for_index(&index_i, index, 0, NULL, NULL)))
+	if (!(error = git_iterator_for_index(&index_i, index, NULL)))
 		error = git_checkout_iterator(index_i, index, opts);
 
 	if (owned)
@@ -2646,6 +2652,7 @@ int git_checkout_tree(
 	git_index *index;
 	git_tree *tree = NULL;
 	git_iterator *tree_i = NULL;
+	git_iterator_options iter_opts = GIT_ITERATOR_OPTIONS_INIT;
 
 	if (!treeish && !repo) {
 		giterr_set(GITERR_CHECKOUT,
@@ -2681,7 +2688,12 @@ int git_checkout_tree(
 	if ((error = git_repository_index(&index, repo)) < 0)
 		return error;
 
-	if (!(error = git_iterator_for_tree(&tree_i, tree, 0, NULL, NULL)))
+	if ((opts->checkout_strategy & GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH)) {
+		iter_opts.pathlist.count = opts->paths.count;
+		iter_opts.pathlist.strings = opts->paths.strings;
+	}
+
+	if (!(error = git_iterator_for_tree(&tree_i, tree, &iter_opts)))
 		error = git_checkout_iterator(tree_i, index, opts);
 
 	git_iterator_free(tree_i);
diff --git a/src/diff.c b/src/diff.c
index 44f627880..32c1d4aa5 100644
--- a/src/diff.c
+++ b/src/diff.c
@@ -74,6 +74,23 @@ static int diff_insert_delta(
 	return error;
 }
 
+static bool diff_pathspec_match(
+	const char **matched_pathspec, git_diff *diff, const char *path)
+{
+	/* The iterator has filtered out paths for us, so the fact that we're
+	 * seeing this patch means that it must match the given path list.
+	 */
+	if (DIFF_FLAG_IS_SET(diff, GIT_DIFF_DISABLE_PATHSPEC_MATCH)) {
+		*matched_pathspec = path;
+		return true;
+	}
+
+	return git_pathspec__match(
+		&diff->pathspec, path, false,
+		DIFF_FLAG_IS_SET(diff, GIT_DIFF_IGNORE_CASE),
+		matched_pathspec, NULL);
+}
+
 static int diff_delta__from_one(
 	git_diff *diff,
 	git_delta_t status,
@@ -110,11 +127,7 @@ static int diff_delta__from_one(
 		DIFF_FLAG_ISNT_SET(diff, GIT_DIFF_INCLUDE_UNREADABLE))
 		return 0;
 
-	if (!git_pathspec__match(
-			&diff->pathspec, entry->path,
-			DIFF_FLAG_IS_SET(diff, GIT_DIFF_DISABLE_PATHSPEC_MATCH),
-			DIFF_FLAG_IS_SET(diff, GIT_DIFF_IGNORE_CASE),
-			&matched_pathspec, NULL))
+	if (!diff_pathspec_match(&matched_pathspec, diff, entry->path))
 		return 0;
 
 	delta = diff_delta__alloc(diff, status, entry->path);
@@ -755,11 +768,7 @@ static int maybe_modified(
 	const char *matched_pathspec;
 	int error = 0;
 
-	if (!git_pathspec__match(
-			&diff->pathspec, oitem->path,
-			DIFF_FLAG_IS_SET(diff, GIT_DIFF_DISABLE_PATHSPEC_MATCH),
-			DIFF_FLAG_IS_SET(diff, GIT_DIFF_IGNORE_CASE),
-			&matched_pathspec, NULL))
+	if (!diff_pathspec_match(&matched_pathspec, diff, oitem->path))
 		return 0;
 
 	memset(&noid, 0, sizeof(noid));
@@ -1053,6 +1062,12 @@ static int handle_unmatched_new_item(
 					&info->nitem, &untracked_state, info->new_iter)) < 0)
 				return error;
 
+			/* if we found nothing that matched our pathlist filter, exclude */
+			if (untracked_state == GIT_ITERATOR_STATUS_FILTERED) {
+				git_vector_pop(&diff->deltas);
+				git__free(last);
+			}
+
 			/* if we found nothing or just ignored items, update the record */
 			if (untracked_state == GIT_ITERATOR_STATUS_IGNORED ||
 				untracked_state == GIT_ITERATOR_STATUS_EMPTY) {
@@ -1264,11 +1279,26 @@ cleanup:
 	return error;
 }
 
-#define DIFF_FROM_ITERATORS(MAKE_FIRST, MAKE_SECOND) do { \
+#define DIFF_FROM_ITERATORS(MAKE_FIRST, FLAGS_FIRST, MAKE_SECOND, FLAGS_SECOND) do { \
 	git_iterator *a = NULL, *b = NULL; \
-	char *pfx = opts ? git_pathspec_prefix(&opts->pathspec) : NULL; \
+	char *pfx = (opts && !(opts->flags & GIT_DIFF_DISABLE_PATHSPEC_MATCH)) ? \
+		git_pathspec_prefix(&opts->pathspec) : NULL; \
+	git_iterator_options a_opts = GIT_ITERATOR_OPTIONS_INIT, \
+		b_opts = GIT_ITERATOR_OPTIONS_INIT; \
+	a_opts.flags = FLAGS_FIRST; \
+	a_opts.start = pfx; \
+	a_opts.end = pfx; \
+	b_opts.flags = FLAGS_SECOND; \
+	b_opts.start = pfx; \
+	b_opts.end = pfx; \
 	GITERR_CHECK_VERSION(opts, GIT_DIFF_OPTIONS_VERSION, "git_diff_options"); \
-	if (!(error = MAKE_FIRST) && !(error = MAKE_SECOND)) \
+	if (opts && (opts->flags & GIT_DIFF_DISABLE_PATHSPEC_MATCH)) { \
+		a_opts.pathlist.strings = opts->pathspec.strings; \
+		a_opts.pathlist.count = opts->pathspec.count; \
+		b_opts.pathlist.strings = opts->pathspec.strings; \
+		b_opts.pathlist.count = opts->pathspec.count; \
+	} \
+	if (!error && !(error = MAKE_FIRST) && !(error = MAKE_SECOND)) \
 		error = git_diff__from_iterators(diff, repo, a, b, opts); \
 	git__free(pfx); git_iterator_free(a); git_iterator_free(b); \
 } while (0)
@@ -1280,8 +1310,8 @@ int git_diff_tree_to_tree(
 	git_tree *new_tree,
 	const git_diff_options *opts)
 {
-	int error = 0;
 	git_iterator_flag_t iflag = GIT_ITERATOR_DONT_IGNORE_CASE;
+	int error = 0;
 
 	assert(diff && repo);
 
@@ -1293,8 +1323,8 @@ int git_diff_tree_to_tree(
 		iflag = GIT_ITERATOR_IGNORE_CASE;
 
 	DIFF_FROM_ITERATORS(
-		git_iterator_for_tree(&a, old_tree, iflag, pfx, pfx),
-		git_iterator_for_tree(&b, new_tree, iflag, pfx, pfx)
+		git_iterator_for_tree(&a, old_tree, &a_opts), iflag,
+		git_iterator_for_tree(&b, new_tree, &b_opts), iflag
 	);
 
 	return error;
@@ -1318,10 +1348,10 @@ int git_diff_tree_to_index(
 	git_index *index,
 	const git_diff_options *opts)
 {
-	int error = 0;
-	bool index_ignore_case = false;
 	git_iterator_flag_t iflag = GIT_ITERATOR_DONT_IGNORE_CASE |
 		GIT_ITERATOR_INCLUDE_CONFLICTS;
+	bool index_ignore_case = false;
+	int error = 0;
 
 	assert(diff && repo);
 
@@ -1331,8 +1361,8 @@ int git_diff_tree_to_index(
 	index_ignore_case = index->ignore_case;
 
 	DIFF_FROM_ITERATORS(
-		git_iterator_for_tree(&a, old_tree, iflag, pfx, pfx),
-		git_iterator_for_index(&b, index, iflag, pfx, pfx)
+		git_iterator_for_tree(&a, old_tree, &a_opts), iflag,
+		git_iterator_for_index(&b, index, &b_opts), iflag
 	);
 
 	/* if index is in case-insensitive order, re-sort deltas to match */
@@ -1356,10 +1386,11 @@ int git_diff_index_to_workdir(
 		return error;
 
 	DIFF_FROM_ITERATORS(
-		git_iterator_for_index(
-			&a, index, GIT_ITERATOR_INCLUDE_CONFLICTS, pfx, pfx),
-		git_iterator_for_workdir(
-			&b, repo, index, NULL, GIT_ITERATOR_DONT_AUTOEXPAND, pfx, pfx)
+		git_iterator_for_index(&a, index, &a_opts),
+		GIT_ITERATOR_INCLUDE_CONFLICTS,
+
+		git_iterator_for_workdir(&b, repo, index, NULL, &b_opts),
+		GIT_ITERATOR_DONT_AUTOEXPAND
 	);
 
 	if (!error && DIFF_FLAG_IS_SET(*diff, GIT_DIFF_UPDATE_INDEX) && (*diff)->index_updated)
@@ -1383,9 +1414,8 @@ int git_diff_tree_to_workdir(
 		return error;
 
 	DIFF_FROM_ITERATORS(
-		git_iterator_for_tree(&a, old_tree, 0, pfx, pfx),
-		git_iterator_for_workdir(
-			&b, repo, index, old_tree, GIT_ITERATOR_DONT_AUTOEXPAND, pfx, pfx)
+		git_iterator_for_tree(&a, old_tree, &a_opts), 0,
+		git_iterator_for_workdir(&b, repo, index, old_tree, &b_opts), GIT_ITERATOR_DONT_AUTOEXPAND
 	);
 
 	return error;
@@ -1433,10 +1463,8 @@ int git_diff_index_to_index(
 	assert(diff && old_index && new_index);
 
 	DIFF_FROM_ITERATORS(
-		git_iterator_for_index(
-			&a, old_index, GIT_ITERATOR_DONT_IGNORE_CASE, pfx, pfx),
-		git_iterator_for_index(
-			&b, new_index, GIT_ITERATOR_DONT_IGNORE_CASE, pfx, pfx)
+		git_iterator_for_index(&a, old_index, &a_opts), GIT_ITERATOR_DONT_IGNORE_CASE,
+		git_iterator_for_index(&b, new_index, &b_opts), GIT_ITERATOR_DONT_IGNORE_CASE
 	);
 
 	/* if index is in case-insensitive order, re-sort deltas to match */
diff --git a/src/index.c b/src/index.c
index e424698bb..53120e49c 100644
--- a/src/index.c
+++ b/src/index.c
@@ -728,6 +728,7 @@ static int truncate_racily_clean(git_index *index)
 		if (!is_racy_timestamp(ts, entry))
 			continue;
 
+		/* TODO: use the (non-fnmatching) filelist iterator */
 		diff_opts.pathspec.count = 1;
 		diff_opts.pathspec.strings = (char **) &entry->path;
 
@@ -2658,6 +2659,7 @@ int git_index_read_index(
 		remove_entries = GIT_VECTOR_INIT;
 	git_iterator *index_iterator = NULL;
 	git_iterator *new_iterator = NULL;
+	git_iterator_options opts = GIT_ITERATOR_OPTIONS_INIT;
 	const git_index_entry *old_entry, *new_entry;
 	git_index_entry *entry;
 	size_t i;
@@ -2667,10 +2669,10 @@ int git_index_read_index(
 		(error = git_vector_init(&remove_entries, index->entries.length, NULL)) < 0)
 		goto done;
 
-	if ((error = git_iterator_for_index(&index_iterator,
-			index, GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL)) < 0 ||
-		(error = git_iterator_for_index(&new_iterator,
-			(git_index *)new_index, GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL)) < 0)
+	opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+
+	if ((error = git_iterator_for_index(&index_iterator, index, &opts)) < 0 ||
+		(error = git_iterator_for_index(&new_iterator, (git_index *)new_index, &opts)) < 0)
 		goto done;
 
 	if (((error = git_iterator_current(&old_entry, index_iterator)) < 0 && 
diff --git a/src/iterator.c b/src/iterator.c
index 900ffdcaa..e35c8dc85 100644
--- a/src/iterator.c
+++ b/src/iterator.c
@@ -31,14 +31,22 @@
 	(P)->base.cb      = &(P)->cb; \
 	ITERATOR_SET_CB(P,NAME_LC); \
 	(P)->base.repo    = (REPO); \
-	(P)->base.start   = start ? git__strdup(start) : NULL; \
-	(P)->base.end     = end ? git__strdup(end) : NULL; \
-	if ((start && !(P)->base.start) || (end && !(P)->base.end)) { \
+	(P)->base.start   = options && options->start ? \
+		git__strdup(options->start) : NULL; \
+	(P)->base.end     = options && options->end ? \
+		git__strdup(options->end) : NULL; \
+	if ((options && options->start && !(P)->base.start) || \
+		(options && options->end && !(P)->base.end)) { \
 		git__free(P); return -1; } \
+	(P)->base.strcomp = git__strcmp; \
+	(P)->base.strncomp = git__strncmp; \
 	(P)->base.prefixcomp = git__prefixcmp; \
-	(P)->base.flags = flags & ~ITERATOR_CASE_FLAGS; \
+	(P)->base.flags = options ? options->flags & ~ITERATOR_CASE_FLAGS : 0; \
 	if ((P)->base.flags & GIT_ITERATOR_DONT_AUTOEXPAND) \
 		(P)->base.flags |= GIT_ITERATOR_INCLUDE_TREES; \
+	if (options && options->pathlist.count && \
+		iterator_pathlist__init(&P->base, &options->pathlist) < 0) { \
+		git__free(P); return -1; } \
 	} while (0)
 
 #define iterator__flag(I,F) ((((git_iterator *)(I))->flags & GIT_ITERATOR_ ## F) != 0)
@@ -56,6 +64,139 @@
 	(iterator__end(I) && ((git_iterator *)(I))->prefixcomp((PATH),iterator__end(I)) > 0)
 
 
+typedef enum {
+	ITERATOR_PATHLIST_NONE = 0,
+	ITERATOR_PATHLIST_MATCH = 1,
+	ITERATOR_PATHLIST_MATCH_DIRECTORY = 2,
+	ITERATOR_PATHLIST_MATCH_CHILD = 3,
+} iterator_pathlist__match_t;
+
+static int iterator_pathlist__init(git_iterator *iter, git_strarray *pathspec)
+{
+	size_t i;
+
+	if (git_vector_init(&iter->pathlist, pathspec->count,
+			(git_vector_cmp)iter->strcomp) < 0)
+		return -1;
+
+	for (i = 0; i < pathspec->count; i++) {
+		if (!pathspec->strings[i])
+			continue;
+
+		if (git_vector_insert(&iter->pathlist, pathspec->strings[i]) < 0)
+			return -1;
+	}
+
+	git_vector_sort(&iter->pathlist);
+
+	return 0;
+}
+
+static iterator_pathlist__match_t iterator_pathlist__match(
+	git_iterator *iter, const char *path, size_t path_len)
+{
+	const char *p;
+	size_t idx;
+	int error;
+
+	error = git_vector_bsearch2(&idx, &iter->pathlist,
+		(git_vector_cmp)iter->strcomp, path);
+
+	if (error == 0)
+		return ITERATOR_PATHLIST_MATCH;
+
+	/* at this point, the path we're examining may be a directory (though we
+	 * don't know that yet, since we're avoiding a stat unless it's necessary)
+	 * so see if the pathlist contains a file beneath this directory.
+	 */
+	while ((p = git_vector_get(&iter->pathlist, idx)) != NULL) {
+		if (iter->prefixcomp(p, path) != 0)
+			break;
+
+		/* an exact match would have been matched by the bsearch above */
+		assert(p[path_len]);
+
+		/* is this a literal directory entry (eg `foo/`) or a file beneath */
+		if (p[path_len] == '/') {
+			return (p[path_len+1] == '\0') ?
+				ITERATOR_PATHLIST_MATCH_DIRECTORY :
+				ITERATOR_PATHLIST_MATCH_CHILD;
+		}
+
+		if (p[path_len] > '/')
+			break;
+
+		idx++;
+	}
+
+	return ITERATOR_PATHLIST_NONE;
+}
+
+static void iterator_pathlist_walk__reset(git_iterator *iter)
+{
+	iter->pathlist_walk_idx = 0;
+}
+
+/* walker for the index iterator that allows it to walk the sorted pathlist
+ * entries alongside the sorted index entries.  the `iter->pathlist_walk_idx`
+ * stores the starting position for subsequent calls, the position is advanced
+ * along with the index iterator, with a special case for handling directories
+ * in the pathlist that are specified without trailing '/'.  (eg, `foo`).
+ * we do not advance over these entries until we're certain that the index
+ * iterator will not ask us for a file beneath that directory (eg, `foo/bar`).
+ */
+static bool iterator_pathlist_walk__contains(git_iterator *iter, const char *path)
+{
+	size_t i;
+	char *p;
+	size_t p_len;
+	int cmp;
+
+	for (i = iter->pathlist_walk_idx; i < iter->pathlist.length; i++) {
+		p = iter->pathlist.contents[i];
+		p_len = strlen(p);
+
+		/* see if the pathlist entry is a prefix of this path */
+		cmp = iter->strncomp(p, path, p_len);
+
+		/* this pathlist entry sorts before the given path, try the next */
+		if (!p_len || cmp < 0)
+			iter->pathlist_walk_idx++;
+
+		/* this pathlist sorts after the given path, no match. */
+		else if (cmp > 0)
+			return false;
+
+		/* match!  an exact match (`foo` vs `foo`), the path is a child of an
+		 * explicit directory in the pathlist (`foo/` vs `foo/bar`) or the path
+		 * is a child of an entry in the pathlist (`foo` vs `foo/bar`)
+		 */
+		else if (path[p_len] == '\0' || p[p_len - 1] == '/' || path[p_len] == '/')
+			return true;
+
+		/* only advance the start index for future callers if we know that we
+		 * will not see a child of this path.  eg, a pathlist entry `foo` is
+		 * a prefix for `foo.txt` and `foo/bar`.  don't advance the start
+		 * pathlist index when we see `foo.txt` or we would miss a subsequent
+		 * inspection of `foo/bar`.  only advance when there are no more
+		 * potential children.
+		 */
+		else if (path[p_len] > '/')
+			iter->pathlist_walk_idx++;
+	}
+
+	return false;
+}
+
+static void iterator_pathlist__update_ignore_case(git_iterator *iter)
+{
+	git_vector_set_cmp(&iter->pathlist, (git_vector_cmp)iter->strcomp);
+	git_vector_sort(&iter->pathlist);
+
+	iter->pathlist_walk_idx = 0;
+}
+
+
 static int iterator__reset_range(
 	git_iterator *iter, const char *start, const char *end)
 {
@@ -82,7 +223,8 @@ static int iterator__update_ignore_case(
 	git_iterator *iter,
 	git_iterator_flag_t flags)
 {
-	int error = 0, ignore_case = -1;
+	bool ignore_case;
+	int error;
 
 	if ((flags & GIT_ITERATOR_IGNORE_CASE) != 0)
 		ignore_case = true;
@@ -91,19 +233,29 @@ static int iterator__update_ignore_case(
 	else {
 		git_index *index;
 
-		if (!(error = git_repository_index__weakptr(&index, iter->repo)))
-			ignore_case = (index->ignore_case != false);
+		if ((error = git_repository_index__weakptr(&index, iter->repo)) < 0)
+			return error;
+
+		ignore_case = (index->ignore_case == 1);
 	}
 
-	if (ignore_case > 0)
+	if (ignore_case) {
 		iter->flags = (iter->flags | GIT_ITERATOR_IGNORE_CASE);
-	else if (ignore_case == 0)
+
+		iter->strcomp = git__strcasecmp;
+		iter->strncomp = git__strncasecmp;
+		iter->prefixcomp = git__prefixcmp_icase;
+	} else {
 		iter->flags = (iter->flags & ~GIT_ITERATOR_IGNORE_CASE);
 
-	iter->prefixcomp = iterator__ignore_case(iter) ?
-		git__prefixcmp_icase : git__prefixcmp;
+		iter->strcomp = git__strcmp;
+		iter->strncomp = git__strncmp;
+		iter->prefixcomp = git__prefixcmp;
+	}
 
-	return error;
+	iterator_pathlist__update_ignore_case(iter);
+
+	return 0;
 }
 
 GIT_INLINE(void) iterator__clear_entry(const git_index_entry **entry)
@@ -149,9 +301,7 @@ typedef struct {
 
 int git_iterator_for_nothing(
 	git_iterator **iter,
-	git_iterator_flag_t flags,
-	const char *start,
-	const char *end)
+	git_iterator_options *options)
 {
 	empty_iterator *i = git__calloc(1, sizeof(empty_iterator));
 	GITERR_CHECK_ALLOC(i);
@@ -162,7 +312,7 @@ int git_iterator_for_nothing(
 
 	ITERATOR_BASE_INIT(i, empty, EMPTY, NULL);
 
-	if ((flags & GIT_ITERATOR_IGNORE_CASE) != 0)
+	if (options && (options->flags & GIT_ITERATOR_IGNORE_CASE) != 0)
 		i->base.flags |= GIT_ITERATOR_IGNORE_CASE;
 
 	*iter = (git_iterator *)i;
@@ -201,7 +351,6 @@ typedef struct {
 	int path_ambiguities;
 	bool path_has_filename;
 	bool entry_is_current;
-	int (*strncomp)(const char *a, const char *b, size_t sz);
 } tree_iterator;
 
 static char *tree_iterator__current_filename(
@@ -271,7 +420,7 @@ static int tree_iterator__search_cmp(const void *key, const void *val, void *p)
 	return git_path_cmp(
 		tf->start, tf->startlen, false,
 		te->filename, te->filename_len, te->attr == GIT_FILEMODE_TREE,
-		((tree_iterator *)p)->strncomp);
+		((git_iterator *)p)->strncomp);
 }
 
 static bool tree_iterator__move_to_next(
@@ -303,7 +452,7 @@ static int tree_iterator__set_next(tree_iterator *ti, tree_iterator_frame *tf)
 	for (; tf->next < tf->n_entries; tf->next++, last = te) {
 		te = tf->entries[tf->next]->te;
 
-		if (last && tree_iterator__te_cmp(last, te, ti->strncomp))
+		if (last && tree_iterator__te_cmp(last, te, ti->base.strncomp))
 			break;
 
 		/* try to load trees for items in [current,next) range */
@@ -468,7 +617,7 @@ static int tree_iterator__update_entry(tree_iterator *ti)
 	return 0;
 }
 
-static int tree_iterator__current(
+static int tree_iterator__current_internal(
 	const git_index_entry **entry, git_iterator *self)
 {
 	int error;
@@ -491,6 +640,39 @@ static int tree_iterator__current(
 	return 0;
 }
 
+static int tree_iterator__advance(
+	const git_index_entry **out, git_iterator *self);
+
+static int tree_iterator__current(
+	const git_index_entry **out, git_iterator *self)
+{
+	const git_index_entry *entry = NULL;
+	iterator_pathlist__match_t m;
+	int error;
+
+	do {
+		if ((error = tree_iterator__current_internal(&entry, self)) < 0)
+			return error;
+
+		if (self->pathlist.length) {
+			m = iterator_pathlist__match(
+				self, entry->path, strlen(entry->path));
+
+			if (m != ITERATOR_PATHLIST_MATCH) {
+				if ((error = tree_iterator__advance(&entry, self)) < 0)
+					return error;
+
+				entry = NULL;
+			}
+		}
+	} while (!entry);
+
+	if (out)
+		*out = entry;
+
+	return error;
+}
+
 static int tree_iterator__advance_into(
 	const git_index_entry **entry, git_iterator *self)
 {
@@ -607,15 +789,13 @@ static int tree_iterator__create_root_frame(tree_iterator *ti, git_tree *tree)
 int git_iterator_for_tree(
 	git_iterator **iter,
 	git_tree *tree,
-	git_iterator_flag_t flags,
-	const char *start,
-	const char *end)
+	git_iterator_options *options)
 {
 	int error;
 	tree_iterator *ti;
 
 	if (tree == NULL)
-		return git_iterator_for_nothing(iter, flags, start, end);
+		return git_iterator_for_nothing(iter, options);
 
 	if ((error = git_object_dup((git_object **)&tree, (git_object *)tree)) < 0)
 		return error;
@@ -625,9 +805,8 @@ int git_iterator_for_tree(
 
 	ITERATOR_BASE_INIT(ti, tree, TREE, git_tree_owner(tree));
 
-	if ((error = iterator__update_ignore_case((git_iterator *)ti, flags)) < 0)
+	if ((error = iterator__update_ignore_case((git_iterator *)ti, options ? options->flags : 0)) < 0)
 		goto fail;
-	ti->strncomp = iterator__ignore_case(ti) ? git__strncasecmp : git__strncmp;
 
 	if ((error = git_pool_init(&ti->pool, sizeof(tree_iterator_entry),0)) < 0 ||
 		(error = tree_iterator__create_root_frame(ti, tree)) < 0 ||
@@ -650,6 +829,8 @@ typedef struct {
 	git_vector entries;
 	git_vector_cmp entry_srch;
 	size_t current;
+	/* when limiting with a pathlist, this is the current index into it */
+	size_t pathlist_idx;
 	/* when not in autoexpand mode, use these to represent "tree" state */
 	git_buf partial;
 	size_t partial_pos;
@@ -669,15 +850,35 @@ static const git_index_entry *index_iterator__index_entry(index_iterator *ii)
 	return ie;
 }
 
-static const git_index_entry *index_iterator__advance_over_conflicts(index_iterator *ii)
+static const git_index_entry *index_iterator__advance_over_unwanted(
+	index_iterator *ii)
 {
 	const git_index_entry *ie = index_iterator__index_entry(ii);
+	bool match;
 
-	if (!iterator__include_conflicts(ii)) {
-		while (ie && git_index_entry_is_conflict(ie)) {
+	while (ie) {
+		if (!iterator__include_conflicts(ii) &&
+				git_index_entry_is_conflict(ie)) {
 			ii->current++;
 			ie = index_iterator__index_entry(ii);
+			continue;
 		}
+
+		/* if we have a pathlist, this entry's path must be in it to be
+		 * returned.  walk the pathlist in unison with the index to
+		 * compare paths.
+		 */
+		if (ii->base.pathlist.length) {
+			match = iterator_pathlist_walk__contains(&ii->base, ie->path);
+
+			if (!match) {
+				ii->current++;
+				ie = index_iterator__index_entry(ii);
+				continue;
+			}
+		}
+
+		break;
 	}
 
 	return ie;
@@ -706,7 +907,7 @@ static void index_iterator__next_prefix_tree(index_iterator *ii)
 
 static int index_iterator__first_prefix_tree(index_iterator *ii)
 {
-	const git_index_entry *ie = index_iterator__advance_over_conflicts(ii);
+	const git_index_entry *ie = index_iterator__advance_over_unwanted(ii);
 	const char *scan, *prior, *slash;
 
 	if (!ie || !iterator__include_trees(ii))
@@ -825,11 +1026,16 @@ static int index_iterator__reset(
 
 	ii->current = 0;
 
+	iterator_pathlist_walk__reset(self);
+
+	/* if we're given a start prefix, find it; if we're given a pathlist, find
+	 * the first of those.  start at the later of the two.
+	 */
 	if (ii->base.start)
 		git_index_snapshot_find(
 			&ii->current, &ii->entries, ii->entry_srch, ii->base.start, 0, 0);
 
-	if ((ie = index_iterator__advance_over_conflicts(ii)) == NULL)
+	if ((ie = index_iterator__advance_over_unwanted(ii)) == NULL)
 		return 0;
 
 	if (git_buf_sets(&ii->partial, ie->path) < 0)
@@ -860,9 +1066,7 @@ static void index_iterator__free(git_iterator *self)
 int git_iterator_for_index(
 	git_iterator **iter,
 	git_index  *index,
-	git_iterator_flag_t flags,
-	const char *start,
-	const char *end)
+	git_iterator_options *options)
 {
 	int error = 0;
 	index_iterator *ii = git__calloc(1, sizeof(index_iterator));
@@ -876,7 +1080,7 @@ int git_iterator_for_index(
 
 	ITERATOR_BASE_INIT(ii, index, INDEX, git_index_owner(index));
 
-	if ((error = iterator__update_ignore_case((git_iterator *)ii, flags)) < 0) {
+	if ((error = iterator__update_ignore_case((git_iterator *)ii, options ? options->flags : 0)) < 0) {
 		git_iterator_free((git_iterator *)ii);
 		return error;
 	}
@@ -916,6 +1120,7 @@ struct fs_iterator {
 	size_t root_len;
 	uint32_t dirload_flags;
 	int depth;
+	iterator_pathlist__match_t pathlist_match;
 
 	int (*enter_dir_cb)(fs_iterator *self);
 	int (*leave_dir_cb)(fs_iterator *self);
@@ -926,6 +1131,7 @@ struct fs_iterator {
 
 typedef struct {
 	struct stat st;
+	iterator_pathlist__match_t pathlist_match;
 	size_t      path_len;
 	char        path[GIT_FLEX_ARRAY];
 } fs_iterator_path_with_stat;
@@ -1007,28 +1213,20 @@ static void fs_iterator__seek_frame_start(
 		ff->index = 0;
 }
 
-static int dirload_with_stat(
-	const char *dirpath,
-	size_t prefix_len,
-	unsigned int flags,
-	const char *start_stat,
-	const char *end_stat,
-	git_vector *contents)
+static int dirload_with_stat(git_vector *contents, fs_iterator *fi)
 {
 	git_path_diriter diriter = GIT_PATH_DIRITER_INIT;
 	const char *path;
-	int (*strncomp)(const char *a, const char *b, size_t sz);
-	size_t start_len = start_stat ? strlen(start_stat) : 0;
-	size_t end_len = end_stat ? strlen(end_stat) : 0;
+	size_t start_len = fi->base.start ? strlen(fi->base.start) : 0;
+	size_t end_len = fi->base.end ? strlen(fi->base.end) : 0;
 	fs_iterator_path_with_stat *ps;
 	size_t path_len, cmp_len, ps_size;
+	iterator_pathlist__match_t pathlist_match = ITERATOR_PATHLIST_MATCH;
 	int error;
 
-	strncomp = (flags & GIT_PATH_DIR_IGNORE_CASE) != 0 ?
-		git__strncasecmp : git__strncmp;
-
 	/* Any error here is equivalent to the dir not existing, skip over it */
-	if ((error = git_path_diriter_init(&diriter, dirpath, flags)) < 0) {
+	if ((error = git_path_diriter_init(
+			&diriter, fi->path.ptr, fi->dirload_flags)) < 0) {
 		error = GIT_ENOTFOUND;
 		goto done;
 	}
@@ -1037,18 +1235,31 @@ static int dirload_with_stat(
 		if ((error = git_path_diriter_fullpath(&path, &path_len, &diriter)) < 0)
 			goto done;
 
-		assert(path_len > prefix_len);
+		assert(path_len > fi->root_len);
 
 		/* remove the prefix if requested */
-		path += prefix_len;
-		path_len -= prefix_len;
+		path += fi->root_len;
+		path_len -= fi->root_len;
 
 		/* skip if before start_stat or after end_stat */
 		cmp_len = min(start_len, path_len);
-		if (cmp_len && strncomp(path, start_stat, cmp_len) < 0)
+		if (cmp_len && fi->base.strncomp(path, fi->base.start, cmp_len) < 0)
 			continue;
+		/* skip if after end_stat */
 		cmp_len = min(end_len, path_len);
-		if (cmp_len && strncomp(path, end_stat, cmp_len) > 0)
+		if (cmp_len && fi->base.strncomp(path, fi->base.end, cmp_len) > 0)
+			continue;
+
+		/* if we have a pathlist that we're limiting to, examine this path.
+		 * if the frame has already deemed us inside the path (eg, we're in
+		 * `foo/bar` and the pathlist previously was detected to say `foo/`)
+		 * then simply continue.  otherwise, examine the pathlist looking for
+		 * this path or children of this path.
+		 */
+		if (fi->base.pathlist.length &&
+			fi->pathlist_match != ITERATOR_PATHLIST_MATCH &&
+			fi->pathlist_match != ITERATOR_PATHLIST_MATCH_DIRECTORY &&
+			!(pathlist_match = iterator_pathlist__match(&fi->base, path, path_len)))
 			continue;
 
 		/* Make sure to append two bytes, one for the path's null
@@ -1062,6 +1273,8 @@ static int dirload_with_stat(
 
 		memcpy(ps->path, path, path_len);
 
+		/* TODO: don't stat if assume unchanged for this path */
+
 		if ((error = git_path_diriter_stat(&ps->st, &diriter)) < 0) {
 			if (error == GIT_ENOTFOUND) {
 				/* file was removed between readdir and lstat */
@@ -1069,6 +1282,12 @@ static int dirload_with_stat(
 				continue;
 			}
 
+			if (pathlist_match == ITERATOR_PATHLIST_MATCH_DIRECTORY) {
+				/* were looking for a directory, but this is a file */
+				git__free(ps);
+				continue;
+			}
+
 			/* Treat the file as unreadable if we get any other error */
 			memset(&ps->st, 0, sizeof(ps->st));
 			ps->st.st_mode = GIT_FILEMODE_UNREADABLE;
@@ -1085,6 +1304,11 @@ static int dirload_with_stat(
 			continue;
 		}
 
+		/* record whether this path was explicitly found in the path list
+		 * or whether we're only examining it because something beneath it
+		 * is in the path list.
+		 */
+		ps->pathlist_match = pathlist_match;
 		git_vector_insert(contents, ps);
 	}
 
@@ -1114,9 +1338,7 @@ static int fs_iterator__expand_dir(fs_iterator *fi)
 	ff = fs_iterator__alloc_frame(fi);
 	GITERR_CHECK_ALLOC(ff);
 
-	error = dirload_with_stat(
-		fi->path.ptr, fi->root_len, fi->dirload_flags,
-		fi->base.start, fi->base.end, &ff->entries);
+	error = dirload_with_stat(&ff->entries, fi);
 
 	if (error < 0) {
 		git_error_state last_error = { 0 };
@@ -1311,6 +1533,7 @@ static int fs_iterator__update_entry(fs_iterator *fi)
 		return GIT_ITEROVER;
 
 	fi->entry.path = ps->path;
+	fi->pathlist_match = ps->pathlist_match;
 	git_index_entry__init_from_stat(&fi->entry, &ps->st, true);
 
 	/* need different mode here to keep directories during iteration */
@@ -1343,6 +1566,7 @@ static int fs_iterator__initialize(
 		return -1;
 	}
 	fi->root_len = fi->path.size;
+	fi->pathlist_match = ITERATOR_PATHLIST_MATCH_CHILD;
 
 	fi->dirload_flags =
 		(iterator__ignore_case(fi) ? GIT_PATH_DIR_IGNORE_CASE : 0) |
@@ -1366,16 +1590,14 @@ static int fs_iterator__initialize(
 int git_iterator_for_filesystem(
 	git_iterator **out,
 	const char *root,
-	git_iterator_flag_t flags,
-	const char *start,
-	const char *end)
+	git_iterator_options *options)
 {
 	fs_iterator *fi = git__calloc(1, sizeof(fs_iterator));
 	GITERR_CHECK_ALLOC(fi);
 
 	ITERATOR_BASE_INIT(fi, fs, FS, NULL);
 
-	if ((flags & GIT_ITERATOR_IGNORE_CASE) != 0)
+	if (options && (options->flags & GIT_ITERATOR_IGNORE_CASE) != 0)
 		fi->base.flags |= GIT_ITERATOR_IGNORE_CASE;
 
 	return fs_iterator__initialize(out, fi, root);
@@ -1559,9 +1781,7 @@ int git_iterator_for_workdir_ext(
 	const char *repo_workdir,
 	git_index *index,
 	git_tree *tree,
-	git_iterator_flag_t flags,
-	const char *start,
-	const char *end)
+	git_iterator_options *options)
 {
 	int error, precompose = 0;
 	workdir_iterator *wi;
@@ -1583,7 +1803,7 @@ int git_iterator_for_workdir_ext(
 	wi->fi.leave_dir_cb = workdir_iterator__leave_dir;
 	wi->fi.update_entry_cb = workdir_iterator__update_entry;
 
-	if ((error = iterator__update_ignore_case((git_iterator *)wi, flags)) < 0 ||
+	if ((error = iterator__update_ignore_case((git_iterator *)wi, options ? options->flags : 0)) < 0 ||
 		(error = git_ignore__for_path(repo, ".gitignore", &wi->ignores)) < 0)
 	{
 		git_iterator_free((git_iterator *)wi);
@@ -1618,6 +1838,7 @@ void git_iterator_free(git_iterator *iter)
 
 	iter->cb->free(iter);
 
+	git_vector_free(&iter->pathlist);
 	git__free(iter->start);
 	git__free(iter->end);
 
@@ -1687,7 +1908,7 @@ int git_iterator_current_parent_tree(
 		if (!(tf = tf->down) ||
 			tf->current >= tf->n_entries ||
 			!(te = tf->entries[tf->current]->te) ||
-			ti->strncomp(scan, te->filename, te->filename_len) != 0)
+			ti->base.strncomp(scan, te->filename, te->filename_len) != 0)
 			return 0;
 
 		scan += te->filename_len;
@@ -1820,9 +2041,18 @@ int git_iterator_advance_over_with_status(
 
 			if (!error)
 				continue;
+			
 			else if (error == GIT_ENOTFOUND) {
+				/* we entered this directory only hoping to find child matches to
+				 * our pathlist (eg, this is `foo` and we had a pathlist entry for
+				 * `foo/bar`).  it should not be ignored, it should be excluded.
+				 */
+				if (wi->fi.pathlist_match == ITERATOR_PATHLIST_MATCH_CHILD)
+					*status = GIT_ITERATOR_STATUS_FILTERED;
+				else
+					wi->is_ignored = GIT_IGNORE_TRUE; /* mark empty dirs ignored */
+
 				error = 0;
-				wi->is_ignored = GIT_IGNORE_TRUE; /* mark empty dirs ignored */
 			} else
 				break; /* real error, stop here */
 		} else {
diff --git a/src/iterator.h b/src/iterator.h
index 893e5db50..59f87e9de 100644
--- a/src/iterator.h
+++ b/src/iterator.h
@@ -39,6 +39,21 @@ typedef enum {
 } git_iterator_flag_t;
 
 typedef struct {
+	const char *start;
+	const char *end;
+
+	/* paths to include in the iterator (literal).  if set, any paths not
+	 * listed here will be excluded from iteration.
+	 */
+	git_strarray pathlist;
+
+	/* flags, from above */
+	unsigned int flags;
+} git_iterator_options;
+
+#define GIT_ITERATOR_OPTIONS_INIT {0}
+
+typedef struct {
 	int (*current)(const git_index_entry **, git_iterator *);
 	int (*advance)(const git_index_entry **, git_iterator *);
 	int (*advance_into)(const git_index_entry **, git_iterator *);
@@ -54,6 +69,10 @@ struct git_iterator {
 	git_repository *repo;
 	char *start;
 	char *end;
+	git_vector pathlist;
+	size_t pathlist_walk_idx;
+	int (*strcomp)(const char *a, const char *b);
+	int (*strncomp)(const char *a, const char *b, size_t n);
 	int (*prefixcomp)(const char *str, const char *prefix);
 	size_t stat_calls;
 	unsigned int flags;
@@ -61,9 +80,7 @@ struct git_iterator {
 
 extern int git_iterator_for_nothing(
 	git_iterator **out,
-	git_iterator_flag_t flags,
-	const char *start,
-	const char *end);
+	git_iterator_options *options);
 
 /* tree iterators will match the ignore_case value from the index of the
  * repository, unless you override with a non-zero flag value
@@ -71,9 +88,7 @@ extern int git_iterator_for_nothing(
 extern int git_iterator_for_tree(
 	git_iterator **out,
 	git_tree *tree,
-	git_iterator_flag_t flags,
-	const char *start,
-	const char *end);
+	git_iterator_options *options);
 
 /* index iterators will take the ignore_case value from the index; the
  * ignore_case flags are not used
@@ -81,9 +96,7 @@ extern int git_iterator_for_tree(
 extern int git_iterator_for_index(
 	git_iterator **out,
 	git_index *index,
-	git_iterator_flag_t flags,
-	const char *start,
-	const char *end);
+	git_iterator_options *options);
 
 extern int git_iterator_for_workdir_ext(
 	git_iterator **out,
@@ -91,9 +104,7 @@ extern int git_iterator_for_workdir_ext(
 	const char *repo_workdir,
 	git_index *index,
 	git_tree *tree,
-	git_iterator_flag_t flags,
-	const char *start,
-	const char *end);
+	git_iterator_options *options);
 
 /* workdir iterators will match the ignore_case value from the index of the
  * repository, unless you override with a non-zero flag value
@@ -103,11 +114,9 @@ GIT_INLINE(int) git_iterator_for_workdir(
 	git_repository *repo,
 	git_index *index,
 	git_tree *tree,
-	git_iterator_flag_t flags,
-	const char *start,
-	const char *end)
+	git_iterator_options *options)
 {
-	return git_iterator_for_workdir_ext(out, repo, NULL, index, tree, flags, start, end);
+	return git_iterator_for_workdir_ext(out, repo, NULL, index, tree, options);
 }
 
 /* for filesystem iterators, you have to explicitly pass in the ignore_case
@@ -116,9 +125,7 @@ GIT_INLINE(int) git_iterator_for_workdir(
 extern int git_iterator_for_filesystem(
 	git_iterator **out,
 	const char *root,
-	git_iterator_flag_t flags,
-	const char *start,
-	const char *end);
+	git_iterator_options *options);
 
 extern void git_iterator_free(git_iterator *iter);
 
@@ -271,7 +278,8 @@ extern git_index *git_iterator_get_index(git_iterator *iter);
 typedef enum {
 	GIT_ITERATOR_STATUS_NORMAL = 0,
 	GIT_ITERATOR_STATUS_IGNORED = 1,
-	GIT_ITERATOR_STATUS_EMPTY = 2
+	GIT_ITERATOR_STATUS_EMPTY = 2,
+	GIT_ITERATOR_STATUS_FILTERED = 3
 } git_iterator_status_t;
 
 /* Advance over a directory and check if it contains no files or just
diff --git a/src/merge.c b/src/merge.c
index 863ac8f2d..fc5088c82 100644
--- a/src/merge.c
+++ b/src/merge.c
@@ -1695,10 +1695,14 @@ on_error:
 
 static git_iterator *iterator_given_or_empty(git_iterator **empty, git_iterator *given)
 {
+	git_iterator_options opts = GIT_ITERATOR_OPTIONS_INIT;
+
 	if (given)
 		return given;
 
-	if (git_iterator_for_nothing(empty, GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL) < 0)
+	opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+
+	if (git_iterator_for_nothing(empty, &opts) < 0)
 		return NULL;
 
 	return *empty;
@@ -1780,14 +1784,17 @@ int git_merge_trees(
 	const git_merge_options *merge_opts)
 {
 	git_iterator *ancestor_iter = NULL, *our_iter = NULL, *their_iter = NULL;
+	git_iterator_options iter_opts = GIT_ITERATOR_OPTIONS_INIT;
 	int error;
 
-	if ((error = git_iterator_for_tree(&ancestor_iter, (git_tree *)ancestor_tree,
-			GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL)) < 0 ||
-		(error = git_iterator_for_tree(&our_iter, (git_tree *)our_tree,
-			GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL)) < 0 ||
-		(error = git_iterator_for_tree(&their_iter, (git_tree *)their_tree,
-			GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL)) < 0)
+	iter_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+
+	if ((error = git_iterator_for_tree(
+			&ancestor_iter, (git_tree *)ancestor_tree, &iter_opts)) < 0 ||
+		(error = git_iterator_for_tree(
+			&our_iter, (git_tree *)our_tree, &iter_opts)) < 0 ||
+		(error = git_iterator_for_tree(
+			&their_iter, (git_tree *)their_tree, &iter_opts)) < 0)
 		goto done;
 
 	error = git_merge__iterators(
@@ -2319,6 +2326,7 @@ static int merge_check_index(size_t *conflicts, git_repository *repo, git_index
 	git_tree *head_tree = NULL;
 	git_index *index_repo = NULL;
 	git_iterator *iter_repo = NULL, *iter_new = NULL;
+	git_iterator_options iter_opts = GIT_ITERATOR_OPTIONS_INIT;
 	git_diff *staged_diff_list = NULL, *index_diff_list = NULL;
 	git_diff_delta *delta;
 	git_diff_options opts = GIT_DIFF_OPTIONS_INIT;
@@ -2348,11 +2356,12 @@ static int merge_check_index(size_t *conflicts, git_repository *repo, git_index
 			goto done;
 	}
 
-	opts.pathspec.count = staged_paths.length;
-	opts.pathspec.strings = (char **)staged_paths.contents;
+	iter_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+	iter_opts.pathlist.strings = (char **)staged_paths.contents;
+	iter_opts.pathlist.count = staged_paths.length;
 
-	if ((error = git_iterator_for_index(&iter_repo, index_repo, GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL)) < 0 ||
-		(error = git_iterator_for_index(&iter_new, index_new, GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL)) < 0 ||
+	if ((error = git_iterator_for_index(&iter_repo, index_repo, &iter_opts)) < 0 ||
+		(error = git_iterator_for_index(&iter_new, index_new, &iter_opts)) < 0 ||
 		(error = git_diff__from_iterators(&index_diff_list, repo, iter_repo, iter_new, &opts)) < 0)
 		goto done;
 
@@ -2396,6 +2405,7 @@ static int merge_check_workdir(size_t *conflicts, git_repository *repo, git_inde
 	 * will be applied by the merge (including conflicts).  Ensure that there
 	 * are no changes in the workdir to these paths.
 	 */
+	opts.flags |= GIT_DIFF_DISABLE_PATHSPEC_MATCH;
 	opts.pathspec.count = merged_paths->length;
 	opts.pathspec.strings = (char **)merged_paths->contents;
 
@@ -2414,6 +2424,7 @@ int git_merge__check_result(git_repository *repo, git_index *index_new)
 {
 	git_tree *head_tree = NULL;
 	git_iterator *iter_head = NULL, *iter_new = NULL;
+	git_iterator_options iter_opts = GIT_ITERATOR_OPTIONS_INIT;
 	git_diff *merged_list = NULL;
 	git_diff_options opts = GIT_DIFF_OPTIONS_INIT;
 	git_diff_delta *delta;
@@ -2422,9 +2433,11 @@ int git_merge__check_result(git_repository *repo, git_index *index_new)
 	const git_index_entry *e;
 	int error = 0;
 
+	iter_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+
 	if ((error = git_repository_head_tree(&head_tree, repo)) < 0 ||
-		(error = git_iterator_for_tree(&iter_head, head_tree, GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL)) < 0 ||
-		(error = git_iterator_for_index(&iter_new, index_new, GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL)) < 0 ||
+		(error = git_iterator_for_tree(&iter_head, head_tree, &iter_opts)) < 0 ||
+		(error = git_iterator_for_index(&iter_new, index_new, &iter_opts)) < 0 ||
 		(error = git_diff__from_iterators(&merged_list, repo, iter_head, iter_new, &opts)) < 0)
 		goto done;
 
diff --git a/src/notes.c b/src/notes.c
index ef4b41b31..fe8d2164f 100644
--- a/src/notes.c
+++ b/src/notes.c
@@ -663,7 +663,7 @@ int git_note_iterator_new(
 	if (error < 0)
 		goto cleanup;
 
-	if ((error = git_iterator_for_tree(it, tree, 0, NULL, NULL)) < 0)
+	if ((error = git_iterator_for_tree(it, tree, NULL)) < 0)
 		git_iterator_free(*it);
 
 cleanup:
diff --git a/src/pathspec.c b/src/pathspec.c
index fab6f9a76..9304da705 100644
--- a/src/pathspec.c
+++ b/src/pathspec.c
@@ -524,16 +524,16 @@ int git_pathspec_match_workdir(
 	uint32_t flags,
 	git_pathspec *ps)
 {
-	int error = 0;
 	git_iterator *iter;
+	git_iterator_options iter_opts = GIT_ITERATOR_OPTIONS_INIT;
+	int error = 0;
 
 	assert(repo);
 
-	if (!(error = git_iterator_for_workdir(
-			&iter, repo, NULL, NULL, pathspec_match_iter_flags(flags), NULL, NULL))) {
+	iter_opts.flags = pathspec_match_iter_flags(flags);
 
+	if (!(error = git_iterator_for_workdir(&iter, repo, NULL, NULL, &iter_opts))) {
 		error = pathspec_match_from_iterator(out, iter, flags, ps);
-
 		git_iterator_free(iter);
 	}
 
@@ -546,16 +546,16 @@ int git_pathspec_match_index(
 	uint32_t flags,
 	git_pathspec *ps)
 {
-	int error = 0;
 	git_iterator *iter;
+	git_iterator_options iter_opts = GIT_ITERATOR_OPTIONS_INIT;
+	int error = 0;
 
 	assert(index);
 
-	if (!(error = git_iterator_for_index(
-			&iter, index, pathspec_match_iter_flags(flags), NULL, NULL))) {
+	iter_opts.flags = pathspec_match_iter_flags(flags);
 
+	if (!(error = git_iterator_for_index(&iter, index, &iter_opts))) {
 		error = pathspec_match_from_iterator(out, iter, flags, ps);
-
 		git_iterator_free(iter);
 	}
 
@@ -568,16 +568,16 @@ int git_pathspec_match_tree(
 	uint32_t flags,
 	git_pathspec *ps)
 {
-	int error = 0;
 	git_iterator *iter;
+	git_iterator_options iter_opts = GIT_ITERATOR_OPTIONS_INIT;
+	int error = 0;
 
 	assert(tree);
 
-	if (!(error = git_iterator_for_tree(
-			&iter, tree, pathspec_match_iter_flags(flags), NULL, NULL))) {
+	iter_opts.flags = pathspec_match_iter_flags(flags);
 
+	if (!(error = git_iterator_for_tree(&iter, tree, &iter_opts))) {
 		error = pathspec_match_from_iterator(out, iter, flags, ps);
-
 		git_iterator_free(iter);
 	}
 
diff --git a/src/refdb_fs.c b/src/refdb_fs.c
index 55d535eb4..1ddce4649 100644
--- a/src/refdb_fs.c
+++ b/src/refdb_fs.c
@@ -480,14 +480,16 @@ static int iter_load_loose_paths(refdb_fs_backend *backend, refdb_fs_iter *iter)
 	int error = 0;
 	git_buf path = GIT_BUF_INIT;
 	git_iterator *fsit = NULL;
+	git_iterator_options fsit_opts = GIT_ITERATOR_OPTIONS_INIT;
 	const git_index_entry *entry = NULL;
 
 	if (!backend->path) /* do nothing if no path for loose refs */
 		return 0;
 
+	fsit_opts.flags = backend->iterator_flags;
+
 	if ((error = git_buf_printf(&path, "%s/refs", backend->path)) < 0 ||
-		(error = git_iterator_for_filesystem(
-			&fsit, path.ptr, backend->iterator_flags, NULL, NULL)) < 0) {
+		(error = git_iterator_for_filesystem(&fsit, path.ptr, &fsit_opts)) < 0) {
 		git_buf_free(&path);
 		return error;
 	}
diff --git a/src/stash.c b/src/stash.c
index fcb1112ac..35824659a 100644
--- a/src/stash.c
+++ b/src/stash.c
@@ -679,12 +679,14 @@ static int merge_indexes(
 	git_index *theirs_index)
 {
 	git_iterator *ancestor = NULL, *ours = NULL, *theirs = NULL;
-	const git_iterator_flag_t flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+	git_iterator_options iter_opts = GIT_ITERATOR_OPTIONS_INIT;
 	int error;
 
-	if ((error = git_iterator_for_tree(&ancestor, ancestor_tree, flags, NULL, NULL)) < 0 ||
-		(error = git_iterator_for_index(&ours, ours_index, flags, NULL, NULL)) < 0 ||
-		(error = git_iterator_for_index(&theirs, theirs_index, flags, NULL, NULL)) < 0)
+	iter_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+
+	if ((error = git_iterator_for_tree(&ancestor, ancestor_tree, &iter_opts)) < 0 ||
+		(error = git_iterator_for_index(&ours, ours_index, &iter_opts)) < 0 ||
+		(error = git_iterator_for_index(&theirs, theirs_index, &iter_opts)) < 0)
 		goto done;
 
 	error = git_merge__iterators(out, repo, ancestor, ours, theirs, NULL);
@@ -704,12 +706,14 @@ static int merge_index_and_tree(
 	git_tree *theirs_tree)
 {
 	git_iterator *ancestor = NULL, *ours = NULL, *theirs = NULL;
-	const git_iterator_flag_t flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+	git_iterator_options iter_opts = GIT_ITERATOR_OPTIONS_INIT;
 	int error;
 
-	if ((error = git_iterator_for_tree(&ancestor, ancestor_tree, flags, NULL, NULL)) < 0 ||
-		(error = git_iterator_for_index(&ours, ours_index, flags, NULL, NULL)) < 0 ||
-		(error = git_iterator_for_tree(&theirs, theirs_tree, flags, NULL, NULL)) < 0)
+	iter_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+
+	if ((error = git_iterator_for_tree(&ancestor, ancestor_tree, &iter_opts)) < 0 ||
+		(error = git_iterator_for_index(&ours, ours_index, &iter_opts)) < 0 ||
+		(error = git_iterator_for_tree(&theirs, theirs_tree, &iter_opts)) < 0)
 		goto done;
 
 	error = git_merge__iterators(out, repo, ancestor, ours, theirs, NULL);
@@ -797,14 +801,15 @@ static int stage_new_files(
 	git_tree *tree)
 {
 	git_iterator *iterators[2] = { NULL, NULL };
+	git_iterator_options iterator_options = GIT_ITERATOR_OPTIONS_INIT;
 	git_index *index = NULL;
 	int error;
 
 	if ((error = git_index_new(&index)) < 0 ||
-		(error = git_iterator_for_tree(&iterators[0], parent_tree,
-			GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL)) < 0 ||
-		(error = git_iterator_for_tree(&iterators[1], tree,
-			GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL)) < 0)
+		(error = git_iterator_for_tree(
+			&iterators[0], parent_tree, &iterator_options)) < 0 ||
+		(error = git_iterator_for_tree(
+			&iterators[1], tree, &iterator_options)) < 0)
 		goto done;
 
 	error = git_iterator_walk(iterators, 2, stage_new_file, index);
diff --git a/src/submodule.c b/src/submodule.c
index 991ebc8f3..7f52c3616 100644
--- a/src/submodule.c
+++ b/src/submodule.c
@@ -286,7 +286,7 @@ static int submodules_from_index(git_strmap *map, git_index *idx)
        git_iterator *i;
        const git_index_entry *entry;
 
-       if ((error = git_iterator_for_index(&i, idx, 0, NULL, NULL)) < 0)
+       if ((error = git_iterator_for_index(&i, idx, NULL)) < 0)
                return error;
 
        while (!(error = git_iterator_advance(&entry, i))) {
@@ -322,7 +322,7 @@ static int submodules_from_head(git_strmap *map, git_tree *head)
        git_iterator *i;
        const git_index_entry *entry;
 
-       if ((error = git_iterator_for_tree(&i, head, 0, NULL, NULL)) < 0)
+       if ((error = git_iterator_for_tree(&i, head, NULL)) < 0)
                return error;
 
        while (!(error = git_iterator_advance(&entry, i))) {
diff --git a/tests/diff/iterator.c b/tests/diff/iterator.c
index 6011c6a9b..eafb1b9da 100644
--- a/tests/diff/iterator.c
+++ b/tests/diff/iterator.c
@@ -30,13 +30,17 @@ static void tree_iterator_test(
 {
 	git_tree *t;
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
 	const git_index_entry *entry;
 	int error, count = 0, count_post_reset = 0;
 	git_repository *repo = cl_git_sandbox_init(sandbox);
 
+	i_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+	i_opts.start = start;
+	i_opts.end = end;
+
 	cl_assert(t = resolve_commit_oid_to_tree(repo, treeish));
-	cl_git_pass(git_iterator_for_tree(
-		&i, t, GIT_ITERATOR_DONT_IGNORE_CASE, start, end));
+	cl_git_pass(git_iterator_for_tree(&i, t, &i_opts));
 
 	/* test loop */
 	while (!(error = git_iterator_advance(&entry, i))) {
@@ -297,6 +301,7 @@ void test_diff_iterator__tree_special_functions(void)
 {
 	git_tree *t;
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
 	const git_index_entry *entry;
 	git_repository *repo = cl_git_sandbox_init("attr");
 	int error, cases = 0;
@@ -306,8 +311,9 @@ void test_diff_iterator__tree_special_functions(void)
 		repo, "24fa9a9fc4e202313e24b648087495441dab432b");
 	cl_assert(t != NULL);
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, t, GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+
+	cl_git_pass(git_iterator_for_tree(&i, t, &i_opts));
 
 	while (!(error = git_iterator_advance(&entry, i))) {
 		cl_assert(entry);
@@ -365,11 +371,16 @@ static void index_iterator_test(
 	const git_index_entry *entry;
 	int error, count = 0, caps;
 	git_repository *repo = cl_git_sandbox_init(sandbox);
+	git_iterator_options iter_opts = GIT_ITERATOR_OPTIONS_INIT;
 
 	cl_git_pass(git_repository_index(&index, repo));
 	caps = git_index_caps(index);
 
-	cl_git_pass(git_iterator_for_index(&i, index, flags, start, end));
+	iter_opts.flags = flags;
+	iter_opts.start = start;
+	iter_opts.end = end;
+
+	cl_git_pass(git_iterator_for_index(&i, index, &iter_opts));
 
 	while (!(error = git_iterator_advance(&entry, i))) {
 		cl_assert(entry);
@@ -581,12 +592,16 @@ static void workdir_iterator_test(
 	const char *an_ignored_name)
 {
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
 	const git_index_entry *entry;
 	int error, count = 0, count_all = 0, count_all_post_reset = 0;
 	git_repository *repo = cl_git_sandbox_init(sandbox);
 
-	cl_git_pass(git_iterator_for_workdir(
-		&i, repo, NULL, NULL, GIT_ITERATOR_DONT_AUTOEXPAND, start, end));
+	i_opts.flags = GIT_ITERATOR_DONT_AUTOEXPAND;
+	i_opts.start = start;
+	i_opts.end = end;
+
+	cl_git_pass(git_iterator_for_workdir(&i, repo, NULL, NULL, &i_opts));
 
 	error = git_iterator_current(&entry, i);
 	cl_assert((error == 0 && entry != NULL) ||
@@ -765,6 +780,7 @@ void test_diff_iterator__workdir_builtin_ignores(void)
 {
 	git_repository *repo = cl_git_sandbox_init("attr");
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
 	const git_index_entry *entry;
 	int idx;
 	static struct {
@@ -796,8 +812,12 @@ void test_diff_iterator__workdir_builtin_ignores(void)
 	cl_git_pass(p_mkdir("attr/sub/sub/.git", 0777));
 	cl_git_mkfile("attr/sub/.git", "whatever");
 
+	i_opts.flags = GIT_ITERATOR_DONT_AUTOEXPAND;
+	i_opts.start = "dir";
+	i_opts.end = "sub/sub/file";
+
 	cl_git_pass(git_iterator_for_workdir(
-		&i, repo, NULL, NULL, GIT_ITERATOR_DONT_AUTOEXPAND, "dir", "sub/sub/file"));
+		&i, repo, NULL, NULL, &i_opts));
 	cl_git_pass(git_iterator_current(&entry, i));
 
 	for (idx = 0; entry != NULL; ++idx) {
@@ -827,12 +847,17 @@ static void check_wd_first_through_third_range(
 	git_repository *repo, const char *start, const char *end)
 {
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
 	const git_index_entry *entry;
 	int error, idx;
 	static const char *expected[] = { "FIRST", "second", "THIRD", NULL };
 
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE;
+	i_opts.start = start;
+	i_opts.end = end;
+
 	cl_git_pass(git_iterator_for_workdir(
-		&i, repo, NULL, NULL, GIT_ITERATOR_IGNORE_CASE, start, end));
+		&i, repo, NULL, NULL, &i_opts));
 	cl_git_pass(git_iterator_current(&entry, i));
 
 	for (idx = 0; entry != NULL; ++idx) {
@@ -877,14 +902,16 @@ static void check_tree_range(
 {
 	git_tree *head;
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
 	int error, count;
 
+	i_opts.flags = ignore_case ? GIT_ITERATOR_IGNORE_CASE : GIT_ITERATOR_DONT_IGNORE_CASE;
+	i_opts.start = start;
+	i_opts.end = end;
+
 	cl_git_pass(git_repository_head_tree(&head, repo));
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, head,
-		ignore_case ? GIT_ITERATOR_IGNORE_CASE : GIT_ITERATOR_DONT_IGNORE_CASE,
-		start, end));
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 
 	for (count = 0; !(error = git_iterator_advance(NULL, i)); ++count)
 		/* count em up */;
@@ -931,6 +958,7 @@ static void check_index_range(
 {
 	git_index *index;
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
 	int error, count, caps;
 	bool is_ignoring_case;
 
@@ -942,7 +970,11 @@ static void check_index_range(
 	if (ignore_case != is_ignoring_case)
 		cl_git_pass(git_index_set_caps(index, caps ^ GIT_INDEXCAP_IGNORE_CASE));
 
-	cl_git_pass(git_iterator_for_index(&i, index, 0, start, end));
+	i_opts.flags = 0;
+	i_opts.start = start;
+	i_opts.end = end;
+
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
 
 	cl_assert(git_iterator_ignore_case(i) == ignore_case);
 
diff --git a/tests/diff/workdir.c b/tests/diff/workdir.c
index 8a23f53ae..e87769170 100644
--- a/tests/diff/workdir.c
+++ b/tests/diff/workdir.c
@@ -444,6 +444,216 @@ void test_diff_workdir__to_index_with_pathspec(void)
 	git_diff_free(diff);
 }
 
+void test_diff_workdir__to_index_with_pathlist_disabling_fnmatch(void)
+{
+	git_diff_options opts = GIT_DIFF_OPTIONS_INIT;
+	git_diff *diff = NULL;
+	diff_expects exp;
+	char *pathspec = NULL;
+	int use_iterator;
+
+	g_repo = cl_git_sandbox_init("status");
+
+	opts.context_lines = 3;
+	opts.interhunk_lines = 1;
+	opts.flags |= GIT_DIFF_INCLUDE_IGNORED | GIT_DIFF_INCLUDE_UNTRACKED |
+		GIT_DIFF_DISABLE_PATHSPEC_MATCH;
+	opts.pathspec.strings = &pathspec;
+	opts.pathspec.count   = 0;
+
+	/* ensure that an empty pathspec list is ignored */
+	cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts));
+
+	for (use_iterator = 0; use_iterator <= 1; use_iterator++) {
+		memset(&exp, 0, sizeof(exp));
+
+		if (use_iterator)
+			cl_git_pass(diff_foreach_via_iterator(
+				diff, diff_file_cb, NULL, NULL, NULL, &exp));
+		else
+			cl_git_pass(git_diff_foreach(diff, diff_file_cb, NULL, NULL, NULL, &exp));
+
+		cl_assert_equal_i(13, exp.files);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_ADDED]);
+		cl_assert_equal_i(4, exp.file_status[GIT_DELTA_DELETED]);
+		cl_assert_equal_i(4, exp.file_status[GIT_DELTA_MODIFIED]);
+		cl_assert_equal_i(1, exp.file_status[GIT_DELTA_IGNORED]);
+		cl_assert_equal_i(4, exp.file_status[GIT_DELTA_UNTRACKED]);
+	}
+
+	git_diff_free(diff);
+
+	/* ensure that a single NULL pathspec is filtered out (like when using
+	 * fnmatch filtering)
+	 */
+
+	opts.pathspec.count   = 1;
+
+	cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts));
+
+	for (use_iterator = 0; use_iterator <= 1; use_iterator++) {
+		memset(&exp, 0, sizeof(exp));
+
+		if (use_iterator)
+			cl_git_pass(diff_foreach_via_iterator(
+				diff, diff_file_cb, NULL, NULL, NULL, &exp));
+		else
+			cl_git_pass(git_diff_foreach(diff, diff_file_cb, NULL, NULL, NULL, &exp));
+
+		cl_assert_equal_i(13, exp.files);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_ADDED]);
+		cl_assert_equal_i(4, exp.file_status[GIT_DELTA_DELETED]);
+		cl_assert_equal_i(4, exp.file_status[GIT_DELTA_MODIFIED]);
+		cl_assert_equal_i(1, exp.file_status[GIT_DELTA_IGNORED]);
+		cl_assert_equal_i(4, exp.file_status[GIT_DELTA_UNTRACKED]);
+	}
+
+	git_diff_free(diff);
+
+	pathspec = "modified_file";
+
+	cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts));
+
+	for (use_iterator = 0; use_iterator <= 1; use_iterator++) {
+		memset(&exp, 0, sizeof(exp));
+
+		if (use_iterator)
+			cl_git_pass(diff_foreach_via_iterator(
+				diff, diff_file_cb, NULL, NULL, NULL, &exp));
+		else
+			cl_git_pass(git_diff_foreach(diff, diff_file_cb, NULL, NULL, NULL, &exp));
+
+		cl_assert_equal_i(1, exp.files);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_ADDED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_DELETED]);
+		cl_assert_equal_i(1, exp.file_status[GIT_DELTA_MODIFIED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_IGNORED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_UNTRACKED]);
+	}
+
+	git_diff_free(diff);
+
+	/* ensure that subdirs can be specified */
+	pathspec = "subdir";
+
+	cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts));
+
+	for (use_iterator = 0; use_iterator <= 1; use_iterator++) {
+		memset(&exp, 0, sizeof(exp));
+
+		if (use_iterator)
+			cl_git_pass(diff_foreach_via_iterator(
+				diff, diff_file_cb, NULL, NULL, NULL, &exp));
+		else
+			cl_git_pass(git_diff_foreach(diff, diff_file_cb, NULL, NULL, NULL, &exp));
+
+		cl_assert_equal_i(3, exp.files);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_ADDED]);
+		cl_assert_equal_i(1, exp.file_status[GIT_DELTA_DELETED]);
+		cl_assert_equal_i(1, exp.file_status[GIT_DELTA_MODIFIED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_IGNORED]);
+		cl_assert_equal_i(1, exp.file_status[GIT_DELTA_UNTRACKED]);
+	}
+
+	git_diff_free(diff);
+
+	/* ensure that subdirs can be specified with a trailing slash */
+	pathspec = "subdir/";
+
+	cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts));
+
+	for (use_iterator = 0; use_iterator <= 1; use_iterator++) {
+		memset(&exp, 0, sizeof(exp));
+
+		if (use_iterator)
+			cl_git_pass(diff_foreach_via_iterator(
+				diff, diff_file_cb, NULL, NULL, NULL, &exp));
+		else
+			cl_git_pass(git_diff_foreach(diff, diff_file_cb, NULL, NULL, NULL, &exp));
+
+		cl_assert_equal_i(3, exp.files);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_ADDED]);
+		cl_assert_equal_i(1, exp.file_status[GIT_DELTA_DELETED]);
+		cl_assert_equal_i(1, exp.file_status[GIT_DELTA_MODIFIED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_IGNORED]);
+		cl_assert_equal_i(1, exp.file_status[GIT_DELTA_UNTRACKED]);
+	}
+
+	git_diff_free(diff);
+
+	/* ensure that fnmatching is completely disabled */
+	pathspec = "subdir/*";
+
+	cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts));
+
+	for (use_iterator = 0; use_iterator <= 1; use_iterator++) {
+		memset(&exp, 0, sizeof(exp));
+
+		if (use_iterator)
+			cl_git_pass(diff_foreach_via_iterator(
+				diff, diff_file_cb, NULL, NULL, NULL, &exp));
+		else
+			cl_git_pass(git_diff_foreach(diff, diff_file_cb, NULL, NULL, NULL, &exp));
+
+		cl_assert_equal_i(0, exp.files);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_ADDED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_DELETED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_MODIFIED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_IGNORED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_UNTRACKED]);
+	}
+
+	git_diff_free(diff);
+
+	/* ensure that the prefix matching isn't completely braindead */
+	pathspec = "subdi";
+
+	cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts));
+
+	for (use_iterator = 0; use_iterator <= 1; use_iterator++) {
+		memset(&exp, 0, sizeof(exp));
+
+		if (use_iterator)
+			cl_git_pass(diff_foreach_via_iterator(
+				diff, diff_file_cb, NULL, NULL, NULL, &exp));
+		else
+			cl_git_pass(git_diff_foreach(diff, diff_file_cb, NULL, NULL, NULL, &exp));
+
+		cl_assert_equal_i(0, exp.files);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_ADDED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_DELETED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_MODIFIED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_IGNORED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_UNTRACKED]);
+	}
+
+	git_diff_free(diff);
+
+	/* ensure that fnmatching isn't working at all */
+	pathspec = "*_deleted";
+
+	cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts));
+
+	for (use_iterator = 0; use_iterator <= 1; use_iterator++) {
+		memset(&exp, 0, sizeof(exp));
+
+		if (use_iterator)
+			cl_git_pass(diff_foreach_via_iterator(
+				diff, diff_file_cb, NULL, NULL, NULL, &exp));
+		else
+			cl_git_pass(git_diff_foreach(diff, diff_file_cb, NULL, NULL, NULL, &exp));
+
+		cl_assert_equal_i(0, exp.files);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_ADDED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_DELETED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_MODIFIED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_IGNORED]);
+		cl_assert_equal_i(0, exp.file_status[GIT_DELTA_UNTRACKED]);
+	}
+
+	git_diff_free(diff);
+}
+
 void test_diff_workdir__filemode_changes(void)
 {
 	git_diff *diff = NULL;
diff --git a/tests/merge/trees/treediff.c b/tests/merge/trees/treediff.c
index b96c4c4db..f21d99b6d 100644
--- a/tests/merge/trees/treediff.c
+++ b/tests/merge/trees/treediff.c
@@ -44,6 +44,7 @@ static void test_find_differences(
     git_oid ancestor_oid, ours_oid, theirs_oid;
     git_tree *ancestor_tree, *ours_tree, *theirs_tree;
 	git_iterator *ancestor_iter, *ours_iter, *theirs_iter;
+	git_iterator_options iter_opts = GIT_ITERATOR_OPTIONS_INIT;
 
 	git_merge_options opts = GIT_MERGE_OPTIONS_INIT;
 	opts.tree_flags |= GIT_MERGE_TREE_FIND_RENAMES;
@@ -67,12 +68,11 @@ static void test_find_differences(
 	cl_git_pass(git_tree_lookup(&ours_tree, repo, &ours_oid));
 	cl_git_pass(git_tree_lookup(&theirs_tree, repo, &theirs_oid));
 
-	cl_git_pass(git_iterator_for_tree(&ancestor_iter, ancestor_tree,
-			GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL));
-	cl_git_pass(git_iterator_for_tree(&ours_iter, ours_tree,
-			GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL));
-	cl_git_pass(git_iterator_for_tree(&theirs_iter, theirs_tree,
-			GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL));
+	iter_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+
+	cl_git_pass(git_iterator_for_tree(&ancestor_iter, ancestor_tree, &iter_opts));
+	cl_git_pass(git_iterator_for_tree(&ours_iter, ours_tree, &iter_opts));
+	cl_git_pass(git_iterator_for_tree(&theirs_iter, theirs_tree, &iter_opts));
 
 	cl_git_pass(git_merge_diff_list__find_differences(merge_diff_list, ancestor_iter, ours_iter, theirs_iter));
 	cl_git_pass(git_merge_diff_list__find_renames(repo, merge_diff_list, &opts));
diff --git a/tests/repo/iterator.c b/tests/repo/iterator.c
index bb2d3a186..9c4cc9ea4 100644
--- a/tests/repo/iterator.c
+++ b/tests/repo/iterator.c
@@ -126,6 +126,7 @@ static void expect_iterator_items(
 void test_repo_iterator__index(void)
 {
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
 	git_index *index;
 
 	g_repo = cl_git_sandbox_init("icase");
@@ -133,19 +134,19 @@ void test_repo_iterator__index(void)
 	cl_git_pass(git_repository_index(&index, g_repo));
 
 	/* autoexpand with no tree entries for index */
-	cl_git_pass(git_iterator_for_index(&i, index, 0, NULL, NULL));
+	cl_git_pass(git_iterator_for_index(&i, index, NULL));
 	expect_iterator_items(i, 20, NULL, 20, NULL);
 	git_iterator_free(i);
 
 	/* auto expand with tree entries */
-	cl_git_pass(git_iterator_for_index(
-		&i, index, GIT_ITERATOR_INCLUDE_TREES, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_INCLUDE_TREES;
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
 	expect_iterator_items(i, 22, NULL, 22, NULL);
 	git_iterator_free(i);
 
 	/* no auto expand (implies trees included) */
-	cl_git_pass(git_iterator_for_index(
-		&i, index, GIT_ITERATOR_DONT_AUTOEXPAND, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_DONT_AUTOEXPAND;
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
 	expect_iterator_items(i, 12, NULL, 22, NULL);
 	git_iterator_free(i);
 
@@ -155,6 +156,7 @@ void test_repo_iterator__index(void)
 void test_repo_iterator__index_icase(void)
 {
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
 	git_index *index;
 	int caps;
 
@@ -167,32 +169,45 @@ void test_repo_iterator__index_icase(void)
 	cl_git_pass(git_index_set_caps(index, caps & ~GIT_INDEXCAP_IGNORE_CASE));
 
 	/* autoexpand with no tree entries over range */
-	cl_git_pass(git_iterator_for_index(&i, index, 0, "c", "k/D"));
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
 	expect_iterator_items(i, 7, NULL, 7, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_index(&i, index, 0, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
 	expect_iterator_items(i, 3, NULL, 3, NULL);
 	git_iterator_free(i);
 
 	/* auto expand with tree entries */
-	cl_git_pass(git_iterator_for_index(
-		&i, index, GIT_ITERATOR_INCLUDE_TREES, "c", "k/D"));
+	i_opts.flags = GIT_ITERATOR_INCLUDE_TREES;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
 	expect_iterator_items(i, 8, NULL, 8, NULL);
 	git_iterator_free(i);
-	cl_git_pass(git_iterator_for_index(
-		&i, index, GIT_ITERATOR_INCLUDE_TREES, "k", "k/Z"));
+
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
 	expect_iterator_items(i, 4, NULL, 4, NULL);
 	git_iterator_free(i);
 
 	/* no auto expand (implies trees included) */
-	cl_git_pass(git_iterator_for_index(
-		&i, index, GIT_ITERATOR_DONT_AUTOEXPAND, "c", "k/D"));
+	i_opts.flags = GIT_ITERATOR_DONT_AUTOEXPAND;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
 	expect_iterator_items(i, 5, NULL, 8, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_index(
-		&i, index, GIT_ITERATOR_DONT_AUTOEXPAND, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
 	expect_iterator_items(i, 1, NULL, 4, NULL);
 	git_iterator_free(i);
 
@@ -200,33 +215,47 @@ void test_repo_iterator__index_icase(void)
 	cl_git_pass(git_index_set_caps(index, caps | GIT_INDEXCAP_IGNORE_CASE));
 
 	/* autoexpand with no tree entries over range */
-	cl_git_pass(git_iterator_for_index(&i, index, 0, "c", "k/D"));
+	i_opts.flags = 0;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
 	expect_iterator_items(i, 13, NULL, 13, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_index(&i, index, 0, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
 	expect_iterator_items(i, 5, NULL, 5, NULL);
 	git_iterator_free(i);
 
 	/* auto expand with tree entries */
-	cl_git_pass(git_iterator_for_index(
-		&i, index, GIT_ITERATOR_INCLUDE_TREES, "c", "k/D"));
+	i_opts.flags = GIT_ITERATOR_INCLUDE_TREES;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
 	expect_iterator_items(i, 14, NULL, 14, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_index(
-		&i, index, GIT_ITERATOR_INCLUDE_TREES, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
 	expect_iterator_items(i, 6, NULL, 6, NULL);
 	git_iterator_free(i);
 
 	/* no auto expand (implies trees included) */
-	cl_git_pass(git_iterator_for_index(
-		&i, index, GIT_ITERATOR_DONT_AUTOEXPAND, "c", "k/D"));
+	i_opts.flags = GIT_ITERATOR_DONT_AUTOEXPAND;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
 	expect_iterator_items(i, 9, NULL, 14, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_index(
-		&i, index, GIT_ITERATOR_DONT_AUTOEXPAND, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
 	expect_iterator_items(i, 1, NULL, 6, NULL);
 	git_iterator_free(i);
 
@@ -237,6 +266,7 @@ void test_repo_iterator__index_icase(void)
 void test_repo_iterator__tree(void)
 {
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
 	git_tree *head;
 
 	g_repo = cl_git_sandbox_init("icase");
@@ -244,19 +274,21 @@ void test_repo_iterator__tree(void)
 	cl_git_pass(git_repository_head_tree(&head, g_repo));
 
 	/* auto expand with no tree entries */
-	cl_git_pass(git_iterator_for_tree(&i, head, 0, NULL, NULL));
+	cl_git_pass(git_iterator_for_tree(&i, head, NULL));
 	expect_iterator_items(i, 20, NULL, 20, NULL);
 	git_iterator_free(i);
 
 	/* auto expand with tree entries */
-	cl_git_pass(git_iterator_for_tree(
-		&i, head, GIT_ITERATOR_INCLUDE_TREES, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_INCLUDE_TREES;
+
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 22, NULL, 22, NULL);
 	git_iterator_free(i);
 
 	/* no auto expand (implies trees included) */
-	cl_git_pass(git_iterator_for_tree(
-		&i, head, GIT_ITERATOR_DONT_AUTOEXPAND, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_DONT_AUTOEXPAND;
+
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 12, NULL, 22, NULL);
 	git_iterator_free(i);
 
@@ -267,75 +299,98 @@ void test_repo_iterator__tree_icase(void)
 {
 	git_iterator *i;
 	git_tree *head;
-	git_iterator_flag_t flag;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
 
 	g_repo = cl_git_sandbox_init("icase");
 
 	cl_git_pass(git_repository_head_tree(&head, g_repo));
 
-	flag = GIT_ITERATOR_DONT_IGNORE_CASE;
+	i_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
 
 	/* auto expand with no tree entries */
-	cl_git_pass(git_iterator_for_tree(&i, head, flag, "c", "k/D"));
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 7, NULL, 7, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_tree(&i, head, flag, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 3, NULL, 3, NULL);
 	git_iterator_free(i);
 
+	i_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE | GIT_ITERATOR_INCLUDE_TREES;
+
 	/* auto expand with tree entries */
-	cl_git_pass(git_iterator_for_tree(
-		&i, head, flag | GIT_ITERATOR_INCLUDE_TREES, "c", "k/D"));
+	i_opts.start = "c";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 8, NULL, 8, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, head, flag | GIT_ITERATOR_INCLUDE_TREES, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 4, NULL, 4, NULL);
 	git_iterator_free(i);
 
 	/* no auto expand (implies trees included) */
-	cl_git_pass(git_iterator_for_tree(
-		&i, head, flag | GIT_ITERATOR_DONT_AUTOEXPAND, "c", "k/D"));
+	i_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE | GIT_ITERATOR_DONT_AUTOEXPAND;
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 5, NULL, 8, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, head, flag | GIT_ITERATOR_DONT_AUTOEXPAND, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 1, NULL, 4, NULL);
 	git_iterator_free(i);
 
-	flag = GIT_ITERATOR_IGNORE_CASE;
-
 	/* auto expand with no tree entries */
-	cl_git_pass(git_iterator_for_tree(&i, head, flag, "c", "k/D"));
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 13, NULL, 13, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_tree(&i, head, flag, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 5, NULL, 5, NULL);
 	git_iterator_free(i);
 
 	/* auto expand with tree entries */
-	cl_git_pass(git_iterator_for_tree(
-		&i, head, flag | GIT_ITERATOR_INCLUDE_TREES, "c", "k/D"));
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE | GIT_ITERATOR_INCLUDE_TREES;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 14, NULL, 14, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, head, flag | GIT_ITERATOR_INCLUDE_TREES, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 6, NULL, 6, NULL);
 	git_iterator_free(i);
 
 	/* no auto expand (implies trees included) */
-	cl_git_pass(git_iterator_for_tree(
-		&i, head, flag | GIT_ITERATOR_DONT_AUTOEXPAND, "c", "k/D"));
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE | GIT_ITERATOR_DONT_AUTOEXPAND;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 9, NULL, 14, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, head, flag | GIT_ITERATOR_DONT_AUTOEXPAND, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 1, NULL, 6, NULL);
 	git_iterator_free(i);
 
@@ -345,6 +400,7 @@ void test_repo_iterator__tree_icase(void)
 void test_repo_iterator__tree_more(void)
 {
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
 	git_tree *head;
 	static const char *expect_basic[] = {
 		"current_file",
@@ -396,19 +452,21 @@ void test_repo_iterator__tree_more(void)
 	cl_git_pass(git_repository_head_tree(&head, g_repo));
 
 	/* auto expand with no tree entries */
-	cl_git_pass(git_iterator_for_tree(&i, head, 0, NULL, NULL));
+	cl_git_pass(git_iterator_for_tree(&i, head, NULL));
 	expect_iterator_items(i, 12, expect_basic, 12, expect_basic);
 	git_iterator_free(i);
 
 	/* auto expand with tree entries */
-	cl_git_pass(git_iterator_for_tree(
-		&i, head, GIT_ITERATOR_INCLUDE_TREES, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_INCLUDE_TREES;
+
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 13, expect_trees, 13, expect_trees);
 	git_iterator_free(i);
 
 	/* no auto expand (implies trees included) */
-	cl_git_pass(git_iterator_for_tree(
-		&i, head, GIT_ITERATOR_DONT_AUTOEXPAND, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_DONT_AUTOEXPAND;
+
+	cl_git_pass(git_iterator_for_tree(&i, head, &i_opts));
 	expect_iterator_items(i, 10, expect_noauto, 13, expect_trees);
 	git_iterator_free(i);
 
@@ -463,6 +521,8 @@ void test_repo_iterator__tree_case_conflicts_0(void)
 	git_tree *tree;
 	git_oid blob_id, biga_id, littlea_id, tree_id;
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
+
 	const char *expect_cs[] = {
 		"A/1.file", "A/3.file", "a/2.file", "a/4.file" };
 	const char *expect_ci[] = {
@@ -486,25 +546,23 @@ void test_repo_iterator__tree_case_conflicts_0(void)
 
 	cl_git_pass(git_tree_lookup(&tree, g_repo, &tree_id));
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, tree, GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
 	expect_iterator_items(i, 4, expect_cs, 4, expect_cs);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, tree, GIT_ITERATOR_IGNORE_CASE, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE;
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
 	expect_iterator_items(i, 4, expect_ci, 4, expect_ci);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, tree, GIT_ITERATOR_DONT_IGNORE_CASE |
-		GIT_ITERATOR_INCLUDE_TREES, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE | GIT_ITERATOR_INCLUDE_TREES;
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
 	expect_iterator_items(i, 6, expect_cs_trees, 6, expect_cs_trees);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, tree, GIT_ITERATOR_IGNORE_CASE |
-		GIT_ITERATOR_INCLUDE_TREES, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE | GIT_ITERATOR_INCLUDE_TREES;
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
 	expect_iterator_items(i, 5, expect_ci_trees, 5, expect_ci_trees);
 	git_iterator_free(i);
 
@@ -517,6 +575,8 @@ void test_repo_iterator__tree_case_conflicts_1(void)
 	git_tree *tree;
 	git_oid blob_id, Ab_id, biga_id, littlea_id, tree_id;
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
+
 	const char *expect_cs[] = {
 		"A/a", "A/b/1", "A/c", "a/C", "a/a", "a/b" };
 	const char *expect_ci[] = {
@@ -541,25 +601,23 @@ void test_repo_iterator__tree_case_conflicts_1(void)
 
 	cl_git_pass(git_tree_lookup(&tree, g_repo, &tree_id));
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, tree, GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
 	expect_iterator_items(i, 6, expect_cs, 6, expect_cs);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, tree, GIT_ITERATOR_IGNORE_CASE, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE;
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
 	expect_iterator_items(i, 4, expect_ci, 4, expect_ci);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, tree, GIT_ITERATOR_DONT_IGNORE_CASE |
-		GIT_ITERATOR_INCLUDE_TREES, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE | GIT_ITERATOR_INCLUDE_TREES;
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
 	expect_iterator_items(i, 9, expect_cs_trees, 9, expect_cs_trees);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, tree, GIT_ITERATOR_IGNORE_CASE |
-		GIT_ITERATOR_INCLUDE_TREES, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE | GIT_ITERATOR_INCLUDE_TREES;
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
 	expect_iterator_items(i, 6, expect_ci_trees, 6, expect_ci_trees);
 	git_iterator_free(i);
 
@@ -572,6 +630,8 @@ void test_repo_iterator__tree_case_conflicts_2(void)
 	git_tree *tree;
 	git_oid blob_id, d1, d2, c1, c2, b1, b2, a1, a2, tree_id;
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
+
 	const char *expect_cs[] = {
 		"A/B/C/D/16", "A/B/C/D/foo", "A/B/C/d/15",  "A/B/C/d/FOO",
 		"A/B/c/D/14", "A/B/c/D/foo", "A/B/c/d/13",  "A/B/c/d/FOO",
@@ -639,19 +699,18 @@ void test_repo_iterator__tree_case_conflicts_2(void)
 
 	cl_git_pass(git_tree_lookup(&tree, g_repo, &tree_id));
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, tree, GIT_ITERATOR_DONT_IGNORE_CASE, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
 	expect_iterator_items(i, 32, expect_cs, 32, expect_cs);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, tree, GIT_ITERATOR_IGNORE_CASE, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE;
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
 	expect_iterator_items(i, 17, expect_ci, 17, expect_ci);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_tree(
-		&i, tree, GIT_ITERATOR_IGNORE_CASE |
-		GIT_ITERATOR_INCLUDE_TREES, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE | GIT_ITERATOR_INCLUDE_TREES;
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
 	expect_iterator_items(i, 21, expect_ci_trees, 21, expect_ci_trees);
 	git_iterator_free(i);
 
@@ -661,23 +720,24 @@ void test_repo_iterator__tree_case_conflicts_2(void)
 void test_repo_iterator__workdir(void)
 {
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
 
 	g_repo = cl_git_sandbox_init("icase");
 
 	/* auto expand with no tree entries */
-	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, 0, NULL, NULL));
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
 	expect_iterator_items(i, 20, NULL, 20, NULL);
 	git_iterator_free(i);
 
 	/* auto expand with tree entries */
-	cl_git_pass(git_iterator_for_workdir(
-		&i, g_repo, NULL, NULL, GIT_ITERATOR_INCLUDE_TREES, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_INCLUDE_TREES;
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
 	expect_iterator_items(i, 22, NULL, 22, NULL);
 	git_iterator_free(i);
 
 	/* no auto expand (implies trees included) */
-	cl_git_pass(git_iterator_for_workdir(
-		&i, g_repo, NULL, NULL, GIT_ITERATOR_DONT_AUTOEXPAND, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_DONT_AUTOEXPAND;
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
 	expect_iterator_items(i, 12, NULL, 22, NULL);
 	git_iterator_free(i);
 }
@@ -685,73 +745,97 @@ void test_repo_iterator__workdir(void)
 void test_repo_iterator__workdir_icase(void)
 {
 	git_iterator *i;
-	git_iterator_flag_t flag;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
 
 	g_repo = cl_git_sandbox_init("icase");
 
-	flag = GIT_ITERATOR_DONT_IGNORE_CASE;
-
 	/* auto expand with no tree entries */
-	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, flag, "c", "k/D"));
+	i_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
 	expect_iterator_items(i, 7, NULL, 7, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, flag, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
 	expect_iterator_items(i, 3, NULL, 3, NULL);
 	git_iterator_free(i);
 
 	/* auto expand with tree entries */
-	cl_git_pass(git_iterator_for_workdir(
-		&i, g_repo, NULL, NULL, flag | GIT_ITERATOR_INCLUDE_TREES, "c", "k/D"));
+	i_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE | GIT_ITERATOR_INCLUDE_TREES;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
 	expect_iterator_items(i, 8, NULL, 8, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_workdir(
-		&i, g_repo, NULL, NULL, flag | GIT_ITERATOR_INCLUDE_TREES, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
 	expect_iterator_items(i, 4, NULL, 4, NULL);
 	git_iterator_free(i);
 
 	/* no auto expand (implies trees included) */
-	cl_git_pass(git_iterator_for_workdir(
-		&i, g_repo, NULL, NULL, flag | GIT_ITERATOR_DONT_AUTOEXPAND, "c", "k/D"));
+	i_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE | GIT_ITERATOR_DONT_AUTOEXPAND;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
 	expect_iterator_items(i, 5, NULL, 8, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_workdir(
-		&i, g_repo, NULL, NULL, flag | GIT_ITERATOR_DONT_AUTOEXPAND, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
 	expect_iterator_items(i, 1, NULL, 4, NULL);
 	git_iterator_free(i);
 
-	flag = GIT_ITERATOR_IGNORE_CASE;
-
 	/* auto expand with no tree entries */
-	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, flag, "c", "k/D"));
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
 	expect_iterator_items(i, 13, NULL, 13, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, flag, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
 	expect_iterator_items(i, 5, NULL, 5, NULL);
 	git_iterator_free(i);
 
 	/* auto expand with tree entries */
-	cl_git_pass(git_iterator_for_workdir(
-		&i, g_repo, NULL, NULL, flag | GIT_ITERATOR_INCLUDE_TREES, "c", "k/D"));
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE | GIT_ITERATOR_INCLUDE_TREES;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
 	expect_iterator_items(i, 14, NULL, 14, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_workdir(
-		&i, g_repo, NULL, NULL, flag | GIT_ITERATOR_INCLUDE_TREES, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
 	expect_iterator_items(i, 6, NULL, 6, NULL);
 	git_iterator_free(i);
 
 	/* no auto expand (implies trees included) */
-	cl_git_pass(git_iterator_for_workdir(
-		&i, g_repo, NULL, NULL, flag | GIT_ITERATOR_DONT_AUTOEXPAND, "c", "k/D"));
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE | GIT_ITERATOR_DONT_AUTOEXPAND;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
 	expect_iterator_items(i, 9, NULL, 14, NULL);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_workdir(
-		&i, g_repo, NULL, NULL, flag | GIT_ITERATOR_DONT_AUTOEXPAND, "k", "k/Z"));
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
 	expect_iterator_items(i, 1, NULL, 6, NULL);
 	git_iterator_free(i);
 }
@@ -796,6 +880,7 @@ static void build_workdir_tree(const char *root, int dirs, int subs)
 void test_repo_iterator__workdir_depth(void)
 {
 	git_iterator *iter;
+	git_iterator_options iter_opts = GIT_ITERATOR_OPTIONS_INIT;
 
 	g_repo = cl_git_sandbox_init("icase");
 
@@ -804,13 +889,13 @@ void test_repo_iterator__workdir_depth(void)
 	build_workdir_tree("icase/dir02/sUB01", 50, 0);
 
 	/* auto expand with no tree entries */
-	cl_git_pass(git_iterator_for_workdir(&iter, g_repo, NULL, NULL, 0, NULL, NULL));
+	cl_git_pass(git_iterator_for_workdir(&iter, g_repo, NULL, NULL, &iter_opts));
 	expect_iterator_items(iter, 125, NULL, 125, NULL);
 	git_iterator_free(iter);
 
 	/* auto expand with tree entries (empty dirs silently skipped) */
-	cl_git_pass(git_iterator_for_workdir(
-		&iter, g_repo, NULL, NULL, GIT_ITERATOR_INCLUDE_TREES, NULL, NULL));
+	iter_opts.flags = GIT_ITERATOR_INCLUDE_TREES;
+	cl_git_pass(git_iterator_for_workdir(&iter, g_repo, NULL, NULL, &iter_opts));
 	expect_iterator_items(iter, 337, NULL, 337, NULL);
 	git_iterator_free(iter);
 }
@@ -818,6 +903,8 @@ void test_repo_iterator__workdir_depth(void)
 void test_repo_iterator__fs(void)
 {
 	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
+
 	static const char *expect_base[] = {
 		"DIR01/Sub02/file",
 		"DIR01/sub00/file",
@@ -863,18 +950,17 @@ void test_repo_iterator__fs(void)
 
 	build_workdir_tree("status/subdir", 2, 4);
 
-	cl_git_pass(git_iterator_for_filesystem(
-		&i, "status/subdir", 0, NULL, NULL));
+	cl_git_pass(git_iterator_for_filesystem(&i, "status/subdir", NULL));
 	expect_iterator_items(i, 8, expect_base, 8, expect_base);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_filesystem(
-		&i, "status/subdir", GIT_ITERATOR_INCLUDE_TREES, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_INCLUDE_TREES;
+	cl_git_pass(git_iterator_for_filesystem(&i, "status/subdir", &i_opts));
 	expect_iterator_items(i, 18, expect_trees, 18, expect_trees);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_filesystem(
-		&i, "status/subdir", GIT_ITERATOR_DONT_AUTOEXPAND, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_DONT_AUTOEXPAND;
+	cl_git_pass(git_iterator_for_filesystem(&i, "status/subdir", &i_opts));
 	expect_iterator_items(i, 5, expect_noauto, 18, expect_trees);
 	git_iterator_free(i);
 
@@ -882,20 +968,18 @@ void test_repo_iterator__fs(void)
 	git__tsort((void **)expect_trees, 18, (git__tsort_cmp)git__strcasecmp);
 	git__tsort((void **)expect_noauto, 5, (git__tsort_cmp)git__strcasecmp);
 
-	cl_git_pass(git_iterator_for_filesystem(
-		&i, "status/subdir", GIT_ITERATOR_IGNORE_CASE, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE;
+	cl_git_pass(git_iterator_for_filesystem(&i, "status/subdir", &i_opts));
 	expect_iterator_items(i, 8, expect_base, 8, expect_base);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_filesystem(
-		&i, "status/subdir", GIT_ITERATOR_IGNORE_CASE |
-		GIT_ITERATOR_INCLUDE_TREES, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE | GIT_ITERATOR_INCLUDE_TREES;
+	cl_git_pass(git_iterator_for_filesystem(&i, "status/subdir", &i_opts));
 	expect_iterator_items(i, 18, expect_trees, 18, expect_trees);
 	git_iterator_free(i);
 
-	cl_git_pass(git_iterator_for_filesystem(
-		&i, "status/subdir", GIT_ITERATOR_IGNORE_CASE |
-		GIT_ITERATOR_DONT_AUTOEXPAND, NULL, NULL));
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE | GIT_ITERATOR_DONT_AUTOEXPAND;
+	cl_git_pass(git_iterator_for_filesystem(&i, "status/subdir", &i_opts));
 	expect_iterator_items(i, 5, expect_noauto, 18, expect_trees);
 	git_iterator_free(i);
 }
@@ -923,7 +1007,7 @@ void test_repo_iterator__fs2(void)
 	g_repo = cl_git_sandbox_init("testrepo");
 
 	cl_git_pass(git_iterator_for_filesystem(
-		&i, "testrepo/.git/refs", 0, NULL, NULL));
+		&i, "testrepo/.git/refs", NULL));
 	expect_iterator_items(i, 13, expect_base, 13, expect_base);
 	git_iterator_free(i);
 }
@@ -947,7 +1031,7 @@ void test_repo_iterator__unreadable_dir(void)
 	cl_git_mkfile("empty_standard_repo/r/d", "final");
 
 	cl_git_pass(git_iterator_for_filesystem(
-		&i, "empty_standard_repo/r", 0, NULL, NULL));
+		&i, "empty_standard_repo/r", NULL));
 
 	cl_git_pass(git_iterator_advance(&e, i)); /* a */
 	cl_git_fail(git_iterator_advance(&e, i)); /* b */
@@ -963,6 +1047,7 @@ void test_repo_iterator__skips_fifos_and_such(void)
 #ifndef GIT_WIN32
 	git_iterator *i;
 	const git_index_entry *e;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
 
 	g_repo = cl_git_sandbox_init("empty_standard_repo");
 
@@ -972,9 +1057,11 @@ void test_repo_iterator__skips_fifos_and_such(void)
 	cl_assert(!mkfifo("empty_standard_repo/fifo", 0777));
 	cl_assert(!access("empty_standard_repo/fifo", F_OK));
 
+	i_opts.flags = GIT_ITERATOR_INCLUDE_TREES |
+		GIT_ITERATOR_DONT_AUTOEXPAND;
+
 	cl_git_pass(git_iterator_for_filesystem(
-		&i, "empty_standard_repo", GIT_ITERATOR_INCLUDE_TREES |
-		GIT_ITERATOR_DONT_AUTOEXPAND, NULL, NULL));
+		&i, "empty_standard_repo", &i_opts));
 
 	cl_git_pass(git_iterator_advance(&e, i)); /* .git */
 	cl_assert(S_ISDIR(e->mode));
@@ -989,3 +1076,469 @@ void test_repo_iterator__skips_fifos_and_such(void)
 	git_iterator_free(i);
 #endif
 }
+
+void test_repo_iterator__indexfilelist(void)
+{
+	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
+	git_index *index;
+	git_vector filelist;
+	int default_icase;
+	int expect;
+
+	cl_git_pass(git_vector_init(&filelist, 100, &git__strcmp_cb));
+	cl_git_pass(git_vector_insert(&filelist, "a"));
+	cl_git_pass(git_vector_insert(&filelist, "B"));
+	cl_git_pass(git_vector_insert(&filelist, "c"));
+	cl_git_pass(git_vector_insert(&filelist, "D"));
+	cl_git_pass(git_vector_insert(&filelist, "e"));
+	cl_git_pass(git_vector_insert(&filelist, "k/1"));
+	cl_git_pass(git_vector_insert(&filelist, "k/a"));
+	cl_git_pass(git_vector_insert(&filelist, "L/1"));
+
+	g_repo = cl_git_sandbox_init("icase");
+
+	cl_git_pass(git_repository_index(&index, g_repo));
+
+	/* In this test we DO NOT force a case setting on the index. */
+	default_icase = ((git_index_caps(index) & GIT_INDEXCAP_IGNORE_CASE) != 0);
+
+	i_opts.pathlist.strings = (char **)filelist.contents;
+	i_opts.pathlist.count = filelist.length;
+
+	/* All indexfilelist iterator tests are "autoexpand with no tree entries" */
+
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
+	expect_iterator_items(i, 8, NULL, 8, NULL);
+	git_iterator_free(i);
+
+	i_opts.start = "c";
+	i_opts.end = NULL;
+
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
+	/* (c D e k/1 k/a L ==> 6) vs (c e k/1 k/a ==> 4) */
+	expect = ((default_icase) ? 6 : 4);
+	expect_iterator_items(i, expect, NULL, expect, NULL);
+	git_iterator_free(i);
+
+	i_opts.start = NULL;
+	i_opts.end = "e";
+
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
+	/* (a B c D e ==> 5) vs (B D L/1 a c e ==> 6) */
+	expect = ((default_icase) ? 5 : 6);
+	expect_iterator_items(i, expect, NULL, expect, NULL);
+	git_iterator_free(i);
+
+	git_index_free(index);
+	git_vector_free(&filelist);
+}
+
+void test_repo_iterator__indexfilelist_2(void)
+{
+	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
+	git_index *index;
+	git_vector filelist = GIT_VECTOR_INIT;
+	int default_icase, expect;
+
+	g_repo = cl_git_sandbox_init("icase");
+
+	cl_git_pass(git_repository_index(&index, g_repo));
+
+	cl_git_pass(git_vector_init(&filelist, 100, &git__strcmp_cb));
+	cl_git_pass(git_vector_insert(&filelist, "0"));
+	cl_git_pass(git_vector_insert(&filelist, "c"));
+	cl_git_pass(git_vector_insert(&filelist, "D"));
+	cl_git_pass(git_vector_insert(&filelist, "e"));
+	cl_git_pass(git_vector_insert(&filelist, "k/1"));
+	cl_git_pass(git_vector_insert(&filelist, "k/a"));
+
+	/* In this test we DO NOT force a case setting on the index. */
+	default_icase = ((git_index_caps(index) & GIT_INDEXCAP_IGNORE_CASE) != 0);
+
+	i_opts.pathlist.strings = (char **)filelist.contents;
+	i_opts.pathlist.count = filelist.length;
+
+	i_opts.start = "b";
+	i_opts.end = "k/D";
+
+	/* (c D e k/1 k/a ==> 5) vs (c e k/1 ==> 3) */
+	expect = default_icase ? 5 : 3;
+
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
+	expect_iterator_items(i, expect, NULL, expect, NULL);
+	git_iterator_free(i);
+
+	git_index_free(index);
+	git_vector_free(&filelist);
+}
+
+void test_repo_iterator__indexfilelist_3(void)
+{
+	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
+	git_index *index;
+	git_vector filelist = GIT_VECTOR_INIT;
+	int default_icase, expect;
+
+	g_repo = cl_git_sandbox_init("icase");
+
+	cl_git_pass(git_repository_index(&index, g_repo));
+
+	cl_git_pass(git_vector_init(&filelist, 100, &git__strcmp_cb));
+	cl_git_pass(git_vector_insert(&filelist, "0"));
+	cl_git_pass(git_vector_insert(&filelist, "c"));
+	cl_git_pass(git_vector_insert(&filelist, "D"));
+	cl_git_pass(git_vector_insert(&filelist, "e"));
+	cl_git_pass(git_vector_insert(&filelist, "k/"));
+	cl_git_pass(git_vector_insert(&filelist, "k.a"));
+	cl_git_pass(git_vector_insert(&filelist, "k.b"));
+	cl_git_pass(git_vector_insert(&filelist, "kZZZZZZZ"));
+
+	/* In this test we DO NOT force a case setting on the index. */
+	default_icase = ((git_index_caps(index) & GIT_INDEXCAP_IGNORE_CASE) != 0);
+
+	i_opts.pathlist.strings = (char **)filelist.contents;
+	i_opts.pathlist.count = filelist.length;
+
+	i_opts.start = "b";
+	i_opts.end = "k/D";
+
+	/* (c D e k/1 k/a k/B k/c k/D) vs (c e k/1 k/B k/D) */
+	expect = default_icase ? 8 : 5;
+
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
+	expect_iterator_items(i, expect, NULL, expect, NULL);
+	git_iterator_free(i);
+
+	git_index_free(index);
+	git_vector_free(&filelist);
+}
+
+void test_repo_iterator__indexfilelist_4(void)
+{
+	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
+	git_index *index;
+	git_vector filelist = GIT_VECTOR_INIT;
+	int default_icase, expect;
+
+	g_repo = cl_git_sandbox_init("icase");
+
+	cl_git_pass(git_repository_index(&index, g_repo));
+
+	cl_git_pass(git_vector_init(&filelist, 100, &git__strcmp_cb));
+	cl_git_pass(git_vector_insert(&filelist, "0"));
+	cl_git_pass(git_vector_insert(&filelist, "c"));
+	cl_git_pass(git_vector_insert(&filelist, "D"));
+	cl_git_pass(git_vector_insert(&filelist, "e"));
+	cl_git_pass(git_vector_insert(&filelist, "k"));
+	cl_git_pass(git_vector_insert(&filelist, "k.a"));
+	cl_git_pass(git_vector_insert(&filelist, "k.b"));
+	cl_git_pass(git_vector_insert(&filelist, "kZZZZZZZ"));
+
+	/* In this test we DO NOT force a case setting on the index. */
+	default_icase = ((git_index_caps(index) & GIT_INDEXCAP_IGNORE_CASE) != 0);
+
+	i_opts.pathlist.strings = (char **)filelist.contents;
+	i_opts.pathlist.count = filelist.length;
+
+	i_opts.start = "b";
+	i_opts.end = "k/D";
+
+	/* (c D e k/1 k/a k/B k/c k/D) vs (c e k/1 k/B k/D) */
+	expect = default_icase ? 8 : 5;
+
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
+	expect_iterator_items(i, expect, NULL, expect, NULL);
+	git_iterator_free(i);
+
+	git_index_free(index);
+	git_vector_free(&filelist);
+}
+
+void test_repo_iterator__indexfilelist_icase(void)
+{
+	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
+	git_index *index;
+	int caps;
+	git_vector filelist;
+
+	cl_git_pass(git_vector_init(&filelist, 100, &git__strcmp_cb));
+	cl_git_pass(git_vector_insert(&filelist, "a"));
+	cl_git_pass(git_vector_insert(&filelist, "B"));
+	cl_git_pass(git_vector_insert(&filelist, "c"));
+	cl_git_pass(git_vector_insert(&filelist, "D"));
+	cl_git_pass(git_vector_insert(&filelist, "e"));
+	cl_git_pass(git_vector_insert(&filelist, "k/1"));
+	cl_git_pass(git_vector_insert(&filelist, "k/a"));
+	cl_git_pass(git_vector_insert(&filelist, "L/1"));
+
+	g_repo = cl_git_sandbox_init("icase");
+
+	cl_git_pass(git_repository_index(&index, g_repo));
+	caps = git_index_caps(index);
+
+	/* force case sensitivity */
+	cl_git_pass(git_index_set_caps(index, caps & ~GIT_INDEXCAP_IGNORE_CASE));
+
+	/* All indexfilelist iterator tests are "autoexpand with no tree entries" */
+
+	i_opts.pathlist.strings = (char **)filelist.contents;
+	i_opts.pathlist.count = filelist.length;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
+	expect_iterator_items(i, 3, NULL, 3, NULL);
+	git_iterator_free(i);
+
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
+	expect_iterator_items(i, 1, NULL, 1, NULL);
+	git_iterator_free(i);
+
+	/* force case insensitivity */
+	cl_git_pass(git_index_set_caps(index, caps | GIT_INDEXCAP_IGNORE_CASE));
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
+	expect_iterator_items(i, 5, NULL, 5, NULL);
+	git_iterator_free(i);
+
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_index(&i, index, &i_opts));
+	expect_iterator_items(i, 2, NULL, 2, NULL);
+	git_iterator_free(i);
+
+	cl_git_pass(git_index_set_caps(index, caps));
+	git_index_free(index);
+	git_vector_free(&filelist);
+}
+
+void test_repo_iterator__workdirfilelist(void)
+{
+	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
+	git_vector filelist;
+	bool default_icase;
+	int expect;
+
+	cl_git_pass(git_vector_init(&filelist, 100, &git__strcmp_cb));
+	cl_git_pass(git_vector_insert(&filelist, "a"));
+	cl_git_pass(git_vector_insert(&filelist, "B"));
+	cl_git_pass(git_vector_insert(&filelist, "c"));
+	cl_git_pass(git_vector_insert(&filelist, "D"));
+	cl_git_pass(git_vector_insert(&filelist, "e"));
+	cl_git_pass(git_vector_insert(&filelist, "k.a"));
+	cl_git_pass(git_vector_insert(&filelist, "k.b"));
+	cl_git_pass(git_vector_insert(&filelist, "k/1"));
+	cl_git_pass(git_vector_insert(&filelist, "k/a"));
+	cl_git_pass(git_vector_insert(&filelist, "kZZZZZZZ"));
+	cl_git_pass(git_vector_insert(&filelist, "L/1"));
+
+	g_repo = cl_git_sandbox_init("icase");
+
+	/* All indexfilelist iterator tests are "autoexpand with no tree entries" */
+	/* In this test we DO NOT force a case on the iteratords and verify default behavior. */
+
+	i_opts.pathlist.strings = (char **)filelist.contents;
+	i_opts.pathlist.count = filelist.length;
+
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
+	expect_iterator_items(i, 8, NULL, 8, NULL);
+	git_iterator_free(i);
+
+	i_opts.start = "c";
+	i_opts.end = NULL;
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
+	default_icase = git_iterator_ignore_case(i);
+	/* (c D e k/1 k/a L ==> 6) vs (c e k/1 k/a ==> 4) */
+	expect = ((default_icase) ? 6 : 4);
+	expect_iterator_items(i, expect, NULL, expect, NULL);
+	git_iterator_free(i);
+
+	i_opts.start = NULL;
+	i_opts.end = "e";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
+	default_icase = git_iterator_ignore_case(i);
+	/* (a B c D e ==> 5) vs (B D L/1 a c e ==> 6) */
+	expect = ((default_icase) ? 5 : 6);
+	expect_iterator_items(i, expect, NULL, expect, NULL);
+	git_iterator_free(i);
+
+	git_vector_free(&filelist);
+}
+
+void test_repo_iterator__workdirfilelist_icase(void)
+{
+	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
+	git_vector filelist;
+
+	cl_git_pass(git_vector_init(&filelist, 100, &git__strcmp_cb));
+	cl_git_pass(git_vector_insert(&filelist, "a"));
+	cl_git_pass(git_vector_insert(&filelist, "B"));
+	cl_git_pass(git_vector_insert(&filelist, "c"));
+	cl_git_pass(git_vector_insert(&filelist, "D"));
+	cl_git_pass(git_vector_insert(&filelist, "e"));
+	cl_git_pass(git_vector_insert(&filelist, "k.a"));
+	cl_git_pass(git_vector_insert(&filelist, "k.b"));
+	cl_git_pass(git_vector_insert(&filelist, "k/1"));
+	cl_git_pass(git_vector_insert(&filelist, "k/a"));
+	cl_git_pass(git_vector_insert(&filelist, "kZZZZ"));
+	cl_git_pass(git_vector_insert(&filelist, "L/1"));
+
+	g_repo = cl_git_sandbox_init("icase");
+
+	i_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+	i_opts.pathlist.strings = (char **)filelist.contents;
+	i_opts.pathlist.count = filelist.length;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
+	expect_iterator_items(i, 3, NULL, 3, NULL);
+	git_iterator_free(i);
+
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
+	expect_iterator_items(i, 1, NULL, 1, NULL);
+	git_iterator_free(i);
+
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
+	expect_iterator_items(i, 5, NULL, 5, NULL);
+	git_iterator_free(i);
+
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_workdir(&i, g_repo, NULL, NULL, &i_opts));
+	expect_iterator_items(i, 2, NULL, 2, NULL);
+	git_iterator_free(i);
+
+	git_vector_free(&filelist);
+}
+
+void test_repo_iterator__treefilelist(void)
+{
+	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
+	git_vector filelist;
+	git_tree *tree;
+	bool default_icase;
+	int expect;
+
+	cl_git_pass(git_vector_init(&filelist, 100, &git__strcmp_cb));
+	cl_git_pass(git_vector_insert(&filelist, "a"));
+	cl_git_pass(git_vector_insert(&filelist, "B"));
+	cl_git_pass(git_vector_insert(&filelist, "c"));
+	cl_git_pass(git_vector_insert(&filelist, "D"));
+	cl_git_pass(git_vector_insert(&filelist, "e"));
+	cl_git_pass(git_vector_insert(&filelist, "k.a"));
+	cl_git_pass(git_vector_insert(&filelist, "k.b"));
+	cl_git_pass(git_vector_insert(&filelist, "k/1"));
+	cl_git_pass(git_vector_insert(&filelist, "k/a"));
+	cl_git_pass(git_vector_insert(&filelist, "kZZZZZZZ"));
+	cl_git_pass(git_vector_insert(&filelist, "L/1"));
+
+	g_repo = cl_git_sandbox_init("icase");
+	git_repository_head_tree(&tree, g_repo);
+
+	/* All indexfilelist iterator tests are "autoexpand with no tree entries" */
+	/* In this test we DO NOT force a case on the iteratords and verify default behavior. */
+
+	i_opts.pathlist.strings = (char **)filelist.contents;
+	i_opts.pathlist.count = filelist.length;
+
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
+	expect_iterator_items(i, 8, NULL, 8, NULL);
+	git_iterator_free(i);
+
+	i_opts.start = "c";
+	i_opts.end = NULL;
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
+	default_icase = git_iterator_ignore_case(i);
+	/* (c D e k/1 k/a L ==> 6) vs (c e k/1 k/a ==> 4) */
+	expect = ((default_icase) ? 6 : 4);
+	expect_iterator_items(i, expect, NULL, expect, NULL);
+	git_iterator_free(i);
+
+	i_opts.start = NULL;
+	i_opts.end = "e";
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
+	default_icase = git_iterator_ignore_case(i);
+	/* (a B c D e ==> 5) vs (B D L/1 a c e ==> 6) */
+	expect = ((default_icase) ? 5 : 6);
+	expect_iterator_items(i, expect, NULL, expect, NULL);
+	git_iterator_free(i);
+
+	git_vector_free(&filelist);
+	git_tree_free(tree);
+}
+
+void test_repo_iterator__treefilelist_icase(void)
+{
+	git_iterator *i;
+	git_iterator_options i_opts = GIT_ITERATOR_OPTIONS_INIT;
+	git_vector filelist;
+	git_tree *tree;
+
+	cl_git_pass(git_vector_init(&filelist, 100, &git__strcmp_cb));
+	cl_git_pass(git_vector_insert(&filelist, "a"));
+	cl_git_pass(git_vector_insert(&filelist, "B"));
+	cl_git_pass(git_vector_insert(&filelist, "c"));
+	cl_git_pass(git_vector_insert(&filelist, "D"));
+	cl_git_pass(git_vector_insert(&filelist, "e"));
+	cl_git_pass(git_vector_insert(&filelist, "k.a"));
+	cl_git_pass(git_vector_insert(&filelist, "k.b"));
+	cl_git_pass(git_vector_insert(&filelist, "k/1"));
+	cl_git_pass(git_vector_insert(&filelist, "k/a"));
+	cl_git_pass(git_vector_insert(&filelist, "kZZZZ"));
+	cl_git_pass(git_vector_insert(&filelist, "L/1"));
+
+	g_repo = cl_git_sandbox_init("icase");
+	git_repository_head_tree(&tree, g_repo);
+
+	i_opts.flags = GIT_ITERATOR_DONT_IGNORE_CASE;
+	i_opts.pathlist.strings = (char **)filelist.contents;
+	i_opts.pathlist.count = filelist.length;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
+	expect_iterator_items(i, 3, NULL, 3, NULL);
+	git_iterator_free(i);
+
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
+	expect_iterator_items(i, 1, NULL, 1, NULL);
+	git_iterator_free(i);
+
+	i_opts.flags = GIT_ITERATOR_IGNORE_CASE;
+
+	i_opts.start = "c";
+	i_opts.end = "k/D";
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
+	expect_iterator_items(i, 5, NULL, 5, NULL);
+	git_iterator_free(i);
+
+	i_opts.start = "k";
+	i_opts.end = "k/Z";
+	cl_git_pass(git_iterator_for_tree(&i, tree, &i_opts));
+	expect_iterator_items(i, 2, NULL, 2, NULL);
+	git_iterator_free(i);
+
+	git_vector_free(&filelist);
+	git_tree_free(tree);
+}
diff --git a/tests/status/worktree_init.c b/tests/status/worktree_init.c
index cc7e126f1..9d5cfa5a3 100644
--- a/tests/status/worktree_init.c
+++ b/tests/status/worktree_init.c
@@ -191,10 +191,10 @@ void test_status_worktree_init__bracket_in_filename(void)
 	cl_git_pass(git_status_file(&status_flags, repo, FILE_WITHOUT_BRACKET));
 	cl_assert(status_flags == GIT_STATUS_WT_NEW);
 
-	cl_git_pass(git_status_file(&status_flags, repo, "LICENSE\\[1\\].md"));
-	cl_assert(status_flags == GIT_STATUS_INDEX_NEW);
+	cl_git_fail_with(git_status_file(&status_flags, repo, "LICENSE\\[1\\].md"), GIT_ENOTFOUND);
 
 	cl_git_pass(git_status_file(&status_flags, repo, FILE_WITH_BRACKET));
+	cl_assert(status_flags == GIT_STATUS_INDEX_NEW);
 
 	git_index_free(index);
 	git_repository_free(repo);
diff --git a/tests/submodule/status.c b/tests/submodule/status.c
index 6721ee92a..5f4e62053 100644
--- a/tests/submodule/status.c
+++ b/tests/submodule/status.c
@@ -264,6 +264,7 @@ static int confirm_submodule_status(
 void test_submodule_status__iterator(void)
 {
 	git_iterator *iter;
+	git_iterator_options iter_opts = GIT_ITERATOR_OPTIONS_INIT;
 	const git_index_entry *entry;
 	size_t i;
 	static const char *expected[] = {
@@ -308,9 +309,10 @@ void test_submodule_status__iterator(void)
 	git_status_options opts = GIT_STATUS_OPTIONS_INIT;
 	git_index *index;
 
+	iter_opts.flags = GIT_ITERATOR_IGNORE_CASE | GIT_ITERATOR_INCLUDE_TREES;
+
 	cl_git_pass(git_repository_index(&index, g_repo));
-	cl_git_pass(git_iterator_for_workdir(&iter, g_repo, index, NULL,
-		GIT_ITERATOR_IGNORE_CASE | GIT_ITERATOR_INCLUDE_TREES, NULL, NULL));
+	cl_git_pass(git_iterator_for_workdir(&iter, g_repo, index, NULL, &iter_opts));
 
 	for (i = 0; !git_iterator_advance(&entry, iter); ++i)
 		cl_assert_equal_s(expected[i], entry->path);
diff --git a/tests/threads/iterator.c b/tests/threads/iterator.c
index 8a2d79c2e..6b86cf1a0 100644
--- a/tests/threads/iterator.c
+++ b/tests/threads/iterator.c
@@ -13,10 +13,13 @@ static void *run_workdir_iterator(void *arg)
 {
 	int error = 0;
 	git_iterator *iter;
+	git_iterator_options iter_opts = GIT_ITERATOR_OPTIONS_INIT;
 	const git_index_entry *entry = NULL;
 
+	iter_opts.flags = GIT_ITERATOR_DONT_AUTOEXPAND;
+
 	cl_git_pass(git_iterator_for_workdir(
-		&iter, _repo, NULL, NULL, GIT_ITERATOR_DONT_AUTOEXPAND, NULL, NULL));
+		&iter, _repo, NULL, NULL, &iter_opts));
 
 	while (!error) {
 		if (entry && entry->mode == GIT_FILEMODE_TREE) {