More external API cleanupmore-api-tweaks

8 files changed, 78 insertions, 52 deletions

diff --git a/include/git2/attr.h b/include/git2/attr.h
index 2de9f4b0e..b1a7e0eb6 100644
--- a/include/git2/attr.h
+++ b/include/git2/attr.h
@@ -183,6 +183,8 @@ GIT_EXTERN(int) git_attr_get_many(
 	size_t num_attr,
 	const char **names);
 
+typedef int (*git_attr_foreach_cb)(const char *name, const char *value, void *payload);
+
 /**
  * Loop over all the git attributes for a path.
  *
@@ -204,7 +206,7 @@ GIT_EXTERN(int) git_attr_foreach(
 	git_repository *repo,
 	uint32_t flags,
 	const char *path,
-	int (*callback)(const char *name, const char *value, void *payload),
+	git_attr_foreach_cb callback,
 	void *payload);
 
 /**
diff --git a/include/git2/blob.h b/include/git2/blob.h
index f0719f15d..a68c78b5a 100644
--- a/include/git2/blob.h
+++ b/include/git2/blob.h
@@ -68,6 +68,17 @@ GIT_INLINE(void) git_blob_free(git_blob *blob)
 	git_object_free((git_object *) blob);
 }
 
+/**
+ * Get the id of a blob.
+ *
+ * @param blob a previously loaded blob.
+ * @return SHA1 hash for this blob.
+ */
+GIT_INLINE(const git_oid *) git_blob_id(const git_blob *blob)
+{
+	return git_object_id((const git_object *)blob);
+}
+
 
 /**
  * Get a read-only buffer with the raw content of a blob.
@@ -88,32 +99,35 @@ GIT_EXTERN(const void *) git_blob_rawcontent(git_blob *blob);
  * @param blob pointer to the blob
  * @return size on bytes
  */
-GIT_EXTERN(size_t) git_blob_rawsize(git_blob *blob);
+GIT_EXTERN(git_off_t) git_blob_rawsize(git_blob *blob);
 
 /**
  * Read a file from the working folder of a repository
  * and write it to the Object Database as a loose blob
  *
- * @param oid return the id of the written blob
+ * @param id return the id of the written blob
  * @param repo repository where the blob will be written.
  *	this repository cannot be bare
- * @param path file from which the blob will be created,
+ * @param relative_path file from which the blob will be created,
  *	relative to the repository's working dir
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_blob_create_fromfile(git_oid *oid, git_repository *repo, const char *path);
+GIT_EXTERN(int) git_blob_create_fromworkdir(git_oid *id, git_repository *repo, const char *relative_path);
 
 /**
  * Read a file from the filesystem and write its content
  * to the Object Database as a loose blob
  *
- * @param oid return the id of the written blob
+ * @param id return the id of the written blob
  * @param repo repository where the blob will be written.
  *	this repository can be bare or not
  * @param path file from which the blob will be created
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_blob_create_fromdisk(git_oid *oid, git_repository *repo, const char *path);
+GIT_EXTERN(int) git_blob_create_fromdisk(git_oid *id, git_repository *repo, const char *path);
+
+
+typedef int (*git_blob_chunk_cb)(char *content, size_t max_length, void *payload);
 
 /**
  * Write a loose blob to the Object Database from a
@@ -141,7 +155,7 @@ GIT_EXTERN(int) git_blob_create_fromdisk(git_oid *oid, git_repository *repo, con
  *  - When an error occurs, the callback should return -1.
  *
  *
- * @param oid Return the id of the written blob
+ * @param id Return the id of the written blob
  *
  * @param repo repository where the blob will be written.
  * This repository can be bare or not.
@@ -152,10 +166,10 @@ GIT_EXTERN(int) git_blob_create_fromdisk(git_oid *oid, git_repository *repo, con
  * @return GIT_SUCCESS or an error code
  */
 GIT_EXTERN(int) git_blob_create_fromchunks(
-	git_oid *oid,
+	git_oid *id,
 	git_repository *repo,
 	const char *hintpath,
-	int (*source_cb)(char *content, size_t max_length, void *payload),
+	git_blob_chunk_cb callback,
 	void *payload);
 
 /**
diff --git a/include/git2/branch.h b/include/git2/branch.h
index f06609a51..c9ae9cc5d 100644
--- a/include/git2/branch.h
+++ b/include/git2/branch.h
@@ -29,7 +29,7 @@ GIT_BEGIN_DECL
  *
  * The returned reference must be freed by the user.
  *
- * @param branch_out Pointer where to store the underlying reference.
+ * @param out Pointer where to store the underlying reference.
  *
  * @param branch_name Name for the branch; this name is
  * validated for consistency. It should also not conflict with
@@ -47,10 +47,10 @@ GIT_BEGIN_DECL
  * pointing to the provided target commit.
  */
 GIT_EXTERN(int) git_branch_create(
-		git_reference **branch_out,
+		git_reference **out,
 		git_repository *repo,
 		const char *branch_name,
-		const git_object *target,
+		const git_commit *target,
 		int force);
 
 /**
@@ -113,7 +113,7 @@ GIT_EXTERN(int) git_branch_move(
  *
  * The generated reference must be freed by the user.
  *
- * @param branch_out pointer to the looked-up branch reference
+ * @param out pointer to the looked-up branch reference
  *
  * @param repo the repository to look up the branch
  *
@@ -127,7 +127,7 @@ GIT_EXTERN(int) git_branch_move(
  * exists, otherwise an error code.
  */
 GIT_EXTERN(int) git_branch_lookup(
-		git_reference **branch_out,
+		git_reference **out,
 		git_repository *repo,
 		const char *branch_name,
 		git_branch_t branch_type);
