• 开发工具
• CLI
• 版本控制

git-local-commits是 git-extras 提供的一键式命令，用于列出当前本地分支中尚未推送到远端跟踪分支的提交。本文以 man/git-local-commits.md 手册文档为核心，结合其 核心实现 与 命令总览 说明其用法、底层原理与实战场景，读者可在推送到远端前快速审查本地积累的提交。

命令速览（SYNOPSIS）

git-local-commits <args>

该命令由 git-extras 安装后以git local-commits的子命令形式调用，任何附加参数都会原样透传给git-log。它的用途非常简单：仅列出本地上有、远端跟踪分支上还没有的提交，不推送、不修改任何内容，是一个纯只读的检查类命令。

核心功能与使用前置条件（DESCRIPTION）

按手册文档的说明，git-local-commits会：

• 列出当前本地分支中尚未被推送到远端跟踪分支的提交；
• 其正常工作要求 HEAD 指向一个正在跟踪其他分支的分支（即存在 upstream 关联）。

这一前置条件来自 核心实现 中的范围语法：

git log "@{upstream}..@" "$@"

@{upstream}..@是一个提交范围表达式，含义是"从远端跟踪分支（@{upstream}）到当前分支（@，即 HEAD）之间的所有提交"。Git 的范围语法A..B表示"在 B 中但不在 A 中"的提交，因此这里精确地取出当前分支领先于其 upstream 的全部提交，再交给git log展示。

因此使用前需要保证本地分支已设置上游跟踪分支，常见方式有：

# 推送并建立跟踪关系 git push -u origin feature-branch # 或为已有分支显式设置 upstream git branch --set-upstream-to=origin/feature-branch

如果当前分支没有关联的 upstream，git log会因无法解析@{upstream}而报错，这也正是 History.md 中"must track a branch"这一历史修订记录强调的前提。

参数透传（OPTIONS）：所有参数直接交给 git-log

手册明确说明：<args>中传给git-local-commits的所有参数都会被原样传递给git-log。这意味着git log的全部筛选与格式化能力都可以复用：

由于参数被原样透传（源码中通过"$@"展开），也可以组合使用，例如git local-commits --oneline -n 10。不过需要注意：任何超出git log支持的参数都会直接由 Git 报错，命令本身不做额外校验。

实战示例（EXAMPLES）

手册给出的标准示例：

$ git local-commits --graph

该命令输出当前分支全部未推送提交的图形化日志，非常适合在 push 前快速确认本地"领先于远端"的提交集合与分叉形态。更多可直接套用的场景：

# 一行一提交，快速数清本地积压了多少提交 git local-commits --oneline # 查看未推送提交的完整差异统计 git local-commits --stat # 只看自己过去一周的未推送提交 git local-commits --author="$(git config user.name)" --since="1 week ago"

在 Commands.md 的命令总览中，该命令被描述为"列出所有尚未发送到 origin 的本地分支提交，任何附加参数都会直接传给 git log"，与手册文档完全一致，可作为快速参考。

与其他 git-extras 命令的分工

git-extras 中还提供了与提交状态相关的其他命令，便于在实际工作流中组合使用：

• git missing <branch>：列出两个分支各自独有、彼此都还没有的提交（双向差异），适合对比任意两个分支；
• git commits-since：列出某个时间段内的提交记录；
• git summary：输出仓库的提交统计总览。

相比之下，git-local-commits聚焦的是"当前分支 vs 其上游跟踪分支"这一个单向的未推送提交视图，语义最贴近git status中"ahead of 'origin/xxx' by N commits"的提示，但输出是完整、可自定义的提交日志而非简短的计数。

补全与环境支持

git-extras 为各主流 Shell 提供了该命令的补全条目，方便快速输入：

• zsh：etc/git-extras-completion.zsh 中登记为local-commits:'list local commits'；
• fish：etc/git-extras.fish 中登记为local-commits:List local commits；
• bash：见 etc/bash_completion.sh。

同时 need_git_commit 文件中列出了该命令（作为需要存在 git 提交才能运行的命令之一参与项目自检），说明它依赖当前仓库已有提交记录这一基本前提。

小结

git-local-commits用一行git log "@{upstream}..@" "$@"完成了"列出本地未推送提交"这一高频需求：它要求分支已设置 upstream，将全部附加参数透传给git log，从而让开发者可以复用 Git 原生的筛选与格式化能力。配合--graph、--oneline、--stat等参数，它能在每次推送前提供一份清晰、可定制的提交审查清单，是 git-extras 提交管理工具箱中轻量而实用的一环。

相关文件：

• 命令实现：bin/git-local-commits
• 手册（Markdown/roff/HTML）：man/git-local-commits.md、man/git-local-commits.1、man/git-local-commits.html
• 命令总览：Commands.md
• 历史变更记录：History.md

• 开发工具
• CLI
• 版本控制