Add git_treebuilder_insert test and clarify doc

This wasn't being tested and since it has a callback, I fixed it
even though the return value of this callback is not treated like
any of the other callbacks in the API.

include/git2/tree.h

@@ -332,11 +332,18 @@ GIT_EXTERN(int) git_treebuilder_insert(
 GIT_EXTERN(int) git_treebuilder_remove(
 	git_treebuilder *bld, const char *filename);
 
+/**
+ * Callback for git_treebuilder_filter
+ *
+ * The return value is treated as a boolean, with zero indicating that the
+ * entry should be left alone and any non-zero value meaning that the
+ * entry should be removed from the treebuilder list (i.e. filtered out).
+ */
 typedef int (*git_treebuilder_filter_cb)(
 	const git_tree_entry *entry, void *payload);
 
 /**
- * Filter the entries in the tree
+ * Selectively remove entries in the tree
  *
  * The `filter` callback will be called for each entry in the tree with a
  * pointer to the entry and the provided `payload`; if the callback returns
@@ -344,7 +351,7 @@ typedef int (*git_treebuilder_filter_cb)(
  *
  * @param bld Tree builder
  * @param filter Callback to filter entries
- * @param payload Extra data to pass to filter
+ * @param payload Extra data to pass to filter callback
  */
 GIT_EXTERN(void) git_treebuilder_filter(
 	git_treebuilder *bld,

tests/object/tree/write.c

@@ -164,16 +164,10 @@ void test_object_tree_write__sorted_subtrees(void)
 	git_treebuilder_free(builder);
 }
 
-void test_object_tree_write__removing_and_re_adding_in_treebuilder(void)
-{
-	git_treebuilder *builder;
-	int i,  aardvark_i, apple_i, apple_after_i, apple_extra_i, last_i;
-	git_oid blank_oid, tree_oid;
-	git_tree *tree;
-	struct {
+static struct {
 	unsigned int attr;
 	const char *filename;
-	} entries[] = {
+} _entries[] = {
 	{ GIT_FILEMODE_BLOB, "aardvark" },
 	{ GIT_FILEMODE_BLOB, ".first" },
 	{ GIT_FILEMODE_BLOB, "apple" },
@@ -181,7 +175,14 @@ void test_object_tree_write__removing_and_re_adding_in_treebuilder(void)
 	{ GIT_FILEMODE_BLOB, "apple_after"},
 	{ GIT_FILEMODE_BLOB, "after_aardvark"},
 	{ 0, NULL },
-	};
+};
+
+void test_object_tree_write__removing_and_re_adding_in_treebuilder(void)
+{
+	git_treebuilder *builder;
+	int i, aardvark_i, apple_i, apple_after_i, apple_extra_i, last_i;
+	git_oid blank_oid, tree_oid;
+	git_tree *tree;
 
 	memset(&blank_oid, 0x0, sizeof(blank_oid));
 
@@ -189,9 +190,9 @@ void test_object_tree_write__removing_and_re_adding_in_treebuilder(void)
 
 	cl_assert_equal_i(0, (int)git_treebuilder_entrycount(builder));
 
-	for (i = 0; entries[i].filename; ++i)
+	for (i = 0; _entries[i].filename; ++i)
 		cl_git_pass(git_treebuilder_insert(NULL,
-			builder, entries[i].filename, &blank_oid, entries[i].attr));
+			builder, _entries[i].filename, &blank_oid, _entries[i].attr));
 
 	cl_assert_equal_i(6, (int)git_treebuilder_entrycount(builder));
 
@@ -260,3 +261,56 @@ void test_object_tree_write__removing_and_re_adding_in_treebuilder(void)
 
 	git_tree_free(tree);
 }
+
+static int treebuilder_filter_prefixed(
+	const git_tree_entry *entry, void *payload)
+{
+	return !git__prefixcmp(git_tree_entry_name(entry), payload);
+}
+
+void test_object_tree_write__filtering(void)
+{
+	git_treebuilder *builder;
+	int i;
+	git_oid blank_oid, tree_oid;
+	git_tree *tree;
+
+	memset(&blank_oid, 0x0, sizeof(blank_oid));
+
+	cl_git_pass(git_treebuilder_create(&builder, NULL));
+
+	for (i = 0; _entries[i].filename; ++i)
+		cl_git_pass(git_treebuilder_insert(NULL,
+			builder, _entries[i].filename, &blank_oid, _entries[i].attr));
+
+	cl_assert_equal_i(6, (int)git_treebuilder_entrycount(builder));
+
+	cl_assert(git_treebuilder_get(builder, "apple") != NULL);
+	cl_assert(git_treebuilder_get(builder, "aardvark") != NULL);
+	cl_assert(git_treebuilder_get(builder, "last") != NULL);
+
+	git_treebuilder_filter(builder, treebuilder_filter_prefixed, "apple");
+
+	cl_assert_equal_i(4, (int)git_treebuilder_entrycount(builder));
+
+	cl_assert(git_treebuilder_get(builder, "apple") == NULL);
+	cl_assert(git_treebuilder_get(builder, "aardvark") != NULL);
+	cl_assert(git_treebuilder_get(builder, "last") != NULL);
+
+	git_treebuilder_filter(builder, treebuilder_filter_prefixed, "a");
+
+	cl_assert_equal_i(2, (int)git_treebuilder_entrycount(builder));
+
+	cl_assert(git_treebuilder_get(builder, "aardvark") == NULL);
+	cl_assert(git_treebuilder_get(builder, "last") != NULL);
+
+	cl_git_pass(git_treebuilder_write(&tree_oid, g_repo, builder));
+
+	git_treebuilder_free(builder);
+
+	cl_git_pass(git_tree_lookup(&tree, g_repo, &tree_oid));
+
+	cl_assert_equal_i(2, (int)git_tree_entrycount(tree));
+
+	git_tree_free(tree);
+}