@@ -136,7 +136,7 @@ GIT_EXTERN(int) git_branch_lookup(
  * Return the reference supporting the remote tracking branch,
  * given a local branch reference.
  *
- * @param tracking_out Pointer where to store the retrieved
+ * @param out Pointer where to store the retrieved
  * reference.
  *
  * @param branch Current underlying reference of the branch.
@@ -145,7 +145,7 @@ GIT_EXTERN(int) git_branch_lookup(
  * reference exists, otherwise an error code.
  */
 GIT_EXTERN(int) git_branch_tracking(
-		git_reference **tracking_out,
+		git_reference **out,
 		git_reference *branch);
 
 /**
diff --git a/include/git2/checkout.h b/include/git2/checkout.h
index 27ecc7102..bd988db2c 100644
--- a/include/git2/checkout.h
+++ b/include/git2/checkout.h
@@ -146,8 +146,12 @@ typedef enum {
  * Checkout options structure
  *
  * Use zeros to indicate default settings.
+ * This needs to be initialized with the `GIT_CHECKOUT_OPTS_INIT` macro:
+ *
+ *		git_checkout_opts opts = GIT_CHECKOUT_OPTS_INIT;
  */
 typedef struct git_checkout_opts {
+	unsigned int version;
 	unsigned int checkout_strategy; /** default will be a dry run */
 
 	int disable_filters; /** don't apply filters like CRLF conversion */
@@ -182,6 +186,8 @@ typedef struct git_checkout_opts {
 	git_strarray paths;
 } git_checkout_opts;
 
+#define GIT_CHECKOUT_OPTS_INIT {1, 0}
+
 /**
  * Updates files in the index and the working tree to match the content of the
  * commit pointed at by HEAD.
@@ -223,7 +229,7 @@ GIT_EXTERN(int) git_checkout_index(
  */
 GIT_EXTERN(int) git_checkout_tree(
 	git_repository *repo,
-	git_object *treeish,
+	const git_object *treeish,
 	git_checkout_opts *opts);
 
 /** @} */
diff --git a/include/git2/clone.h b/include/git2/clone.h
index 7d8d32118..2a0272339 100644
--- a/include/git2/clone.h
+++ b/include/git2/clone.h
@@ -42,9 +42,9 @@ GIT_EXTERN(int) git_clone(
 		git_repository **out,
 		const char *origin_url,
 		const char *workdir_path,
+		git_checkout_opts *checkout_opts,
 		git_transfer_progress_callback fetch_progress_cb,
-		void *fetch_progress_payload,
-		git_checkout_opts *checkout_opts);
+		void *fetch_progress_payload);
 
 /**
  * Create a bare clone of a remote repository.
diff --git a/include/git2/commit.h b/include/git2/commit.h
index a159b79e1..872f691ce 100644
--- a/include/git2/commit.h
+++ b/include/git2/commit.h
@@ -76,7 +76,10 @@ GIT_INLINE(void) git_commit_free(git_commit *commit)
  * @param commit a previously loaded commit.
  * @return object identity for the commit.
  */
-GIT_EXTERN(const git_oid *) git_commit_id(git_commit *commit);
+GIT_INLINE(const git_oid *) git_commit_id(const git_commit *commit)
+{
+	return git_object_id((const git_object *)commit);
+}
 
 /**
  * Get the encoding for the message of a commit,
@@ -88,7 +91,7 @@ GIT_EXTERN(const git_oid *) git_commit_id(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return NULL, or the encoding
  */
-GIT_EXTERN(const char *) git_commit_message_encoding(git_commit *commit);
+GIT_EXTERN(const char *) git_commit_message_encoding(const git_commit *commit);
 
 /**
  * Get the full message of a commit.
@@ -96,7 +99,7 @@ GIT_EXTERN(const char *) git_commit_message_encoding(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return the message of a commit
  */
-GIT_EXTERN(const char *) git_commit_message(git_commit *commit);
+GIT_EXTERN(const char *) git_commit_message(const git_commit *commit);
 
 /**
  * Get the commit time (i.e. committer time) of a commit.
@@ -104,7 +107,7 @@ GIT_EXTERN(const char *) git_commit_message(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return the time of a commit
  */
-GIT_EXTERN(git_time_t) git_commit_time(git_commit *commit);
+GIT_EXTERN(git_time_t) git_commit_time(const git_commit *commit);
 
 /**
  * Get the commit timezone offset (i.e. committer's preferred timezone) of a commit.
@@ -112,7 +115,7 @@ GIT_EXTERN(git_time_t) git_commit_time(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return positive or negative timezone offset, in minutes from UTC
  */
-GIT_EXTERN(int) git_commit_time_offset(git_commit *commit);
+GIT_EXTERN(int) git_commit_time_offset(const git_commit *commit);
 
 /**
  * Get the committer of a commit.
@@ -120,7 +123,7 @@ GIT_EXTERN(int) git_commit_time_offset(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return the committer of a commit
  */
-GIT_EXTERN(const git_signature *) git_commit_committer(git_commit *commit);
+GIT_EXTERN(const git_signature *) git_commit_committer(const git_commit *commit);
 
 /**
  * Get the author of a commit.
@@ -128,7 +131,7 @@ GIT_EXTERN(const git_signature *) git_commit_committer(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return the author of a commit
  */
-GIT_EXTERN(const git_signature *) git_commit_author(git_commit *commit);
+GIT_EXTERN(const git_signature *) git_commit_author(const git_commit *commit);
 
 /**
  * Get the tree pointed to by a commit.
@@ -137,7 +140,7 @@ GIT_EXTERN(const git_signature *) git_commit_author(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, git_commit *commit);
+GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, const git_commit *commit);
 
 /**
  * Get the id of the tree pointed to by a commit. This differs from
@@ -147,7 +150,7 @@ GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, git_commit *commit);
  * @param commit a previously loaded commit.
  * @return the id of tree pointed to by commit.
  */
-GIT_EXTERN(const git_oid *) git_commit_tree_oid(git_commit *commit);
+GIT_EXTERN(const git_oid *) git_commit_tree_id(const git_commit *commit);
 
 /**
  * Get the number of parents of this commit
@@ -155,17 +158,17 @@ GIT_EXTERN(const git_oid *) git_commit_tree_oid(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return integer of count of parents
  */
-GIT_EXTERN(unsigned int) git_commit_parentcount(git_commit *commit);
+GIT_EXTERN(unsigned int) git_commit_parentcount(const git_commit *commit);
 
 /**
  * Get the specified parent of the commit.
  *
- * @param parent Pointer where to store the parent commit
+ * @param out Pointer where to store the parent commit
  * @param commit a previously loaded commit.
  * @param n the position of the parent (from 0 to `parentcount`)
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_commit_parent(git_commit **parent, git_commit *commit, unsigned int n);
+GIT_EXTERN(int) git_commit_parent(git_commit **out, git_commit *commit, unsigned int n);
 
 /**
  * Get the oid of a specified parent for a commit. This is different from
@@ -176,7 +179,7 @@ GIT_EXTERN(int) git_commit_parent(git_commit **parent, git_commit *commit, unsig
  * @param n the position of the parent (from 0 to `parentcount`)
  * @return the id of the parent, NULL on error.
  */
-GIT_EXTERN(const git_oid *) git_commit_parent_oid(git_commit *commit, unsigned int n);
+GIT_EXTERN(const git_oid *) git_commit_parent_id(git_commit *commit, unsigned int n);
 
 /**
  * Get the commit object that is the <n>th generation ancestor
@@ -204,7 +207,7 @@ GIT_EXTERN(int) git_commit_nth_gen_ancestor(
  * The message will not be cleaned up. This can be achieved
  * through `git_message_prettify()`.
  *
- * @param oid Pointer where to store the OID of the
+ * @param id Pointer where to store the OID of the
  *	newly created commit
  *
  * @param repo Repository where to store the commit
@@ -245,7 +248,7 @@ GIT_EXTERN(int) git_commit_nth_gen_ancestor(
  *	the given reference will be updated to point to it
  */
 GIT_EXTERN(int) git_commit_create(
-		git_oid *oid,
+		git_oid *id,
 		git_repository *repo,
 		const char *update_ref,
 		const git_signature *author,
@@ -273,7 +276,7 @@ GIT_EXTERN(int) git_commit_create(
  * @see git_commit_create
  */
 GIT_EXTERN(int) git_commit_create_v(
-		git_oid *oid,
+		git_oid *id,
 		git_repository *repo,
 		const char *update_ref,
 		const git_signature *author,
diff --git a/include/git2/diff.h b/include/git2/diff.h
index 47bfa5f69..f925cbe39 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -106,6 +106,7 @@ typedef enum {
  * - max_size: maximum blob size to diff, above this treated as binary
  */
 typedef struct {
+	unsigned int version;		/**< version for the struct */
 	uint32_t flags;				/**< defaults to GIT_DIFF_NORMAL */
 	uint16_t context_lines;		/**< defaults to 3 */
 	uint16_t interhunk_lines;	/**< defaults to 0 */
@@ -186,7 +187,7 @@ typedef struct {
 /**
  * When iterating over a diff, callback that will be made per file.
  */
-typedef int (*git_diff_file_fn)(
+typedef int (*git_diff_file_cb)(
 	void *cb_data,
 	const git_diff_delta *delta,
 	float progress);
@@ -204,7 +205,7 @@ typedef struct {
 /**
  * When iterating over a diff, callback that will be made per hunk.
  */
-typedef int (*git_diff_hunk_fn)(
+typedef int (*git_diff_hunk_cb)(
 	void *cb_data,
 	const git_diff_delta *delta,
 	const git_diff_range *range,
@@ -215,20 +216,20 @@ typedef int (*git_diff_hunk_fn)(
  * Line origin constants.
  *
  * These values describe where a line came from and will be passed to
- * the git_diff_data_fn when iterating over a diff.  There are some
+ * the git_diff_data_cb when iterating over a diff.  There are some
  * special origin constants at the end that are used for the text
  * output callbacks to demarcate lines that are actually part of
  * the file or hunk headers.
  */
 typedef enum {
-	/* These values will be sent to `git_diff_data_fn` along with the line */
+	/* These values will be sent to `git_diff_data_cb` along with the line */
 	GIT_DIFF_LINE_CONTEXT   = ' ',
 	GIT_DIFF_LINE_ADDITION  = '+',
 	GIT_DIFF_LINE_DELETION  = '-',
 	GIT_DIFF_LINE_ADD_EOFNL = '\n', /**< Removed line w/o LF & added one with */
 	GIT_DIFF_LINE_DEL_EOFNL = '\0', /**< LF was removed at end of file */
 
-	/* The following values will only be sent to a `git_diff_data_fn` when
+	/* The following values will only be sent to a `git_diff_data_cb` when
 	 * the content of a diff is being formatted (eg. through
 	 * git_diff_print_patch() or git_diff_print_compact(), for instance).
 	 */
@@ -245,7 +246,7 @@ typedef enum {
  * of text.  This uses some extra GIT_DIFF_LINE_... constants for output
  * of lines of file and hunk headers.
  */
-typedef int (*git_diff_data_fn)(
+typedef int (*git_diff_data_cb)(
 	void *cb_data,
 	const git_diff_delta *delta,
 	const git_diff_range *range,
@@ -474,9 +475,9 @@ GIT_EXTERN(int) git_diff_find_similar(
 GIT_EXTERN(int) git_diff_foreach(
 	git_diff_list *diff,
 	void *cb_data,
-	git_diff_file_fn file_cb,
-	git_diff_hunk_fn hunk_cb,
-	git_diff_data_fn line_cb);
+	git_diff_file_cb file_cb,
+	git_diff_hunk_cb hunk_cb,
+	git_diff_data_cb line_cb);
 
 /**
  * Iterate over a diff generating text output like "git diff --name-status".
@@ -492,7 +493,7 @@ GIT_EXTERN(int) git_diff_foreach(
 GIT_EXTERN(int) git_diff_print_compact(
 	git_diff_list *diff,
 	void *cb_data,
-	git_diff_data_fn print_cb);
+	git_diff_data_cb print_cb);
 
 /**
  * Look up the single character abbreviation for a delta status code.
@@ -528,7 +529,7 @@ GIT_EXTERN(char) git_diff_status_char(git_delta_t status);
 GIT_EXTERN(int) git_diff_print_patch(
 	git_diff_list *diff,
 	void *cb_data,
-	git_diff_data_fn print_cb);
+	git_diff_data_cb print_cb);
 
 /**
  * Query how many diff records are there in a diff list.
@@ -680,7 +681,7 @@ GIT_EXTERN(int) git_diff_patch_get_line_in_hunk(
 GIT_EXTERN(int) git_diff_patch_print(
 	git_diff_patch *patch,
 	void *cb_data,
-	git_diff_data_fn print_cb);
+	git_diff_data_cb print_cb);
 
 /**
  * Get the content of a patch as a single diff text.
@@ -719,9 +720,9 @@ GIT_EXTERN(int) git_diff_blobs(
 	git_blob *new_blob,
 	const git_diff_options *options,
 	void *cb_data,
-	git_diff_file_fn file_cb,
-	git_diff_hunk_fn hunk_cb,
-	git_diff_data_fn line_cb);
+	git_diff_file_cb file_cb,
+	git_diff_hunk_cb hunk_cb,
+	git_diff_data_cb line_cb);
 
 GIT_END_DECL
 
diff --git a/include/git2/object.h b/include/git2/object.h
index fd6ae95c1..69af392a0 100644
--- a/include/git2/object.h
+++ b/include/git2/object.h
@@ -184,7 +184,7 @@ GIT_EXTERN(size_t) git_object__size(git_otype type);
  */
 GIT_EXTERN(int) git_object_peel(
 		git_object **peeled,
-		git_object *object,
+		const git_object *object,
 		git_otype target_type);
 
 /** @} */