Skip to content

feat(wt sync): add stack file persistence and parent-based integration detection (part 03/03) - #2060

Closed
pablospe wants to merge 31 commits into
max-sixty:mainfrom
pablospe:sync-stack-file
Closed

pablospe wants to merge 31 commits into
max-sixty:mainfrom
pablospe:sync-stack-file

Conversation

@pablospe

Copy link
Copy Markdown
Contributor

Summary

  • Add .git/wt/stack file (git-machete compatible format) for explicit parent tracking
  • Phase 2 integration detection: detect branches merged into non-default parent branches
  • Parent chain walking with cycle detection for reparenting when mid-stack branches are integrated
  • Stack file is written after safety checks but before rebasing (also in dry-run)

Stack: 2/3 — depends on #2059 (sync-core). Review the incremental diff: sync-core...sync-stack-file

Test plan

  • 5 integration tests: stack file creation, cascading merges, mid-stack PR merged into parent, PR merged into non-default branch, stack file fixing scenario
  • clippy clean, all existing tests pass

@worktrunk-bot worktrunk-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few observations on the stack-file persistence layer:

1. New persistent file not in the FAQ inventory. docs/content/faq.md lists everything Worktrunk creates under .git/wt/ (cache, logs, trash). This PR adds .git/wt/stack as a new durable file but doesn't update that table. The project CLAUDE.md data-safety section explicitly calls out that surface area: "New code that changes this surface area should be reviewed against these sections."

2. --dry-run has a side effect. In handle_sync, the dry-run branch calls write_stack_file before returning, and does so before the dirty/rebase safety checks run. Users generally expect --dry-run to be read-only — a dry-run on a stale stack file will silently rewrite .git/wt/stack (and create_dir_all the wt dir). Worth either confining the write to the non-dry-run path, or documenting the side effect explicitly in the --dry-run help and the module docstring.

3. SyncPlan is a dead wrapper. The struct has a single tree: DependencyTree field and the caller immediately unwraps it (let plan = build_dependency_tree(&repo)?; let tree = plan.tree;). CLAUDE.md: "Don't create helpers, utilities, or abstractions for one-time operations." Returning DependencyTree directly is simpler and matches the pre-PR signature.

4. No unit tests for the stack-file parser/formatter. parse_stack_file and format_stack_file aren't trivial — they claim git-machete compatibility, mix tab/space indent handling, handle comments, strip annotations, and implicitly omit the root. The integration tests only exercise the happy-path round-trip. Direct unit tests for:

  • round-trip (format_stack_file → parse_stack_file preserves structure)
  • tab vs space indentation
  • comments and blank lines
  • annotations after branch name
  • sibling branches at the same indent level

would pin down the contract and catch regressions if someone tries to switch indent styles later. The existing #[cfg(test)] mod tests block only covers topological_order / stack_containing.

5. Minor: docstring example for parse_stack_file shows main at the top (lines 144–150), but format_stack_file never writes the root branch — so the file worktrunk actually produces looks different from the example in the doc. Either update the example to match what format_stack_node writes, or make format_stack_node include the root.

One inline suggestion below for the .unwrap() on line 170 (CLAUDE.md: "Never .expect() or .unwrap() in functions returning Result").

Comment thread src/commands/sync.rs Resolved
@worktrunk-bot

Copy link
Copy Markdown
Collaborator

codecov/patch is failing at 88.22% (target 95.73%). 71 lines uncovered — mostly error paths and new logic. Grouping the ones specific to this PR's additions:

Stack-file logic (src/commands/sync.rs):

  • parse_stack_file: L166 (comment/blank line skip), L183–L184 (indent stack-pop, space-indent branch)
  • format_stack_node: L226 (the empty-children early exit)
  • Reparenting cycle detection: L468–L475 — the while integrated.contains_key(new_parent) walk and the visited.insert cycle guard have no test

Rebase conflict paths (handle_sync):

  • L677–L694 — conflict during rebase --onto (reparented branch)
  • L706–L723 — conflict during normal rebase

