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}