josh-sync/CHANGELOG.md

Changelog

1.5.0

Breaking Changes

None.

Features

• --force flag for reverse sync: josh-sync sync --reverse --force bypasses the PR step and force-pushes the subrepo's state directly onto the monorepo branch. Also skips the skip-dirty guard. Only valid with --reverse. Returns status forced.

1.4.0

Breaking Changes

None.

Features

• schema_version config field: New optional integer field in .josh-sync.yml. Defaults to 1 when absent. josh-sync fails fast with a clear error if an unsupported version is present — safe path for future config migrations without silent misinterpretation.

Fixes

• Linearize fallback applying wrong diff: Fallback for failed cherry-pick was diffing from HEAD to the commit's full tree instead of from the commit's own parent, causing unrelated file deletions. Now diffs from the commit's own parent (${sha}^ / ${sha}^1).
• Linearize fallback for already-applied merge commits: When cherry-pick -m 1 produces an empty result because a merge's changes were already applied by a prior cherry-pick, the commit is now skipped instead of attempting a failing git apply.
• Linearize fallback output: Suppressed git noise from cherry-pick, checkout, and commit during linearization; added delimiters and consistent indented log lines.

Docs

• Workflow guide: removed redundant step-by-step subsections (table already covers them); tightened ADR-011 alternatives; removed stale version pins.
• README: added Versioning section with semver policy table and floating tag explanation.

1.3.0

Breaking Changes

None.

Features

• Linearize fallback for reverse sync: When josh-proxy rejects a push due to unmappable merge commits, reverse sync automatically falls back to linearizing the history — cherry-picking regular commits individually and squashing only the problematic merge commits via cherry-pick -m 1. Preserves individual commit granularity while handling complex merge topologies that josh cannot map. PR body notes when linearization was used.

Fixes

• Reverse sync human commit detection: Fixed --ancestry-path returning empty when mono-filtered has advanced past the last forward sync. Any monorepo commit (even outside the subfolder) causes josh to create a new filtered commit, breaking the ancestry path to subrepo HEAD. Now uses git merge-base to find the last connected point.
• State not updated on false skip: When trees differ but no human commits are found, reverse sync now returns skip-dirty instead of skip. State is not updated, so the system retries on the next run instead of silently dropping commits.

Docs

• Expanded troubleshooting guide for "Josh rejected push" with root cause analysis and prevention advice.
• Added ADR-011: Linearize fallback for reverse sync.
• Added recommended Git workflow section to the guide.

1.2.0

Breaking Changes

None.

Features

• File exclusion: exclude config field removes files/directories from the subrepo at the josh-proxy transport layer. Patterns are embedded inline in the josh-proxy URL using :exclude[::pattern,...] syntax — no extra files to generate or commit.
• Filter change reconciliation: When the josh filter changes (e.g., adding/removing exclude patterns), josh-sync automatically creates a reconciliation merge commit that connects old and new histories. No manual reset or force-push required.
• Tree comparison guard: Reverse sync now compares subrepo tree to josh-filtered tree before checking commit log. Skips immediately when trees are identical, avoiding false positives from reconciliation merge history.
• Unrelated histories detection: Forward sync detects when histories are unrelated (no common ancestor) and falls back to reconciliation instead of creating a useless conflict PR.

Fixes

• Pre-v1.2 state compatibility: When upgrading from v1.0/v1.1 (no josh_filter stored in state), the old filter is derived from subfolder so reconciliation triggers correctly.
• Reconciliation merge parent order: Josh-filtered history is always first parent so josh-proxy can follow first-parent traversal back to the monorepo.
• Reverse sync --ancestry-path flag prevents old subrepo history from leaking through reconciliation merge parents.
• PR body \n now renders as actual newlines instead of literal text.
• Conflict result no longer updates sync state (added continue to skip state write).
• action.yml now copies VERSION file for correct --version output in CI.
• .gitignore now includes dist/ and .env.

1.1.0

Breaking Changes

None.

Features

• onboard command: Interactive, resumable workflow for importing existing subrepos into the monorepo. Walks through: prerequisites check, import (creates PRs), wait for merge, reset (pushes josh-filtered history). Checkpoint/resume at every step.
• migrate-pr command: Migrates open PRs from an archived subrepo to the new one. Supports interactive selection, --all flag, and specific PR numbers. Uses git apply --3way for resilient patch application.
• Onboard state tracking: Stored on the josh-sync-state branch at <target>/onboard.json. Tracks step progress, import PR numbers, reset branches, and migrated PRs.

1.0.0

Initial release. Extracted from private-monorepo-example into a standalone reusable library.

Features

• Bidirectional sync: forward (mono → subrepo) and reverse (subrepo → mono)
• Multi-target support via .josh-sync.yml config
• Per-target credential overrides (SSH keys, HTTPS tokens)
• Force-with-lease safety for forward sync
• Loop prevention via git trailers
• State tracking on orphan branch (josh-sync-state)
• Initial import and subrepo reset commands
• Composite action for Gitea/GitHub CI
• Nix flake with devenv module
• Preflight validation checks
• Config schema (JSON Schema)

Breaking Changes (vs. inline scripts)

• Python + pyyaml replaced by yq-go (single static binary)
• 7 separate scripts replaced by single josh-sync CLI
• Consumer workflows use composite action (uses: https://your-gitea/org/josh-sync@v1)