Skip to main content

jouet_git/stack/
sync.rs

1//! `jouet stack sync`: bring each layer up to date by merging its parent,
2//! bottom first, verifying each merge by ancestry and content before it is
3//! committed. Never a rebase, and never a force push.
4//!
5//! The lessons this encodes:
6//! - A layer starts from its local branch, never `origin/…`, so fixes not
7//!   yet pushed are kept; a local branch behind its remote is refused.
8//! - After a prerequisite merged (often squashed), the trunk is merged in
9//!   rather than rebased onto, which would conflict with the old commits.
10//! - A merge whose tree lacks some of the parent's changes is not
11//!   committed: sync stops there and says what to do.
12//! - A branch checked out in another worktree belongs to whoever works
13//!   there, so sync stops rather than change it under them.
14
15use super::{Stack, missing_changes, trunk_tip};
16use crate::{Error, Git};
17use jouet_output::exit::Exit;
18use serde::Serialize;
19use std::path::{Path, PathBuf};
20
21#[derive(Debug, Clone, Copy, Default)]
22pub struct Options {
23    /// Show the plan; merge, fetch and push nothing.
24    pub dry_run: bool,
25    /// Push the layers that are ahead of their remote branch, afterwards.
26    pub push: bool,
27    /// Fetch the remote first.
28    pub fetch: bool,
29}
30
31/// What happened to one layer, or would in a dry run.
32#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
33pub struct Step {
34    pub branch: String,
35    /// `up_to_date`, `merged` (or `would_merge`), `skipped_merged`.
36    pub action: &'static str,
37    /// What was merged in: the parent branch, or `origin/main`.
38    #[serde(skip_serializing_if = "Option::is_none")]
39    pub from: Option<String>,
40    /// The merge commit.
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub commit: Option<String>,
43    /// The local branch was created from the remote's first.
44    #[serde(skip_serializing_if = "std::ops::Not::not")]
45    pub created: bool,
46}
47
48/// Where sync stopped, and what to do.
49#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
50pub struct Stopped {
51    pub branch: String,
52    /// `conflict`, `content`, `behind_remote`, `checked_out_elsewhere`,
53    /// `dirty`, `missing_branch` or `error`.
54    pub reason: &'static str,
55    pub message: String,
56    /// What to do, as commands where it can.
57    pub next: String,
58    #[serde(skip_serializing_if = "Vec::is_empty")]
59    pub files: Vec<String>,
60    #[serde(skip)]
61    pub exit: Exit,
62}
63
64/// A push of one layer.
65#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
66pub struct Push {
67    pub branch: String,
68    pub ok: bool,
69    #[serde(skip_serializing_if = "Option::is_none")]
70    pub error: Option<String>,
71}
72
73#[derive(Debug, Clone, Default, Serialize)]
74pub struct Report {
75    pub steps: Vec<Step>,
76    #[serde(skip_serializing_if = "Option::is_none")]
77    pub stopped: Option<Stopped>,
78    #[serde(skip_serializing_if = "Vec::is_empty")]
79    pub pushed: Vec<Push>,
80    #[serde(skip_serializing_if = "std::ops::Not::not")]
81    pub dry_run: bool,
82}
83
84impl Report {
85    pub fn exit(&self) -> Exit {
86        if let Some(stopped) = &self.stopped {
87            return stopped.exit;
88        }
89        if self.pushed.iter().any(|p| !p.ok) {
90            return Exit::Remote;
91        }
92        Exit::Ok
93    }
94}
95
96/// Syncs the stack, bottom first, stopping at the first layer that cannot
97/// be brought up to date.
98pub fn sync(git: &Git, stack: &Stack, opts: Options) -> Report {
99    let mut report = Report {
100        dry_run: opts.dry_run,
101        ..Report::default()
102    };
103    if opts.fetch
104        && !opts.dry_run
105        && let Err(e) = git.text(&["fetch", "--quiet", "--prune", &stack.remote])
106    {
107        report.stopped = Some(Stopped {
108            branch: stack.trunk.clone(),
109            reason: "error",
110            message: e.message,
111            next: format!("check that `git fetch {}` works, then rerun", stack.remote),
112            files: Vec::new(),
113            exit: Exit::Remote,
114        });
115        return report;
116    }
117    let here = git.toplevel().ok().and_then(|p| p.canonicalize().ok());
118    let checked_out = worktrees(git);
119    // In a dry run, a layer that would be merged changes for the one above.
120    let mut below_changes = false;
121    for (i, layer) in stack.layers.iter().enumerate() {
122        if layer.merged {
123            report.steps.push(step(&layer.branch, "skipped_merged"));
124            below_changes = false;
125            continue;
126        }
127        match layer_sync(git, stack, i, here.as_deref(), &checked_out, opts) {
128            Ok(mut step) => {
129                let on_layer_below = !layer.parent_merged && layer.parent != stack.trunk;
130                if opts.dry_run && below_changes && on_layer_below && step.action == "up_to_date" {
131                    step.action = "would_merge";
132                    step.from = Some(layer.parent.clone());
133                }
134                below_changes = step.action == "would_merge";
135                report.steps.push(step);
136            }
137            Err(stopped) => {
138                report.stopped = Some(stopped);
139                break;
140            }
141        }
142    }
143    if opts.push && !opts.dry_run && report.stopped.is_none() {
144        report.pushed = push(git, stack);
145    }
146    report
147}
148
149fn step(branch: &str, action: &'static str) -> Step {
150    Step {
151        branch: branch.to_string(),
152        action,
153        from: None,
154        commit: None,
155        created: false,
156    }
157}
158
159fn stop(branch: &str, reason: &'static str, message: String, next: String, exit: Exit) -> Stopped {
160    Stopped {
161        branch: branch.to_string(),
162        reason,
163        message,
164        next,
165        files: Vec::new(),
166        exit,
167    }
168}
169
170/// Each branch checked out in a worktree, with the worktree.
171fn worktrees(git: &Git) -> Vec<(String, PathBuf)> {
172    let out = git
173        .text(&["worktree", "list", "--porcelain"])
174        .unwrap_or_default();
175    let mut found = Vec::new();
176    let mut path: Option<PathBuf> = None;
177    for line in out.lines() {
178        if let Some(p) = line.strip_prefix("worktree ") {
179            path = Some(PathBuf::from(p));
180        } else if let (Some(b), Some(p)) = (line.strip_prefix("branch refs/heads/"), &path) {
181            found.push((
182                b.to_string(),
183                p.canonicalize().unwrap_or_else(|_| p.clone()),
184            ));
185        }
186    }
187    found
188}
189
190fn layer_sync(
191    git: &Git,
192    stack: &Stack,
193    i: usize,
194    here: Option<&Path>,
195    checked_out: &[(String, PathBuf)],
196    opts: Options,
197) -> Result<Step, Stopped> {
198    let layer = &stack.layers[i];
199    let branch = &layer.branch;
200    let local_ref = format!("refs/heads/{branch}");
201    let remote_name = format!("{}/{branch}", stack.remote);
202    let remote = git.commit_sha(&format!("refs/remotes/{remote_name}"));
203    let mut created = false;
204    let local = match git.commit_sha(&local_ref) {
205        Some(sha) => sha,
206        None => {
207            let Some(remote) = remote.clone() else {
208                return Err(stop(
209                    branch,
210                    "missing_branch",
211                    format!("`{branch}` has no local or remote branch"),
212                    "fetch it or remove it from the stack, then rerun".to_string(),
213                    Exit::Precondition,
214                ));
215            };
216            // Nothing local to lose: the local branch starts as the remote's.
217            if !opts.dry_run {
218                git.text(&["branch", "--no-track", branch, &remote])
219                    .map_err(|e| error(branch, e))?;
220            }
221            created = true;
222            remote
223        }
224    };
225    if let Some(remote) = &remote {
226        let behind = git.count(&format!("{local}..{remote}")).unwrap_or(0);
227        if behind > 0 {
228            return Err(stop(
229                branch,
230                "behind_remote",
231                format!(
232                    "`{branch}` is {behind} commit(s) behind {remote_name}: someone pushed work the local branch does not have"
233                ),
234                format!(
235                    "merge it first (`git merge {remote_name}` where `{branch}` is checked out), then rerun"
236                ),
237                Exit::Precondition,
238            ));
239        }
240    }
241    // What to merge in: the trunk once the layer below has merged, else
242    // the layer below as it is locally (synced already in this run).
243    let (from, from_sha) = if layer.parent_merged || layer.parent == stack.trunk {
244        let Some(sha) = trunk_tip(git, stack) else {
245            return Err(stop(
246                branch,
247                "missing_branch",
248                format!("the trunk `{}` was not found", stack.trunk),
249                format!("`git fetch {}`, then rerun", stack.remote),
250                Exit::Precondition,
251            ));
252        };
253        let name = if git
254            .commit_sha(&format!("refs/remotes/{}/{}", stack.remote, stack.trunk))
255            .is_some()
256        {
257            format!("{}/{}", stack.remote, stack.trunk)
258        } else {
259            stack.trunk.clone()
260        };
261        (name, sha)
262    } else {
263        let Some(sha) = git
264            .commit_sha(&format!("refs/heads/{}", layer.parent))
265            .or_else(|| git.commit_sha(&format!("refs/remotes/{}/{}", stack.remote, layer.parent)))
266        else {
267            return Err(stop(
268                branch,
269                "missing_branch",
270                format!("its parent `{}` was not found", layer.parent),
271                format!("`git fetch {}`, then rerun", stack.remote),
272                Exit::Precondition,
273            ));
274        };
275        (layer.parent.clone(), sha)
276    };
277    let base = git
278        .line(&["merge-base", &local, &from_sha])
279        .unwrap_or_default();
280    if git.is_ancestor(&from_sha, &local) {
281        // Up to date by ancestry; it must be by content too.
282        let parent_base = super::parent_base(git, stack, i, &from_sha);
283        if let Some(pb) = parent_base.filter(|_| !layer.parent_merged) {
284            let problems =
285                missing_changes(git, &pb, &from_sha, &local).map_err(|e| error(branch, e))?;
286            if !problems.is_empty() {
287                return Err(content_stop(branch, &from, &problems));
288            }
289        }
290        let mut s = step(branch, "up_to_date");
291        s.created = created;
292        return Ok(s);
293    }
294    let mut s = step(
295        branch,
296        if opts.dry_run {
297            "would_merge"
298        } else {
299            "merged"
300        },
301    );
302    s.from = Some(from.clone());
303    s.created = created;
304    if opts.dry_run {
305        return Ok(s);
306    }
307    // Where to merge: this worktree when the branch is checked out here; a
308    // temporary one when it is checked out nowhere.
309    let elsewhere = checked_out
310        .iter()
311        .find(|(b, _)| b == branch)
312        .map(|(_, p)| p.clone());
313    let in_place = elsewhere.as_deref().is_some_and(|p| Some(p) == here);
314    if let (Some(path), false) = (&elsewhere, in_place) {
315        return Err(stop(
316            branch,
317            "checked_out_elsewhere",
318            format!(
319                "`{branch}` is checked out in {}, which another session may be working in",
320                path.display()
321            ),
322            format!(
323                "run `jouet stack sync` in {} (or merge `{from}` there yourself), then rerun here",
324                path.display()
325            ),
326            Exit::Precondition,
327        ));
328    }
329    let temp;
330    let work = if in_place {
331        let dirty = git
332            .text(&["status", "--porcelain", "--untracked-files=no"])
333            .map_err(|e| error(branch, e))?;
334        if !dirty.trim().is_empty() {
335            return Err(stop(
336                branch,
337                "dirty",
338                format!("`{branch}` is checked out here with uncommitted changes"),
339                "commit them (or set them aside in a WIP commit), then rerun".into(),
340                Exit::Precondition,
341            ));
342        }
343        Git::new(here.unwrap_or(Path::new(".")))
344    } else {
345        temp = TempWorktree::add(git, branch).map_err(|e| error(branch, e))?;
346        Git::new(&temp.path)
347    };
348    let merged = work
349        .command(&["merge", "--no-ff", "--no-commit", "--quiet", &from_sha])
350        .output()
351        .map_err(|e| {
352            error(
353                branch,
354                Error::new(Exit::Failed, format!("running git merge: {e}")),
355            )
356        })?;
357    if !merged.status.success() {
358        let files: Vec<String> = work
359            .text(&["diff", "--name-only", "--diff-filter=U"])
360            .unwrap_or_default()
361            .lines()
362            .map(str::to_string)
363            .collect();
364        let next = if in_place {
365            "resolve them, `git add` them and `git commit` (or `git merge --abort`), then rerun `jouet stack sync`".to_string()
366        } else {
367            let _ = work.text(&["merge", "--abort"]);
368            format!(
369                "`git switch {branch} && git merge {from}`, resolve them and `git commit`, then rerun `jouet stack sync`"
370            )
371        };
372        let mut stopped = stop(
373            branch,
374            "conflict",
375            format!("merging `{from}` into `{branch}` conflicts"),
376            next,
377            Exit::Failed,
378        );
379        stopped.files = files;
380        return Err(stopped);
381    }
382    // Verify the merged tree before committing it: every change the merge
383    // was to bring in must be there.
384    let tree = work.text(&["write-tree"]).map_err(|e| error(branch, e))?;
385    let tree = tree.trim();
386    let problems = missing_changes(&work, &base, &from_sha, tree).map_err(|e| error(branch, e))?;
387    if !problems.is_empty() {
388        let _ = work.text(&["merge", "--abort"]);
389        return Err(content_stop(branch, &from, &problems));
390    }
391    work.text(&["commit", "--quiet", "--no-edit"])
392        .map_err(|e| error(branch, e))?;
393    let new = work.commit_sha("HEAD").unwrap_or_default();
394    if !in_place {
395        // The temporary worktree was detached at the branch; move the
396        // branch only if nobody moved it meanwhile.
397        git.text(&["update-ref", &local_ref, &new, &local])
398            .map_err(|e| error(branch, e))?;
399    }
400    s.commit = Some(new);
401    Ok(s)
402}
403
404fn content_stop(branch: &str, from: &str, problems: &[super::FileProblem]) -> Stopped {
405    let files: Vec<String> = problems.iter().map(|p| p.path.clone()).collect();
406    let described: Vec<String> = problems
407        .iter()
408        .map(|p| match &p.commit {
409            Some(c) => format!("{} (undoes {c})", p.path),
410            None => format!("{} ({})", p.path, p.problem.describe()),
411        })
412        .collect();
413    let mut stopped = stop(
414        branch,
415        "content",
416        format!(
417            "`{branch}` would not have all of `{from}`'s changes: {}",
418            described.join(", ")
419        ),
420        format!(
421            "in `{branch}`, restore them with `git checkout {from} -- {}` and commit, unless the difference is meant; then rerun `jouet stack sync`",
422            files.join(" ")
423        ),
424        Exit::Failed,
425    );
426    stopped.files = files;
427    stopped
428}
429
430fn error(branch: &str, e: Error) -> Stopped {
431    stop(
432        branch,
433        "error",
434        e.message,
435        "fix that, then rerun".into(),
436        e.exit,
437    )
438}
439
440/// Pushes every layer that is ahead of its remote branch, with a plain
441/// push: never a force push. A branch never pushed is left alone.
442fn push(git: &Git, stack: &Stack) -> Vec<Push> {
443    let mut pushed = Vec::new();
444    for layer in stack.layers.iter().filter(|l| !l.merged) {
445        let local = git.commit_sha(&format!("refs/heads/{}", layer.branch));
446        let remote = git.commit_sha(&format!("refs/remotes/{}/{}", stack.remote, layer.branch));
447        let (Some(local), Some(remote)) = (local, remote) else {
448            continue;
449        };
450        if local == remote || git.is_ancestor(&local, &remote) {
451            continue;
452        }
453        let refspec = format!("refs/heads/{0}:refs/heads/{0}", layer.branch);
454        let result = git.text(&["push", "--quiet", &stack.remote, &refspec]);
455        pushed.push(Push {
456            branch: layer.branch.clone(),
457            ok: result.is_ok(),
458            error: result.err().map(|e| e.message),
459        });
460    }
461    pushed
462}
463
464/// A detached worktree of a branch, removed when dropped.
465struct TempWorktree<'a> {
466    git: &'a Git,
467    path: PathBuf,
468    _dir: tempfile::TempDir,
469}
470
471impl<'a> TempWorktree<'a> {
472    fn add(git: &'a Git, branch: &str) -> Result<Self, Error> {
473        let dir = tempfile::tempdir().map_err(|e| {
474            Error::new(Exit::Failed, format!("creating a temporary directory: {e}"))
475        })?;
476        let path = dir.path().join("wt");
477        git.text(&[
478            "worktree",
479            "add",
480            "--quiet",
481            "--detach",
482            &path.to_string_lossy(),
483            &format!("refs/heads/{branch}"),
484        ])?;
485        Ok(Self {
486            git,
487            path,
488            _dir: dir,
489        })
490    }
491}
492
493impl Drop for TempWorktree<'_> {
494    fn drop(&mut self) {
495        let _ = self.git.text(&[
496            "worktree",
497            "remove",
498            "--force",
499            &self.path.to_string_lossy(),
500        ]);
501    }
502}
503
504#[cfg(test)]
505mod tests;