1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
//! `mkit update-ref [-d] <ref> [<newvalue> [<oldvalue>]]` — low-level guarded
//! ref write/delete, like `git update-ref`.
//!
//! Supports `refs/heads/<branch>` and `refs/tags/<name>` (the namespaces mkit
//! manages); other namespaces (`HEAD`, `refs/remotes/…`) are rejected.
//! `<newvalue>` / `<oldvalue>` resolve through the shared revspec grammar
//! (ref, full/short hash, `HEAD~n`). Without `<oldvalue>` the write is
//! unconditional; with one it is a compare-and-swap that fails unless the ref
//! currently holds that value. In **update** mode an all-zero `<oldvalue>`
//! means "the ref must not already exist" (git's create-only convention); in
//! `-d` (delete) mode `<oldvalue>`, if given, must be a concrete value the
//! ref currently holds (an all-zero value is rejected — you cannot delete a
//! ref asserted to be absent).
//!
//! Safety divergence: `-d` on a branch uses the same guard as `branch -d` —
//! it refuses to delete the currently checked-out branch (git's plumbing
//! would, leaving HEAD dangling).
use clap::Parser;
use mkit_core::hash::Hash;
use mkit_core::layout::RepoLayout;
use mkit_core::refs::{self, RefWriteCondition};
use mkit_core::store::ObjectStore;
use super::revspec;
use crate::clap_shim;
use crate::exit;
#[derive(Debug, Parser)]
#[command(
name = "mkit update-ref",
about = "Create, update, or delete a ref (guarded)."
)]
struct UpdateRefOpts {
/// Delete the ref instead of updating it.
#[arg(short = 'd', long)]
delete: bool,
/// The ref to write: `refs/heads/<branch>` or `refs/tags/<name>`.
name: String,
/// New value as a revision (required unless `-d`); for `-d` this slot is
/// the optional expected old value.
value: Option<String>,
/// Expected current value for a compare-and-swap (update mode only).
old_value: Option<String>,
}
/// Which ref namespace a `refs/…` path addresses.
enum Namespace {
Head,
Tag,
}
#[must_use]
pub fn run(args: &[String]) -> u8 {
let opts = match clap_shim::parse::<UpdateRefOpts>("mkit update-ref", args) {
Ok(o) => o,
Err(code) => return code,
};
let cwd = match std::env::current_dir() {
Ok(p) => p,
Err(e) => return emit_err(&format!("cwd: {e}"), exit::NOINPUT),
};
let layout = match super::resolve_layout(&cwd) {
Ok(layout) => layout,
Err(code) => return code,
};
let store = match ObjectStore::open(&layout) {
Ok(s) => s,
Err(e) => return emit_err(&format!("not a mkit repo: {e}"), exit::GENERAL_ERROR),
};
let Some((ns, name)) = parse_ref(&opts.name) else {
return emit_err(
&format!(
"unsupported ref '{}': update-ref handles refs/heads/<branch> and refs/tags/<name>",
opts.name
),
exit::USAGE,
);
};
// update-ref publishes a gc root (refs/heads/* or refs/tags/*) at an
// arbitrary object, so hold the repo lock across resolve + publish: a
// concurrent `gc --grace-secs 0` then can't prune a (possibly
// unreachable) target between resolving it and writing the ref (#267).
// Acquired after repo validation (store open) so a non-repo reported
// cleanly above; covers the delete path too for consistency.
let _lock = match super::acquire_worktree_lock(&layout) {
Ok(l) => l,
Err(code) => return code,
};
if opts.delete {
if opts.old_value.is_some() {
return super::usage_error("usage: mkit update-ref -d <ref> [<oldvalue>]");
}
return run_delete(&store, &layout, &ns, name, opts.value.as_deref());
}
let Some(newspec) = opts.value.as_deref() else {
return super::usage_error("usage: mkit update-ref <ref> <newvalue> [<oldvalue>]");
};
let newhash = match resolve(&store, &layout, newspec) {
Ok(h) => h,
Err(msg) => return emit_err(&msg, exit::DATAERR),
};
// Refuse to publish a ref pointing at an object that is not present
// (resolved under the lock, so this also closes the resolve→publish race).
if !store.contains(&newhash) {
return emit_err(
&format!("object '{newspec}' does not exist in the store"),
exit::DATAERR,
);
}
let condition = match opts.old_value.as_deref() {
None => RefWriteCondition::Any,
Some(s) if is_zero(s) => RefWriteCondition::Missing,
Some(s) => match resolve(&store, &layout, s) {
Ok(h) => RefWriteCondition::Match(h),
Err(msg) => return emit_err(&msg, exit::DATAERR),
},
};
let res = match ns {
// Branch moves MUST funnel through the history-recording helper so a
// `--features history-mmr` build advances the ref and its journal
// together under lock (the CLI ref-write invariant). Tags are not
// history-tracked (the journal is keyed per branch).
Namespace::Head => super::write_ref_recording_history(&layout, name, condition, &newhash),
Namespace::Tag => refs::update_tag(&layout, name, condition, &newhash),
};
match res {
Ok(()) => exit::OK,
Err(e) => emit_err(
&format!("update-ref {}: {e}", opts.name),
exit::GENERAL_ERROR,
),
}
}
/// `-d`: delete the ref, optionally verifying its current value first.
fn run_delete(
store: &ObjectStore,
layout: &RepoLayout,
ns: &Namespace,
name: &str,
old_value: Option<&str>,
) -> u8 {
if let Some(spec) = old_value {
if is_zero(spec) {
return emit_err(
"cannot delete a ref whose expected old value is all-zero (absent)",
exit::USAGE,
);
}
let expected = match resolve(store, layout, spec) {
Ok(h) => h,
Err(msg) => return emit_err(&msg, exit::DATAERR),
};
let current = match ns {
Namespace::Head => refs::read_ref(layout, name),
Namespace::Tag => refs::read_tag(layout, name),
};
match current {
Ok(Some(h)) if h == expected => {}
Ok(_) => {
return emit_err(
"ref does not have the expected old value; not deleting",
exit::GENERAL_ERROR,
);
}
Err(e) => return emit_err(&format!("read ref: {e}"), exit::GENERAL_ERROR),
}
}
let res = match ns {
// Branch delete uses the safe path — refuses the current branch.
Namespace::Head => refs::delete_ref_safe(layout, name),
Namespace::Tag => refs::delete_tag(layout, name),
};
match res {
Ok(()) => exit::OK,
Err(e) => emit_err(&format!("delete ref: {e}"), exit::GENERAL_ERROR),
}
}
/// Map a `refs/heads/<branch>` / `refs/tags/<name>` path to its namespace and
/// short name. Returns `None` for any other ref.
fn parse_ref(full: &str) -> Option<(Namespace, &str)> {
if let Some(b) = full.strip_prefix("refs/heads/") {
Some((Namespace::Head, b))
} else if let Some(t) = full.strip_prefix("refs/tags/") {
Some((Namespace::Tag, t))
} else {
None
}
}
/// Resolve a revision spec to a concrete object hash.
fn resolve(store: &ObjectStore, layout: &RepoLayout, spec: &str) -> Result<Hash, String> {
revspec::resolve_revision(store, layout, spec)
.map_err(|e| format!("bad revision '{spec}': {e}"))
}
/// Is `s` git's all-zero object id (mkit's is 64 hex zeros)?
fn is_zero(s: &str) -> bool {
s.len() == 64 && s.bytes().all(|b| b == b'0')
}
use super::error as emit_err;