The module docstring says "Stops on first conflict; user resolves and re-runs" but there's no integration test exercising the conflict branch. A test that sets up a conflicting change and asserts the hint/exit is the highest-value gap.

Control-flow edges in handle_sync (likely trivially testable):

  • L564 — bail\!("Current worktree has no branch. Use --all...")
  • L568–L574 — "Branch X is not part of any stack. Nothing to sync."
  • L582–L583 — "All branches are up to date."
  • L621–L626 — "rebase in progress" error path

The parse/format edge cases line up with review point #4 (unit tests for the parser/formatter). The reparenting cycle guard is also untested — adding a direct unit test for build_dependency_tree against a synthetic repo, or a fake stack file with a manufactured cycle, would pin it down. Full line list: codecov report.

@pablospe

Copy link
Copy Markdown
Contributor Author

Addressed the review feedback:

  1. FAQ inventory — Added .git/wt/stack to the file table in 60b5cbe.
  2. --dry-run side effect — Removed write_stack_file from the dry-run path in 8abc367.
  3. SyncPlan wrapper — Removed, returning DependencyTree directly in b5a2c14.
  4. Parser/formatter unit tests — Still TODO (will address with codecov).
  5. Docstring example — Still TODO.

Also replaced .unwrap() with let-else in 9d49693 (inline comment resolved).

@worktrunk-bot

Copy link
Copy Markdown
Collaborator

Confirmed — 60b5cbe adds .git/wt/stack to the FAQ table, 8abc367 drops the write_stack_file call from the dry-run branch, and b5a2c14 returns DependencyTree directly. The inline .unwrap() is also gone in 9d49693. Points 4 and 5 (parser/formatter unit tests and the docstring example) remain open as you noted — the unit tests would also chip away at the codecov/patch gap on parse_stack_file / format_stack_node.

