Add Reference::symbolic_set_target

libgit2-sys/lib.rs

@@ -2437,6 +2437,12 @@ extern "C" {
         id: *const git_oid,
         log_message: *const c_char,
     ) -> c_int;
+    pub fn git_reference_symbolic_set_target(
+        out: *mut *mut git_reference,
+        r: *mut git_reference,
+        target: *const c_char,
+        log_message: *const c_char,
+    ) -> c_int;
     pub fn git_reference_type(r: *const git_reference) -> git_reference_t;
     pub fn git_reference_iterator_new(
         out: *mut *mut git_reference_iterator,

src/reference.rs

@@ -361,6 +361,35 @@ impl<'repo> Reference<'repo> {
             Ok(Binding::from_raw(raw))
         }
     }
+
+    /// Create a new reference with the same name as the given reference but a
+    /// different symbolic target. 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
+    /// [`Repository::reference_symbolic`] for rules about valid names.
+    ///
+    /// The message for the reflog will be ignored if the reference does not
+    /// belong in the standard set (HEAD, branches and remote-tracking
+    /// branches) and it does not have a reflog.
+    pub fn symbolic_set_target(
+        &mut self,
+        target: &str,
+        reflog_msg: &str,
+    ) -> Result<Reference<'repo>, Error> {
+        let mut raw = ptr::null_mut();
+        let target = CString::new(target)?;
+        let msg = CString::new(reflog_msg)?;
+        unsafe {
+            try_call!(raw::git_reference_symbolic_set_target(
+                &mut raw, self.raw, target, msg
+            ));
+            Ok(Binding::from_raw(raw))
+        }
+    }
 }
 
 impl<'repo> PartialOrd for Reference<'repo> {
@@ -512,6 +541,14 @@ mod tests {
             .reference_symbolic("refs/tags/tag1", "refs/heads/main", false, "test")
             .unwrap();
         assert_eq!(sym1.kind().unwrap(), ReferenceType::Symbolic);
+        let mut sym2 = repo
+            .reference_symbolic("refs/tags/tag2", "refs/heads/main", false, "test")
+            .unwrap()
+            .symbolic_set_target("refs/tags/tag1", "test")
+            .unwrap();
+        assert_eq!(sym2.kind().unwrap(), ReferenceType::Symbolic);
+        assert_eq!(sym2.symbolic_target().unwrap(), "refs/tags/tag1");
+        sym2.delete().unwrap();
         sym1.delete().unwrap();
 
         {

src/repo.rs

@@ -1480,6 +1480,19 @@ impl Repository {
 
     /// Create a new symbolic reference.
     ///
+    /// 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.
+    ///
+    /// 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.