Description
Shows the current branch, its target branch, and every commit on the current branch that the target doesn't have, newest first. It's the list of what you would be proposing if you opened a pull request now.
The target branch is found the same way as for grit status: the target.branch setting, then origin/master, origin/main, master and main. Use --target <REF> to compare against any ref or revision instead (branch, remote-tracking ref, tag, or commit id). grit ahead is an alias for the same command — grit's shortlog means commits ahead of a target, not Git's author-grouped shortlog -sne. Unlike grit status, which shows at most ten commits, grit shortlog lists up to -n / --max-count commits (default 100). Full ahead and behind counts are always exact even when the lists are truncated.
When no target branch can be discovered, the result is an empty list. An explicit --target that cannot be resolved is an error.
With --behind, also lists commits that are on the target but not on this branch yet (the commits you would pick up by fast-forwarding or merging the target).
For author commit counts over an arbitrary revision range (Git's shortlog -sne shape), use grit log --group-by author instead — grit shortlog means commits ahead of the target branch, not author grouping.
Options
| Flag | Meaning |
|---|---|
--target <REF> |
Ref or revision to compare against instead of the discovered target branch. |
-n, --max-count |
Maximum commits to list on each side (default 100). Counts stay exact when the list is truncated. |
--behind |
Also list commits on the target that are not on this branch (behind / behind_commits in JSON). |
--stat |
Per-commit diffstat (same shape as grit log --stat). |
--name-only |
Per-commit changed paths (same shape as grit log --name-only). |
Only --stat and --name-only are supported for per-commit diffs; use grit log for patch and other formats.
Global options: global options.
JSON output
Schema: v1
Pass --json for stable, scripting-friendly output:
| Field | Type | Meaning |
|---|---|---|
branch |
string | Current branch name. |
target |
string or null | Target branch used for comparison, or null when none was found. |
ahead |
number | How many commits are on the branch but not on the target. |
behind |
number or null | How many commits are on the target but not on the branch; null when no target was found. |
commits |
array | Ahead commits, newest first, each using the shared CommitJson shape plus optional stat / files when --stat / --name-only is set. |
truncated |
boolean | true when ahead exceeds the number of commits listed. |
behind_commits |
array or null | Behind commits when --behind is set; same commit object shape as commits. |
behind_truncated |
boolean or null | true when behind exceeds behind_commits length; only with --behind. |
next |
null | Reserved for future paging; always null today. |
Markdown output
Exit status
See Exit codes for the shared rules and structured --json kind values.