Skip to main content

grit_lib/error/
refs.rs

1//! [`RefError`]: reference, reflog, and `HEAD` state failures.
2
3use thiserror::Error;
4
5use super::RefLockError;
6
7/// Reference failure: ref names and values, `packed-refs`, ref locks, ref stores (files and
8/// reftable), reflog selectors, and the state of `HEAD`.
9///
10/// Surfaced on the umbrella as [`Error::Ref`](crate::error::Error::Ref). Branch and tag
11/// porcelain failures have their own areas ([`Error::Branch`](crate::error::Error::Branch),
12/// [`Error::Tag`](crate::error::Error::Tag)).
13#[derive(Debug, Error)]
14#[non_exhaustive]
15pub enum RefError {
16    /// A reference name or value is invalid.
17    #[error("invalid ref: {detail}")]
18    Invalid {
19        /// What is wrong with the ref name or value.
20        detail: String,
21    },
22
23    /// A `packed-refs` line Git would reject when reading the ref database.
24    #[error("unexpected line in {path}: {line}")]
25    PackedRefsUnexpectedLine {
26        /// Path to the `packed-refs` file being read.
27        path: String,
28        /// Offending line contents.
29        line: String,
30    },
31
32    /// Reference lock failure while updating refs.
33    #[error(transparent)]
34    Lock(#[from] RefLockError),
35
36    /// Reference store transaction or iteration failure.
37    #[error(transparent)]
38    Store(crate::refs::store::RefStoreError),
39
40    /// Reftable file, stack, or transaction failure.
41    #[error(transparent)]
42    Reftable(#[from] crate::reftable::ReftableError),
43
44    /// [`create_commit`](crate::porcelain::commit::create_commit) requires a branch checkout.
45    #[error("HEAD is detached")]
46    DetachedHead,
47
48    /// `HEAD` is on a branch with no commits yet, but the operation needs a commit
49    /// ([`Repository::head_commit`](crate::repo::Repository::head_commit),
50    /// [`replay_commit`](crate::porcelain::replay::replay_commit)).
51    #[error("no commits yet on this branch")]
52    UnbornHead,
53
54    /// `HEAD` could not be resolved to a branch, detached commit, or unborn branch.
55    #[error("HEAD is in an unknown state")]
56    InvalidHead,
57
58    /// `HEAD` is not a symbolic ref to the branch an update expected it to be on.
59    #[error("HEAD does not point at branch '{branch}'")]
60    HeadNotOnBranch {
61        /// Full name of the branch `HEAD` was expected to point at.
62        branch: String,
63    },
64
65    /// A detached-`HEAD` update found `HEAD` attached to a branch.
66    #[error("HEAD points at a branch, not a detached commit")]
67    HeadNotDetached,
68
69    /// A ref update tried to write through a lock it had already committed or dropped.
70    #[error("ref lock for '{refname}' was already released")]
71    LockReleased {
72        /// The ref whose lock was released.
73        refname: String,
74    },
75
76    /// A ref query sorted by creator date, or filtered by reachability, without an object
77    /// database to read commits from.
78    #[error("ref query requires an object database")]
79    QueryNeedsObjectDatabase,
80
81    /// A ref query's `--contains` / `--merged` / `--no-merged` target does not peel to a commit.
82    #[error("object {oid} is not a commit")]
83    QueryTargetNotCommit {
84        /// The target object.
85        oid: crate::objects::ObjectId,
86    },
87
88    /// Ref does not exist and has no reflog entries.
89    #[error("unknown ref '{refname}'")]
90    ReflogUnknownRef {
91        /// User-supplied or DWIM ref name.
92        refname: String,
93    },
94
95    /// A reflog selector is missing its reference or `@{n}` delimiters.
96    #[error("expected ref@{{n}} form, got '{spec}'")]
97    ReflogInvalidSelector {
98        /// Selector after trimming surrounding whitespace.
99        spec: String,
100    },
101
102    /// A reflog selector index is not a nonnegative integer that fits in `usize`.
103    #[error("invalid reflog index in '{spec}'")]
104    ReflogInvalidIndex {
105        /// Selector after trimming surrounding whitespace.
106        spec: String,
107        /// Integer parsing failure, including overflow.
108        #[source]
109        source: std::num::ParseIntError,
110    },
111
112    /// A reflog expiry (`gc.reflogExpire`, `--expire`) is neither `never`/`now`/`all` nor a
113    /// date.
114    #[error("invalid reflog expiry: {value:?}")]
115    InvalidReflogExpiry {
116        /// The expiry as given.
117        value: String,
118    },
119
120    /// `ref@{{n}}` is out of range for the current reflog.
121    #[error("reflog entry {refname}@{{{index}}} not found")]
122    ReflogIndexOutOfRange {
123        /// Ref whose reflog was read.
124        refname: String,
125        /// Requested newest-first index.
126        index: usize,
127    },
128}
129
130impl RefError {
131    /// Stable snake_case slug for this failure (the former umbrella variant names).
132    #[must_use]
133    pub fn kind_name(&self) -> &'static str {
134        match self {
135            Self::Invalid { .. } => "invalid_ref",
136            Self::PackedRefsUnexpectedLine { .. } => "packed_refs_unexpected_line",
137            Self::Lock(..) => "ref_lock",
138            Self::Store(..) => "ref_store",
139            Self::Reftable(..) => "reftable",
140            Self::DetachedHead => "detached_head",
141            Self::UnbornHead => "unborn_head",
142            Self::InvalidHead => "invalid_head",
143            Self::HeadNotOnBranch { .. } => "head_not_on_branch",
144            Self::HeadNotDetached => "head_not_detached",
145            Self::LockReleased { .. } => "ref_lock_released",
146            Self::QueryNeedsObjectDatabase => "ref_query_needs_object_database",
147            Self::QueryTargetNotCommit { .. } => "ref_query_target_not_commit",
148            Self::ReflogUnknownRef { .. } => "reflog_unknown_ref",
149            Self::ReflogInvalidSelector { .. } => "reflog_invalid_selector",
150            Self::ReflogInvalidIndex { .. } => "reflog_invalid_index",
151            Self::ReflogIndexOutOfRange { .. } => "reflog_index_out_of_range",
152            Self::InvalidReflogExpiry { .. } => "invalid_reflog_expiry",
153        }
154    }
155}