diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c84a3c..c3fcdb0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Fixed + +- `docket feature start` records the freshest fork point as `base`. It took the merge base with the local `main`, which goes stale in clones that branch from `origin/main`, so `feature done` reported every file the default branch had gained since as unintentional. It now compares `origin/HEAD`, `origin/main`, `origin/master`, `main` and `master` and keeps the newest merge base, preferring the remote one when they diverge. + ## [0.31.1] - 2026-11-03 ### Fixed diff --git a/docket/feature_outcome.py b/docket/feature_outcome.py index 686ead1..3acb1ee 100644 --- a/docket/feature_outcome.py +++ b/docket/feature_outcome.py @@ -12,7 +12,13 @@ from docket.config import DEFAULTS from docket.context import scope_strength -DEFAULT_BRANCHES = ("main", "master") +# Keep these refs and the origin/HEAD lookup in step with merge_driver._default_tip. +DEFAULT_BRANCHES = ( + "refs/remotes/origin/main", + "refs/remotes/origin/master", + "refs/heads/main", + "refs/heads/master", +) class OutcomeError(ValueError): @@ -33,29 +39,50 @@ def _current_branch(root: Path) -> str: def fork_point(root: Path) -> tuple[str, str]: - """The merge base with the default branch, and a warning when there is none. + """The newest merge base with a default branch, and a warning when there is none. HEAD is the wrong base. A feature declared after work began would miss every commit that came first, and its unintentional set would be silently - short. + short. Local default branches can be stale, so compare all default refs, + including origin/HEAD, and choose the base all others are ancestors of. + If the bases diverge, prefer the remote-tracking ref's base in candidate + order. On the default branch itself (main, master, or origin/HEAD's + target), keep HEAD and warn. """ current = _current_branch(root) - for candidate in DEFAULT_BRANCHES: - if _git(root, "rev-parse", "--verify", candidate).returncode != 0: - continue - if candidate == current: - break - result = _git(root, "merge-base", "HEAD", candidate) - if result.returncode == 0 and result.stdout.strip(): - return result.stdout.strip(), "" - head = _git(root, "rev-parse", "HEAD") if head.returncode != 0: return ( "", "recording no base: this repository has no commits yet", ) + bases: list[str] = [] + named = _git(root, "symbolic-ref", "-q", "refs/remotes/origin/HEAD") + candidates = [named.stdout.strip()] if named.returncode == 0 else [] + origin_default = candidates[0].removeprefix("refs/remotes/origin/") if candidates else "" + if f"refs/heads/{current}" not in DEFAULT_BRANCHES and current != origin_default: + for candidate in dict.fromkeys((*candidates, *DEFAULT_BRANCHES)): + found = _git(root, "rev-parse", "-q", "--verify", f"{candidate}^{{commit}}") + if found.returncode != 0: + continue + if not current and found.stdout.strip() == head.stdout.strip(): + bases.clear() + break + result = _git(root, "merge-base", "HEAD", candidate) + base = result.stdout.strip() + if result.returncode == 0 and base and base not in bases: + bases.append(base) + + for base in bases: + if all( + other == base or _git(root, "merge-base", "--is-ancestor", other, base).returncode == 0 + for other in bases + ): + return base, "" + if bases: + # Diverged bases have no single newest commit; remote refs come first. + return bases[0], "" return ( head.stdout.strip(), "recording HEAD as the base: this is the default branch, so there is no fork point", diff --git a/docs/features.md b/docs/features.md index 570161a..bc342c2 100644 --- a/docs/features.md +++ b/docs/features.md @@ -83,10 +83,7 @@ $ docket feature abandon some-other-slug --text "superseded by a different appro ## The fork-point base and the change set -`start` records `base` as the merge base with the default branch. This includes -earlier branch work when you declare a feature partway through a task. On the -default branch itself, `base` is HEAD and `start` warns that there is no fork -point. +`start` records `base` as the newest merge base between HEAD and the default-branch refs: origin/HEAD's target, `origin/main`, `origin/master`, `main` and `master`, whichever exist. "Newest" means the base the others are ancestors of, so a stale local `main` does not pull the base back. When the bases diverge, it prefers the remote-tracking base. This includes earlier branch work when you declare a feature partway through a task. On the default branch itself (`main`, `master`, or origin/HEAD's target), `base` is HEAD and `start` warns that there is no fork point. `done` walks the branch's own commits with `git log --first-parent --no-merges -M base..HEAD`, then classifies each changed path against the feature's diff --git a/tests/test_feature_cli.py b/tests/test_feature_cli.py index c8d28dd..2dad625 100644 --- a/tests/test_feature_cli.py +++ b/tests/test_feature_cli.py @@ -164,6 +164,33 @@ def test_abandon_closes_without_a_change_set(self): self.assertEqual(feature["intentional"], []) +class FeatureStartForkPointTests(FeatureCliTests): + def git(self, *args): + return subprocess.run( + ["git", "-C", str(self.root), *args], check=True, capture_output=True, text=True + ).stdout.strip() + + def commit(self, name): + (self.root / name).write_text(f"{name}\n", encoding="utf-8") + self.git("add", name) + self.git("-c", "user.email=t@example.test", "-c", "user.name=t", "commit", "-m", name) + + def test_feature_start_records_the_fresh_fork_point(self): + self.commit("base.txt") + self.git("checkout", "-b", "upstream") + self.commit("upstream.txt") + fresh = self.git("rev-parse", "HEAD") + self.git("update-ref", "refs/remotes/origin/main", fresh) + self.git("checkout", "-b", "feat/fresh", "origin/main") + self.commit("work.txt") + + code, _ = self.run_cli("feature", "start", "one", "--text", "t", "--path", "src/**") + self.assertEqual(code, 0) + store = self.root / ".docket" / "features.jsonl" + event = json.loads(store.read_text(encoding="utf-8").splitlines()[0]) + self.assertEqual(event["base"], fresh) + + class FeatureCheckTests(FeatureCliTests): def test_check_passes_on_a_healthy_store(self): self.run_cli("feature", "start", "one", "--text", "t", "--path", "a/**") diff --git a/tests/test_feature_outcome.py b/tests/test_feature_outcome.py index 65e5768..4df377d 100644 --- a/tests/test_feature_outcome.py +++ b/tests/test_feature_outcome.py @@ -44,6 +44,17 @@ def setUp(self): def tearDown(self): self.tmp.cleanup() + def commit(self, name): + (self.root / name).write_text(f"{name}\n", encoding="utf-8") + git(self.root, "add", name) + git(self.root, "commit", "-m", name) + return subprocess.run( + ["git", "-C", str(self.root), "rev-parse", "HEAD"], + capture_output=True, + text=True, + check=True, + ).stdout.strip() + def test_fork_point_on_the_default_branch_returns_head_and_warns(self): sha, warning = outcome.fork_point(self.root) self.assertTrue(sha) @@ -64,6 +75,104 @@ def test_fork_point_on_a_branch_is_the_merge_base(self): self.assertEqual(sha, head) self.assertEqual(warning, "") + def test_fork_point_prefers_origin_main_over_a_stale_local_main(self): + git(self.root, "checkout", "-b", "upstream") + fresh = self.commit("upstream.txt") + git(self.root, "update-ref", "refs/remotes/origin/main", fresh) + git(self.root, "checkout", "-b", "feat/x", "origin/main") + self.commit("work.txt") + + sha, warning = outcome.fork_point(self.root) + self.assertEqual(sha, fresh) + self.assertEqual(warning, "") + + def test_fork_point_with_only_a_local_main_is_unchanged(self): + git(self.root, "checkout", "-b", "feat/x") + self.commit("work.txt") + git(self.root, "checkout", "main") + self.commit("upstream.txt") + git(self.root, "checkout", "feat/x") + expected = subprocess.run( + ["git", "-C", str(self.root), "merge-base", "HEAD", "main"], + capture_output=True, + text=True, + check=True, + ).stdout.strip() + + sha, warning = outcome.fork_point(self.root) + self.assertEqual(sha, expected) + self.assertEqual(warning, "") + + def test_fork_point_prefers_a_newer_local_main_over_origin_main(self): + git(self.root, "update-ref", "refs/remotes/origin/main", "HEAD") + fresh = self.commit("upstream.txt") + git(self.root, "checkout", "-b", "feat/x") + self.commit("work.txt") + self.assertEqual(outcome.fork_point(self.root), (fresh, "")) + + def test_fork_point_prefers_the_remote_base_when_default_branches_diverge(self): + git(self.root, "checkout", "-b", "upstream") + remote = self.commit("upstream.txt") + git(self.root, "update-ref", "refs/remotes/origin/main", remote) + git(self.root, "checkout", "main") + self.commit("local.txt") + git(self.root, "checkout", "-b", "feat/x") + git(self.root, "merge", "origin/main", "-m", "merge") + self.assertEqual(outcome.fork_point(self.root), (remote, "")) + + def test_fork_point_uses_origin_head_for_a_custom_default_branch(self): + git(self.root, "checkout", "-b", "upstream") + fresh = self.commit("upstream.txt") + git(self.root, "update-ref", "refs/remotes/origin/trunk", fresh) + git(self.root, "symbolic-ref", "refs/remotes/origin/HEAD", "refs/remotes/origin/trunk") + git(self.root, "checkout", "-b", "feat/x", "origin/trunk") + self.commit("work.txt") + self.assertEqual(outcome.fork_point(self.root), (fresh, "")) + + def test_fork_point_skips_an_unresolved_origin_head(self): + git(self.root, "symbolic-ref", "refs/remotes/origin/HEAD", "refs/remotes/origin/missing") + git(self.root, "checkout", "-b", "upstream") + fresh = self.commit("upstream.txt") + git(self.root, "update-ref", "refs/remotes/origin/master", fresh) + git(self.root, "checkout", "-b", "feat/x", "origin/master") + self.commit("work.txt") + self.assertEqual(outcome.fork_point(self.root), (fresh, "")) + + def test_fork_point_on_local_main_with_a_remote_returns_head_and_warns(self): + head = self.commit("local.txt") + git(self.root, "checkout", "-b", "upstream") + fresh = self.commit("upstream.txt") + git(self.root, "update-ref", "refs/remotes/origin/main", fresh) + git(self.root, "checkout", "main") + sha, warning = outcome.fork_point(self.root) + self.assertEqual(sha, head) + self.assertIn("recording HEAD as the base", warning) + + def test_fork_point_on_the_origin_head_branch_returns_head_and_warns(self): + git(self.root, "checkout", "-b", "trunk") + git(self.root, "update-ref", "refs/remotes/origin/trunk", "HEAD") + git(self.root, "symbolic-ref", "refs/remotes/origin/HEAD", "refs/remotes/origin/trunk") + head = self.commit("unpushed.txt") + sha, warning = outcome.fork_point(self.root) + self.assertEqual(sha, head) + self.assertIn("recording HEAD as the base", warning) + + def test_fork_point_detached_at_the_remote_default_tip_returns_head_and_warns(self): + git(self.root, "checkout", "-b", "upstream") + head = self.commit("upstream.txt") + git(self.root, "update-ref", "refs/remotes/origin/main", head) + git(self.root, "checkout", "--detach", "origin/main") + sha, warning = outcome.fork_point(self.root) + self.assertEqual(sha, head) + self.assertIn("recording HEAD as the base", warning) + + def test_fork_point_on_a_new_branch_at_the_remote_default_tip_does_not_warn(self): + git(self.root, "checkout", "-b", "upstream") + head = self.commit("upstream.txt") + git(self.root, "update-ref", "refs/remotes/origin/main", head) + git(self.root, "checkout", "-b", "feat/x", "origin/main") + self.assertEqual(outcome.fork_point(self.root), (head, "")) + def test_merging_the_default_branch_adds_nothing_to_the_change_set(self): git(self.root, "checkout", "-b", "feat/x") (self.root / "work.txt").write_text("work\n", encoding="utf-8") diff --git a/tests/test_merge_driver.py b/tests/test_merge_driver.py index d9a9161..b62cd84 100644 --- a/tests/test_merge_driver.py +++ b/tests/test_merge_driver.py @@ -585,6 +585,14 @@ def test_a_branch_merging_main_in_keeps_main_feature_ids(self): self.assertEqual(self.git("merge", "-q", "--no-edit", "main").returncode, 0) self.assertEqual(self.feature_slugs(), [("f1", "other"), ("f2", "work")]) + def test_a_branch_merging_origin_main_in_keeps_main_feature_ids_with_a_stale_local_main(self): + self.diverge_features() + self.git("update-ref", "refs/remotes/origin/main", "HEAD") + self.git("checkout", "-q", "topic") + self.git("branch", "-f", "main", "topic~1") + self.assertEqual(self.git("merge", "-q", "--no-edit", "origin/main").returncode, 0) + self.assertEqual(self.feature_slugs(), [("f1", "other"), ("f2", "work")]) + def test_main_merging_a_feature_branch_in_renumbers_the_branch_feature(self): self.diverge_features() self.assertEqual(self.git("merge", "-q", "--no-edit", "topic").returncode, 0)