Merge pull request #1920 from libgit2/cmn/ref-with-log

Reference operations with log

1 files changed, 148 insertions, 3 deletions

diff --git a/include/git2/refs.h b/include/git2/refs.h
index e2bfa9615..1df42fead 100644
--- a/include/git2/refs.h
+++ b/include/git2/refs.h
@@ -99,6 +99,48 @@ GIT_EXTERN(int) git_reference_dwim(git_reference **out, git_repository *repo, co
 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.
+ *
+ * @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
+ * @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
+ */
+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);
+
+/**
  * Create a new direct reference.
  *
  * A direct reference (also called an object id reference) refers directly
@@ -131,6 +173,49 @@ GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repositor
 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.
+ *
+ * @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 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
+ */
+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);
+
+/**
  * Get the OID pointed to by a direct reference.
  *
  * Only available if the reference is direct (i.e. an object id reference,
@@ -234,6 +319,31 @@ GIT_EXTERN(int) git_reference_symbolic_set_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.
+ *
+ * @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
+ */
+GIT_EXTERN(int) git_reference_symbolic_set_target_with_log(
+	git_reference **out,
+	git_reference *ref,
+	const char *target,
+	const git_signature *signature,
+	const char *log_message);
+
+/**
+ * Create a new reference with the same name as the given reference but a
  * different OID target. The reference must be a direct reference, otherwise
  * this will fail.
  *
@@ -250,6 +360,29 @@ GIT_EXTERN(int) git_reference_set_target(
 	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.
+ *
+ * @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
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_reference_set_target_with_log(
+	git_reference **out,
+	git_reference *ref,
+	const git_oid *id,
+	const git_signature *signature,
+	const char *log_message);
+
+/**
  * Rename an existing reference.
  *
  * This method works for both direct and symbolic references.
@@ -428,12 +561,24 @@ GIT_EXTERN(int) git_reference_foreach_glob(
 /**
  * Check if a reflog exists for the specified reference.
  *
- * @param ref A git reference
- *
+ * @param repo the repository
+ * @param refname the reference's name
  * @return 0 when no reflog can be found, 1 when it exists;
  * otherwise an error code.
  */
-GIT_EXTERN(int) git_reference_has_log(git_reference *ref);
+GIT_EXTERN(int) git_reference_has_log(git_repository *repo, const char *refname);
+
+/**
+ * Ensure there is a reflog for a particular reference.
+ *
+ * Make sure that successive updates to the reference will append to
+ * its log.
+ *
+ * @param repo the repository
+ * @param refname the reference's name
+ * @return 0 or an error code.
+ */
+GIT_EXTERN(int) git_reference_ensure_log(git_repository *repo, const char *refname);
 
 /**
  * Check if a reference is a local branch.