Ledger merge driver

.gitattributes

@@ -1,4 +1,7 @@
-# Both stores are append-only JSONL, so a union merge is the right resolution:
-# it keeps every line from both sides. Duplicate ids that union produces are
-# renumbered afterwards by `docket rebase` and `docket feature remap`.
+# The ledger merges through `docket merge-driver`, which appends the other
+# side's new records under fresh ids. Each clone registers the driver with
+# `docket init`; without it git reports an ordinary conflict.
+# features.jsonl stays on union until it has a driver of its own: duplicate
+# feature ids after a union need renumbering by hand.
 .docket/*.jsonl merge=union
+.docket/ledger.jsonl merge=docket

CHANGELOG.md

@@ -10,6 +10,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - `docket graph --format mermaid|dot` draws a flagged record with a dashed border and an unsupported one with a dotted border. The csv node table gains a `support` column.
+- A git merge driver for `.docket/ledger.jsonl`. Branches that both recorded merge without a conflict: the other side's new records take fresh IDs, references follow, and a record already merged is not added twice. When it cannot merge it leaves conflict markers. `docket init` now adds `.docket/ledger.jsonl merge=docket` to `.gitattributes` and, when `docket` is on PATH, registers the driver in the clone's git config; re-run it in a fresh clone. The session briefing notes a clone where the attribute is set but the driver is not.
+
+### Fixed
+
+- This repository's `.gitattributes` no longer applies a union merge to the ledger, which produced duplicate IDs.
+- `docket rebase` no longer appends a tail it has already absorbed.
 
 ## [0.21.0] - 2026-10-02
 

docket/cli/__init__.py

@@ -4,7 +4,13 @@
 import sys
 
 from docket import features, version
-from docket.cli.admin import cmd_check, cmd_init, cmd_migrate, cmd_rebase
+from docket.cli.admin import (
+    cmd_check,
+    cmd_init,
+    cmd_merge_driver,
+    cmd_migrate,
+    cmd_rebase,
+)
 from docket.cli.completion import cmd_completion
 from docket.cli.construct import cmd_construct
 from docket.cli.context_cmd import CONTEXT_ENVELOPES, cmd_context
@@ -191,6 +197,14 @@ def main(argv: list[str] | None = None) -> int:
     rb.add_argument("--emit-map", metavar="PATH", help="write the old-to-new id map as JSON")
     rb.set_defaults(func=cmd_rebase)
 
+    # No help text and absent from the metavar list above: git calls this,
+    # people do not.
+    md = sub.add_parser("merge-driver")
+    md.add_argument("base")
+    md.add_argument("ours")
+    md.add_argument("theirs")
+    md.set_defaults(func=cmd_merge_driver)
+
     mg = sub.add_parser("migrate", help="convert a legacy ledger to the current schema")
     source = mg.add_mutually_exclusive_group()
     source.add_argument("--map", help="classification map to apply instead of the derived one")

docket/cli/admin.py

@@ -12,7 +12,7 @@
 import sys
 from pathlib import Path
 
-from docket import env, feature_archive, feature_project, features
+from docket import env, feature_archive, feature_project, features, merge_setup
 from docket.ledger import ID_RE, LedgerError, _Prefix, append, validate_record
 
 
@@ -251,6 +251,8 @@ def cmd_init(args: argparse.Namespace) -> int:
         # The append lock is local state. A team that commits .docket/ would
         # otherwise commit it.
         ignore.write_text("*.lock\n", encoding="utf-8")
+    for message in merge_setup.setup(root):
+        print(message)
     if target.exists():
         print(f"docket: already project-local at {target}")
         return 0
@@ -279,4 +281,11 @@ def cmd_init(args: argparse.Namespace) -> int:
     return 0
 
 
-__all__ = ["cmd_check", "cmd_init", "cmd_migrate", "cmd_rebase"]
+def cmd_merge_driver(args: argparse.Namespace) -> int:
+    """Git merge driver entry point; see docket/merge_driver.py."""
+    from docket import merge_driver
+
+    return merge_driver.run(Path(args.base), Path(args.ours), Path(args.theirs))
+
+
+__all__ = ["cmd_check", "cmd_init", "cmd_merge_driver", "cmd_migrate", "cmd_rebase"]

docket/cli/context_cmd.py

@@ -50,6 +50,15 @@ def update_line() -> str | None:
         return None
 
 
+def _merge_notice() -> str | None:
+    from docket import merge_setup
+
+    try:
+        return merge_setup.notice(env.project_root())
+    except Exception:
+        return None
+
+
 def _print_context(text: str, args: argparse.Namespace, notice: str | None = None) -> int:
     body = f"{notice}\n{text}" if notice else text
     if not body:
@@ -120,7 +129,7 @@ def cmd_context(args: argparse.Namespace) -> int:
     except ConfigError as exc:
         print(f"docket: {exc}", file=sys.stderr)
         return 1
-    line = update_line()
+    line = "\n".join(filter(None, (update_line(), _merge_notice()))) or None
     # Validate against the loaded minimum, not a literal. A config that raises
     # budget.minimum would otherwise let a too-small value through and surface
     # as an uncaught ValueError from the renderer.

docket/merge_driver.py

@@ -0,0 +1,95 @@
+"""A git merge driver for the ledger.
+
+Git hands a merge driver three temp files and keeps whatever the second one
+holds. On a non-zero exit it marks the path unmerged but still takes that
+file as the worktree version, so a failure must leave conflict markers in it:
+an untouched OURS would look like a clean ledger, and staging it would drop
+every incoming record.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from docket import ledger, rebase
+
+
+def _conflict(base: Path, ours: Path, theirs: Path) -> None:
+    try:
+        original = ours.read_bytes()
+        incoming = theirs.read_bytes()
+    except OSError:
+        return
+    status = None
+    try:
+        status = subprocess.run(
+            [
+                "git",
+                "merge-file",
+                "-L",
+                "ours",
+                "-L",
+                "base",
+                "-L",
+                "theirs",
+                str(ours),
+                str(base),
+                str(theirs),
+            ],
+            capture_output=True,
+            timeout=30,
+        ).returncode
+    except (OSError, subprocess.SubprocessError):
+        print("docket: git merge-file could not run; wrote whole-file markers", file=sys.stderr)
+    # merge-file exits with the conflict count (1..127); 0 means it merged the
+    # text cleanly, which the driver's own refusal overrides, and anything else
+    # is a failure that may have left OURS untouched.
+    if status is not None and 0 < status < 128:
+        return
+    block = b"<<<<<<< ours\n" + _terminated(original) + b"=======\n"
+    block += _terminated(incoming) + b">>>>>>> theirs\n"
+    try:
+        ours.write_bytes(block)
+    except OSError as exc:
+        print(f"docket: cannot write conflict markers: {exc}", file=sys.stderr)
+
+
+def _terminated(data: bytes) -> bytes:
+    return data if not data or data.endswith(b"\n") else data + b"\n"
+
+
+def run(base: Path, ours: Path, theirs: Path) -> int:
+    """Merge THEIRS into OURS in place. 0 when merged, 1 when left in conflict."""
+
+    try:
+        # lock=False: the default lock creates <file>.lock next to git's temp
+        # files at the repository root, where nothing ignores it.
+        old, mine, incoming = (ledger.read(p, lock=False) for p in (base, ours, theirs))
+        tail, moved = rebase.merge(old, mine, incoming)
+        ledger.validate_entries(mine + tail)
+    except (ledger.LedgerError, rebase.RebaseError, OSError) as exc:
+        print(f"docket: cannot merge the ledger: {exc}", file=sys.stderr)
+        _conflict(base, ours, theirs)
+        return 1
+    if tail:
+        lines = "".join(
+            json.dumps(r, ensure_ascii=False, separators=(",", ":")) + "\n" for r in tail
+        )
+        with ours.open("rb") as handle:
+            handle.seek(0, 2)
+            needs_newline = False
+            if handle.tell():
+                handle.seek(-1, 2)
+                needs_newline = handle.read(1) != b"\n"
+        with ours.open("a", encoding="utf-8", newline="") as handle:
+            handle.write(("\n" if needs_newline else "") + lines)
+    for old_id, new_id in moved.items():
+        if old_id != new_id:
+            print(f"docket: {old_id} -> {new_id}", file=sys.stderr)
+    return 0
+
+
+__all__ = ["run"]

docket/merge_setup.py

@@ -0,0 +1,94 @@
+"""Wire the ledger merge driver into a clone.
+
+The attribute line is committed, but git reads a driver's command only from
+git config, never from the repository, so every clone needs `docket init`.
+"""
+
+from __future__ import annotations
+
+import shlex
+import shutil
+import subprocess
+from pathlib import Path
+
+ATTRIBUTE = ".docket/ledger.jsonl merge=docket"
+# docket on PATH, never an absolute path: the plugin cache path changes with
+# every release, and a config naming a deleted version fails every merge.
+DRIVER = "docket merge-driver %O %A %B"
+
+
+def _git(root: Path, *args: str) -> subprocess.CompletedProcess[str] | None:
+    try:
+        return subprocess.run(
+            ["git", "-C", str(root), *args], capture_output=True, text=True, timeout=5
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+
+def _in_repository(root: Path) -> bool:
+    result = _git(root, "rev-parse", "--git-dir")
+    return result is not None and result.returncode == 0
+
+
+def _has_attribute(root: Path) -> bool:
+    path = root / ".gitattributes"
+    if not path.is_file():
+        return False
+    return ATTRIBUTE in (line.strip() for line in path.read_text(encoding="utf-8").splitlines())
+
+
+def setup(root: Path) -> list[str]:
+    """Add the attribute line and register the driver; return what to tell the user."""
+
+    if not _in_repository(root):
+        return []
+    messages: list[str] = []
+    path = root / ".gitattributes"
+    try:
+        if not _has_attribute(root):
+            text = path.read_text(encoding="utf-8") if path.is_file() else ""
+            if text and not text.endswith("\n"):
+                text += "\n"
+            # Appended, not substituted: a later matching line overrides an earlier
+            # one, so a .docket/*.jsonl union line keeps covering features.jsonl.
+            path.write_text(text + ATTRIBUTE + "\n", encoding="utf-8")
+            messages.append(f"docket: added the ledger merge driver to {path}; commit it")
+    except (UnicodeError, OSError) as exc:
+        messages.append(f"docket: could not update {path}: {exc}")
+    if shutil.which("docket") is None:
+        messages.append(
+            "docket: merge driver not registered: docket is not on PATH, so git could not run it. "
+            "Put docket on PATH and run docket init again."
+        )
+        return messages
+    # Only the driver key: git aborts every merge ("lacks command line") when
+    # merge.docket.name exists without merge.docket.driver, and needs no name.
+    result = _git(root, "config", "--local", "merge.docket.driver", DRIVER)
+    if result is not None and result.returncode == 0:
+        messages.append("docket: registered the ledger merge driver in this clone's git config")
+    else:
+        reason = result.stderr.strip() if result is not None else "git could not run"
+        messages.append(
+            f"docket: merge driver not registered: git config failed ({reason}); nothing was changed"
+        )
+    return messages
+
+
+def notice(root: Path) -> str | None:
+    """One briefing line when the repository asks for the driver and this clone lacks it."""
+
+    try:
+        if not _has_attribute(root) or not _in_repository(root):
+            return None
+        result = _git(root, "config", "--get", "merge.docket.driver")
+        command = result.stdout.strip() if result is not None and result.returncode == 0 else ""
+        words = shlex.split(command) if command else []
+        if words and shutil.which(words[0]):
+            return None
+    except (OSError, ValueError):
+        return None
+    return "# merge driver not set up in this clone; run docket init"
+
+
+__all__ = ["ATTRIBUTE", "DRIVER", "notice", "setup"]