Skip to content

docs(verify): same_commit's docstring misstates git's abbreviation default #674

Description

@pbean

same_commit's docstring justifies its 7-character floor with a claim about git that does not hold:

def same_commit(a: str, b: str) -> bool:
    """Hash equality tolerant of abbreviated forms (>= 7 chars, git's default
    --short length); sessions sometimes report `git rev-parse --short HEAD`."""

There is no fixed "default --short length". With core.abbrev unset git uses auto, which scales the abbreviation with the repository's reachable-object count and clamps upward to 7 only for small repositories. Measured:

  • the project test fixture's sandbox repo (~7 reachable objects) → git rev-parse --short HEAD yields 7
  • this repository → yields 8 (78c3a748)

So the sentence is accidentally true in the test sandbox and false in the repo the orchestrator actually runs in. Git's documented hard minimum of 4 is a separate mechanism governing explicit core.abbrev / --short=<n> values, and git still lengthens beyond it whenever uniqueness demands.

The 7 is a constant mirroring nothing external — _OBJECT_ID's comment gets this right ("Length floor mirrors same_commit's 7"), so the two sit in the same file disagreeing about where the number comes from.

Impact is documentation-only — no behavior depends on the claim — but it is the kind of premise that gets reused. It was on its way into a test docstring on #647 before being caught, and a related restatement was drafted into a review comment.

Also worth recording while this is open: same_commit currently has zero executable call sites. The only remaining references are prose (verify.py:255, verify.py:346, two test docstrings). Whether it should be retired is a separate question from the wording, and not one this issue proposes to answer.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions