refs: remove the _with_log differentiation

Any well-behaved program should write a descriptive message to the
reflog whenever it updates a reference. Let's make this more prominent
by removing the version without the reflog parameters.

1 files changed, 24 insertions, 128 deletions

diff --git a/include/git2/refs.h b/include/git2/refs.h
index 1df42fead..e4c6f1b16 100644
--- a/include/git2/refs.h
+++ b/include/git2/refs.h
@@ -89,37 +89,9 @@ GIT_EXTERN(int) git_reference_dwim(git_reference **out, git_repository *repo, co
  * This function will return an error if a reference already exists with the
  * given name unless `force` is true, in which case it will be overwritten.
  *
- * @param out Pointer to the newly created reference
- * @param repo Repository where that reference will live
- * @param name The name of the reference
- * @param target The target of the reference
- * @param force Overwrite existing references
- * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code
- */
-GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repository *repo, const char *name, const char *target, int force);
-
-/**
- * Create a new symbolic reference and update the reflog with a given
- * message.
- *
- * A symbolic reference is a reference name that refers to another
- * reference name.  If the other name moves, the symbolic name will move,
- * too.  As a simple example, the "HEAD" reference might refer to
- * "refs/heads/master" while on the "master" branch of a repository.
- *
- * The symbolic reference will be created in the repository and written to
- * the disk.  The generated reference object must be freed by the user.
- *
- * Valid reference names must follow one of two patterns:
- *
- * 1. Top-level names must contain only capital letters and underscores,
- *    and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD").
- * 2. Names prefixed with "refs/" can be almost anything.  You must avoid
- *    the characters '~', '^', ':', '\\', '?', '[', and '*', and the
- *    sequences ".." and "@{" which have special meaning to revparse.
- *
- * This function will return an error if a reference already exists with the
- * given name unless `force` is true, in which case it will be overwritten.
+ * The signature and message for the reflog will be ignored if the
+ * reference does not belong in the standard set (HEAD, branches and
+ * remote-tracking branches) and and it does not have a reflog.
  *
  * @param out Pointer to the newly created reference
  * @param repo Repository where that reference will live
@@ -127,18 +99,10 @@ GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repositor
  * @param target The target of the reference
  * @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 that has to be appended
- * to the reflog
- * @return 0 on success, EEXISTS, EINVALIDSPEC or an error code
+ * @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
  */
-GIT_EXTERN(int) git_reference_symbolic_create_with_log(
-	git_reference **out,
-	git_repository *repo,
-	const char *name,
-	const char *target,
-	int force,
-	const git_signature *signature,
-	const char *log_message);
+GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repository *repo, const char *name, const char *target, int force, const git_signature *signature, const char *log_message);
 
 /**
  * Create a new direct reference.
@@ -163,57 +127,21 @@ GIT_EXTERN(int) git_reference_symbolic_create_with_log(
  * This function will return an error if a reference already exists with the
  * given name unless `force` is true, in which case it will be overwritten.
  *
- * @param out Pointer to the newly created reference
- * @param repo Repository where that reference will live
- * @param name The name of the reference
- * @param id The object id pointed to by the reference.
- * @param force Overwrite existing references
- * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code
- */
-GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force);
-
-/**
- * Create a new direct reference and update the reflog with a given
- * message.
- *
- * A direct reference (also called an object id reference) refers directly
- * to a specific object id (a.k.a. OID or SHA) in the repository.  The id
- * permanently refers to the object (although the reference itself can be
- * moved).  For example, in libgit2 the direct ref "refs/tags/v0.17.0"
- * refers to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977.
- *
- * The direct reference will be created in the repository and written to
- * the disk.  The generated reference object must be freed by the user.
- *
- * Valid reference names must follow one of two patterns:
- *
- * 1. Top-level names must contain only capital letters and underscores,
- *    and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD").
- * 2. Names prefixed with "refs/" can be almost anything.  You must avoid
- *    the characters '~', '^', ':', '\\', '?', '[', and '*', and the
- *    sequences ".." and "@{" which have special meaning to revparse.
- *
- * This function will return an error if a reference already exists with the
- * given name unless `force` is true, in which case it will be overwritten.
+ * The signature and message for the reflog will be ignored if the
+ * reference does not belong in the standard set (HEAD, branches and
+ * remote-tracking branches) and and it does not have a reflog.
  *
  * @param out Pointer to the newly created reference
  * @param repo Repository where that reference will live
  * @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 that has to be appended
- * to the reflog
- * @return 0 on success, EEXISTS, EINVALIDSPEC or an error code
+ * @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
  */
-GIT_EXTERN(int) git_reference_create_with_log(
-	git_reference **out,
-	git_repository *repo,
-	const char *name,
-	const git_oid *id,
-	int force,
-	const git_signature *signature,
-	const char *log_message);
+GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force, const git_signature *signature, const char *log_message);
 
 /**
  * Get the OID pointed to by a direct reference.
@@ -307,35 +235,18 @@ GIT_EXTERN(git_repository *) git_reference_owner(const git_reference *ref);
  * The target name will be checked for validity.
  * See `git_reference_create_symbolic()` for rules about valid names.
  *
- * @param out Pointer to the newly created reference
- * @param ref The reference
- * @param target The new target for the reference
- * @return 0 on success, GIT_EINVALIDSPEC or an error code
- */
-GIT_EXTERN(int) git_reference_symbolic_set_target(
-	git_reference **out,
-	git_reference *ref,
-	const char *target);
-
-/**
- * Create a new reference with the same name as the given reference but a
- * different symbolic target  and update the reflog with a given message.
- *
- * The reference must be a symbolic reference, otherwise this will fail.
- *
- * The new reference will be written to disk, overwriting the given reference.
- *
- * The target name will be checked for validity.
- * See `git_reference_create_symbolic()` for rules about valid names.
+ * The signature and message for the reflog will be ignored if the
+ * reference does not belong in the standard set (HEAD, branches and
+ * remote-tracking branches) and and it does not have a reflog.
  *
  * @param out Pointer to the newly created reference
  * @param ref The reference
  * @param target The new target for the reference
  * @param signature The identity that will used to populate the reflog entry
- * @param log_message The one line long message that has to be appended
- * @return 0 on success, EINVALIDSPEC or an error code
+ * @param log_message The one line long message to be appended to the reflog
+ * @return 0 on success, GIT_EINVALIDSPEC or an error code
  */
-GIT_EXTERN(int) git_reference_symbolic_set_target_with_log(
+GIT_EXTERN(int) git_reference_symbolic_set_target(
 	git_reference **out,
 	git_reference *ref,
 	const char *target,
@@ -349,33 +260,18 @@ GIT_EXTERN(int) git_reference_symbolic_set_target_with_log(
  *
  * The new reference will be written to disk, overwriting the given reference.
  *
- * @param out Pointer to the newly created reference
- * @param ref The reference
- * @param id The new target OID for the reference
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_reference_set_target(
-	git_reference **out,
-	git_reference *ref,
-	const git_oid *id);
-
-/**
- * Create a new reference with the same name as the given reference but a
- * different OID target and update the reflog with a given message.
- *
- * The reference must be a direct reference, otherwise this will fail.
- *
- * The new reference will be written to disk, overwriting the given reference.
+ * The signature and message for the reflog will be ignored if the
+ * reference does not belong in the standard set (HEAD, branches and
+ * remote-tracking branches) and and it does not have a reflog.
  *
  * @param out Pointer to the newly created reference
  * @param ref The reference
  * @param id The new target OID for the reference
  * @param signature The identity that will used to populate the reflog entry
- * @param log_message The one line long message that has to be appended
- * to the reflog
+ * @param log_message The one line long message to be appended to the reflog
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_reference_set_target_with_log(
+GIT_EXTERN(int) git_reference_set_target(
 	git_reference **out,
 	git_reference *ref,
 	const git_oid *id,