Merge remote-tracking branch 'origin/development' into fix-git-status-list-new-unreadable-folder

Conflicts:
	include/git2/diff.h

20 files changed, 221 insertions, 125 deletions

diff --git a/include/git2/blob.h b/include/git2/blob.h
index 1b6583309..c24ff7e7f 100644
--- a/include/git2/blob.h
+++ b/include/git2/blob.h
@@ -210,7 +210,7 @@ GIT_EXTERN(int) git_blob_create_frombuffer(
  *
  * The heuristic used to guess if a file is binary is taken from core git:
  * Searching for NUL bytes and looking for a reasonable ratio of printable
- * to non-printable characters among the first 4000 bytes.
+ * to non-printable characters among the first 8000 bytes.
  *
  * @param blob The blob which content should be analyzed
  * @return 1 if the content of the blob is detected
diff --git a/include/git2/checkout.h b/include/git2/checkout.h
index 494f67456..ad44173e6 100644
--- a/include/git2/checkout.h
+++ b/include/git2/checkout.h
@@ -43,17 +43,17 @@ GIT_BEGIN_DECL
  * In between those are `GIT_CHECKOUT_SAFE` and `GIT_CHECKOUT_SAFE_CREATE`
  * both of which only make modifications that will not lose changes.
  *
- *                      |  target == baseline   |  target != baseline  |
- * ---------------------|-----------------------|----------------------|
- *  workdir == baseline |       no action       |  create, update, or  |
- *                      |                       |     delete file      |
- * ---------------------|-----------------------|----------------------|
- *  workdir exists and  |       no action       |   conflict (notify   |
- *    is != baseline    | notify dirty MODIFIED | and cancel checkout) |
- * ---------------------|-----------------------|----------------------|
- *   workdir missing,   | create if SAFE_CREATE |     create file      |
- *   baseline present   | notify dirty DELETED  |                      |
- * ---------------------|-----------------------|----------------------|
+ *                         |  target == baseline   |  target != baseline  |
+ *    ---------------------|-----------------------|----------------------|
+ *     workdir == baseline |       no action       |  create, update, or  |
+ *                         |                       |     delete file      |
+ *    ---------------------|-----------------------|----------------------|
+ *     workdir exists and  |       no action       |   conflict (notify   |
+ *       is != baseline    | notify dirty MODIFIED | and cancel checkout) |
+ *    ---------------------|-----------------------|----------------------|
+ *      workdir missing,   | create if SAFE_CREATE |     create file      |
+ *      baseline present   | notify dirty DELETED  |                      |
+ *    ---------------------|-----------------------|----------------------|
  *
  * The only difference between SAFE and SAFE_CREATE is that SAFE_CREATE
  * will cause a file to be checked out if it is missing from the working
@@ -106,7 +106,7 @@ GIT_BEGIN_DECL
  *   target contains that file.
  */
 typedef enum {
-	GIT_CHECKOUT_NONE = 0, /** default is a dry run, no actual updates */
+	GIT_CHECKOUT_NONE = 0, /**< default is a dry run, no actual updates */
 
 	/** Allow safe updates that cannot overwrite uncommitted data */
 	GIT_CHECKOUT_SAFE = (1u << 0),
diff --git a/include/git2/cherrypick.h b/include/git2/cherrypick.h
index e998d325f..9eccb0af9 100644
--- a/include/git2/cherrypick.h
+++ b/include/git2/cherrypick.h
@@ -56,7 +56,7 @@ GIT_EXTERN(int) git_cherry_pick_init_options(
  * @param cherry_pick_commit the commit to cherry-pick
  * @param our_commit the commit to revert against (eg, HEAD)
  * @param mainline the parent of the revert commit, if it is a merge
- * @param merge_tree_opts the merge tree options (or null for defaults)
+ * @param merge_options the merge options (or null for defaults)
  * @return zero on success, -1 on failure.
  */
 GIT_EXTERN(int) git_cherry_pick_commit(
diff --git a/include/git2/clone.h b/include/git2/clone.h
index 985c04bf6..b2c944a78 100644
--- a/include/git2/clone.h
+++ b/include/git2/clone.h
@@ -23,6 +23,13 @@
  */
 GIT_BEGIN_DECL
 
+typedef enum {
+	GIT_CLONE_LOCAL_AUTO,
+	GIT_CLONE_LOCAL,
+	GIT_CLONE_NO_LOCAL,
+	GIT_CLONE_LOCAL_NO_LINKS,
+} git_clone_local_t;
+
 /**
  * Clone options structure
  *
@@ -57,6 +64,7 @@ typedef struct git_clone_options {
 
 	int bare;
 	int ignore_cert_errors;
+	git_clone_local_t local;
 	const char *remote_name;
 	const char* checkout_branch;
 	git_signature *signature;
@@ -123,6 +131,35 @@ GIT_EXTERN(int) git_clone_into(
 	const char *branch,
 	const git_signature *signature);
 
+/**
+ * Perform a local clone into a repository
+ *
+ * A "local clone" bypasses any git-aware protocols and simply copies
+ * over the object database from the source repository. It is often
+ * faster than a git-aware clone, but no verification of the data is
+ * performed, and can copy over too much data.
+ *
+ * @param repo the repository to use
+ * @param remote the remote repository to clone from
+ * @param co_opts options to use during checkout
+ * @param branch the branch to checkout after the clone, pass NULL for the
+ *        remote's default branch
+ * @param link wether to use hardlinks instead of copying
+ * objects. This is only possible if both repositories are on the same
+ * filesystem.
+ * @param signature the identity used when updating the reflog
+ * @return 0 on success, any non-zero return value from a callback
+ *         function, or a negative value to indicate an error (use
+ *         `giterr_last` for a detailed error message)
+ */
+GIT_EXTERN(int) git_clone_local_into(
+	git_repository *repo,
+	git_remote *remote,
+	const git_checkout_options *co_opts,
+	const char *branch,
+	int link,
+	const git_signature *signature);
+
 /** @} */
 GIT_END_DECL
 #endif
diff --git a/include/git2/diff.h b/include/git2/diff.h
index db2233f82..f126453f4 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -218,9 +218,9 @@ typedef struct git_diff git_diff;
  * considered reserved for internal or future use.
  */
 typedef enum {
-	GIT_DIFF_FLAG_BINARY     = (1u << 0), /** file(s) treated as binary data */
-	GIT_DIFF_FLAG_NOT_BINARY = (1u << 1), /** file(s) treated as text data */
-	GIT_DIFF_FLAG_VALID_ID  = (1u << 2), /** `id` value is known correct */
+	GIT_DIFF_FLAG_BINARY     = (1u << 0), /**< file(s) treated as binary data */
+	GIT_DIFF_FLAG_NOT_BINARY = (1u << 1), /**< file(s) treated as text data */
+	GIT_DIFF_FLAG_VALID_ID  = (1u << 2), /**< `id` value is known correct */
 } git_diff_flag_t;
 
 /**
@@ -234,16 +234,16 @@ typedef enum {
  * DELETED pairs).
  */
 typedef enum {
-	GIT_DELTA_UNMODIFIED = 0, /** no changes */
-	GIT_DELTA_ADDED = 1,	  /** entry does not exist in old version */
-	GIT_DELTA_DELETED = 2,	  /** entry does not exist in new version */
-	GIT_DELTA_MODIFIED = 3,   /** entry content changed between old and new */
-	GIT_DELTA_RENAMED = 4,    /** entry was renamed between old and new */
-	GIT_DELTA_COPIED = 5,     /** entry was copied from another old entry */
-	GIT_DELTA_IGNORED = 6,    /** entry is ignored item in workdir */
-	GIT_DELTA_UNTRACKED = 7,  /** entry is untracked item in workdir */
-	GIT_DELTA_TYPECHANGE = 8, /** type of entry changed between old and new */
-	GIT_DELTA_UNREADABLE = 9, /** entry is unreadable */
+	GIT_DELTA_UNMODIFIED = 0, /**< no changes */
+	GIT_DELTA_ADDED = 1,	  /**< entry does not exist in old version */
+	GIT_DELTA_DELETED = 2,	  /**< entry does not exist in new version */
+	GIT_DELTA_MODIFIED = 3,   /**< entry content changed between old and new */
+	GIT_DELTA_RENAMED = 4,    /**< entry was renamed between old and new */
+	GIT_DELTA_COPIED = 5,     /**< entry was copied from another old entry */
+	GIT_DELTA_IGNORED = 6,    /**< entry is ignored item in workdir */
+	GIT_DELTA_UNTRACKED = 7,  /**< entry is untracked item in workdir */
+	GIT_DELTA_TYPECHANGE = 8, /**< type of entry changed between old and new */
+	GIT_DELTA_UNREADABLE = 9, /**< entry is unreadable */
 } git_delta_t;
 
 /**
@@ -423,12 +423,12 @@ typedef int (*git_diff_file_cb)(
  */
 typedef struct git_diff_hunk git_diff_hunk;
 struct git_diff_hunk {
-	int    old_start;     /** Starting line number in old_file */
-	int    old_lines;     /** Number of lines in old_file */
-	int    new_start;     /** Starting line number in new_file */
-	int    new_lines;     /** Number of lines in new_file */
-	size_t header_len;    /** Number of bytes in header text */
-	char   header[128];   /** Header text, NUL-byte terminated */
+	int    old_start;     /**< Starting line number in old_file */
+	int    old_lines;     /**< Number of lines in old_file */
+	int    new_start;     /**< Starting line number in new_file */
+	int    new_lines;     /**< Number of lines in new_file */
+	size_t header_len;    /**< Number of bytes in header text */
+	char   header[128];   /**< Header text, NUL-byte terminated */
 };
 
 /**
@@ -471,13 +471,13 @@ typedef enum {
  */
 typedef struct git_diff_line git_diff_line;
 struct git_diff_line {
-	char   origin;       /** A git_diff_line_t value */
-	int    old_lineno;   /** Line number in old file or -1 for added line */
-	int    new_lineno;   /** Line number in new file or -1 for deleted line */
-	int    num_lines;    /** Number of newline characters in content */
-	size_t content_len;  /** Number of bytes of data */
-	git_off_t content_offset; /** Offset in the original file to the content */
-	const char *content; /** Pointer to diff text, not NUL-byte terminated */
+	char   origin;       /**< A git_diff_line_t value */
+	int    old_lineno;   /**< Line number in old file or -1 for added line */
+	int    new_lineno;   /**< Line number in new file or -1 for deleted line */
+	int    num_lines;    /**< Number of newline characters in content */
+	size_t content_len;  /**< Number of bytes of data */
+	git_off_t content_offset; /**< Offset in the original file to the content */
+	const char *content; /**< Pointer to diff text, not NUL-byte terminated */
 };
 
 /**
@@ -489,10 +489,10 @@ struct git_diff_line {
  * of lines of file and hunk headers.
  */
 typedef int (*git_diff_line_cb)(
-	const git_diff_delta *delta, /** delta that contains this data */
-	const git_diff_hunk *hunk,   /** hunk containing this data */
-	const git_diff_line *line,   /** line data */
-	void *payload);              /** user reference data */
+	const git_diff_delta *delta, /**< delta that contains this data */
+	const git_diff_hunk *hunk,   /**< hunk containing this data */
+	const git_diff_line *line,   /**< line data */
+	void *payload);              /**< user reference data */
 
 /**
  * Flags to control the behavior of diff rename/copy detection.
diff --git a/include/git2/errors.h b/include/git2/errors.h
index e22f0d86d..c914653fc 100644
--- a/include/git2/errors.h
+++ b/include/git2/errors.h
@@ -19,13 +19,13 @@ GIT_BEGIN_DECL
 
 /** Generic return codes */
 typedef enum {
-	GIT_OK         =  0,		/*< No error */
+	GIT_OK         =  0,		/**< No error */
 
-	GIT_ERROR      = -1,		/*< Generic error */
-	GIT_ENOTFOUND  = -3,		/*< Requested object could not be found */
-	GIT_EEXISTS    = -4,		/*< Object exists preventing operation */
-	GIT_EAMBIGUOUS = -5,		/*< More than one object matches */
-	GIT_EBUFS      = -6,		/*< Output buffer too short to hold data */
+	GIT_ERROR      = -1,		/**< Generic error */
+	GIT_ENOTFOUND  = -3,		/**< Requested object could not be found */
+	GIT_EEXISTS    = -4,		/**< Object exists preventing operation */
+	GIT_EAMBIGUOUS = -5,		/**< More than one object matches */
+	GIT_EBUFS      = -6,		/**< Output buffer too short to hold data */
 
 	/* GIT_EUSER is a special error that is never generated by libgit2
 	 * code.  You can return it from a callback (e.g to stop an iteration)
@@ -33,17 +33,17 @@ typedef enum {
 	 */
 	GIT_EUSER      = -7,
 
-	GIT_EBAREREPO       =  -8,	/*< Operation not allowed on bare repository */
-	GIT_EUNBORNBRANCH   =  -9,	/*< HEAD refers to branch with no commits */
-	GIT_EUNMERGED       = -10,	/*< Merge in progress prevented operation */
-	GIT_ENONFASTFORWARD = -11,	/*< Reference was not fast-forwardable */
-	GIT_EINVALIDSPEC    = -12,	/*< Name/ref spec was not in a valid format */
-	GIT_EMERGECONFLICT  = -13,	/*< Merge conflicts prevented operation */
-	GIT_ELOCKED         = -14,	/*< Lock file prevented operation */
-	GIT_EMODIFIED       = -15,	/*< Reference value does not match expected */
+	GIT_EBAREREPO       =  -8,	/**< Operation not allowed on bare repository */
+	GIT_EUNBORNBRANCH   =  -9,	/**< HEAD refers to branch with no commits */
+	GIT_EUNMERGED       = -10,	/**< Merge in progress prevented operation */
+	GIT_ENONFASTFORWARD = -11,	/**< Reference was not fast-forwardable */
+	GIT_EINVALIDSPEC    = -12,	/**< Name/ref spec was not in a valid format */
+	GIT_EMERGECONFLICT  = -13,	/**< Merge conflicts prevented operation */
+	GIT_ELOCKED         = -14,	/**< Lock file prevented operation */
+	GIT_EMODIFIED       = -15,	/**< Reference value does not match expected */
 
-	GIT_PASSTHROUGH     = -30,	/*< Internal only */
-	GIT_ITEROVER        = -31,	/*< Signals end of iteration with iterator */
+	GIT_PASSTHROUGH     = -30,	/**< Internal only */
+	GIT_ITEROVER        = -31,	/**< Signals end of iteration with iterator */
 } git_error_code;
 
 /**
diff --git a/include/git2/index.h b/include/git2/index.h
index cdb87282c..0b4476b4e 100644
--- a/include/git2/index.h
+++ b/include/git2/index.h
@@ -73,10 +73,13 @@ typedef struct git_index_entry {
  */
 #define GIT_IDXENTRY_NAMEMASK  (0x0fff)
 #define GIT_IDXENTRY_STAGEMASK (0x3000)
-#define GIT_IDXENTRY_EXTENDED  (0x4000)
-#define GIT_IDXENTRY_VALID     (0x8000)
 #define GIT_IDXENTRY_STAGESHIFT 12
 
+typedef enum {
+	GIT_IDXENTRY_EXTENDED  = (0x4000),
+	GIT_IDXENTRY_VALID     = (0x8000),
+} git_indxentry_flag_t;
+
 #define GIT_IDXENTRY_STAGE(E) \
 	(((E)->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT)
 
@@ -92,36 +95,36 @@ typedef struct git_index_entry {
  * in-memory only and used by libgit2.  Only the flags in
  * `GIT_IDXENTRY_EXTENDED_FLAGS` will get saved on-disk.
  *
- * These bitmasks match the three fields in the `git_index_entry`
- * `flags_extended` value that belong on disk.  You can use them to
- * interpret the data in the `flags_extended`.
+ * Thee first three bitmasks match the three fields in the
+ * `git_index_entry` `flags_extended` value that belong on disk.  You
+ * can use them to interpret the data in the `flags_extended`.
+ *
+ * The rest of the bitmasks match the other fields in the `git_index_entry`
+ * `flags_extended` value that are only used in-memory by libgit2.
+ * You can use them to interpret the data in the `flags_extended`.
+ *
  */
-#define GIT_IDXENTRY_INTENT_TO_ADD     (1 << 13)
-#define GIT_IDXENTRY_SKIP_WORKTREE     (1 << 14)
-/* GIT_IDXENTRY_EXTENDED2 is reserved for future extension */
-#define GIT_IDXENTRY_EXTENDED2         (1 << 15)
+typedef enum {
 
-#define GIT_IDXENTRY_EXTENDED_FLAGS (GIT_IDXENTRY_INTENT_TO_ADD | GIT_IDXENTRY_SKIP_WORKTREE)
+	GIT_IDXENTRY_INTENT_TO_ADD  =  (1 << 13),
+	GIT_IDXENTRY_SKIP_WORKTREE  =  (1 << 14),
+	/** Reserved for future extension */
+	GIT_IDXENTRY_EXTENDED2      =  (1 << 15),
 
-/**
- * Bitmasks for in-memory only fields of `git_index_entry`'s `flags_extended`
- *
- * These bitmasks match the other fields in the `git_index_entry`
- * `flags_extended` value that are only used in-memory by libgit2.  You
- * can use them to interpret the data in the `flags_extended`.
- */
-#define GIT_IDXENTRY_UPDATE            (1 << 0)
-#define GIT_IDXENTRY_REMOVE            (1 << 1)
-#define GIT_IDXENTRY_UPTODATE          (1 << 2)
-#define GIT_IDXENTRY_ADDED             (1 << 3)
+	GIT_IDXENTRY_EXTENDED_FLAGS = (GIT_IDXENTRY_INTENT_TO_ADD | GIT_IDXENTRY_SKIP_WORKTREE),
+	GIT_IDXENTRY_UPDATE            =  (1 << 0),
+	GIT_IDXENTRY_REMOVE            =  (1 << 1),
+	GIT_IDXENTRY_UPTODATE          =  (1 << 2),
+	GIT_IDXENTRY_ADDED             =  (1 << 3),
 
-#define GIT_IDXENTRY_HASHED            (1 << 4)
-#define GIT_IDXENTRY_UNHASHED          (1 << 5)
-#define GIT_IDXENTRY_WT_REMOVE         (1 << 6) /* remove in work directory */
-#define GIT_IDXENTRY_CONFLICTED        (1 << 7)
+	GIT_IDXENTRY_HASHED            =  (1 << 4),
+	GIT_IDXENTRY_UNHASHED          =  (1 << 5),
+	GIT_IDXENTRY_WT_REMOVE         =  (1 << 6), /**< remove in work directory */
+	GIT_IDXENTRY_CONFLICTED        =  (1 << 7),
 
-#define GIT_IDXENTRY_UNPACKED          (1 << 8)
-#define GIT_IDXENTRY_NEW_SKIP_WORKTREE (1 << 9)
+	GIT_IDXENTRY_UNPACKED          =  (1 << 8),
+	GIT_IDXENTRY_NEW_SKIP_WORKTREE =  (1 << 9),
+} git_idxentry_extended_flag_t;
 
 /** Capabilities of system that affect index actions. */
 typedef enum {
@@ -412,10 +415,10 @@ GIT_EXTERN(int) git_index_add(git_index *index, const git_index_entry *source_en
  *
  * This entry is calculated from the entry's flag attribute like this:
  *
- *	(entry->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT
+ *    (entry->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT
  *
  * @param entry The entry
- * @returns the stage number
+ * @return the stage number
  */
 GIT_EXTERN(int) git_index_entry_stage(const git_index_entry *entry);
 
diff --git a/include/git2/merge.h b/include/git2/merge.h
index abbc3a5bb..9eb14ccb1 100644
--- a/include/git2/merge.h
+++ b/include/git2/merge.h
@@ -268,6 +268,26 @@ typedef enum {
 	GIT_MERGE_ANALYSIS_UNBORN = (1 << 3),
 } git_merge_analysis_t;
 
+typedef enum {
+	/*
+	 * No configuration was found that suggests a preferred behavior for
+	 * merge.
+	 */
+	GIT_MERGE_PREFERENCE_NONE = 0,
+
+	/**
+	 * There is a `merge.ff=false` configuration setting, suggesting that
+	 * the user does not want to allow a fast-forward merge.
+	 */
+	GIT_MERGE_PREFERENCE_NO_FASTFORWARD = (1 << 0),
+
+	/**
+	 * There is a `merge.ff=only` configuration setting, suggesting that
+	 * the user only wants fast-forward merges.
+	 */
+	GIT_MERGE_PREFERENCE_FASTFORWARD_ONLY = (1 << 1),
+} git_merge_preference_t;
+
 /**
  * Analyzes the given branch(es) and determines the opportunities for
  * merging them into the HEAD of the repository.
@@ -280,6 +300,7 @@ typedef enum {
  */
 GIT_EXTERN(int) git_merge_analysis(
 	git_merge_analysis_t *analysis_out,
+	git_merge_preference_t *preference_out,
 	git_repository *repo,
 	const git_merge_head **their_heads,
 	size_t their_heads_len);
@@ -378,8 +399,8 @@ GIT_EXTERN(int) git_merge_head_from_id(
 /**
  * Gets the commit ID that the given `git_merge_head` refers to.
  *
- * @param id pointer to commit id to be filled in
  * @param head the given merge head
+ * @return commit id
  */
 GIT_EXTERN(const git_oid *) git_merge_head_id(
 	const git_merge_head *head);
@@ -424,8 +445,8 @@ GIT_EXTERN(int) git_merge_file(
  * @param out The git_merge_file_result to be filled in
  * @param repo The repository
  * @param ancestor The index entry for the ancestor file (stage level 1)
- * @param our_path The index entry for our file (stage level 2)
- * @param their_path The index entry for their file (stage level 3)
+ * @param ours The index entry for our file (stage level 2)
+ * @param theirs The index entry for their file (stage level 3)
  * @param opts The merge file options or NULL
  * @return 0 on success or error code
  */
@@ -497,8 +518,8 @@ GIT_EXTERN(int) git_merge_commits(
  * completes, resolve any conflicts and prepare a commit.
  *
  * @param repo the repository to merge
- * @param merge_heads the heads to merge into
- * @param merge_heads_len the number of heads to merge
+ * @param their_heads the heads to merge into
+ * @param their_heads_len the number of heads to merge
  * @param merge_opts merge options
  * @param checkout_opts checkout options
  * @return 0 on success or error code
diff --git a/include/git2/message.h b/include/git2/message.h
index bcdb72f6a..d78b1dce5 100644
--- a/include/git2/message.h
+++ b/include/git2/message.h
@@ -29,12 +29,14 @@ GIT_BEGIN_DECL
  *
  * @param message The message to be prettified.
  *
- * @param strip_comments Non-zero to remove lines starting with "#", 0 to
- *     leave them in.
+ * @param strip_comments Non-zero to remove comment lines, 0 to leave them in.
+ *
+ * @param comment_char Comment character. Lines starting with this character
+ * are considered to be comments and removed if `strip_comments` is non-zero.
  *
  * @return 0 or an error code.
  */
-GIT_EXTERN(int) git_message_prettify(git_buf *out, const char *message, int strip_comments);
+GIT_EXTERN(int) git_message_prettify(git_buf *out, const char *message, int strip_comments, char comment_char);
 
 /** @} */
 GIT_END_DECL
diff --git a/include/git2/net.h b/include/git2/net.h
index e70ba1f71..a727696a2 100644
--- a/include/git2/net.h
+++ b/include/git2/net.h
@@ -41,6 +41,11 @@ struct git_remote_head {
 	git_oid oid;
 	git_oid loid;
 	char *name;
+	/**
+	 * If the server send a symref mapping for this ref, this will
+	 * point to the target.
+	 */
+	char *symref_target;
 };
 
 /**
diff --git a/include/git2/reflog.h b/include/git2/reflog.h
index df06e1b8e..ac42a231c 100644
--- a/include/git2/reflog.h
+++ b/include/git2/reflog.h
@@ -69,7 +69,7 @@ GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *id, const g
  *
  * @param repo the repository
  * @param old_name the old name of the reference
- * @param new_name the new name of the reference
+ * @param name the new name of the reference
  * @return 0 on success, GIT_EINVALIDSPEC or an error code
  */
 GIT_EXTERN(int) git_reflog_rename(git_repository *repo, const char *old_name, const char *name);
diff --git a/include/git2/refs.h b/include/git2/refs.h
index ae2d379d9..e5bb15c7c 100644
--- a/include/git2/refs.h
+++ b/include/git2/refs.h
@@ -178,7 +178,6 @@ GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repositor
  * @param name The name of the reference
  * @param id The object id pointed to by the reference.
  * @param force Overwrite existing references
- * @param force Overwrite existing references
  * @param signature The identity that will used to populate the reflog entry
  * @param log_message The one line long message to be appended to the reflog
  * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code
@@ -221,7 +220,6 @@ GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo,
  * @param name The name of the reference
  * @param id The object id pointed to by the reference.
  * @param force Overwrite existing references
- * @param force Overwrite existing references
  * @param current_id The expected value of the reference at the time of update
  * @param signature The identity that will used to populate the reflog entry
  * @param log_message The one line long message to be appended to the reflog
@@ -415,7 +413,7 @@ GIT_EXTERN(int) git_reference_delete(git_reference *ref);
  * This method removes the named reference from the repository without
  * looking at its old value.
  *
- * @param ref The reference to remove
+ * @param name The reference to remove
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_reference_remove(git_repository *repo, const char *name);
diff --git a/include/git2/remote.h b/include/git2/remote.h
index 3633501e2..28771ac42 100644
--- a/include/git2/remote.h
+++ b/include/git2/remote.h
@@ -610,6 +610,37 @@ GIT_EXTERN(void) git_remote_set_update_fetchhead(git_remote *remote, int value);
  */
 GIT_EXTERN(int) git_remote_is_valid_name(const char *remote_name);
 
+/**
+* Delete an existing persisted remote.
+*
+* All remote-tracking branches and configuration settings
+* for the remote will be removed.
+*
+* once deleted, the passed remote object will be freed and invalidated.
+*
+* @param remote A valid remote
+* @return 0 on success, or an error code.
+*/
+GIT_EXTERN(int) git_remote_delete(git_remote *remote);
+
+/**
+ * Retrieve the name of the remote's default branch
+ *
+ * The default branch of a repository is the branch which HEAD points
+ * to. If the remote does not support reporting this information
+ * directly, it performs the guess as git does; that is, if there are
+ * multiple branches which point to the same commit, the first one is
+ * chosen. If the master branch is a candidate, it wins.
+ *
+ * This function must only be called after connecting.
+ *
+ * @param out the buffern in which to store the reference name
+ * @param remote the remote
+ * @return 0, GIT_ENOTFOUND if the remote does not have any references
+ * or none of them point to HEAD's commit, or an error message.
+ */
+GIT_EXTERN(int) git_remote_default_branch(git_buf *out, git_remote *remote);
+
 /** @} */
 GIT_END_DECL
 #endif
diff --git a/include/git2/repository.h b/include/git2/repository.h
index 037cb3f96..6a8ff4545 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -649,7 +649,7 @@ GIT_EXTERN(int) git_repository_set_head_detached(
  *
  * @param repo Repository pointer
  * @param signature The identity that will used to populate the reflog entry
- * @param log_message The one line long message to be appended to the reflog
+ * @param reflog_message The one line long message to be appended to the reflog
  * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing
  * branch or an error code
  */
diff --git a/include/git2/reset.h b/include/git2/reset.h
index 1759cc036..b8c580339 100644
--- a/include/git2/reset.h
+++ b/include/git2/reset.h
@@ -19,9 +19,9 @@ GIT_BEGIN_DECL
  * Kinds of reset operation
  */
 typedef enum {
-	GIT_RESET_SOFT  = 1, /** Move the head to the given commit */
-	GIT_RESET_MIXED = 2, /** SOFT plus reset index to the commit */
-	GIT_RESET_HARD  = 3, /** MIXED plus changes in working tree discarded */
+	GIT_RESET_SOFT  = 1, /**< Move the head to the given commit */
+	GIT_RESET_MIXED = 2, /**< SOFT plus reset index to the commit */
+	GIT_RESET_HARD  = 3, /**< MIXED plus changes in working tree discarded */
 } git_reset_t;
 
 /**
diff --git a/include/git2/revert.h b/include/git2/revert.h
index da37fbe7b..fc1767c93 100644
--- a/include/git2/revert.h
+++ b/include/git2/revert.h
@@ -56,7 +56,7 @@ GIT_EXTERN(int) git_revert_init_options(
  * @param revert_commit the commit to revert
  * @param our_commit the commit to revert against (eg, HEAD)
  * @param mainline the parent of the revert commit, if it is a merge
- * @param merge_tree_opts the merge tree options (or null for defaults)
+ * @param merge_options the merge options (or null for defaults)
  * @return zero on success, -1 on failure.
  */
 int git_revert_commit(
@@ -71,9 +71,8 @@ int git_revert_commit(
  * Reverts the given commit, producing changes in the working directory.
  *
  * @param repo the repository to revert
- * @param commits the commits to revert
- * @param commits_len the number of commits to revert
- * @param flags merge flags
+ * @param commit the commit to revert
+ * @param given_opts merge flags
  * @return zero on success, -1 on failure.
  */
 GIT_EXTERN(int) git_revert(
diff --git a/include/git2/signature.h b/include/git2/signature.h
index a1dd1ec7a..feb1b4073 100644
--- a/include/git2/signature.h
+++ b/include/git2/signature.h
@@ -69,7 +69,7 @@ GIT_EXTERN(int) git_signature_default(git_signature **out, git_repository *repo)
  * Call `git_signature_free()` to free the data.
  *
  * @param dest pointer where to store the copy
- * @param entry signature to duplicate
+ * @param sig signature to duplicate
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_signature_dup(git_signature **dest, const git_signature *sig);
diff --git a/include/git2/submodule.h b/include/git2/submodule.h
index 28e235725..864d1c58c 100644
--- a/include/git2/submodule.h
+++ b/include/git2/submodule.h
@@ -283,7 +283,7 @@ GIT_EXTERN(const char *) git_submodule_url(git_submodule *submodule);
  * Resolve a submodule url relative to the given repository.
  *
  * @param out buffer to store the absolute submodule url in
- * @param repository Pointer to repository object
+ * @param repo Pointer to repository object
  * @param url Relative url
  * @return 0 or an error code
  */
diff --git a/include/git2/tree.h b/include/git2/tree.h
index 6669652ae..56922d40b 100644
--- a/include/git2/tree.h
+++ b/include/git2/tree.h
@@ -151,7 +151,7 @@ GIT_EXTERN(int) git_tree_entry_bypath(
  * and must be freed explicitly with `git_tree_entry_free()`.
  *
  * @param dest pointer where to store the copy
- * @param entry tree entry to duplicate
+ * @param source tree entry to duplicate
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_tree_entry_dup(git_tree_entry **dest, const git_tree_entry *source);
diff --git a/include/git2/types.h b/include/git2/types.h
index 46dfd8b75..3019c4677 100644
--- a/include/git2/types.h
+++ b/include/git2/types.h
@@ -154,15 +154,15 @@ typedef struct git_packbuilder git_packbuilder;
 
 /** Time in a signature */
 typedef struct git_time {
-	git_time_t time; /** time in seconds from epoch */
-	int offset; /** timezone offset, in minutes */
+	git_time_t time; /**< time in seconds from epoch */
+	int offset; /**< timezone offset, in minutes */
 } git_time;
 
 /** An action signature (e.g. for committers, taggers, etc) */
 typedef struct git_signature {
-	char *name; /** full name of the author */
-	char *email; /** email of the author */
-	git_time when; /** time when the action happened */
+	char *name; /**< full name of the author */
+	char *email; /**< email of the author */
+	git_time when; /**< time when the action happened */
 } git_signature;
 
 /** In-memory representation of a reference. */
@@ -183,9 +183,9 @@ typedef struct git_status_list git_status_list;
 
 /** Basic type of any Git reference. */
 typedef enum {
-	GIT_REF_INVALID = 0, /** Invalid reference */
-	GIT_REF_OID = 1, /** A reference which points at an object id */
-	GIT_REF_SYMBOLIC = 2, /** A reference which points at another reference */
+	GIT_REF_INVALID = 0, /**< Invalid reference */
+	GIT_REF_OID = 1, /**< A reference which points at an object id */
+	GIT_REF_SYMBOLIC = 2, /**< A reference which points at another reference */
 	GIT_REF_LISTALL = GIT_REF_OID|GIT_REF_SYMBOLIC,
 } git_ref_t;
 
@@ -314,12 +314,12 @@ typedef enum {
  *   when we don't want any particular ignore rule to be specified.
  */
 typedef enum {
-	GIT_SUBMODULE_IGNORE_RESET     = -1, /* reset to on-disk value */
+	GIT_SUBMODULE_IGNORE_RESET     = -1, /**< reset to on-disk value */
 
-	GIT_SUBMODULE_IGNORE_NONE      = 1,  /* any change or untracked == dirty */
-	GIT_SUBMODULE_IGNORE_UNTRACKED = 2,  /* dirty if tracked files change */
-	GIT_SUBMODULE_IGNORE_DIRTY     = 3,  /* only dirty if HEAD moved */
-	GIT_SUBMODULE_IGNORE_ALL       = 4,  /* never dirty */
+	GIT_SUBMODULE_IGNORE_NONE      = 1,  /**< any change or untracked == dirty */
+	GIT_SUBMODULE_IGNORE_UNTRACKED = 2,  /**< dirty if tracked files change */
+	GIT_SUBMODULE_IGNORE_DIRTY     = 3,  /**< only dirty if HEAD moved */
+	GIT_SUBMODULE_IGNORE_ALL       = 4,  /**< never dirty */
 
 	GIT_SUBMODULE_IGNORE_DEFAULT   = 0
 } git_submodule_ignore_t;