Skip to content

Use "committish" rather than "commitish" in docs - #7236

Merged
philrz merged 1 commit into
mainfrom
committish-in-docs
Aug 24, 2026
Merged

Use "committish" rather than "commitish" in docs#7236
philrz merged 1 commit into
mainfrom
committish-in-docs

Conversation

@philrz

@philrz philrz commented Aug 22, 2026

Copy link
Copy Markdown
Contributor

What's Changing

This proposes using the Git-aligned spelling "committish" rather than the "commitish" that currently appears in the docs.

The "commitish" spelling also appears many places in the code, so if we make the change at the docs layer we might want to think about doing it in the code to match.

Why

The term originates with Git, whose glossary defines it as "commit-ish (also committish)". Both of the spellings Git sanctions have either the hyphen or the double "t". Ours has neither.

Git's own practice is lopsided. Counts of each spelling inside the git/git repository, via GitHub code search:

Spelling Occurrences in git/git
committish 40
commit-ish 33
commitish 1

Note: That single "commitish" hit in git/git is related to the change 84a7c33a4b that was their own similar spelling adjustment. Its message reads "The git glossary accepts a hyphen or a double-t, but not a single-t" and "none of the typos appear in user-visible locations", and Git made the change anyway, in comments and in a parameter name in branch.h. It was a contained cleanup (3 files, ~13 lines), not a codebase-wide rename, which is roughly the shape I'm proposing here.

I went with committish rather than commit-ish because it reads better in running prose and avoids an awkward line-break hazard. Git explicitly sanctions both.

Since super db is Git-shaped, readers may arrive with Git's vocabulary already loaded, so it seems logical to match Git's spelling.

Part of why I lean toward wanting to make this change is because I hope to introduce codespell for automated spell checking in a future PR, and they correct "commitish" to "committish" in their default dictionary. If we want to stick with what we're already doing, of course I could just add an exclusion. Ours to decide.

Counterargument

In fairness, the raw numbers across all of GitHub favor our current spelling:

Spelling Occurrences across GitHub
commitish 107,008
committish 52,096
commit-ish 30,208

But roughly 44,928 of those commitish hits are target_commitish, the field name in GitHub's Releases API, so that's one upstream API decision replicated across tens of thousands of repos.

In the Code

The word appears 118 times repo-wide: 42 in docs and the rest in Go and the PEG grammar. Claude helped me check that "commitish" does not currently leak out into help text, parse errors, or user-visible strings, so if we were ok making this change in the user-facing docs and want to let it live on as "commitish" in the code, I'm personally fine with that. But if folks that look after the code are on board with the docs change and want to be fully consistent in the code too, great.

@philrz philrz self-assigned this Aug 22, 2026
@philrz
philrz requested a review from a team August 22, 2026 19:53
@philrz
philrz merged commit 189d675 into main Aug 24, 2026
4 checks passed
@philrz
philrz deleted the committish-in-docs branch August 24, 2026 16:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants