| use std::cmp::Ordering; |
| use std::ffi::CString; |
| use std::marker; |
| use std::mem; |
| use std::ptr; |
| use std::str; |
| |
| use crate::object::CastOrPanic; |
| use crate::util::{c_cmp_to_ordering, Binding}; |
| use crate::{ |
| call, raw, Blob, Commit, Error, Object, ObjectType, Oid, ReferenceFormat, ReferenceType, |
| Repository, Tag, Tree, |
| }; |
| |
| // Not in the public header files (yet?), but a hard limit used by libgit2 |
| // internally |
| const GIT_REFNAME_MAX: usize = 1024; |
| |
| /// This is used to logically indicate that a [`raw::git_reference`] or |
| /// [`raw::git_reference_iterator`] holds a reference to [`raw::git_refdb`]. |
| /// It is not necessary to have a wrapper like this in the |
| /// [`marker::PhantomData`], since all that matters is that it is tied to the |
| /// lifetime of the [`Repository`], but this helps distinguish the actual |
| /// references involved. |
| struct Refdb<'repo>(#[allow(dead_code)] &'repo Repository); |
| |
| /// A structure to represent a git [reference][1]. |
| /// |
| /// [1]: http://git-scm.com/book/en/Git-Internals-Git-References |
| pub struct Reference<'repo> { |
| raw: *mut raw::git_reference, |
| _marker: marker::PhantomData<Refdb<'repo>>, |
| } |
| |
| /// An iterator over the references in a repository. |
| pub struct References<'repo> { |
| raw: *mut raw::git_reference_iterator, |
| _marker: marker::PhantomData<Refdb<'repo>>, |
| } |
| |
| /// An iterator over the names of references in a repository. |
| pub struct ReferenceNames<'repo, 'references> { |
| inner: &'references mut References<'repo>, |
| } |
| |
| impl<'repo> Reference<'repo> { |
| /// Ensure the reference name is well-formed. |
| /// |
| /// Validation is performed as if [`ReferenceFormat::ALLOW_ONELEVEL`] |
| /// was given to [`Reference::normalize_name`]. No normalization is |
| /// performed, however. |
| /// |
| /// ```rust |
| /// use git2::Reference; |
| /// |
| /// assert!(Reference::is_valid_name("HEAD")); |
| /// assert!(Reference::is_valid_name("refs/heads/main")); |
| /// |
| /// // But: |
| /// assert!(!Reference::is_valid_name("main")); |
| /// assert!(!Reference::is_valid_name("refs/heads/*")); |
| /// assert!(!Reference::is_valid_name("foo//bar")); |
| /// ``` |
| /// |
| /// [`ReferenceFormat::ALLOW_ONELEVEL`]: |
| /// struct.ReferenceFormat#associatedconstant.ALLOW_ONELEVEL |
| /// [`Reference::normalize_name`]: struct.Reference#method.normalize_name |
| pub fn is_valid_name(refname: &str) -> bool { |
| crate::init(); |
| let refname = CString::new(refname).unwrap(); |
| let mut valid: libc::c_int = 0; |
| unsafe { |
| call::c_try(raw::git_reference_name_is_valid( |
| &mut valid, |
| refname.as_ptr(), |
| )) |
| .unwrap(); |
| } |
| valid == 1 |
| } |
| |
| /// Normalize reference name and check validity. |
| /// |
| /// This will normalize the reference name by collapsing runs of adjacent |
| /// slashes between name components into a single slash. It also validates |
| /// the name according to the following rules: |
| /// |
| /// 1. If [`ReferenceFormat::ALLOW_ONELEVEL`] is given, the name may |
| /// contain only capital letters and underscores, and must begin and end |
| /// with a letter. (e.g. "HEAD", "ORIG_HEAD"). |
| /// 2. The flag [`ReferenceFormat::REFSPEC_SHORTHAND`] has an effect |
| /// only when combined with [`ReferenceFormat::ALLOW_ONELEVEL`]. If |
| /// it is given, "shorthand" branch names (i.e. those not prefixed by |
| /// `refs/`, but consisting of a single word without `/` separators) |
| /// become valid. For example, "main" would be accepted. |
| /// 3. If [`ReferenceFormat::REFSPEC_PATTERN`] is given, the name may |
| /// contain a single `*` in place of a full pathname component (e.g. |
| /// `foo/*/bar`, `foo/bar*`). |
| /// 4. Names prefixed with "refs/" can be almost anything. You must avoid |
| /// the characters '~', '^', ':', '\\', '?', '[', and '*', and the |
| /// sequences ".." and "@{" which have special meaning to revparse. |
| /// |
| /// If the reference passes validation, it is returned in normalized form, |
| /// otherwise an [`Error`] with [`ErrorCode::InvalidSpec`] is returned. |
| /// |
| /// ```rust |
| /// use git2::{Reference, ReferenceFormat}; |
| /// |
| /// assert_eq!( |
| /// Reference::normalize_name( |
| /// "foo//bar", |
| /// ReferenceFormat::NORMAL |
| /// ) |
| /// .unwrap(), |
| /// "foo/bar".to_owned() |
| /// ); |
| /// |
| /// assert_eq!( |
| /// Reference::normalize_name( |
| /// "HEAD", |
| /// ReferenceFormat::ALLOW_ONELEVEL |
| /// ) |
| /// .unwrap(), |
| /// "HEAD".to_owned() |
| /// ); |
| /// |
| /// assert_eq!( |
| /// Reference::normalize_name( |
| /// "refs/heads/*", |
| /// ReferenceFormat::REFSPEC_PATTERN |
| /// ) |
| /// .unwrap(), |
| /// "refs/heads/*".to_owned() |
| /// ); |
| /// |
| /// assert_eq!( |
| /// Reference::normalize_name( |
| /// "main", |
| /// ReferenceFormat::ALLOW_ONELEVEL | ReferenceFormat::REFSPEC_SHORTHAND |
| /// ) |
| /// .unwrap(), |
| /// "main".to_owned() |
| /// ); |
| /// ``` |
| /// |
| /// [`ReferenceFormat::ALLOW_ONELEVEL`]: |
| /// struct.ReferenceFormat#associatedconstant.ALLOW_ONELEVEL |
| /// [`ReferenceFormat::REFSPEC_SHORTHAND`]: |
| /// struct.ReferenceFormat#associatedconstant.REFSPEC_SHORTHAND |
| /// [`ReferenceFormat::REFSPEC_PATTERN`]: |
| /// struct.ReferenceFormat#associatedconstant.REFSPEC_PATTERN |
| /// [`Error`]: struct.Error |
| /// [`ErrorCode::InvalidSpec`]: enum.ErrorCode#variant.InvalidSpec |
| pub fn normalize_name(refname: &str, flags: ReferenceFormat) -> Result<String, Error> { |
| crate::init(); |
| let mut dst = [0u8; GIT_REFNAME_MAX]; |
| let refname = CString::new(refname)?; |
| unsafe { |
| try_call!(raw::git_reference_normalize_name( |
| dst.as_mut_ptr() as *mut libc::c_char, |
| dst.len() as libc::size_t, |
| refname, |
| flags.bits() |
| )); |
| let s = &dst[..dst.iter().position(|&a| a == 0).unwrap()]; |
| Ok(str::from_utf8(s).unwrap().to_owned()) |
| } |
| } |
| |
| /// Get access to the underlying raw pointer. |
| pub fn raw(&self) -> *mut raw::git_reference { |
| self.raw |
| } |
| |
| /// Delete an existing reference. |
| /// |
| /// This method works for both direct and symbolic references. The reference |
| /// will be immediately removed on disk. |
| /// |
| /// This function will return an error if the reference has changed from the |
| /// time it was looked up. |
| pub fn delete(&mut self) -> Result<(), Error> { |
| unsafe { |
| try_call!(raw::git_reference_delete(self.raw)); |
| } |
| Ok(()) |
| } |
| |
| /// Check if a reference is a local branch. |
| pub fn is_branch(&self) -> bool { |
| unsafe { raw::git_reference_is_branch(&*self.raw) == 1 } |
| } |
| |
| /// Check if a reference is a note. |
| pub fn is_note(&self) -> bool { |
| unsafe { raw::git_reference_is_note(&*self.raw) == 1 } |
| } |
| |
| /// Check if a reference is a remote tracking branch |
| pub fn is_remote(&self) -> bool { |
| unsafe { raw::git_reference_is_remote(&*self.raw) == 1 } |
| } |
| |
| /// Check if a reference is a tag |
| pub fn is_tag(&self) -> bool { |
| unsafe { raw::git_reference_is_tag(&*self.raw) == 1 } |
| } |
| |
| /// Get the reference type of a reference. |
| /// |
| /// If the type is unknown, then `None` is returned. |
| pub fn kind(&self) -> Option<ReferenceType> { |
| ReferenceType::from_raw(unsafe { raw::git_reference_type(&*self.raw) }) |
| } |
| |
| /// Get the full name of a reference. |
| /// |
| /// Returns `None` if the name is not valid utf-8. |
| pub fn name(&self) -> Option<&str> { |
| str::from_utf8(self.name_bytes()).ok() |
| } |
| |
| /// Get the full name of a reference. |
| pub fn name_bytes(&self) -> &[u8] { |
| unsafe { crate::opt_bytes(self, raw::git_reference_name(&*self.raw)).unwrap() } |
| } |
| |
| /// Get the full shorthand of a reference. |
| /// |
| /// This will transform the reference name into a name "human-readable" |
| /// version. If no shortname is appropriate, it will return the full name. |
| /// |
| /// Returns `None` if the shorthand is not valid utf-8. |
| pub fn shorthand(&self) -> Option<&str> { |
| str::from_utf8(self.shorthand_bytes()).ok() |
| } |
| |
| /// Get the full shorthand of a reference. |
| pub fn shorthand_bytes(&self) -> &[u8] { |
| unsafe { crate::opt_bytes(self, raw::git_reference_shorthand(&*self.raw)).unwrap() } |
| } |
| |
| /// Get the OID pointed to by a direct reference. |
| /// |
| /// Only available if the reference is direct (i.e. an object id reference, |
| /// not a symbolic one). |
| pub fn target(&self) -> Option<Oid> { |
| unsafe { Binding::from_raw_opt(raw::git_reference_target(&*self.raw)) } |
| } |
| |
| /// Return the peeled OID target of this reference. |
| /// |
| /// This peeled OID only applies to direct references that point to a hard |
| /// Tag object: it is the result of peeling such Tag. |
| pub fn target_peel(&self) -> Option<Oid> { |
| unsafe { Binding::from_raw_opt(raw::git_reference_target_peel(&*self.raw)) } |
| } |
| |
| /// Get full name to the reference pointed to by a symbolic reference. |
| /// |
| /// May return `None` if the reference is either not symbolic or not a |
| /// valid utf-8 string. |
| pub fn symbolic_target(&self) -> Option<&str> { |
| self.symbolic_target_bytes() |
| .and_then(|s| str::from_utf8(s).ok()) |
| } |
| |
| /// Get full name to the reference pointed to by a symbolic reference. |
| /// |
| /// Only available if the reference is symbolic. |
| pub fn symbolic_target_bytes(&self) -> Option<&[u8]> { |
| unsafe { crate::opt_bytes(self, raw::git_reference_symbolic_target(&*self.raw)) } |
| } |
| |
| /// Resolve a symbolic reference to a direct reference. |
| /// |
| /// This method iteratively peels a symbolic reference until it resolves to |
| /// a direct reference to an OID. |
| /// |
| /// If a direct reference is passed as an argument, a copy of that |
| /// reference is returned. |
| pub fn resolve(&self) -> Result<Reference<'repo>, Error> { |
| let mut raw = ptr::null_mut(); |
| unsafe { |
| try_call!(raw::git_reference_resolve(&mut raw, &*self.raw)); |
| Ok(Binding::from_raw(raw)) |
| } |
| } |
| |
| /// Peel a reference to an object |
| /// |
| /// This method recursively peels the reference until it reaches |
| /// an object of the specified type. |
| pub fn peel(&self, kind: ObjectType) -> Result<Object<'repo>, Error> { |
| let mut raw = ptr::null_mut(); |
| unsafe { |
| try_call!(raw::git_reference_peel(&mut raw, self.raw, kind)); |
| Ok(Binding::from_raw(raw)) |
| } |
| } |
| |
| /// Peel a reference to a blob |
| /// |
| /// This method recursively peels the reference until it reaches |
| /// a blob. |
| pub fn peel_to_blob(&self) -> Result<Blob<'repo>, Error> { |
| Ok(self.peel(ObjectType::Blob)?.cast_or_panic(ObjectType::Blob)) |
| } |
| |
| /// Peel a reference to a commit |
| /// |
| /// This method recursively peels the reference until it reaches |
| /// a commit. |
| pub fn peel_to_commit(&self) -> Result<Commit<'repo>, Error> { |
| Ok(self |
| .peel(ObjectType::Commit)? |
| .cast_or_panic(ObjectType::Commit)) |
| } |
| |
| /// Peel a reference to a tree |
| /// |
| /// This method recursively peels the reference until it reaches |
| /// a tree. |
| pub fn peel_to_tree(&self) -> Result<Tree<'repo>, Error> { |
| Ok(self.peel(ObjectType::Tree)?.cast_or_panic(ObjectType::Tree)) |
| } |
| |
| /// Peel a reference to a tag |
| /// |
| /// This method recursively peels the reference until it reaches |
| /// a tag. |
| pub fn peel_to_tag(&self) -> Result<Tag<'repo>, Error> { |
| Ok(self.peel(ObjectType::Tag)?.cast_or_panic(ObjectType::Tag)) |
| } |
| |
| /// Rename an existing reference. |
| /// |
| /// This method works for both direct and symbolic references. |
| /// |
| /// If the force flag is not enabled, and there's already a reference with |
| /// the given name, the renaming will fail. |
| pub fn rename( |
| &mut self, |
| new_name: &str, |
| force: bool, |
| msg: &str, |
| ) -> Result<Reference<'repo>, Error> { |
| let mut raw = ptr::null_mut(); |
| let new_name = CString::new(new_name)?; |
| let msg = CString::new(msg)?; |
| unsafe { |
| try_call!(raw::git_reference_rename( |
| &mut raw, self.raw, new_name, force, msg |
| )); |
| Ok(Binding::from_raw(raw)) |
| } |
| } |
| |
| /// Conditionally 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. |
| /// |
| /// The new reference will be written to disk, overwriting the given |
| /// reference. |
| pub fn set_target(&mut self, id: Oid, reflog_msg: &str) -> Result<Reference<'repo>, Error> { |
| let mut raw = ptr::null_mut(); |
| let msg = CString::new(reflog_msg)?; |
| unsafe { |
| try_call!(raw::git_reference_set_target( |
| &mut raw, |
| self.raw, |
| id.raw(), |
| msg |
| )); |
| 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> { |
| fn partial_cmp(&self, other: &Reference<'repo>) -> Option<Ordering> { |
| Some(self.cmp(other)) |
| } |
| } |
| |
| impl<'repo> Ord for Reference<'repo> { |
| fn cmp(&self, other: &Reference<'repo>) -> Ordering { |
| c_cmp_to_ordering(unsafe { raw::git_reference_cmp(&*self.raw, &*other.raw) }) |
| } |
| } |
| |
| impl<'repo> PartialEq for Reference<'repo> { |
| fn eq(&self, other: &Reference<'repo>) -> bool { |
| self.cmp(other) == Ordering::Equal |
| } |
| } |
| |
| impl<'repo> Eq for Reference<'repo> {} |
| |
| impl<'repo> Binding for Reference<'repo> { |
| type Raw = *mut raw::git_reference; |
| unsafe fn from_raw(raw: *mut raw::git_reference) -> Reference<'repo> { |
| Reference { |
| raw, |
| _marker: marker::PhantomData, |
| } |
| } |
| fn raw(&self) -> *mut raw::git_reference { |
| self.raw |
| } |
| } |
| |
| impl<'repo> Drop for Reference<'repo> { |
| fn drop(&mut self) { |
| unsafe { raw::git_reference_free(self.raw) } |
| } |
| } |
| |
| impl<'repo> References<'repo> { |
| /// Consumes a `References` iterator to create an iterator over just the |
| /// name of some references. |
| /// |
| /// This is more efficient if only the names are desired of references as |
| /// the references themselves don't have to be allocated and deallocated. |
| /// |
| /// The returned iterator will yield strings as opposed to a `Reference`. |
| pub fn names<'a>(&'a mut self) -> ReferenceNames<'repo, 'a> { |
| ReferenceNames { inner: self } |
| } |
| } |
| |
| impl<'repo> Binding for References<'repo> { |
| type Raw = *mut raw::git_reference_iterator; |
| unsafe fn from_raw(raw: *mut raw::git_reference_iterator) -> References<'repo> { |
| References { |
| raw, |
| _marker: marker::PhantomData, |
| } |
| } |
| fn raw(&self) -> *mut raw::git_reference_iterator { |
| self.raw |
| } |
| } |
| |
| impl<'repo> Iterator for References<'repo> { |
| type Item = Result<Reference<'repo>, Error>; |
| fn next(&mut self) -> Option<Result<Reference<'repo>, Error>> { |
| let mut out = ptr::null_mut(); |
| unsafe { |
| try_call_iter!(raw::git_reference_next(&mut out, self.raw)); |
| Some(Ok(Binding::from_raw(out))) |
| } |
| } |
| } |
| |
| impl<'repo> Drop for References<'repo> { |
| fn drop(&mut self) { |
| unsafe { raw::git_reference_iterator_free(self.raw) } |
| } |
| } |
| |
| impl<'repo, 'references> Iterator for ReferenceNames<'repo, 'references> { |
| type Item = Result<&'references str, Error>; |
| fn next(&mut self) -> Option<Result<&'references str, Error>> { |
| let mut out = ptr::null(); |
| unsafe { |
| try_call_iter!(raw::git_reference_next_name(&mut out, self.inner.raw)); |
| let bytes = crate::opt_bytes(self, out).unwrap(); |
| let s = str::from_utf8(bytes).unwrap(); |
| Some(Ok(mem::transmute::<&str, &'references str>(s))) |
| } |
| } |
| } |
| |
| #[cfg(test)] |
| mod tests { |
| use crate::{ObjectType, Reference, ReferenceType}; |
| |
| #[test] |
| fn is_valid_name() { |
| assert!(Reference::is_valid_name("refs/foo")); |
| assert!(!Reference::is_valid_name("foo")); |
| assert!(Reference::is_valid_name("FOO_BAR")); |
| |
| assert!(!Reference::is_valid_name("foo")); |
| assert!(!Reference::is_valid_name("_FOO_BAR")); |
| } |
| |
| #[test] |
| #[should_panic] |
| fn is_valid_name_for_invalid_ref() { |
| Reference::is_valid_name("ab\012"); |
| } |
| |
| #[test] |
| fn smoke() { |
| let (_td, repo) = crate::test::repo_init(); |
| let mut head = repo.head().unwrap(); |
| assert!(head.is_branch()); |
| assert!(!head.is_remote()); |
| assert!(!head.is_tag()); |
| assert!(!head.is_note()); |
| |
| // HEAD is a symbolic reference but git_repository_head resolves it |
| // so it is a GIT_REFERENCE_DIRECT. |
| assert_eq!(head.kind().unwrap(), ReferenceType::Direct); |
| |
| assert!(head == repo.head().unwrap()); |
| assert_eq!(head.name(), Some("refs/heads/main")); |
| |
| assert!(head == repo.find_reference("refs/heads/main").unwrap()); |
| assert_eq!( |
| repo.refname_to_id("refs/heads/main").unwrap(), |
| head.target().unwrap() |
| ); |
| |
| assert!(head.symbolic_target().is_none()); |
| assert!(head.target_peel().is_none()); |
| |
| assert_eq!(head.shorthand(), Some("main")); |
| assert!(head.resolve().unwrap() == head); |
| |
| let mut tag1 = repo |
| .reference("refs/tags/tag1", head.target().unwrap(), false, "test") |
| .unwrap(); |
| assert!(tag1.is_tag()); |
| assert_eq!(tag1.kind().unwrap(), ReferenceType::Direct); |
| |
| let peeled_commit = tag1.peel(ObjectType::Commit).unwrap(); |
| assert_eq!(ObjectType::Commit, peeled_commit.kind().unwrap()); |
| assert_eq!(tag1.target().unwrap(), peeled_commit.id()); |
| |
| tag1.delete().unwrap(); |
| |
| let mut sym1 = repo |
| .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(); |
| |
| { |
| assert!(repo.references().unwrap().count() == 1); |
| assert!(repo.references().unwrap().next().unwrap().unwrap() == head); |
| let mut names = repo.references().unwrap(); |
| let mut names = names.names(); |
| assert_eq!(names.next().unwrap().unwrap(), "refs/heads/main"); |
| assert!(names.next().is_none()); |
| assert!(repo.references_glob("foo").unwrap().count() == 0); |
| assert!(repo.references_glob("refs/heads/*").unwrap().count() == 1); |
| } |
| |
| let mut head = head.rename("refs/foo", true, "test").unwrap(); |
| head.delete().unwrap(); |
| } |
| } |
