git_policy_cli/
conclusion_cleanup.rs

1//! What:
2//!  Native conclusion cleanup reproduced in the owning worktree's Git directory after a
3//!       merge,
4//!  cherry-pick or revert conclusion lands,
5//!  and the names of that state.
6//! Why:
7//!  Native `git commit` removes `MERGE_HEAD` and its siblings in the shadow;
8//!  the real
9//!      worktree must end the same way,
10//!  but an entry is removed only while it still holds the
11//!      bytes or value copied at preparation,
12//!  because a changed entry belongs to a later command
13//!      (`src/shadow-repository/shadow-conclusion-cleanup.ts`,
14//!  `-files.ts`,
15//!  `-names.ts`).
16//!
17//! In TS you'd write (pseudocode):
18//! ```ts
19//! await reproduceConclusionCleanup({ gitPath, cwd, gitDir, shadowPath, transactionDirectory, refFormat });
20//! ```
21
22/// Debug diagnostics.
23use super::diagnostic_log::debug;
24/// Tree removal and private files.
25use super::private_storage::remove_tree;
26/// The fail-closed recovery failure.
27use super::recovery_error::{RecoveryError, io_failure};
28/// Exact reads and existence probes.
29use super::recovery_files::{path_present, read_optional, remove_file_if_present};
30/// Shadow commands.
31use super::shadow_git::shadow_request;
32/// Running real Git.
33use super::transaction_git::{GitContext, GitRequest, run_git, run_git_checked};
34/// The ref storage backend.
35use super::transaction_journal::RefFormat;
36/// `BTreeMap` is a sorted map.
37use std::collections::BTreeMap;
38/// `Path`/`PathBuf` are borrowed/owned filesystem paths.
39use std::path::{Path, PathBuf};
40
41/// The rerere resolution cache Git rewrites during a conflicted merge,
42///  copied back after landing.
43pub const MERGE_RR_FILENAME: &str = "MERGE_RR";
44
45/// Conclusion state files copied into the shadow at preparation.
46pub const CONCLUSION_STATE_FILES: [&str; 8] = [
47    "MERGE_HEAD",
48    "MERGE_MSG",
49    "MERGE_MODE",
50    "SQUASH_MSG",
51    "AUTO_MERGE",
52    "CHERRY_PICK_HEAD",
53    "REVERT_HEAD",
54    MERGE_RR_FILENAME,
55];
56
57/// Conclusion state directory copied into the shadow at preparation.
58pub const SEQUENCER_DIRECTORY: &str = "sequencer";
59
60/// Pseudorefs a reftable repository keeps in its ref store rather than as files.
61pub const STORE_HELD_PSEUDOREFS: [&str; 3] = ["AUTO_MERGE", "CHERRY_PICK_HEAD", "REVERT_HEAD"];
62
63/// Entries landing removes from the owning worktree when native Git removed them in the shadow.
64pub const REMOVED_CONCLUSION_FILES: [&str; 7] = [
65    "AUTO_MERGE",
66    "MERGE_HEAD",
67    "MERGE_MODE",
68    "MERGE_MSG",
69    "SQUASH_MSG",
70    "CHERRY_PICK_HEAD",
71    "REVERT_HEAD",
72];
73
74/// Private directory of the transaction holding the preparation-time copies.
75pub const CONCLUSION_COPY_DIRECTORY: &str = "conclusion";
76
77/// Record of the store-held pseudoref values copied at preparation.
78pub const STORE_RECORD_FILENAME: &str = "store-held.json";
79
80/// What:
81///  Whether an entry lives in the ref store under this backend.
82/// Why:
83///   `isStoreHeld`:
84///  reftable keeps three pseudorefs in the store.
85///
86/// In TS you'd write (pseudocode):
87/// ```ts
88/// isStoreHeld({ refFormat, name })
89/// ```
90pub fn is_store_held(format: RefFormat, name: &str) -> bool {
91    return format == RefFormat::Reftable && STORE_HELD_PSEUDOREFS.contains(&name);
92}
93
94/// What:
95///  Resolve a pseudoref with `git rev-parse --verify --quiet`,
96///  or nothing when absent.
97/// Why:
98///   `resolvePseudoref`.
99///
100/// In TS you'd write (pseudocode):
101/// ```ts
102/// async function resolvePseudoref({ gitPath, cwd, name }): Promise<string | typeof ENTRY_ABSENT>;
103/// ```
104pub fn resolve_pseudoref(context: &GitContext, request: GitRequest) -> Option<String> {
105    let output: super::transaction_git::GitOutput = run_git(context, &request).ok()?;
106    if !output.succeeded() {
107        return None;
108    }
109    let text: &str = std::str::from_utf8(output.stdout.as_slice()).ok()?;
110    return Some(String::from(super::js_text::trim_javascript(text)));
111}
112
113/// What:
114///  Every regular file under a directory,
115///  by path relative to it.
116/// Why:
117///   `readTree`:
118///  the sequencer copy and the real sequencer are compared whole.
119///
120/// In TS you'd write (pseudocode):
121/// ```ts
122/// async function readTree(root: string): Promise<ReadonlyMap<string, Uint8Array>>;
123/// ```
124fn read_tree(root: &Path) -> Result<BTreeMap<PathBuf, Vec<u8>>, RecoveryError> {
125    // `mut` allows collecting files while walking.
126    let mut files: BTreeMap<PathBuf, Vec<u8>> = BTreeMap::new();
127    if !path_present(root)? {
128        return Ok(files);
129    }
130    let mut pending: Vec<PathBuf> = vec![root.to_path_buf()];
131    while let Some(directory) = pending.pop() {
132        let listing: std::fs::ReadDir = match std::fs::read_dir(&directory) {
133            Ok(found) => found,
134            Err(error) => return Err(io_failure("listing", directory.as_path(), &error)),
135        };
136        for item in listing {
137            let entry: std::fs::DirEntry = match item {
138                Ok(found) => found,
139                Err(error) => return Err(io_failure("listing", directory.as_path(), &error)),
140            };
141            let kind: std::fs::FileType = match entry.file_type() {
142                Ok(found) => found,
143                Err(error) => return Err(io_failure("inspecting", entry.path().as_path(), &error)),
144            };
145            let path: PathBuf = entry.path();
146            if kind.is_dir() {
147                pending.push(path);
148            } else if kind.is_file() {
149                let bytes: Vec<u8> = match std::fs::read(&path) {
150                    Ok(read) => read,
151                    Err(error) => return Err(io_failure("reading", path.as_path(), &error)),
152                };
153                let relative: PathBuf = path
154                    .strip_prefix(root)
155                    .unwrap_or(path.as_path())
156                    .to_path_buf();
157                files.insert(relative, bytes);
158            }
159        }
160    }
161    return Ok(files);
162}
163
164/// What:
165///  Whether two directory trees hold the same regular files with the same bytes,
166///  and are
167///       not empty.
168/// Why:
169///   `sameTree`:
170///  the sequencer is removed only while it is exactly the copied state.
171///
172/// In TS you'd write (pseudocode):
173/// ```ts
174/// async function sameTree({ left, right }): Promise<boolean>;
175/// ```
176pub fn same_tree(left: &Path, right: &Path) -> Result<bool, RecoveryError> {
177    let first: BTreeMap<PathBuf, Vec<u8>> = read_tree(left)?;
178    let second: BTreeMap<PathBuf, Vec<u8>> = read_tree(right)?;
179    return Ok(!first.is_empty() && first == second);
180}
181
182/// What:
183///  The store-held values copied at preparation,
184///  from `store-held.json`.
185/// Why:
186///   A value that is not text is no copy;
187///  the record itself must be valid UTF-8 JSON.
188///
189/// In TS you'd write (pseudocode):
190/// ```ts
191/// JSON.parse(decode(await readFile(join(copies, STORE_RECORD_FILENAME))))
192/// ```
193fn read_store_record(copies: &Path) -> Result<serde_json::Value, RecoveryError> {
194    let path: PathBuf = copies.join(STORE_RECORD_FILENAME);
195    let bytes: Vec<u8> = match std::fs::read(&path) {
196        Ok(read) => read,
197        Err(error) => return Err(io_failure("reading", path.as_path(), &error)),
198    };
199    let Some(text) = super::json_record::decode_fatal(bytes.as_slice()) else {
200        return Err(RecoveryError(format!("{} is not UTF-8.", path.display())));
201    };
202    match serde_json::from_str::<serde_json::Value>(text) {
203        Ok(value) => return Ok(value),
204        Err(_) => return Err(RecoveryError(format!("{} is not JSON.", path.display()))),
205    }
206}
207
208/// What:
209///  Remove one store-held pseudoref from the owning worktree when the shadow no longer
210///       holds it and the worktree still holds the copied value.
211/// Why:
212///   A reftable repository deletes it with `git update-ref -d <name> <copied value>`.
213///
214/// In TS you'd write (pseudocode):
215/// ```ts
216/// if (inShadow.exitCode !== 0 && inReal === copied) await runTransactionGit({ args: ['update-ref', '-d', name, copied] });
217/// ```
218fn clean_store_held(
219    context: &GitContext,
220    cwd: &Path,
221    shadow: &Path,
222    name: &str,
223    copied: &str,
224) -> Result<(), RecoveryError> {
225    let in_shadow: bool = match run_git(
226        context,
227        &shadow_request(shadow, shadow, &["rev-parse", "--verify", "--quiet", name]),
228    ) {
229        Ok(output) => output.succeeded(),
230        Err(_) => false,
231    };
232    let in_real: Option<String> = resolve_pseudoref(
233        context,
234        GitRequest::new(cwd, &["rev-parse", "--verify", "--quiet", name]),
235    );
236    if !in_shadow
237        && in_real.as_deref() == Some(copied)
238        && let Err(failure) = run_git_checked(
239            context,
240            &GitRequest::new(cwd, &["update-ref", "-d", name, copied]),
241        )
242    {
243        return Err(RecoveryError(failure.0));
244    }
245    return Ok(());
246}
247
248/// What:
249///  Reproduce native conclusion cleanup in the owning worktree's Git directory.
250/// Why:
251///   `reproduceConclusionCleanup`:
252///  removed entries,
253///  `MERGE_RR` copied back,
254///  `ORIG_HEAD`
255///       kept,
256///  and `sequencer/` removed only when native Git removed the shadow copy.
257///
258/// In TS you'd write (pseudocode):
259/// ```ts
260/// async function reproduceConclusionCleanup({ gitPath, cwd, gitDir, shadowPath, transactionDirectory, refFormat }): Promise<void>;
261/// ```
262pub fn reproduce_conclusion_cleanup(
263    context: &GitContext,
264    cwd: &Path,
265    git_dir: &Path,
266    shadow: &Path,
267    transaction_directory: &Path,
268    format: RefFormat,
269) -> Result<(), RecoveryError> {
270    let copies: PathBuf = transaction_directory.join(CONCLUSION_COPY_DIRECTORY);
271    if !path_present(copies.as_path())? {
272        debug(
273            "reproduceConclusionCleanup",
274            format!(
275                "no conclusion state was copied: {}",
276                transaction_directory.display()
277            )
278            .as_str(),
279        );
280        return Ok(());
281    }
282    let store: serde_json::Value = read_store_record(copies.as_path())?;
283    for name in REMOVED_CONCLUSION_FILES {
284        if is_store_held(format, name) {
285            if let Some(copied) = store.get(name).and_then(serde_json::Value::as_str) {
286                clean_store_held(context, cwd, shadow, name, copied)?;
287            }
288            continue;
289        }
290        let copy: Option<Vec<u8>> = read_optional(copies.join(name).as_path())?;
291        let in_shadow: Option<Vec<u8>> = read_optional(shadow.join(name).as_path())?;
292        let real: Option<Vec<u8>> = read_optional(git_dir.join(name).as_path())?;
293        if copy.is_some() && in_shadow.is_none() && copy == real {
294            remove_file_if_present(git_dir.join(name).as_path())?;
295            debug(
296                "reproduceConclusionCleanup",
297                format!("removed conclusion entry {name} as native Git did").as_str(),
298            );
299        }
300    }
301    if let Some(merge_rr) = read_optional(shadow.join(MERGE_RR_FILENAME).as_path())? {
302        let temporary: PathBuf = git_dir.join(format!("{MERGE_RR_FILENAME}.cli-git-{}", std::process::id()));
303        if let Err(error) = std::fs::write(&temporary, merge_rr.as_slice()) {
304            return Err(io_failure("writing", temporary.as_path(), &error));
305        }
306        let destination: PathBuf = git_dir.join(MERGE_RR_FILENAME);
307        if let Err(error) = std::fs::rename(&temporary, &destination) {
308            return Err(io_failure("replacing", destination.as_path(), &error));
309        }
310    }
311    let sequencer_copy: PathBuf = copies.join(SEQUENCER_DIRECTORY);
312    let removed_in_shadow: bool = path_present(sequencer_copy.as_path())?
313        && !path_present(shadow.join(SEQUENCER_DIRECTORY).as_path())?;
314    let real_sequencer: PathBuf = git_dir.join(SEQUENCER_DIRECTORY);
315    if removed_in_shadow && same_tree(sequencer_copy.as_path(), real_sequencer.as_path())? {
316        if let Err(error) = remove_tree(real_sequencer.as_path()) {
317            return Err(io_failure("removing", real_sequencer.as_path(), &error));
318        }
319        debug(
320            "reproduceConclusionCleanup",
321            "removed sequencer state as native Git did after the last pick",
322        );
323    }
324    return Ok(());
325}
326
327/// Cleanup controls stay out of the release executable.
328#[cfg(test)]
329#[path = "conclusion_cleanup_tests.rs"]
330mod tests;
git_policy_cli/conclusion_cleanup.rs

git_policy_cli/
conclusion_cleanup.rs
