Improve docs, examples, warnings

This improves docs in some of the public header files, cleans
up and improves some of the example code, and fixes a couple
of pedantic warnings in places.

examples/Makefile

 .PHONY: all
 
 CC = gcc
-CFLAGS = -g -I../include -I../src
+CFLAGS = -g -I../include -I../src -Wall -Wextra -Wmissing-prototypes
 LFLAGS = -L../build -lgit2 -lz
 APPS = general showindex diff
 

examples/diff.c

@@ -3,7 +3,7 @@
 #include <stdlib.h>
 #include <string.h>
 
-void check(int error, const char *message)
+static void check(int error, const char *message)
 {
 	if (error) {
 		fprintf(stderr, "%s (%d)\n", message, error);
@@ -11,7 +11,8 @@ void check(int error, const char *message)
 	}
 }
 
-int resolve_to_tree(git_repository *repo, const char *identifier, git_tree **tree)
+static int resolve_to_tree(
+	git_repository *repo, const char *identifier, git_tree **tree)
 {
 	int err = 0;
 	size_t len = strlen(identifier);
@@ -61,16 +62,18 @@ char *colors[] = {
 	"\033[36m" /* cyan */
 };
 
-int printer(
+static int printer(
 	void *data,
-	git_diff_delta *delta,
-	git_diff_range *range,
+	const git_diff_delta *delta,
+	const git_diff_range *range,
 	char usage,
 	const char *line,
 	size_t line_len)
 {
 	int *last_color = data, color = 0;
 
+	(void)delta; (void)range; (void)line_len;
+
 	if (*last_color >= 0) {
 		switch (usage) {
 		case GIT_DIFF_LINE_ADDITION: color = 3; break;
@@ -93,7 +96,7 @@ int printer(
 	return 0;
 }
 
-int check_uint16_param(const char *arg, const char *pattern, uint16_t *val)
+static int check_uint16_param(const char *arg, const char *pattern, uint16_t *val)
 {
 	size_t len = strlen(pattern);
 	uint16_t strval;
@@ -107,7 +110,7 @@ int check_uint16_param(const char *arg, const char *pattern, uint16_t *val)
 	return 1;
 }
 
-int check_str_param(const char *arg, const char *pattern, char **val)
+static int check_str_param(const char *arg, const char *pattern, char **val)
 {
 	size_t len = strlen(pattern);
 	if (strncmp(arg, pattern, len))
@@ -116,7 +119,7 @@ int check_str_param(const char *arg, const char *pattern, char **val)
 	return 1;
 }
 
-void usage(const char *message, const char *arg)
+static void usage(const char *message, const char *arg)
 {
 	if (message && arg)
 		fprintf(stderr, "%s: %s\n", message, arg);
@@ -128,14 +131,15 @@ void usage(const char *message, const char *arg)
 
 int main(int argc, char *argv[])
 {
-	char path[GIT_PATH_MAX];
 	git_repository *repo = NULL;
 	git_tree *t1 = NULL, *t2 = NULL;
-	git_diff_options opts = {0};
+	git_diff_options opts;
 	git_diff_list *diff;
 	int i, color = -1, compact = 0, cached = 0;
 	char *a, *dir = ".", *treeish1 = NULL, *treeish2 = NULL;
 
+	memset(&opts, 0, sizeof(opts));
+
 	/* parse arguments as copied from git-diff */
 
 	for (i = 1; i < argc; ++i) {

examples/showindex.c

@@ -5,24 +5,34 @@ int main (int argc, char** argv)
 {
 	git_repository *repo;
 	git_index *index;
-  unsigned int i, e, ecount;
-  git_index_entry **entries;
-  git_oid oid;
-
+	unsigned int i, ecount;
+	char *dir = ".";
 	char out[41];
 	out[40] = '\0';
 
-  git_repository_open(&repo, "/opt/libgit2-test/.git");
+	if (argc > 1)
+		dir = argv[1];
+	if (argc > 2) {
+		fprintf(stderr, "usage: showindex [<repo-dir>]\n");
+		return 1;
+	}
+
+	if (git_repository_open_ext(&repo, dir, 0, NULL) < 0) {
+		fprintf(stderr, "could not open repository: %s\n", dir);
+		return 1;
+	}
 
 	git_repository_index(&index, repo);
 	git_index_read(index);
 
 	ecount = git_index_entrycount(index);
+	if (!ecount)
+		printf("Empty index\n");
+
 	for (i = 0; i < ecount; ++i) {
-    git_index_entry *e = git_index_get_byindex(index, i);
+		const git_index_entry *e = git_index_get_byindex(index, i);
 
-    oid = e->oid;
-    git_oid_fmt(out, &oid);
+		git_oid_fmt(out, &e->oid);
 
 		printf("File Path: %s\n", e->path);
 		printf("    Stage: %d\n", git_index_entry_stage(e));
@@ -38,7 +48,8 @@ int main (int argc, char** argv)
 	}
 
 	git_index_free(index);
-
 	git_repository_free(repo);
+
+	return 0;
 }
 

include/git2/status.h

@@ -19,6 +19,16 @@
  */
 GIT_BEGIN_DECL
 
+/**
+ * Status flags for a single file.
+ *
+ * A combination of these values will be returned to indicate the status of
+ * a file.  Status compares the working directory, the index, and the
+ * current HEAD of the repository.  The `GIT_STATUS_INDEX` set of flags
+ * represents the status of file in the index relative to the HEAD, and the
+ * `GIT_STATUS_WT` set of flags represent the status of the file in the
+ * working directory relative to the index.
+ */
 typedef enum {
 	GIT_STATUS_CURRENT = 0,
 
@@ -39,12 +49,16 @@ typedef enum {
 /**
  * Gather file statuses and run a callback for each one.
  *
- * The callback is passed the path of the file, the status and the data
- * pointer passed to this function. If the callback returns something other
- * than 0, this function will stop looping and return GIT_EUSER.
+ * The callback is passed the path of the file, the status (a combination of
+ * the `git_status_t` values above) and the `payload` data pointer passed
+ * into this function.
+ *
+ * If the callback returns a non-zero value, this function will stop looping
+ * and return GIT_EUSER.
  *
- * @param repo a repository object
- * @param callback the function to call on each file
+ * @param repo A repository object
+ * @param callback The function to call on each file
+ * @param payload Pointer to pass through to callback function
  * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_status_foreach(
@@ -53,7 +67,7 @@ GIT_EXTERN(int) git_status_foreach(
 	void *payload);
 
 /**
- * Select the files on which to report status.
+ * For extended status, select the files on which to report status.
  *
  * - GIT_STATUS_SHOW_INDEX_AND_WORKDIR is the default.  This is the
  *   rough equivalent of `git status --porcelain` where each file
@@ -81,40 +95,55 @@ typedef enum {
 /**
  * Flags to control status callbacks
  *
- * - GIT_STATUS_OPT_INCLUDE_UNTRACKED says that callbacks should
- *   be made on untracked files.  These will only be made if the
- *   workdir files are included in the status "show" option.
- * - GIT_STATUS_OPT_INCLUDE_IGNORED says that ignored files should
- *   get callbacks.  Again, these callbacks will only be made if
- *   the workdir files are included in the status "show" option.
- *   Right now, there is no option to include all files in
- *   directories that are ignored completely.
- * - GIT_STATUS_OPT_INCLUDE_UNMODIFIED indicates that callback
- *   should be made even on unmodified files.
- * - GIT_STATUS_OPT_EXCLUDE_SUBMODULES indicates that directories
- *   which appear to be submodules should just be skipped over.
- * - GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS indicates that the
- *   contents of untracked directories should be included in the
- *   status.  Normally if an entire directory is new, then just
- *   the top-level directory will be included (with a trailing
- *   slash on the entry name).  Given this flag, the directory
- *   itself will not be included, but all the files in it will.
- * - GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH indicates that the given
- *   path will be treated as a literal path, and not as a pathspec.
+ * - GIT_STATUS_OPT_INCLUDE_UNTRACKED says that callbacks should be made
+ *   on untracked files.  These will only be made if the workdir files are
+ *   included in the status "show" option.
+ * - GIT_STATUS_OPT_INCLUDE_IGNORED says that ignored files should get
+ *   callbacks.  Again, these callbacks will only be made if the workdir
+ *   files are included in the status "show" option.  Right now, there is
+ *   no option to include all files in directories that are ignored
+ *   completely.
+ * - GIT_STATUS_OPT_INCLUDE_UNMODIFIED indicates that callback should be
+ *   made even on unmodified files.
+ * - GIT_STATUS_OPT_EXCLUDE_SUBMODULES indicates that directories which
+ *   appear to be submodules should just be skipped over.
+ * - GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS indicates that the contents of
+ *   untracked directories should be included in the status.  Normally if
+ *   an entire directory is new, then just the top-level directory will be
+ *   included (with a trailing slash on the entry name).  Given this flag,
+ *   the directory itself will not be included, but all the files in it
+ *   will.
+ * - GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH indicates that the given path
+ *   will be treated as a literal path, and not as a pathspec.
+ *
+ * Calling `git_status_foreach()` is like calling the extended version
+ * with: GIT_STATUS_OPT_INCLUDE_IGNORED, GIT_STATUS_OPT_INCLUDE_UNTRACKED,
+ * and GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS.
  */
-
-enum {
+typedef enum {
 	GIT_STATUS_OPT_INCLUDE_UNTRACKED = (1 << 0),
 	GIT_STATUS_OPT_INCLUDE_IGNORED = (1 << 1),
 	GIT_STATUS_OPT_INCLUDE_UNMODIFIED = (1 << 2),
 	GIT_STATUS_OPT_EXCLUDE_SUBMODULES = (1 << 3),
 	GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS = (1 << 4),
 	GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH = (1 << 5),
-};
+} git_status_opt_t;
 
 /**
- * Options to control how callbacks will be made by
- * `git_status_foreach_ext()`.
+ * Options to control how `git_status_foreach_ext()` will issue callbacks.
+ *
+ * This structure is set so that zeroing it out will give you relatively
+ * sane defaults.
+ *
+ * The `show` value is one of the `git_status_show_t` constants that
+ * control which files to scan and in what order.
+ *
+ * The `flags` value is an OR'ed combination of the `git_status_opt_t`
+ * values above.
+ *
+ * The `pathspec` is an array of path patterns to match (using
+ * fnmatch-style matching), or just an array of paths to match exactly if
+ * `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified in the flags.
  */
 typedef struct {
 	git_status_show_t show;
@@ -124,6 +153,17 @@ typedef struct {
 
 /**
  * Gather file status information and run callbacks as requested.
+ *
+ * This is an extended version of the `git_status_foreach()` API that
+ * allows for more granular control over which paths will be processed and
+ * in what order.  See the `git_status_options` structure for details
+ * about the additional controls that this makes available.
+ *
+ * @param repo Repository object
+ * @param opts Status options structure
+ * @param callback The function to call on each file
+ * @param payload Pointer to pass through to callback function
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_status_foreach_ext(
 	git_repository *repo,
@@ -132,14 +172,17 @@ GIT_EXTERN(int) git_status_foreach_ext(
 	void *payload);
 
 /**
- * Get file status for a single file
- *
- * @param status_flags the status value
- * @param repo a repository object
- * @param path the file to retrieve status for, rooted at the repo's workdir
- * @return GIT_EINVALIDPATH when `path` points at a folder, GIT_ENOTFOUND when
- *		the file doesn't exist in any of HEAD, the index or the worktree,
- *		0 otherwise
+ * Get file status for a single file.
+ *
+ * This is not quite the same as calling `git_status_foreach_ext()` with
+ * the pathspec set to the specified path.
+ *
+ * @param status_flags The status value for the file
+ * @param repo A repository object
+ * @param path The file to retrieve status for, rooted at the repo's workdir
+ * @return 0 on success, GIT_ENOTFOUND if the file is not found in the HEAD,
+ *      index, and work tree, GIT_EINVALIDPATH if `path` points at a folder,
+ *      GIT_EAMBIGUOUS if "path" matches multiple files, -1 on other error.
  */
 GIT_EXTERN(int) git_status_file(
 	unsigned int *status_flags,
@@ -156,9 +199,9 @@ GIT_EXTERN(int) git_status_file(
  * One way to think of this is if you were to do "git add ." on the
  * directory containing the file, would it be added or not?
  *
- * @param ignored boolean returning 0 if the file is not ignored, 1 if it is
- * @param repo a repository object
- * @param path the file to check ignores for, rooted at the repo's workdir.
+ * @param ignored Boolean returning 0 if the file is not ignored, 1 if it is
+ * @param repo A repository object
+ * @param path The file to check ignores for, rooted at the repo's workdir.
  * @return 0 if ignore rules could be processed for the file (regardless
  *         of whether it exists or not), or an error < 0 if they could not.
  */

tests-clar/network/fetch.c

@@ -18,10 +18,7 @@ void test_network_fetch__cleanup(void)
 
 static int update_tips(const char *refname, const git_oid *a, const git_oid *b, void *data)
 {
-	refname = refname;
-	a = a;
-	b = b;
-	data = data;
+	GIT_UNUSED(refname); GIT_UNUSED(a); GIT_UNUSED(b); GIT_UNUSED(data);
 
 	++counter;