git-sim 发布：在自有仓库中交互式模拟 Git 命令，并接入 AI 智能体预检

在你自己的仓库中为 Git 提供可视化层：模拟、记录、回放、审计并分享单个 Git 命令或整个 Git 工作流，无论你或你的代理在哪里运行它们。

如果 git-sim 对你有帮助，⭐ 给仓库加星或在 GitHub 上赞助它。

要求

• Windows、macOS 或 Linux
• Python 3.10 至 3.14，以及 Git
• 动画视频（--animate）需要 Manim：参见安装

服务器、Docker 镜像、CI 运行器和 WSL 上的极简 Linux 发行版通常缺少以下必需依赖：libEGL、libGL 和 fontconfig。如果 git-sim 报错并提示需要它们，请使用适用于你的 Linux 版本的以下命令：

$ sudo apt install libegl1 libgl1 libfontconfig1           # Debian, Ubuntu, WSL
$ sudo dnf install mesa-libEGL mesa-libGL fontconfig       # Fedora, RHEL

开始使用

1. 安装 git-sim

$ pip install git-sim

或者 pipx install git-sim，或者 uv tool install git-sim。

2. 模拟任何 Git 命令：在你的本地仓库中，在任何 Git 命令前加上 git-sim 而不是 git

$ git-sim merge dev
$ git-sim reset --hard HEAD^
$ git-sim rebase main

默认情况下，git-sim 会创建一个网页优先、可分享的可视化，并在你的浏览器中打开。它会生成一个交互式模拟，精确展示任何 Git 命令将如何影响你的仓库，而不会实际运行真正的 Git 命令，因此你的仓库不会有任何变化。

运行 git-sim -h 列出所有命令。

3. 实时观看你的仓库更新：一个实时图形，按顺序为每个 Git 操作制作动画，并记录下来，以便你可以保存、回放和分享

$ git-sim live

4. 安装 git-sim VS Code 扩展：通过集成的命令面板工具，直接在 VS Code 中使用所有 git-sim 功能。

$ code --install-extension initialcommit.git-sim

或者在扩展视图中搜索 git-sim（VS Code 中的 Marketplace，Cursor、Windsurf 和 VSCodium 中的 Open VSX）。

5. Jupyter Notebook 集成：在笔记本的 Python 环境中安装 git-sim 后，在 Jupyter 中使用它：

%load_ext git_sim.jupyter   # once per notebook: adds the %gitsim magic
%gitsim rebase main         # the interactive graph, right under the cell
%gitsim live                # a live graph that follows the repo as it changes
%gitsim live stop           # stops live mode (so does restarting the kernel)

在 Jupyter 中，git-sim 会针对笔记本工作目录中的仓库模拟 Git 命令，或使用 -C 标志后指定的路径。

图形框架会扩展以适应它，除非你以像素为单位设置 --height。

%gitsim live 会在后台运行实时模式，直到你停止它或重启内核，并且需要 Jupyter 在你自己的机器上运行（不是 Colab、JupyterHub 或 Binder）。

6. GitHub PR 集成：参见安装。

7. 在运行前检查高风险命令：它有多高风险，以及你可能失去什么

$ git-sim preflight reset --hard HEAD~1

8. 连接你的 AI 代理：将预检钩子和 MCP 服务器添加到你的机器上的代理中

$ git-sim wire-agents

没有现成的 Git 仓库可供可视化？内置的 git-dummy 可以按你想要的任意结构创建 Git 仓库供你操作：

git-dummy --scenario orders 会构建本 README 中图表所基于的示例仓库（fetch 和 pull 用 --scenario orders-behind），这样你就能在其中运行相同的命令。

你的 Git 仓库数据保留在你自己的机器上

默认情况下，当你运行 git-sim 时，它会生成一个交互式 Git 图表，并在 initialcommit.com 上的 git-sim 查看器中打开，但图表数据会被压缩并放在链接的 #fragment 中，浏览器从不会将其发送到服务器，因此关于你代码的任何内容都不会离开你的本地机器。

例如，git-sim branch feature 会打开一个如下所示的链接，此处已缩短（完整链接约 2,000 个字符）：

https://initialcommit.com/tools/git-sim/viewer#d=eNrNWdtu2zgQ_RVBxaK7QEzzTqmIDbjJusWifdkC-06LlK1GlgxJiZP9-h3q4lvcpqqdrf1gmJSGnDOXw-H4unyYe4kZ-...&t=git+branch+feature&m=light&p=git-sim-branch_10-04-26_19-02-11.html

# 之后的所有内容都留在你的本地浏览器中：d 是压缩后的图表，t 是命令，m 是配色主题，p 是保存在你机器上的图表文件名。网站收到的只有 https://initialcommit.com/tools/git-sim/viewer。

该页面也会保存在本地，--open-in local（或 git_sim_open_in=local）会离线打开该文件，完全不调用 initialcommit.com 上的 git-sim 查看器。

唯一的例外是公开链接，你可以决定通过 Share → Public link 选项来创建它。生成公开链接会将 git-sim 图表数据存储在 initialcommit.com 的服务器上。为方便起见，该链接会被缩短，发布时会显示图表本身，同时你还会获得一个可随时删除所存储图表数据的链接。

实时模式

要进入 git-sim 的实时模式，请浏览到任意本地 Git 仓库并运行：

$ git-sim live

运行 git-sim live 可实时记录你或你的 AI 代理执行的每一个 Git 操作，形成一个可回放、可分享的可视化交互式会话。

它会为你的 Git 仓库的每一次变更命名、制作动画并进行跟踪，因此你可以逐步回溯其中任何一次变更、回放整个会话、将其保存为单个 HTML 页面，或下载为视频。

默认情况下，页面会在 initialcommit.com 上的 git-sim 查看器中打开，该查看器会连接到 git-sim live 在你机器上运行的轻量级 Web 服务器，该服务器只能从 127.0.0.1 并通过会话密钥访问。所有 Git 数据都会被压缩并存储在 URL 的 #fragment 中，因此关于你仓库的任何内容都不会离开你的机器；如果你不想调用 initialcommit.com 的 git-sim 查看器并希望完全本地运行，--open-in local 会改为由 git-sim 自身提供该页面。

在 VS Code 中运行：VS Code 扩展会在其 Live graph 标签页和侧边栏视图中显示相同的实时图表（参见该扩展的页面）。

它如何监视你的仓库：实时模式读取 Git 在两次检查之间报告的内容，而不是监视 .git，并等待仓库稳定下来，因此一次 rebase 或 pull 会显示为一次变更。它会尽可能根据 reflog 为每次变更命名（git commit、git reset <commit>、git switch -c <branch>），否则根据变更内容命名（创建了分支、暂存了文件、弹出了 stash）。Chrome 和 Edge 会请求一次访问本地服务器的权限。如果浏览器拒绝，页面会提供本地版本。

实用选项：

-C <path>：跟踪另一个仓库
--no-zones：仅显示提交图，不含工作目录表
--interval <seconds>：检查频率（默认 1）
--sessions、--replay：列出此仓库已记录的会话，或重新打开最新的会话（--session <folder> 用于另一个）
--once：绘制当前状态并退出
--json：每次变更打印一行 JSON 而不是打开页面，供编辑器使用
--port <number>：本地服务器的端口
-d：不打开任何内容，只打印地址

设置 GIT_SIM_LIVE_DEBUG=1 以记录每个检测到的变更。

将 git-sim 图表嵌入你的网页

将 git-sim 图形嵌入任何网页、博客文章、教程或文档中。包含完整的交互式查看器。在任意 git-sim 图形的 Share 菜单中点击 Copy embed，然后将 HTML 粘贴到你的页面中：

<div class="git-sim" data-graph="eJzVXWtvo0gW_SuI0a52..." data-title="git rebase main">
  <a href="https://initialcommit.com/learn/git/go?cmd=rebase&amp;from=embed">git rebase</a> main, created with <a href="https://initialcommit.com/tools/git-sim">git-sim</a>
</div>
<script src="https://initialcommit.com/js/tools/git-sim-embed.js" defer></script>

压缩后的图形数据包含在 data-graph 属性中，因此无需托管文件。

若要改为以文件形式托管，请使用 git-sim --img-format svg rebase main 保存 SVG（或使用 Share 菜单中的 Download SVG），并用 data-src="/path/to/graph.svg" 代替 data-graph。

预检

$ git-sim preflight reset --hard HEAD~2

git-sim 的预检模式会确定性地评估任何 Git 命令对你的仓库是否安全或可能具有破坏性，包括其风险有多高、哪些提交可能变得不可达、哪些更改将永久丢失，以及撤销该命令的命令，而这一切都不会影响你的仓库。

这可以接入 AI 代理，让你（人类）参与进来，批准/拒绝可能具有破坏性的 Git 命令。运行 git-sim wire-agents 为 AI 代理设置自动 git-sim 预检。

Git 的标志和选项会直接透传，并且引用整个命令也可以：git-sim preflight "git stash drop"）。

根据需要，使用 --json 或 --markdown 格式化报告。

面向代理式 AI 的 git-sim

AI 编码代理会替你运行 Git 命令。git-sim 通过两种方式帮助你和你的代理做正确的事：

• git-sim 预检钩子会在代理运行有风险的 Git 命令之前将其阻止，向你展示该命令将执行什么操作以及如何撤销的详细信息，并请你批准或拒绝。
• git-sim MCP 服务器为代理提供两个可按需调用的工具：git_preflight(command, repo_path) 用于检查命令是否可以安全运行，git_simulate(command, repo_path) 用于可视化模拟该命令（interactive=true 用于交互式页面）。

要在你机器上的每个代理中设置这两者，请运行：

$ git-sim wire-agents
$ git-sim unwire-agents

然后重启任何正在运行的代理。Wire-agents 会在 Claude Code、Codex CLI、Cursor、GitHub Copilot CLI、Gemini CLI 和 VS Code（Copilot）中同时设置钩子和 MCP 服务器，并且仅在 Windsurf、Cline、Roo Code、Amazon Q Developer CLI 和 Claude Desktop 中设置 MCP 服务器，因为这些没有钩子。

-指定特定代理：--agent claude --agent cursor -根据需要跳过 hook 或 mcp：--no-hook 或 --no-mcp -试运行：--dry-run -移除 hook 和 mcp 配置：git-sim unwire-agents

以下是一个示例，展示了 Claude Code 在尝试运行硬 Git reset 时的提示是什么样子：

git-sim preflight: DESTRUCTIVE  git reset -q --hard HEAD~2
Moves main from e35b0b7 to cb54632 (hard reset).
Loses: 2 commits removed from branch main; unstaged changes in README.md (NOT recoverable)
Undo: Commits stay in the reflog ~90 days: git reset --hard e35b0b7

钩子设置

将这些设置为环境变量：

手动设置示例

Claude Code 中的钩子，位于 .claude/settings.json 或 ~/.claude/settings.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [{ "type": "command", "command": "git-sim-hook", "timeout": 120 }]
      }
    ]
  }
}

Claude Code 中的 MCP 服务器：

$ claude mcp add git-sim -- git-sim-mcp

或在任何支持 stdio 服务器的客户端中：

{ "mcpServers": { "git-sim": { "command": "git-sim-mcp" } } }

支持的 Git 命令

命令语法遵循 Git 自身的语法。点击命令可查看其用法和选项，点击图形可在查看器中打开它并拖动其滑块：

git add：暂存文件、文件夹或所有内容

用法：git-sim add <pathspec>... | git-sim add -A

• 指定一个或多个文件或文件夹（相对于运行它的位置），按 git 读取它们的方式：文件夹会暂存其中的每一项更改，而 git-sim add . 会暂存当前文件夹下的所有内容
• -A/--all 会暂存仓库中的每一项更改（已修改、已删除和未跟踪的文件），无论从何处运行
• 模拟输出将显示文件被移动到暂存区
• 请注意，模拟输出还会显示活动分支上最近的 5 次提交

git bisect：找到引入 bug 的那次提交

用法：git-sim bisect start [<bad> [<good>...]] | git-sim bisect good|bad|old|new|skip [<commit>] | git-sim bisect reset [<commit>]

• start <bad> <good> 绘制 bad 和 good-<sha> 标记，将仍被怀疑的提交变为紫色，并将 HEAD 移动到 git 接下来要检出测试的提交
• 下一次提交来自 git 本身（git rev-list --bisect，以及提交被跳过时 git 自身的规则），因此绘制结果与 git bisect 的行为一致
• good、bad 和 skip 继续进行中的会话（从 refs/bisect/* 读取），标记 HEAD 或给定的提交；一旦只剩一个可疑对象，它就会被绘制为金色，作为第一个坏提交
• reset 移除标记并将 HEAD 返回到会话开始的位置

git blame：每一行最后是谁更改的，以及在哪个提交中更改

用法：git-sim blame <file> [-L <start>,<end>]

• 文件的代码视图：每一行都有一个彩色的边栏，对应最后更改它的提交，并在每段连续行的开头显示该提交的短哈希
• 这些提交在图中都被涂成相同的颜色；已编辑但尚未提交的行显示为灰色
• -L 将其限制为某个行范围，与 git 中一样（10,20 或 10,+5）

git branch：创建、删除、重命名、列出和跟踪分支

用法：git-sim branch <new branch name> [<start-point>] | git-sim branch -d|-D <branch> | git-sim branch -m <branch> <new name> | git-sim branch [-a] [-v|-vv] [--merged|--no-merged [<commit>]] | git-sim branch -u <upstream> [<branch>]

• 将 <new branch name> 指定为新分支的名称，以模拟创建该分支
• 模拟输出将显示新创建的分支引用以及活动分支上最近的 5 次提交
• -d 删除一个已合并到活动分支的分支；如果没有合并，git-sim 会像 git 一样拒绝
• -D 强制删除：只有被删除分支才能到达的提交会以金色绘制，并附上恢复它们的 git branch <name> <sha> 命令
• -m 重命名分支，就地移动其标签
• 不带名称时，列出分支：图中绘制每个分支，并用一张卡片列出它们，标记当前分支。-a/--all 添加远程跟踪分支，-v 显示每个分支的最后一次提交，-vv 还显示其上游以及领先或落后多少
• --merged [<commit>] 和 --no-merged [<commit>]（默认 HEAD）高亮 git 会列出的分支：其顶端在或不在该提交历史中的分支
• -u <upstream>/--set-upstream-to=<upstream> 显示它写入 [branch "x"] 的 .git/config 行，以及分支标签上新的 [upstream: ahead n, behind m]

git check-ignore：哪条忽略规则决定了一个路径

用法：git-sim check-ignore [-v] <path>...

• 显示带行号的忽略文件，并高亮决定每个路径的规则；来自 .git/info/exclude、嵌套的 .gitignore 或你的 core.excludesFile 的规则会有自己的卡片
• 旁边是每个路径的判定结果：被哪一行忽略、被 ! 行取消忽略、未被任何规则匹配，或已被跟踪（任何忽略规则都无法撤销）
• -v（--verbose）显示 git check-ignore -v 打印的内容：每个匹配项的来源、行号和模式

git checkout：切换分支，或创建一个分支

用法：git-sim checkout [-b] <branch>

• 将 <branch> 检出到工作目录，即将 HEAD 移动到指定的 <branch>
• -b 标志会创建一个具有指定名称 <branch> 的新分支并检出它，前提是该分支尚不存在

git cherry-pick：将提交复制到活动分支

用法：git-sim cherry-pick <commit>|<A..B> [-n] | git-sim cherry-pick --continue|--abort|--skip

• 将 <commit> 指定为一个引用（分支名/标签）或提交 ID，以拣选到活动分支
• 范围 A..B 会选取从 B 可达但不从 A 可达的每个提交，从最旧的开始，作为一串新提交
• -n/--no-commit 将更改应用到索引和工作树，而不创建提交
• 支持使用以下方式编辑拣选提交的消息：$ git-sim cherry-pick <commit> -e "Edited commit message"
• --continue、--abort 和 --skip 作用于因冲突而暂停的 cherry-pick：git-sim 在仓库的副本中运行真实命令（你的仓库绝不会被改动），并绘制出它会做什么：新提交淡入，HEAD 和分支移动，被留下的提交变为金色，并列出新的冲突

git clean：删除未跟踪的文件

用法：git-sim clean [-f] [-n] [-d] [-x]

• 模拟输出将显示未跟踪的文件被删除，取自 git 自身的试运行（使用相同标志的 git clean -n）
• -d 包括未跟踪的目录，-x 包括被忽略的文件（构建输出、虚拟环境）
• 如果没有 -f 或 -n，模拟会指出真实 git 将拒绝运行
• 请注意，模拟输出还会显示活动分支上最近的 5 个提交

git clone：复制仓库

用法：git-sim clone [--depth <n>] [-b <branch>] <url> [<path>]

• 从 <url>（网页 URL 或文件系统路径）克隆远程仓库到当前目录下的新文件夹
• 输出将报告克隆操作是否成功，并显示本地克隆的日志
• --depth <n> 进行浅克隆：只绘制最后 <n> 个提交，最旧的提交标记为 grafted，与留在服务器上的父提交切断
• -b/--branch <branch> 检出该分支（或标签），而不是远程 HEAD 指向的那个

git commit：将暂存的更改记录为新提交

用法：git-sim commit -m "Commit message"

• 模拟输出将显示新提交添加到活动分支的顶端
• 使用 -m 选项指定提交信息
• HEAD 和活动分支将移动到新提交
• 模拟输出将显示暂存区中的文件被包含在新提交中
• 支持使用以下命令修正最后一次提交：$ git-sim commit --amend -m "Amended commit message"
• --amend --no-edit 保留当前提交信息
• -a 首先暂存每个已修改的已跟踪文件（不包括未跟踪的文件）

git config：在任何范围读取和写入设置

用法：git-sim config [--global|--system] <section.option> [<value>] | git-sim config --list [--global|--system]

• 在设置文件旁边绘制一张卡片，详细说明该设置：其节、名称和值（或旧值和新值），颜色与文件中的行匹配，该设置的作用，以及它落在哪个范围
• 读取设置时，从 Git 会使用的范围（系统、全局或本地）回答，并说明是哪一个
• 使用 --list 或 -l 并排显示系统、全局和本地文件，按它们相互覆盖的顺序排列
• 使用 --global 读取或写入你自己的设置文件 ~/.gitconfig，它适用于你所有的仓库，除非某个仓库设置了自己的值
• 使用 --system 读取或写入系统文件，它适用于机器上的每个用户和仓库（写入需要管理员权限）；git-sim 会询问 Git 该文件在哪里

git describe：根据最近的标签命名提交

用法：git-sim describe [--tags] [<commit>]

• 根据其历史中最近的标签命名一个提交（默认 HEAD），如 git describe 所做：v1.0-2-g8c02d5a 是 v1.0 之后的 2 个提交，然后是 g 和提交自身的短 ID；有标签的提交仅由标签命名
• 图形回溯到该标签：自标签以来的提交被高亮显示，有标签的提交采用标签的颜色，名称标注在所描述的提交上，并在卡片中分解
• 除非给出 --tags，否则只有附注标签才计数，与 git 中一样；如果没有标签可计数，git-sim 会说明原因（完全没有标签、只有轻量标签，或该提交的历史中没有标签）

git diff：两个点之间发生了什么变化

用法：git-sim diff [--staged] [--stat] [<commit> [<commit>]] [<path>...] | git-sim diff <A>..<B> | git-sim diff <A>...<B>

• 显示差异从何处到何处：HEAD 到工作目录（“未暂存的更改”；如果有暂存的内容，则从暂存区开始，这才是 git diff 真正比较的对象），HEAD 到暂存区（--staged，别名 --cached：“已暂存的更改”），一个提交到工作目录，或一个提交到另一个提交
• 提交在图中标记为 from / to；A...B 从它们的合并基础开始，与 git 一样
• 按顺序播放：先是 "from" 一侧单独出现（紫色，作为图下方的芯片并显示在其提交上），然后一个箭头指向 "to" 一侧（青色），接着是卡片
• 卡片像 git diff --stat 那样列出每个更改的文件：其状态（M、A、D、R）、路径、添加和删除的行数，以及一个五格条形图；不是修订版本的参数是用于限制它的路径
• --stat 用 git 自己的话总结卡片："3 files changed, 10 insertions(+), 2 deletions(-)"

git fetch：从远程下载新提交

用法：git-sim fetch [--prune] <remote> <branch> | git-sim fetch --all [--prune]

• 从指定的 <remote> 获取指定的 <branch> 到本地仓库
• --prune/-p 还会移除远程上分支已消失的远程跟踪分支：它们的标签会淡出；没有它时，会有一条注释指出哪些仍然残留
• --all 获取每个远程：绘制每个远程移动或创建的远程跟踪标签，每个远程有一行说明它带来了什么（或者它没有新内容）

git grep：搜索已跟踪的文件

用法：git-sim grep [-n] [-i] <pattern> [<revision>] [-- <path>...]

• 像 git grep 那样在已跟踪的文件（或某个提交、分支或标签的文件）中搜索模式；git 自己查找匹配项，因此适用其正则表达式
• 卡片按文件对匹配行进行分组，每个匹配项都高亮显示；-n/--line-number 添加行号，-i/--ignore-case 忽略大小写
• 被搜索的修订版本在图中高亮显示；用 --compact 绘制且没有修订版本时，卡片单独显示

git init：创建仓库

用法：git-sim init

• 之前：你的项目文件夹及其文件；之后：文件上移，为新的 .git/ 文件夹腾出空间，绘制为其中内容的树状图（HEAD、config、objects/、refs/ 及其 heads/、tags/ 和 remotes/、hooks/、info/），每个都附有其用途
• 在现有仓库中运行它会显示没有任何变化，因为 git 会重新初始化它

git log：浏览和筛选历史

用法：git-sim log [-n <number>] [--all] [--oneline] [--graph] [-p] [--follow] [-S <text>] [--author <name>] [--since|--after <date>] [--until|--before <date>] [[--] <path>...]

• 模拟输出默认显示活动分支上最近的 5 个提交
• 使用 -n <number> 设置从每个分支头显示的提交数量
• 设置 --all 以在日志输出中显示所有本地分支
• --oneline 和 --graph 改变 git 打印列表的方式；绘图本身已经是图，因此它们显示在标题中
• 筛选器保留图形并高亮显示 git 会列出的提交：路径（git-sim log -- app.py）、-S <text>（添加或删除该文本的提交）、--author、--since/--after 和 --until/--before。卡片说明匹配了什么（"3 commits changed app.py"）并按最新优先列出它们；使用筛选器时，-n 是 git 列出的提交数
• --follow <file> 将文件的历史追溯到其重命名之前（"following its rename from main.py"）；-p 将最新列出的提交的补丁作为卡片添加

git ls-remote：列出远程的引用

用法：git-sim ls-remote [<remote>] [--heads] [--tags]

• 列出 <remote> 上的引用（默认：当前分支的远程，否则为 origin）：其 HEAD、分支和标签及其提交，与上次获取的远程跟踪副本并列
• 每个不同的引用都会被标记：自上次获取后已移动、尚未获取、在远程上已删除，或此处领先且有推送会发送的提交；只有你拥有的标签也会被标记
• --heads（别名 --branches）仅列出分支，--tags/-t 仅列出标签
• <remote> 也可以是 URL 或路径；此时这里没有可比较的内容
• 不会下载任何内容，也不会发生任何变化

git merge：将分支合并到活动分支

用法：git-sim merge <branch> [-m "Commit message"] [--no-ff|--squash] | git-sim merge --continue|--abort

• 指定 <branch> 为要合并到活动分支的分支名称
• 如果需要，使用 -m 选项指定提交信息
• 模拟输出将在可能时描绘快进合并
• 否则，将描绘三方合并
• 要在可能快进时强制创建合并提交，请使用 --no-ff
• 如果因合并冲突导致合并失败，则显示冲突的文件
• --squash 将该分支的更改作为一个集合暂存，但不提交任何内容：HEAD 不会移动，该分支也不会被记录为已合并
• --continue、--abort 作用于因冲突而暂停的合并：git-sim 在仓库副本中运行真实命令（你的仓库绝不会被触碰），并绘制出它会做什么：新提交淡入，HEAD 和分支移动，被落下的提交变为金色，并列出新的冲突

git mv：移动或重命名已跟踪的文件

用法：git-sim mv <file> <new file>

• 将 <file> 指定为要更新名称/路径的文件
• 将 <new file> 指定为文件的新名称/路径
• 模拟输出将显示正在更新的文件的名称/路径
• 请注意，模拟输出还将显示活动分支上最近的 5 个提交

git pull：获取并集成远程分支

用法：git-sim pull [--rebase] [<remote> <branch>]

• 将指定的 <branch> 从指定的 <remote> 拉取到本地仓库
• 如果未指定 <remote> 和 <branch>，则从默认远程拉取活动分支
• 如果发生合并冲突，它们会显示在表格中
• --rebase/-r 将你的本地提交重放到已获取的内容之上，而不是进行合并：副本淡入，原始提交以金色绘制在下方

git push：将提交、标签或删除发送到远程

用法：git-sim push [<remote> <branch>] [--force|--force-with-lease] | git-sim push <remote> --delete <branch|tag> | git-sim push <remote> <tag> | git-sim push --tags

• 将指定的 <branch> 推送到指定的 <remote> 并显示本地结果
• --force 会覆盖远程分支：只有远程才有的提交会以金色绘制，因为此后没有人能从远程访问到它们
• --force-with-lease 仅在远程仍与你上次获取时一致时才执行相同操作；否则模拟会显示拒绝
• 如果未指定 <remote> 和 <branch>，则将活动分支推送到默认远程
• --delete/-d 删除远程上的分支：其远程跟踪标签淡出，没有其他远程分支能到达的提交变为金色
• --tags 推送远程没有的每个标签（不推送分支）：每个标签都会获得一个 on origin 标签
• git-sim push <remote> <tag> 以相同方式推送一个标签（并说明随它一起推送多少个提交）；--delete <tag> 删除远程上的一个标签，其 on origin 标签变为 deleted on origin，而你自己本地的标签保持不变
• 如果推送因远程存在本地仓库中没有的更改而失败，则会包含一条消息告知用户先拉取，并用颜色编码标出需要拉取的提交

git rebase：在新基底上重放提交

用法：git-sim rebase <new-base> [--onto <commit>] [-i [--todo <file>]] | git-sim rebase --continue|--abort|--skip

• 将 <new-base> 指定为要将活动分支变基到的分支名称
• --onto <commit> 则改为将 <new-base> 之后的提交重放到 <commit> 之上
• -i 逐个重放每个提交；--todo <file> 接受一个变基待办列表（pick、reword、edit、squash、fixup、drop + sha），因此 squash 会折叠进前一个副本，drop 会以金色显示
• --continue、--abort 和 --skip 作用于因冲突而暂停的变基：git-sim 在仓库副本中运行真实命令（你的仓库绝不会被触碰），并绘制出它会做什么：新提交淡入，HEAD 和分支移动，被落下的提交变为金色，并列出新的冲突

git reflog：HEAD 曾经所在的位置，以及你可以恢复什么

用法：git-sim reflog [-n <number>]

• 将 HEAD 的最后 <number> 个位置（默认 5）绘制为紫色 HEAD@{k} 标签
• 不再有任何分支或标签能到达的提交会以金色绘制，并附上能将其恢复的 git reset --hard HEAD@{k} 命令

git remote：添加、重命名、删除和查看远程

用法：git-sim remote [-v] [add|rename|remove|get-url|set-url|show] [<remote>] [<url>]

• 模拟输出显示 .git/config 及其远程部分，旁边是一张卡片，标明远程名称、其 URL 以及该命令的作用：添加、重命名、删除远程，或将其指向新的 URL
• 不带选项运行 git-sim remote 将列出所有现有远程及其详细信息
• -v/--verbose 列出每个远程的 fetch 和 push URL，正如 git remote -v 所打印的那样
• show <remote> 向远程询问其分支并像 git remote show 那样报告：其 URL 和 HEAD 分支，每个分支是已跟踪、新（尚未获取）还是过时（在远程已删除，本地仍存在），以及为 git pull 和 git push 配置的本地分支，其设置在 .git/config 中亮起。没有任何变化

git reset：移动分支，并可能丢弃更改

用法：git-sim reset <reset-to> [--mixed|--soft|--hard] | git-sim reset [<commit>] <path>...

• 将 <reset-to> 指定为任意提交 ID、分支名、标签或其他引用，以模拟从当前 HEAD 重置到该处（默认：HEAD）
• 带路径时，HEAD 保持不动，指定的文件被取消暂存（其索引条目恢复到该提交的版本）
• 与普通的 git reset 命令一样，默认重置模式为 --mixed，但可以使用 --soft、--hard 或 --mixed 指定
• 模拟输出将显示分支/HEAD 重置以及工作目录、暂存区的结果状态，以及运行实际命令是否会删除任何文件更改

git restore：取消暂存文件或丢弃其更改

用法：git-sim restore [--staged] <file 1> <file 2> ... <file n>

• 将一个或多个 <file> 指定为已修改的工作目录文件或已暂存文件
• 模拟输出将显示文件被移回工作目录或丢弃的更改
• 注意，模拟输出还将显示活动分支上最近的 5 次提交

git revert：用新提交撤销一次提交

用法：git-sim revert <to-revert> [-m <parent-number>] [-n]

• 将 <to-revert> 指定为任意提交 ID、分支名、标签或其他引用，以模拟还原该提交
• 还原合并提交需要 -m <parent-number>（与 git 中一样）；被还原的文件是合并相对于该父提交引入的文件
• -n/--no-commit 暂存反向更改而不创建提交
• 模拟输出将显示还原 <to-revert> 中更改的新提交
• 模拟输出将包含活动分支上接下来最近的 4 次提交

git rm：删除已跟踪文件

用法：git-sim rm [--cached] <file 1> <file 2> ... <file n>

• 将一个或多个 <file> 指定为已跟踪文件
• 模拟输出将显示文件从 Git 跟踪中移除
• --cached 停止跟踪文件但将其保留在磁盘上：每个文件变为未跟踪，同时其删除被暂存
• 注意，模拟输出还将显示活动分支上最近的 5 次提交

git shortlog：每位作者的提交数

用法：git-sim shortlog [-s] [-n] [-e] [<revision>|<A>..<B>]（短标志可组合：-sn、-sne）

• 像 git shortlog 那样，按作者统计某个修订版本（默认 HEAD）或范围的提交数：一张卡片按名称或使用 -n/--numbered 时按提交数从多到少对作者排名，并显示每位作者的计数和条形图
• 没有 -s/--summary 时，每位作者的首个提交主题列在其名称下；-e/--email 会添加其地址
• 绘制的提交在图谱中采用其作者的颜色

git show：一次提交及其更改的文件

用法：git-sim show [<commit>|<tag>|<commit>:<path>]

• 高亮显示的提交（默认 HEAD），并在图谱下方的卡片中像 git show --stat 那样列出其更改的文件；注释标签的标注者和消息会被注明
• 对于合并提交，文件与其第一个父提交比较（git 打印组合差异）
• <commit>:<path> 显示某个文件（或目录列表）在该提交中的起始内容

git stash：将更改搁置一旁，再取回

用法：git-sim stash [push] [-u] [-m <message>] <file> | git-sim stash pop|apply | git-sim stash list|show|drop|clear [<stash-index>]

• 将一个或多个 <file> 指定为已修改的工作目录文件或已暂存文件
• 如果未指定 <file>，将包含所有可用文件
• -u/--include-untracked 也会贮藏未跟踪文件（否则，一条注释会统计留下的文件数）；-m 为条目命名，一条注释会显示它，如同 git stash list 将
• list、show、drop 和 clear 将 stash 绘制为一叠条目，最新的（stash@{0}）在最上面：每张卡片都有该条目的消息、其文件和行数，以及它所基于的提交（短 sha 和消息，而非其周围的历史）；drop 将被丢弃的条目淡出，并将其下方的条目向上滑动一个数字，clear 将它们全部淡出，show 高亮该条目并像 git stash show --stat 一样列出其文件
• 模拟输出将显示文件被移入/移出 Git stash
• 请注意，模拟输出还将显示活动分支上最近的 5 次提交

git status：工作目录和暂存区

用法：git-sim status

• 模拟输出将显示工作目录、暂存区和未跟踪文件的状态
• 请注意，模拟输出还将显示活动分支上最近的 5 次提交

git submodule：仓库中的仓库

用法：git-sim submodule [status|add <url> [<path>]|init|update [--init]|deinit [--force] <path>]

• 绘制超级项目的历史，外加一个表格，每个子模块一行：其路径、固定的提交及其状态
• add 记录一个新的固定子模块；update --init 初始化并检出；deinit 清空子模块的工作树（当它有本地更改时，没有 --force 会被拒绝）

git switch：切换分支，或创建一个分支

用法：git-sim switch [-c] <branch> [<start-point>] | git-sim switch -

• 将检出的分支切换到 <branch>，即将 HEAD 移动到指定的 <branch>
• -c 标志创建一个具有指定名称 <branch> 的新分支并切换到它，前提是它尚不存在；使用 <start-point> 时分支从那里开始，而远程跟踪起点（origin/x）成为其上游
• git-sim switch - 返回到上一个分支（reflog 中的 @{-1}），以其提交为标签
• 只有远程才有的 <branch>（仅存在 origin/<branch>）会在同一提交处本地创建，并跟踪它，正如 git 所做的那样

git tag：给提交打标签

用法：git-sim tag <new tag name> [<commit>] | git-sim tag -a <name> -m "<message>" [<commit>] | git-sim tag -d <name> | git-sim tag -l ["<pattern>"]

• 指定 <new tag name> 作为新标签的名称以模拟创建
• 模拟输出将显示新创建的标签引用以及活动分支上最近的 5 次提交
• -a 与 -m（或单独 -m）会创建一个附注标签：图下方的一张卡片显示它写入的标签对象，包括它指向的提交、打标签者、日期和消息
• -l/--list 在卡片中列出标签，高亮匹配模式（一个 glob，例如 "v1.*"）的标签

git worktree：多个工作目录

用法：git-sim worktree [list|add [-b <new-branch>] <path> [<branch>]|remove [--force] <path>|prune]

• 绘制提交图，外加一个表格，每个工作树一行：其目录、分支和状态（干净、N 个未提交更改、目录缺失）
• 当工作树有未提交更改时，remove 会被拒绝（如同 git 中），除非给出 --force，在这种情况下该行会被划掉并显示删除的更改计数
• prune 划掉目录已不存在的工作树记录

选项

$ git-sim [global options] <subcommand> [subcommand options]

你最常会用到的：

--img-format png（或 jpg、svg）：用静态图像代替交互式页面
--animate：改用 .mp4 视频（需要下面的 extras 安装）
--dark-mode：深色配色方案
--all、-n <number>：每个分支，以及每个分支有多少次提交
--open-in local：打开保存的页面而不是托管的查看器
--media-dir <path>：输出保存的位置（git-sim media-dir 打印默认值）

每个选项也可以通过一个名为 git_sim_ 加上选项的环境变量来设置，例如 git_sim_dark_mode=true 或 git_sim_img_format=png。命令行上的选项优先于变量。

所有全局选项

[global options] 适用于总体的 git-sim 模拟本身，包括：

--img-format：输出格式，即 html（默认：交互式页面）、jpg、png 或 svg（仅图形，用于嵌入页面）。在环境中设置 git_sim_img_format=jpg 可将图像设为默认输出。
--open-in：交互式页面的打开位置：hosted（默认）在 initialcommit.com 的 git-sim 查看器中显示，local 打开已保存的 .html 文件。无论哪种方式，页面都会保存在本地，托管页面会说明保存位置。设置 git_sim_open_in=local 可将本地设为默认。
--reverse, -r / --no-reverse：默认情况下，最新的提交位于左侧，箭头向右指向父提交，因此历史记录从左到右阅读。--no-reverse 将最新提交放在右侧，箭头指向左侧，即原始布局。
-n <number>：从每个分支头显示的提交数量。
--all：在日志输出中显示所有本地分支。
--animate：不输出静态图像，而是在 .mp4 视频中动画演示 Git 命令行为。
--color-by author：按参数为提交着色，例如作者。
--invert-branches：在适用的情况下，通过反转多个父提交的顺序来反转分支的位置。
--hide-merged-branches：隐藏来自已合并分支的提交，即仅显示主线提交。
--media-dir：存储模拟输出媒体文件的路径。
-d：禁用生成后自动打开图像/视频文件。有助于避免在无 GUI 的控制台模式下出错。
--dark-mode：使用深色配色方案而非默认的浅色方案（--light-mode 仍被接受但不产生任何效果）。
--stdout：将原始图像数据写入 stdout，同时抑制所有其他程序输出。除非指定 --img-format jpg，否则写入 png。
--output-only-path：仅将生成的媒体文件路径输出到 stdout。便于其他程序读取。
--quiet, -q：除错误外抑制所有输出。
--highlight-commit-messages：使提交消息文本更大更粗，并隐藏提交 ID。
--style：输出图像或动画视频的图形样式，即 clean（默认）或 thick。
--compact：为小空间绘制，例如卡片或缩略图：无标题，提交下方无提交消息（悬停仍会显示），文件表仅与其行数一样大，并且仅显示不涉及提交的命令的文件（add、restore、rm、mv、clean、status）。

仅动画的全局选项（需与 --animate 配合使用）：

--video-format：视频文件的输出格式，即 mp4 或 webm。默认输出格式为 mp4。
--speed=n：设置输出模拟的动画速度倍数，n 可以是整数或浮点数，默认为 1.5。
--low-quality：以低质量渲染动画以加快创建时间，推荐用于非演示用途。
--show-intro：添加带有自定义徽标和标题的片头序列。
--show-outro：添加带有自定义徽标和文本的片尾序列。
--title=title：在动画开头显示的自定义标题。
--logo=logo.png：用于动画片头/片尾的自定义徽标路径。
--outro-top-text：片尾期间显示在徽标上方的自定义文本。
--outro-bottom-text：片尾期间显示在徽标下方的自定义文本。
--font：用于显示渲染文本的字体系列。

安装

为方便起见，git-sim 分 3 个层级发布。Core 是默认层级，也是绝大多数用户的正确选择：

对于 extras 层级：

动画视频（--animate）使用 Manim，需要 FFmpeg 和其他系统软件包：请先按照 Manim 指南为 Windows、macOS、Linux 或 Conda 安装它们。在 macOS 上，建议使用 Homebrew Python 或虚拟环境，而不是系统 Python。

对于 min 层级：

pip extras 只能添加软件包，因此 min 层级是安装时不带渲染依赖项（skia-python、numpy）的核心包：

$ pip install --no-deps git-sim
$ pip install gitpython "mcp>=2.0" typer pydantic-settings fonttools git-dummy

Docker

在 Docker 容器中运行 git-sim

1. 克隆 git-sim 仓库：

$ git clone https://github.com/initialcommit-com/git-sim.git

1. 进入 git-sim 文件夹并构建 Docker 镜像：

$ docker build -t git-sim .

1. Run git-sim commands as follows:
   • Windows：docker run --rm -v %cd%:/usr/src/git-sim git-sim [global options] <subcommand> [subcommand options]
   • MacOS / Linux：docker run --rm -v $(pwd):/usr/src/git-sim git-sim [global options] <subcommand> [subcommand options]

可选：在 MacOS / Linux / 或 Windows 中的 GitBash 上，为这个长 docker 命令创建一个别名，以便你可以像普通 git-sim 命令一样运行它。为此，将以下行添加到你的 .bashrc 或等效文件中，然后重启终端：

git-sim() { docker run --rm -v $(pwd):/usr/src/git-sim git-sim "$@"; }

这将使你能够运行上面描述的所有 git-sim 子命令。

GitHub

GitHub Actions：使用 git-sim 自动评估 PR

将此作为 .github/workflows/git-sim.yml 添加到你的仓库：

name: git-sim
on:
  pull_request_target:
    types: [opened, synchronize, reopened]
permissions:
  contents: read
  pull-requests: write
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: initialcommit-com/git-sim/integrations/github-action@v0.4.0

当有新的 PR 进来时，git-sim GitHub Action 会自动评估它，添加一条评论，包含风险级别、包含的提交、如何撤销以及文本提交图。可视化交互图作为工件 git-sim-pr-<number> 附加到运行中。

要更改其运行方式，请在 uses: 行下添加一个 with: 块：

      - uses: initialcommit-com/git-sim/integrations/github-action@v0.4.0
        with:
          mode: rebase
          comment: "false"

工作流在 pull_request_target 上运行，因为 GitHub 会跳过存在合并冲突的拉取请求的 pull_request 工作流，而这些正是你最想检查的。它还允许 Action 对来自 fork 的拉取请求发表评论。这在这里是安全的，因为 Action 从不运行拉取请求的代码：它只读取其提交。

GitHub CLI：gh gitsim

安装并登录 GitHub CLI 后（gh auth login），从此仓库的克隆中安装扩展：

$ git clone https://github.com/initialcommit-com/git-sim.git ~/git-sim
$ cd ~/git-sim/integrations/gh-gitsim
$ gh extension install .

然后，在拉取请求仓库的克隆中：

$ gh gitsim pr 42           # what merging pull request #42 into its base would do
$ gh gitsim pr 42 rebase    # what rebasing it onto its base would do

gh gitsim pr 在临时工作树中模拟，因此你的检出和分支永远不会被触碰。任何其他 gh gitsim 命令与运行 git-sim 相同。在 Windows 上，gh 使用 Git for Windows 中的 bash 运行扩展。

支持 git-sim

Git-Sim 是自由开源软件（FOSS）。你的支持将帮助我全职投入它（以及其他 Git 项目）！

• ⭐ 为仓库加星
• 在 GitHub 上赞助 Git-Sim
• 通过 Patreon 支持 Git-Sim

作者

Jacob Stopak - 代表 Initial Commit