Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
51 changes: 39 additions & 12 deletions docket/feature_outcome.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand All @@ -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",
Expand Down
5 changes: 1 addition & 4 deletions docs/features.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
27 changes: 27 additions & 0 deletions tests/test_feature_cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -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/**")
Expand Down
109 changes: 109 additions & 0 deletions tests/test_feature_outcome.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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")
Expand Down
8 changes: 8 additions & 0 deletions tests/test_merge_driver.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading