Find Any Commit on GitHub with gh search commits

You know someone fixed that parser bug last spring, but not in which repository or by whom, and git log only sees what you have cloned. This guide shows you how to search GitHub commit history with gh search commits, narrow it by repository, author and date, and pull out JSON for scripts. Allow about ten minutes, assuming gh is installed and authenticated for the account you intend to use.

• Read-only. Searching changes no commits, branches or pull requests, so there is nothing to undo.
• No sudo. Reading search results needs no elevated privileges.

1. Check the installed command

This guide follows the installed gh-search-commits(1) manual. The command here is GitHub CLI 2.87.3, while the Ubuntu package metadata on this machine reports gh 2.45.0-1ubuntu0.3+esm3. The two disagree because the executable found first on PATH is not the packaged one. Check your own system before relying on version-specific output or scripting around formatting.

$ command -v gh
/usr/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh search commits --help

2. Run a broad keyword search

Words after the subcommand form the query. This example looks for commits matching both words:

$ gh search commits readme typo
Showing 30 of 30 commits
... result rows printed here ...

The exact repositories, authors and row formatting depend on GitHub's current index and your account access. The default limit is 30 commits. A phrase must be quoted so the shell passes it as one argument:

$ gh search commits "bug fix"

This is not a local grep of cloned repositories. It asks GitHub's search service, so authentication, network access, API limits and repository visibility can all affect the result.

3. Narrow the repository and identity

Use --repo when the search must stay inside a named repository. Replace the placeholder with an owner and repository that you can access:

$ gh search commits "parser error" --repo OWNER/REPOSITORY --limit 20

There are separate filters for authors and committers, and they are not interchangeable. The author records who wrote the change. The committer records who recorded it in the repository history.

$ gh search commits --author=OCTOUSER --repo OWNER/REPOSITORY
$ gh search commits --committer=OCTOUSER --repo OWNER/REPOSITORY
$ gh search commits --author-name="Jane Doe" --repo OWNER/REPOSITORY

4. Filter by dates, hashes and merge status

Author and committer dates are separate options. The manual accepts date expressions such as a less-than comparison. Quote the value so the shell does not treat the comparison character specially:

$ gh search commits --author-date="<2026-02-01" --repo OWNER/REPOSITORY
$ gh search commits --committer-date=">=2026-01-01" --repo OWNER/REPOSITORY

For a known object, use --hash. To focus on history topology, add --merge; to search for a particular parent or tree, use --parent or --tree.

$ gh search commits --hash=COMMIT_SHA --repo OWNER/REPOSITORY
$ gh search commits --merge --repo OWNER/REPOSITORY --limit 50

5. Control ordering and the amount fetched

--limit sets the maximum number of commits fetched and defaults to 30. Start small while refining a query, then raise it deliberately. The default sort is best-match, and date ordering only applies when you choose a supported sort value:

$ gh search commits "release note" --repo OWNER/REPOSITORY \
    --sort=committer-date --order=desc --limit 10

The available sort values are author-date and committer-date.

6. Request stable fields for a script

Human-oriented rows are fine at a terminal, but a script should ask for named JSON fields. The installed help lists author, commit, committer, id, parents, repository, sha and url. Pair --json with --jq for a small, predictable projection:

$ gh search commits "security fix" --repo OWNER/REPOSITORY \
    --limit 10 --json sha,commit,url \
    --jq '.[] | [.sha, .commit.message, .url] | @tsv'
COMMIT_SHA	commit message text	https://github.com/OWNER/REPOSITORY/commit/COMMIT_SHA

JSON field names and the jq expression are case-sensitive. Commit messages can contain tabs or newlines, so treat this display as a report, not an unambiguous interchange format. If another tool consumes the data, keep the JSON and parse it with that tool instead of scraping the default table.

7. Diagnose an empty or failed search

Repeat the command with a small limit and an explicit repository. Check that OWNER/REPOSITORY is spelled correctly and that the account can see it. Then separate query problems from authentication problems:

$ gh auth status
$ gh search commits --repo OWNER/REPOSITORY --limit 1
$ printf 'exit status: %s\n' "$?"
exit status: 0

The final status describes the command, not whether a row matched. Inspect the actual output before treating status 0 as a useful match.

• Authentication missing. Follow your organisation's approved gh auth process. Do not paste tokens into a command, shell history or an article.
• Hyphen in the query behaves oddly. Read the broader gh search --help guidance about query handling before changing the search terms.