Skip to main content

git2db/
references.rs

1//! Reference resolution and management
2//!
3//! Consolidated reference handling patterns from the original codebase
4
5use crate::errors::{Git2DBError, Git2DBResult};
6use crate::manager::GitManager;
7use git2::{Oid, Repository};
8use serde::{Deserialize, Deserializer, Serialize, Serializer};
9use std::collections::HashMap;
10use std::path::Path;
11use tracing::{debug, trace};
12
13/// Git reference types
14#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
15#[serde(rename_all = "snake_case")]
16pub enum GitRef {
17    /// Default branch (HEAD)
18    DefaultBranch,
19    /// Specific branch
20    Branch(String),
21    /// Specific tag
22    Tag(String),
23    /// Specific commit
24    #[serde(serialize_with = "serialize_oid", deserialize_with = "deserialize_oid")]
25    Commit(Oid),
26    /// Arbitrary revspec
27    Revspec(String),
28}
29
30fn serialize_oid<S>(oid: &Oid, serializer: S) -> Result<S::Ok, S::Error>
31where
32    S: Serializer,
33{
34    serializer.serialize_str(&oid.to_string())
35}
36
37fn deserialize_oid<'de, D>(deserializer: D) -> Result<Oid, D::Error>
38where
39    D: Deserializer<'de>,
40{
41    let s = String::deserialize(deserializer)?;
42    Oid::from_str(&s).map_err(serde::de::Error::custom)
43}
44
45impl GitRef {
46    /// Parse a reference string
47    pub fn parse(ref_str: &str) -> Git2DBResult<Self> {
48        if ref_str.is_empty() || ref_str == "HEAD" {
49            return Ok(GitRef::DefaultBranch);
50        }
51
52        // Try to parse as commit hash
53        if ref_str.len() >= 7 && ref_str.chars().all(|c| c.is_ascii_hexdigit()) {
54            if ref_str.len() == 40 {
55                // Full SHA
56                let oid = Oid::from_str(ref_str)
57                    .map_err(|_| Git2DBError::reference(ref_str, "Invalid commit hash"))?;
58                return Ok(GitRef::Commit(oid));
59            } else if ref_str.len() >= 7 {
60                // Short SHA - treat as revspec for now
61                return Ok(GitRef::Revspec(ref_str.to_owned()));
62            }
63        }
64
65        // Check for tag prefix
66        if let Some(tag_name) = ref_str.strip_prefix("refs/tags/") {
67            return Ok(GitRef::Tag(tag_name.to_owned()));
68        }
69
70        if let Some(tag_name) = ref_str.strip_prefix("tags/") {
71            return Ok(GitRef::Tag(tag_name.to_owned()));
72        }
73
74        // Check for branch prefix
75        if let Some(branch_name) = ref_str.strip_prefix("refs/heads/") {
76            return Ok(GitRef::Branch(branch_name.to_owned()));
77        }
78
79        if let Some(branch_name) = ref_str.strip_prefix("origin/") {
80            return Ok(GitRef::Branch(branch_name.to_owned()));
81        }
82
83        // Default to branch name or revspec
84        if git2::Reference::is_valid_name(&format!("refs/heads/{ref_str}")) {
85            Ok(GitRef::Branch(ref_str.to_owned()))
86        } else {
87            Ok(GitRef::Revspec(ref_str.to_owned()))
88        }
89    }
90
91    /// Convert to reference string
92    pub fn to_ref_string(&self) -> Option<String> {
93        match self {
94            GitRef::DefaultBranch => None,
95            GitRef::Branch(name) => Some(format!("refs/heads/{name}")),
96            GitRef::Tag(name) => Some(format!("refs/tags/{name}")),
97            GitRef::Commit(oid) => Some(oid.to_string()),
98            GitRef::Revspec(spec) => Some(spec.clone()),
99        }
100    }
101
102    /// Get display name for the reference
103    pub fn display_name(&self) -> String {
104        match self {
105            GitRef::DefaultBranch => "HEAD".to_owned(),
106            GitRef::Branch(name) => name.clone(),
107            GitRef::Tag(name) => format!("tags/{name}"),
108            GitRef::Commit(oid) => format!("{oid:.8}"),
109            GitRef::Revspec(spec) => spec.clone(),
110        }
111    }
112}
113
114impl std::fmt::Display for GitRef {
115    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
116        write!(f, "{}", self.display_name())
117    }
118}
119
120/// Trait for types that can be converted into a GitRef
121///
122/// This allows for flexible API design where methods can accept either:
123/// - String references (parsed at runtime)
124/// - Explicit GitRef enums (clear intent)
125/// - Direct Oids (type-safe, no ambiguity)
126///
127/// # Examples
128///
129/// ```rust,ignore
130/// # use git2db::{Git2DB, GitRef};
131/// # use git2::Oid;
132/// # async fn example(worktree: &mut git2db::WorktreeHandle) -> Result<(), Box<dyn std::error::Error>> {
133/// // String reference (ergonomic)
134/// worktree.checkout("main").await?;
135///
136/// // Explicit GitRef (clear intent)
137/// worktree.checkout(GitRef::Branch("develop".into())).await?;
138///
139/// // Direct Oid (type-safe)
140/// let oid = Oid::from_str("abc123...")?;
141/// worktree.checkout(oid).await?;
142/// # Ok(())
143/// # }
144/// ```
145pub trait IntoGitRef {
146    /// Convert self into a GitRef
147    fn into_git_ref(self) -> GitRef;
148}
149
150impl IntoGitRef for &str {
151    fn into_git_ref(self) -> GitRef {
152        GitRef::parse(self).unwrap_or_else(|_| GitRef::Revspec(self.to_owned()))
153    }
154}
155
156impl IntoGitRef for String {
157    fn into_git_ref(self) -> GitRef {
158        GitRef::parse(&self).unwrap_or(GitRef::Revspec(self))
159    }
160}
161
162impl IntoGitRef for GitRef {
163    fn into_git_ref(self) -> GitRef {
164        self
165    }
166}
167
168impl IntoGitRef for Oid {
169    fn into_git_ref(self) -> GitRef {
170        GitRef::Commit(self)
171    }
172}
173
174/// Reference information
175#[derive(Debug, Clone)]
176pub struct ReferenceInfo {
177    /// Reference name
178    pub name: String,
179    /// Target OID
180    pub target: Oid,
181    /// Reference type
182    pub ref_type: git2::ReferenceType,
183    /// Whether this is the current HEAD
184    pub is_head: bool,
185}
186
187/// Reference resolver with caching
188pub struct ReferenceResolver {
189    cache: parking_lot::RwLock<HashMap<String, CachedReference>>,
190    cache_ttl: std::time::Duration,
191}
192
193/// Cached reference information
194#[derive(Debug, Clone)]
195struct CachedReference {
196    oid: Oid,
197    cached_at: std::time::Instant,
198}
199
200impl Default for ReferenceResolver {
201    fn default() -> Self {
202        Self::new()
203    }
204}
205
206impl ReferenceResolver {
207    /// Create a new reference resolver
208    ///
209    /// Uses the global GitManager singleton for repository access.
210    pub fn new() -> Self {
211        Self {
212            cache: parking_lot::RwLock::new(HashMap::new()),
213            cache_ttl: std::time::Duration::from_secs(60), // 1 minute cache
214        }
215    }
216
217    /// Create with custom cache TTL
218    pub fn with_cache_ttl(cache_ttl: std::time::Duration) -> Self {
219        Self {
220            cache: parking_lot::RwLock::new(HashMap::new()),
221            cache_ttl,
222        }
223    }
224
225    /// Resolve a git reference to an OID
226    pub async fn resolve<P: AsRef<Path>>(
227        &self,
228        repo_path: P,
229        git_ref: &GitRef,
230    ) -> Git2DBResult<Oid> {
231        let repo_path = repo_path.as_ref().to_path_buf();
232        let cache_key = format!("{}:{}", repo_path.display(), git_ref.display_name());
233
234        // Check cache first (sync - just HashMap access)
235        {
236            let cache = self.cache.read();
237            if let Some(cached) = cache.get(&cache_key) {
238                if cached.cached_at.elapsed() < self.cache_ttl {
239                    trace!("Reference cache hit for {}", cache_key);
240                    return Ok(cached.oid);
241                }
242            }
243        }
244
245        // Clone git_ref for move into closure
246        let git_ref = git_ref.clone();
247
248        // Resolve in blocking task
249        let oid = tokio::task::spawn_blocking(move || -> Git2DBResult<Oid> {
250            let repo_cache = GitManager::global().get_repository(&repo_path)?;
251            let repo = repo_cache.open()?;
252            resolve_in_repo(&repo, &git_ref)
253        })
254        .await
255        .map_err(|e| Git2DBError::internal(format!("Task join error: {e}")))??;
256
257        // Update cache (sync - just HashMap write)
258        {
259            let mut cache = self.cache.write();
260            cache.insert(
261                cache_key,
262                CachedReference {
263                    oid,
264                    cached_at: std::time::Instant::now(),
265                },
266            );
267        }
268
269        Ok(oid)
270    }
271
272    /// Resolve reference information (name and target)
273    pub async fn resolve_reference<P: AsRef<Path>>(
274        &self,
275        repo_path: P,
276        git_ref: &GitRef,
277    ) -> Git2DBResult<Option<ReferenceInfo>> {
278        let repo_path = repo_path.as_ref().to_path_buf();
279        let git_ref = git_ref.clone();
280
281        tokio::task::spawn_blocking(move || -> Git2DBResult<Option<ReferenceInfo>> {
282            let repo_cache = GitManager::global().get_repository(&repo_path)?;
283            let repo = repo_cache.open()?;
284
285            match &git_ref {
286                GitRef::DefaultBranch => match repo.head() {
287                    Ok(head_ref) => {
288                        let name = head_ref.shorthand().unwrap_or("HEAD").to_owned();
289                        let target = head_ref.target().unwrap_or_else(Oid::zero);
290                        let ref_type = head_ref.kind().unwrap_or(git2::ReferenceType::Direct);
291                        Ok(Some(ReferenceInfo {
292                            name,
293                            target,
294                            ref_type,
295                            is_head: true,
296                        }))
297                    }
298                    Err(_) => Ok(None),
299                },
300
301                GitRef::Branch(branch_name) => {
302                    let ref_name = format!("refs/heads/{branch_name}");
303                    match repo.find_reference(&ref_name) {
304                        Ok(reference) => {
305                            let target = reference.target().unwrap_or_else(Oid::zero);
306                            let ref_type = reference.kind().unwrap_or(git2::ReferenceType::Direct);
307
308                            // Check if this is the current HEAD
309                            let is_head = repo
310                                .head()
311                                .map(|head| head.name() == Some(&ref_name))
312                                .unwrap_or(false);
313
314                            Ok(Some(ReferenceInfo {
315                                name: branch_name.clone(),
316                                target,
317                                ref_type,
318                                is_head,
319                            }))
320                        }
321                        Err(_) => Ok(None),
322                    }
323                }
324
325                GitRef::Tag(tag_name) => {
326                    let ref_name = format!("refs/tags/{tag_name}");
327                    match repo.find_reference(&ref_name) {
328                        Ok(reference) => {
329                            let target = reference.target().unwrap_or_else(Oid::zero);
330                            let ref_type = reference.kind().unwrap_or(git2::ReferenceType::Direct);
331                            Ok(Some(ReferenceInfo {
332                                name: tag_name.clone(),
333                                target,
334                                ref_type,
335                                is_head: false,
336                            }))
337                        }
338                        Err(_) => Ok(None),
339                    }
340                }
341
342                GitRef::Commit(_) | GitRef::Revspec(_) => {
343                    // Commits and revspecs don't have associated references
344                    Ok(None)
345                }
346            }
347        })
348        .await
349        .map_err(|e| Git2DBError::internal(format!("Task join error: {e}")))?
350    }
351
352    /// List all references in repository
353    pub async fn list_references<P: AsRef<Path>>(
354        &self,
355        repo_path: P,
356    ) -> Git2DBResult<Vec<ReferenceInfo>> {
357        let repo_path = repo_path.as_ref().to_path_buf();
358
359        tokio::task::spawn_blocking(move || -> Git2DBResult<Vec<ReferenceInfo>> {
360            let repo_cache = GitManager::global().get_repository(&repo_path)?;
361            let repo = repo_cache.open()?;
362
363            let mut references = Vec::new();
364            let current_head = repo.head().ok();
365
366            // Iterate through all references
367            let refs = repo.references().map_err(|e| {
368                Git2DBError::repository(&repo_path, format!("Failed to list references: {e}"))
369            })?;
370
371            for reference in refs {
372                let reference = reference.map_err(|e| {
373                    Git2DBError::repository(&repo_path, format!("Failed to read reference: {e}"))
374                })?;
375
376                if let Some(name) = reference.shorthand() {
377                    let target = reference.target().unwrap_or_else(Oid::zero);
378                    let ref_type = reference.kind().unwrap_or(git2::ReferenceType::Direct);
379
380                    // Check if this is the current HEAD
381                    let is_head = current_head
382                        .as_ref()
383                        .and_then(|head| head.name())
384                        .map(|head_name| reference.name() == Some(head_name))
385                        .unwrap_or(false);
386
387                    references.push(ReferenceInfo {
388                        name: name.to_owned(),
389                        target,
390                        ref_type,
391                        is_head,
392                    });
393                }
394            }
395
396            Ok(references)
397        })
398        .await
399        .map_err(|e| Git2DBError::internal(format!("Task join error: {e}")))?
400    }
401
402    /// Get the default branch name
403    pub async fn get_default_branch<P: AsRef<Path>>(&self, repo_path: P) -> Git2DBResult<String> {
404        let repo_path = repo_path.as_ref().to_path_buf();
405
406        tokio::task::spawn_blocking(move || -> Git2DBResult<String> {
407            let repo_cache = GitManager::global().get_repository(&repo_path)?;
408            let repo = repo_cache.open()?;
409
410            // Try to get the symbolic reference HEAD points to
411            if let Ok(head_ref) = repo.head() {
412                if let Some(name) = head_ref.symbolic_target() {
413                    if let Some(branch_name) = name.strip_prefix("refs/heads/") {
414                        return Ok(branch_name.to_owned());
415                    }
416                }
417            }
418
419            // Check for common default branch names
420            for default_name in ["main", "master"] {
421                if repo
422                    .find_branch(default_name, git2::BranchType::Local)
423                    .is_ok()
424                {
425                    return Ok(default_name.to_owned());
426                }
427            }
428
429            // Fallback: get the first branch
430            let mut branches = repo.branches(Some(git2::BranchType::Local)).map_err(|e| {
431                Git2DBError::repository(&repo_path, format!("Failed to list branches: {e}"))
432            })?;
433
434            if let Some(Ok((branch, _))) = branches.next() {
435                if let Some(name) = branch.name().map_err(|e| {
436                    Git2DBError::repository(&repo_path, format!("Failed to get branch name: {e}"))
437                })? {
438                    return Ok(name.to_owned());
439                }
440            }
441
442            // Final fallback
443            Ok("main".to_owned())
444        })
445        .await
446        .map_err(|e| Git2DBError::internal(format!("Task join error: {e}")))?
447    }
448
449    /// Clear the reference cache
450    pub fn clear_cache(&self) {
451        let mut cache = self.cache.write();
452        cache.clear();
453        debug!("Cleared reference cache");
454    }
455}
456
457/// Resolve reference within a repository (standalone helper function)
458fn resolve_in_repo(repo: &Repository, git_ref: &GitRef) -> Git2DBResult<Oid> {
459    match git_ref {
460        GitRef::DefaultBranch => repo
461            .head()
462            .and_then(|head| head.peel_to_commit())
463            .map(|commit| commit.id())
464            .map_err(|e| Git2DBError::reference("HEAD", format!("Failed to resolve HEAD: {e}"))),
465
466        GitRef::Commit(oid) => {
467            // Verify the commit exists
468            repo.find_commit(*oid).map(|_| *oid).map_err(|e| {
469                Git2DBError::reference(oid.to_string(), format!("Commit not found: {e}"))
470            })
471        }
472
473        GitRef::Branch(branch_name) => {
474            let ref_str = format!("refs/heads/{branch_name}");
475            // Try to find as a reference first
476            if let Ok(reference) = repo.find_reference(&ref_str) {
477                reference
478                    .peel_to_commit()
479                    .map(|commit| commit.id())
480                    .map_err(|e| {
481                        Git2DBError::reference(
482                            &ref_str,
483                            format!("Failed to resolve reference: {e}"),
484                        )
485                    })
486            } else {
487                // Fallback to revparse for complex expressions
488                repo.revparse_single(&ref_str)
489                    .and_then(|obj| obj.peel_to_commit())
490                    .map(|commit| commit.id())
491                    .map_err(|e| {
492                        Git2DBError::reference(&ref_str, format!("Failed to resolve revspec: {e}"))
493                    })
494            }
495        }
496
497        GitRef::Tag(tag_name) => {
498            let ref_str = format!("refs/tags/{tag_name}");
499            // Try to find as a reference first
500            if let Ok(reference) = repo.find_reference(&ref_str) {
501                reference
502                    .peel_to_commit()
503                    .map(|commit| commit.id())
504                    .map_err(|e| {
505                        Git2DBError::reference(
506                            &ref_str,
507                            format!("Failed to resolve reference: {e}"),
508                        )
509                    })
510            } else {
511                // Fallback to revparse for complex expressions
512                repo.revparse_single(&ref_str)
513                    .and_then(|obj| obj.peel_to_commit())
514                    .map(|commit| commit.id())
515                    .map_err(|e| {
516                        Git2DBError::reference(&ref_str, format!("Failed to resolve revspec: {e}"))
517                    })
518            }
519        }
520
521        GitRef::Revspec(revspec) => {
522            let ref_str = revspec.clone();
523
524            // Try to find as a reference first
525            if let Ok(reference) = repo.find_reference(&ref_str) {
526                reference
527                    .peel_to_commit()
528                    .map(|commit| commit.id())
529                    .map_err(|e| {
530                        Git2DBError::reference(
531                            &ref_str,
532                            format!("Failed to resolve reference: {e}"),
533                        )
534                    })
535            } else {
536                // Fallback to revparse for complex expressions
537                repo.revparse_single(&ref_str)
538                    .and_then(|obj| obj.peel_to_commit())
539                    .map(|commit| commit.id())
540                    .map_err(|e| {
541                        Git2DBError::reference(&ref_str, format!("Failed to resolve revspec: {e}"))
542                    })
543            }
544        }
545    }
546}
547
548#[cfg(test)]
549mod tests {
550    use super::*;
551
552    #[test]
553    fn test_git_ref_parse() -> crate::Git2DBResult<()> {
554        assert_eq!(GitRef::parse("")?, GitRef::DefaultBranch);
555        assert_eq!(GitRef::parse("HEAD")?, GitRef::DefaultBranch);
556        assert_eq!(GitRef::parse("main")?, GitRef::Branch("main".to_owned()));
557        assert_eq!(
558            GitRef::parse("refs/heads/main")?,
559            GitRef::Branch("main".to_owned())
560        );
561        assert_eq!(
562            GitRef::parse("refs/tags/v1.0")?,
563            GitRef::Tag("v1.0".to_owned())
564        );
565        assert_eq!(GitRef::parse("tags/v1.0")?, GitRef::Tag("v1.0".to_owned()));
566
567        // Test commit hash
568        let full_hash = "1234567890abcdef1234567890abcdef12345678";
569        if let GitRef::Commit(oid) = GitRef::parse(full_hash)? {
570            assert_eq!(oid.to_string(), full_hash);
571        } else {
572            panic!("Expected commit reference");
573        }
574
575        // Test short hash (should be revspec)
576        assert_eq!(
577            GitRef::parse("1234567")?,
578            GitRef::Revspec("1234567".to_owned())
579        );
580        Ok(())
581    }
582
583    #[test]
584    fn test_git_ref_display() {
585        assert_eq!(GitRef::DefaultBranch.display_name(), "HEAD");
586        assert_eq!(GitRef::Branch("main".to_owned()).display_name(), "main");
587        assert_eq!(GitRef::Tag("v1.0".to_owned()).display_name(), "tags/v1.0");
588        assert_eq!(
589            GitRef::Revspec("feature".to_owned()).display_name(),
590            "feature"
591        );
592    }
593
594    #[test]
595    fn test_git_ref_to_ref_string() {
596        assert_eq!(GitRef::DefaultBranch.to_ref_string(), None);
597        assert_eq!(
598            GitRef::Branch("main".to_owned()).to_ref_string(),
599            Some("refs/heads/main".to_owned())
600        );
601        assert_eq!(
602            GitRef::Tag("v1.0".to_owned()).to_ref_string(),
603            Some("refs/tags/v1.0".to_owned())
604        );
605    }
606}