(pre-commit.ci - pr is reporting "error during mergeable check" — that's a pre-commit.ci infrastructure blip, not a real failure; a rerun should clear it.)

@pablospe
pablospe force-pushed the sync-stack-file branch 2 times, most recently from a0dbe79 to e428f5d Compare April 10, 2026 21:39

@worktrunk-bot worktrunk-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CI is already red on lint for the latest push — both cargo fmt and cargo clippy fail. The clippy error is also a CLAUDE.md rule: no .unwrap() in functions returning Result. Inline suggestion below for the clippy hit; cargo fmt needs to be re-run on src/commands/sync.rs and src/main.rs as well.

One other observation on the most recent commits:

rebased_branches is now dead code. 8d51f4d switched --push from pushing rebased_branches to pushing all upstream branches in branches_to_sync, but the let mut rebased_branches: Vec<String> = Vec::new(); (line 696) and the rebased_branches.push(...) (line 781) were left behind. The vec is populated but never read.

Comment thread src/commands/sync.rs Resolved
@worktrunk-bot

Copy link
Copy Markdown
Collaborator

All three test (linux|macos|windows) jobs are also red — 17 snapshot failures total. The sync-specific ones are the ones directly caused by this PR's latest commits; the rest look like leftover rebase fallout.

Sync-specific (need cargo insta test --accept):

  • sync_creates_stack_file — 3e8cd36 fixed the print_tree_node connector drawing, but this snapshot still has the pre-fix output (pr1 / pr2 / pr3 without └── connectors).
  • sync_push and sync_push_skips_deleted_remote — e428f5d changed the progress line from Pushing pr1... to Pushing pr1 to origin..., and the snapshots weren't regenerated.

Likely rebase fallout (not sync-specific):

  • config_show: 7 deprecation/warning snapshots (deprecated_approved_commands_copies_to_approvals_file, deprecated_commit_generation_*, deprecated_template_variables_*, explicit_config_path_not_found_shows_warning, wt_list_skips_migration_file_after_first_write)
  • list_config: 6 snapshots (list_config_branches_enabled, list_config_cli_override, list_config_full_and_branches, list_config_full_enabled, list_project_url_column, list_no_config)

Spot-checking list_config_cli_override, the diff is about column widths / status icons (⚑ → ↑1, "Showing 4 worktrees, 1 branches" → "Showing 4 worktrees, 1 branches, 3 ahead") — that matches changes to list rendering that landed on main separately, not anything from this PR. A cargo insta test --accept against a fresh rebase should pick them up.

After fixing the clippy/fmt issues from the review, cargo run -- hook pre-merge --yes will regenerate all of these in one pass.

@pablospe pablospe changed the title feat: add stack file persistence and parent-based integration detection feat(wt sync): add stack file persistence and parent-based integration detection (part 03/03) Apr 10, 2026

@worktrunk-bot worktrunk-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CI is red on four issues — the first two were flagged in earlier reviews and have new context.

1. Clippy unnecessary_unwrap still failing (src/commands/sync.rs:746). This is the same finding from the previous review that wasn't addressed. 9d49693b fixed the parse_stack_file unwrap but not this one. Inline suggestion below.

2. pre-commit fmt also wants to reflow save_fork_points and the reformatted progress_message block — run cargo fmt after applying the clippy fix.

3. Skill reference FAQ out of sync with docs. docs/content/faq.md adds both .git/wt/stack and .git/wt/stack-forkpoints, but skills/worktrunk/reference/faq.md only has .git/wt/stack. test_command_pages_and_skill_files_are_in_sync is panicking on this. Fix:

cargo test --test integration test_command_pages_and_skill_files_are_in_sync

…then commit the updated skill file. (The 7047ec7b sync commit predates 812bfdd5 which introduced stack-forkpoints.)

4. config_show / list_config snapshot drift. The snapshots committed in aee9c2b1 still don't match test output — multiple failures in test_deprecated_* and test_list_config_*. Looks like main has moved again since the snapshot restore. cargo insta test --accept after rebasing.


Scope concern — overlap with #2061. The incremental commits pushed since the previous review include 47b4c8cd feat: add --fetch, --push, --prune flags and [sync] config section, which is the exact scope of #2061 (sync-flags, part 3/3). Comparing the branch tips, sync-stack-file is 9 commits ahead of sync-flags and 0 commits behind — this PR now contains everything #2061 was meant to add. Either close #2061 as superseded, or revert the flags/config commits here and keep them in #2061. As-is, merging #2060 leaves #2061 with nothing to do.


Minor (not blocking):

  • rebased_branches (line 696) is still populated but never read — same finding as the previous review, still unaddressed after 933cb871 switched --push to iterate branches_to_sync directly. Can be deleted.
  • load_fork_points + save_fork_points roundtrip preserves old entries verbatim (line 691 and line 1064-ish). When a worktree is pruned or a branch is renamed, its entry stays in .git/wt/stack-forkpoints forever. Consider pruning entries for branches not in the current tree at save time.

Comment thread src/commands/sync.rs Resolved
@pablospe
pablospe force-pushed the sync-stack-file branch 2 times, most recently from 1f75899 to a65f691 Compare April 10, 2026 22:42
pablospe added 12 commits April 11, 2026 09:18
Core implementation of `wt sync` that detects parent-child relationships
between worktree branches and rebases them in topological order.

Features:
- Automatic dependency tree detection via merge-base analysis
- Topological sort for correct rebase ordering
- Integration detection (squash-merged branches) with reparenting
- Dirty worktree detection to prevent data loss
- --dry-run mode to preview planned rebases
- --stack flag to sync only the current stack (default: all stacks)

Includes 10 integration tests covering linear stacks, deep stacks,
mid-stack changes, dirty worktree blocking, and PR merge scenarios.
The root call passed empty prefix, and children of root also received
empty prefix, making them all appear as root nodes. Fix by passing an
explicit is_root flag so only the actual root prints without connectors.
The --all field was never read (main.rs derives `all` from `!args.stack`),
and its help text referenced config that doesn't exist yet. Remove the
dead field and its conflicts_with constraint.
Covers the conflict handling branch that shows error and resolution
hint when a rebase conflict occurs during sync.
Persists the dependency tree to `.git/wt/stack` (git-machete compatible
format) on every sync. When present, the stack file:

- Provides explicit parent tracking instead of merge-base inference
- Enables Phase 2 integration detection against non-default branches
  (e.g., PR2 squash-merged into PR1, not just into main)
- Supports parent chain walking for cascading merge reparenting

Includes 5 integration tests: stack file creation, mid-stack fix with
stack file, non-default branch merges, mid-stack parent merges, and
cascading merges.
Optional phases for `wt sync`:

- `--fetch` runs `git fetch --prune` before syncing
- `--push` force-pushes rebased branches with `--force-with-lease`
  (skips branches without an upstream)
- `--prune` removes integrated worktrees (worktree + local branch +
  remote branch), without --force to preserve untracked files

All phases default to off. Configurable via `[sync]` config section:

```toml
[sync]
fetch = true
push = true
prune = false
all = true
```

CLI flags (`--no-fetch`, `--no-push`, `--no-prune`) override config.

Includes 4 integration tests: fetch, push, push-skips-deleted-remote,
and prune.
…alize

SyncConfig is a table section, not a scalar, so it needs to be in the
table_lines match arm to generate correct TOML for the deserialization test.
Use .ok().flatten() instead of ? for upstream() calls in the push
and prune loops. One branch with an upstream error should not abort
the entire phase. Also collapse nested if block to satisfy clippy,
and refactor prune to use execute_removal for consistent worktree
cleanup.
Replace open-coded if-else chains with flag_pair() calls for all
sync flag pairs (fetch, push, prune, all/stack), matching the
pattern used by wt merge.
…pairs

Change all sync flag pairs to use overrides_with, matching the
convention used by wt merge. This allows shell alias composition
where the last flag wins, instead of erroring on conflicting flags.
pablospe added 19 commits April 11, 2026 09:18
These snapshots legitimately include the [sync] config section added by
the sync-flags feature. They were incorrectly reverted to main.
These snapshots capture `wt list` output (not config TOML), so they
don't need the [sync] section. The corrupted versions had wrong paths
(../../../../), dirty markers (⚑), and timeout placeholders (⋯) from
being captured in a wrong CWD during a previous rebase.
Functions returning Result must not use .unwrap(). Use a let-else
pattern to safely skip lines where split_whitespace yields nothing.
Users expect --dry-run to be read-only. The write_stack_file call
was incorrectly placed in the dry-run branch, causing a side effect.
SyncPlan had a single field that the caller immediately unwrapped.
Return DependencyTree directly from build_dependency_tree instead.
Document the stack file created by wt sync in the "What files does
Worktrunk create?" section.
Use `git status --porcelain -uno` instead of `is_dirty()` which
includes untracked files. Untracked files are safe during rebase
and should not block `wt sync`.
Previously --push only pushed branches that were rebased in the current
run. Now it pushes all branches in the stack that have an upstream,
making `wt sync --push` a complete "sync and push" workflow.
Always use `git rebase --onto <parent> <fork-point> <branch>` instead
of `git rebase <parent>`. The fork-point (parent's tip SHA at last sync)
is stored in `.git/wt/stack-forkpoints` and updated after each sync.

This fixes the "rebase of a rebase" problem: when a parent branch is
rewritten (rebased, amended, force-pushed), `git rebase parent` tries
to replay the parent's old commits because the merge-base shifts to an
older common ancestor. With `--onto`, only the branch's own commits
are replayed, correctly handling parent rewrites.
Respects pushRemote, remote.pushDefault, and branch.<name>.remote
config so push and prune work with fork-based workflows.
Replace is_some()/unwrap() with if-let pattern, and remove
rebased_branches which became dead code after --push was changed
to push all upstream branches.
Covers parse_stack_file edge cases (comments, blank lines, annotations,
tab/space indentation, siblings, empty input, with/without root),
format/parse round-trips, stack_containing edge cases, and fork-points
serialization.
- Detached HEAD with --stack reports "no branch" error (covers L622-623)
- Fix test_sync_creates_stack_file: dry-run no longer writes stack file
- Update push snapshots to include remote name in output

@worktrunk-bot worktrunk-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The incremental changes since the previous review are on the light side — cargo fmt, dead-code removal, a docstring clarification, and a new unit-test block for the stack-file parser/formatter (which addresses the earlier ask). No new logic to re-verify.

Two concerns on the current state:

1. codecov/patch is failing at 92.28% — 58 uncovered lines in src/commands/sync.rs and 9 in src/config/user/sections.rs. The project CLAUDE.md is explicit: "NEVER merge a PR with failing codecov/patch without explicit user approval." The uncovered clusters worth attention (not all of the 58, just the ones where tests would add meaningful signal):

  • sync.rs L516–L524 — the inner loop of chained reparenting. sync_cascading_merges covers one level of integrated-ancestor reparenting; the while-body that walks through multiple consecutive integrated ancestors is never entered. A test where both pr1 and pr2 are squash-merged simultaneously while pr3 remains would exercise it.
  • sync.rs L681–L686 — the mid-rebase abort guard (bail! when a worktree is already in REBASE_* state before sync starts).
  • sync.rs L831–L881 — error paths in the --push and --prune loops (push failure, prune failure, the warnings printed for them).
  • src/config/user/sections.rs — SyncConfig accessors that return the hardcoded defaults when the Option<bool> is None. A couple of list_config snapshot assertions would cover these.

2. Exit code on rebase conflict. wt sync currently returns Ok(()) on a rebase conflict (see the inline suggestion below), so the process exits 0 even though the user is left with an unresolved rebase. wt step rebase returns GitError::RebaseConflict in the same situation (non-zero exit), and wt sync && next-step chains will silently proceed past a conflict today. The sync_rebase_conflict snapshot already captures this (success: true, exit_code: 0) — accepting the fix will require regenerating it.

The existing hint message is already user-friendly, so the fix just needs to set a non-zero exit code after printing. The WorktrunkError::AlreadyDisplayed { exit_code: 1 } variant exists for exactly this case (empty Display, exit_code() returns 1) and is used the same way in src/commands/external.rs and src/commands/for_each.rs.

Comment thread src/commands/sync.rs
Comment on lines +776 to +778
// Save fork-points for branches processed so far
let _ = save_fork_points(&repo, &fork_points);
return Ok(());

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

return Ok(()) exits the process with status 0 even though the user has an unresolved rebase in the worktree. wt step rebase returns GitError::RebaseConflict for the same condition (non-zero exit), and shell chains like wt sync && ... will silently proceed past the conflict today. Also, let _ = save_fork_points(...) drops any IO error from the save — inconsistent with the ? used on the same call in the happy path a few lines below. Fix both at once:

Suggested change
// Save fork-points for branches processed so far
let _ = save_fork_points(&repo, &fork_points);
return Ok(());
// Save fork-points for branches processed so far
save_fork_points(&repo, &fork_points)?;
return Err(worktrunk::git::WorktrunkError::AlreadyDisplayed { exit_code: 1 }.into());

(src/commands/external.rs and src/commands/for_each.rs use the same AlreadyDisplayed { exit_code: 1 } pattern after printing their own nicely-formatted error.)

@pablospe
pablospe marked this pull request as draft April 11, 2026 07:43
@pablospe

Copy link
Copy Markdown
Contributor Author

Moved to a standalone binary: https://github.com/pablospe/worktrunk-sync — works via the external subcommand dispatch merged in #2054.

@worktrunk-bot

Copy link
Copy Markdown
Collaborator

Thanks for the update — a standalone binary is a clean fit, and it's nice confirmation that the wt-<name> dispatch from #2054 covers this use case. The open review points (codecov/patch gap, rebase-conflict exit code) don't carry over to an out-of-tree binary, so nothing further from the review side.

@pablospe

Copy link
Copy Markdown
Contributor Author

Superseded — sync moved to separate repo: https://github.com/pablospe/worktrunk-sync

@pablospe pablospe closed this Apr 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants