git-sim

通过单个终端命令在您自己的仓库中直观地模拟Git操作。

这将生成一个图像（默认）或视频可视化，描述Git命令的行为。

命令语法直接基于Git的命令行语法，因此使用git-sim尽可能地熟悉。

示例：$ git-sim merge <branch> <br/><br/>

查看git-sim发布博客文章了解完整详情！

支持git-sim

Git-Sim是免费开源软件（FOSS）。您的支持将帮助我全职致力于它（和其他Git项目）！

• 在GitHub上赞助Git-Sim
• 通过Patreon支持Git-Sim

使用场景

• 可视化Git命令，在实际运行之前了解它们对您的仓库的影响
• 通过模拟来防止意外的工作目录和仓库状态
• 与您的团队或全世界分享Git命令的可视化效果（jpg/png图像或mp4/webm视频）
• 将可视化效果保存为团队文档的一部分，以记录工作流程并防止重复出现问题
• 创建静态Git图表（jpg/png）或动态动画视频（mp4/webm）以加快内容创建速度
• 帮助视觉学习者理解Git命令的工作原理
• 结合内置命令git-dummy生成一个虚拟Git仓库，然后在其上模拟操作

特性

• 在终端中运行一行git-sim命令，从您的仓库生成自定义Git命令可视化（.jpg）
• 支持的命令：add、branch、checkout、cherry-pick、clean、clone、commit、config、fetch、init、log、merge、mv、pull、push、rebase、remote、reset、restore、revert、rm、stash、status、switch、tag
• 使用--animate标志生成动画视频（.mp4）而不是静态图像（注意：性能显著下降，建议使用--low-quality加快测试速度，准备生成演示质量视频时再移除）
• 通过参数（如作者）为提交着色，使用--color-by=author选项
• 在深色模式（默认）和浅色模式之间选择
• 指定输出格式为jpg、png、mp4或webm
• 结合内置命令git-dummy生成虚拟Git仓库，然后在其上模拟操作
• 仅限动画：根据需要添加自定义品牌介绍/结束序列
• 仅限动画：根据需要加快或减慢动画速度

快速开始

注意：如果您更喜欢使用Docker安装git-sim，请跳过这里的步骤（1）和（2），直接跳到下面的Docker安装部分，然后再回到这里的步骤（3）。

1. 为您的操作系统/环境安装Manim及其依赖项：

   • 在Windows上安装Manim
   • 在MacOS上安装Manim
   • 在Linux上安装Manim
   • 在Conda中安装Manim

2. 安装git-sim：

$ pip3 install git-sim

注意：对于MacOS，建议不要使用系统Python安装Git-Sim，而是使用Homebrew安装一个Python版本来与Git-Sim一起使用。虚拟环境也应该可以。

3. 浏览到您想要模拟Git命令的Git仓库：

$ cd path/to/git/repo

4. 运行程序：

$ git-sim [全局选项] <子命令> [子命令选项]

可选：如果您没有现有的Git仓库来模拟命令，可以使用内置的git-dummy命令生成一个具有所需分支和提交数量的虚拟Git仓库，以便用git-sim模拟操作：

$ git-dummy --name="dummy-repo" --branches=3 --commits=10
$ cd dummy-repo
$ git-sim [全局选项] <子命令> [子命令选项]

或者如果您想在一个命令中完成所有操作：

$ git-dummy --no-subdir --branches=3 --commits=10 && git-sim [全局选项] <子命令> [子命令选项]

5. 模拟输出将创建为.jpg文件。输出文件以执行的子命令和时间戳命名，默认存储在名为git-sim_media/的子目录中。可以使用命令行标志--media-dir=path/to/output自定义此子目录的位置。请注意，当使用--animate全局标志时，渲染时间会更长，并将生成.mp4视频输出文件。

6. 为方便起见，可以为git-sim中可用的任何全局命令行选项设置环境变量。所有环境变量都以git_sim_开头，后跟选项名称。

例如，可以像这样设置--media-dir选项的环境变量：

$ export git_sim_media_dir=~/Desktop

同样，可以像这样设置--speed选项：

$ export git_sim_speed=2

布尔标志可以这样设置：

$ export git_sim_light_mode=true

一般来说：

$ export git_sim_选项名称=选项值

在命令行上明确指定的选项优先于相应的环境变量值。

7. 查看全局帮助以获取全局选项/标志和子命令列表：

$ git-sim -h

8. 查看子命令帮助以获取特定子命令的选项/标志列表：

$ git-sim <子命令> -h

要求

• Python 3.7或更高版本
• Pip（Python的包管理器）
• Manim（社区版）

命令

基本用法类似于Git本身 - git-sim接受一组熟悉的子命令，包括"add"、"branch"、"checkout"、"cherry-pick"、"clean"、"clone"、"commit"、"config"、"fetch"、"init"、"log"、"merge"、"mv"、"pull"、"push"、"rebase"、"remote"、"reset"、"restore"、"revert"、"rm"、"stash"、"status"、"switch"、"tag"以及相应的选项。

$ git-sim [全局选项] <子命令> [子命令选项]

[全局选项]适用于整个git-sim模拟本身，包括： -n <数字>: 显示每个分支头的提交数量。 --all: 在日志输出中显示所有本地分支。 --animate: 不输出静态图像，而是将Git命令行为以.mp4视频形式动画展示。 --color-by author: 按参数（如作者）为提交着色。 --invert-branches: 通过在适用情况下反转多个父级的顺序来反转分支的位置。 --hide-merged-branches: 隐藏已合并分支的提交，即只显示主线提交。 --media-dir: 存储模拟输出媒体文件的路径。 -d: 禁用生成后自动打开图像/视频文件。在无GUI的控制台模式下避免错误时很有用。 --light-mode: 使用浅色模式配色方案而非默认的深色模式。 --reverse, -r: 以相反方向显示提交历史。 --img-format: 图像文件的输出格式，如jpg或png。默认输出格式为jpg。 --stdout: 将原始图像数据写入标准输出，同时抑制所有其他程序输出。 --output-only-path: 仅将生成的媒体文件路径输出到标准输出。对其他程序摄取有用。 --quiet, -q: 除错误外抑制所有输出。 --highlight-commit-messages: 使提交消息文本更大更粗，并隐藏提交ID。 --style: 输出图像或动画视频的图形风格，如clean（默认）或thick。

仅用于动画的全局选项（与--animate一起使用）：

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

[子命令选项]类似于特定于指定子命令的常规Git选项（完整列表见下文）。

以下是可以模拟的Git命令及其相应的选项/标志列表。

git add

用法：git-sim add <文件1> <文件2> ... <文件n>

• 指定一个或多个<文件>作为已修改的工作目录文件，或未跟踪文件
• 模拟输出将显示文件被移动到暂存区
• 注意模拟输出还会显示活动分支上最近的5个提交

git branch

用法：git-sim branch <新分支名>

• 指定<新分支名>作为要模拟创建的新分支名称
• 模拟输出将显示新创建的分支引用以及活动分支上最近的5个提交

git checkout

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

• 将<分支>检出到工作目录，即将HEAD移动到指定的<分支>
• -b标志创建一个指定名称<分支>的新分支并检出，假设该分支尚不存在

git cherry-pick

用法：git-sim cherry-pick <提交>

• 指定<提交>为要cherry-pick到活动分支的引用（分支名/标签）或提交ID
• 支持编辑cherry-pick的提交消息：$ git-sim cherry-pick <提交> -e "编辑后的提交消息"

git clean

用法：git-sim clean

• 模拟输出将显示未跟踪文件被删除
• 由于这只是模拟，不需要像常规Git那样指定-i、-n、-f
• 注意模拟输出还会显示活动分支上最近的5个提交

git clone

用法：git-sim clone <url>

• 从<url>（网址或文件系统路径）克隆远程仓库到当前目录的新文件夹
• 输出将报告克隆操作是否成功，并显示本地克隆的日志

git commit

用法：git-sim commit -m "提交消息"

• 模拟输出将显示新提交添加到活动分支的顶端
• 使用-m选项指定提交消息
• HEAD和活动分支将移动到新提交
• 模拟输出将显示暂存区中的文件被包含在新提交中
• 支持修改最后一次提交：$ git-sim commit --amend -m "修改后的提交消息"

git config

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

• 模拟输出描述指定的配置更改
• 使用--list或-l显示所有配置

git fetch

用法：git-sim fetch <远程> <分支>

• 从指定的<远程>获取指定的<分支>到本地仓库

git init

用法：git-sim init

• 模拟输出描述初始化的.git/目录及其内容

git log

用法：git-sim log [-n <数字>] [--all]

• 默认情况下，模拟输出将显示活动分支上最近的5个提交
• 使用-n <数字>设置要显示的每个分支头的提交数量
• 设置--all以在日志输出中显示所有本地分支

git merge

用法：git-sim merge <分支> [-m "提交消息"] [--no-ff]

• 指定 <branch> 作为要合并到当前分支的分支名
• 如果需要，可以使用 -m 选项指定提交消息
• 模拟输出将在可能的情况下显示快进合并
• 否则，将显示三向合并
• 要在可以快进的情况下强制进行合并提交，请使用 --no-ff
• 如果由于合并冲突导致合并失败，将显示冲突文件

git mv

用法：git-sim mv <文件> <新文件>

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

git pull

用法：git-sim pull [<远程仓库> <分支>]

• 从指定的 <远程仓库> 拉取指定的 <分支> 到本地仓库
• 如果未指定 <远程仓库> 和 <分支>，则从默认远程仓库拉取当前分支
• 如果发生合并冲突，将在表格中显示

git push

用法：git-sim push [<远程仓库> <分支>]

• 将指定的 <分支> 推送到指定的 <远程仓库> 并显示本地结果
• 如果未指定 <远程仓库> 和 <分支>，则将当前分支推送到默认远程仓库
• 如果由于远程存在本地仓库中不存在的更改而导致推送失败，将包含一条消息告诉用户先拉取，并用颜色标注需要拉取的提交

git rebase

用法：git-sim rebase <新基础>

• 指定 <新基础> 作为要将当前分支变基到的分支名

git remote

用法：git-sim remote [add|rename|remove|get-url|set-url] [<远程仓库>] [<URL>]

• 模拟输出将显示远程仓库按指示被添加、重命名、删除或修改
• 不带选项运行 git-sim remote 将列出所有现有远程仓库及其详细信息

git reset

用法：git-sim reset <重置目标> [--mixed|--soft|--hard]

• 指定 <重置目标> 为任何提交ID、分支名、标签或其他引用，以模拟从当前HEAD重置（默认：HEAD）
• 与普通的git reset命令一样，默认重置模式为 --mixed，但可以使用 --soft、--hard 或 --mixed 指定
• 模拟输出将显示分支/HEAD重置和工作目录、暂存区的结果状态，以及运行实际命令是否会删除任何文件更改

git restore

用法：git-sim restore <文件1> <文件2> ... <文件n>

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

git revert

用法：git-sim revert <要还原的提交>

• 指定 <要还原的提交> 为任何提交ID、分支名、标签或其他引用以模拟还原
• 模拟输出将显示还原 <要还原的提交> 的更改的新提交
• 模拟输出将包括当前分支上接下来的4次最近提交

git rm

用法：git-sim rm <文件1> <文件2> ... <文件n>

• 指定一个或多个 <文件> 作为被跟踪的文件
• 模拟输出将显示文件从Git跟踪中被移除
• 请注意，模拟输出还将显示当前分支上最近的5次提交

git stash

用法：git-sim stash [push|pop|apply] <文件>

• 指定一个或多个 <文件> 作为已修改的工作目录文件或已暂存文件
• 如果未指定 <文件>，将包括所有可用文件
• 模拟输出将显示文件被移入/移出Git暂存区
• 请注意，模拟输出还将显示当前分支上最近的5次提交

git status

用法：git-sim status

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

git switch

用法：git-sim switch [-c] <分支>

• 将检出的分支切换到 <分支>，即将 HEAD 移动到指定的 <分支>
• -c 标志创建一个指定名称 <分支> 的新分支并切换到它，前提是该分支不存在

git tag

用法：git-sim tag <新标签名>

• 指定 <新标签名> 作为要模拟创建的新标签的名称
• 模拟输出将显示新创建的标签引用以及当前分支上最近的5次提交

视频动画示例

$ git-sim --animate reset HEAD^

https://user-images.githubusercontent.com/49353917/210943230-f38d879b-bb0d-4d42-a196-f24efb9e351a.mp4

$ git checkout main
$ git-sim --animate merge dev

https://user-images.githubusercontent.com/49353917/210943418-22c2cd11-be96-41bc-b621-7018eebc6bc0.mp4

$ git checkout dev
$ git-sim --animate rebase main

https://user-images.githubusercontent.com/49353917/210943815-4b8be2da-18da-4c42-927a-61cf9a22834e.mp4

$ git checkout main
$ git-sim --animate cherry-pick dev

https://user-images.githubusercontent.com/49353917/210944001-77bd0130-306b-40a8-ba0b-22e50172802b.mp4

基本命令示例

模拟git log命令的输出：

$ cd path/to/git/repo
$ git-sim log

模拟git status命令的输出：

$ git-sim status

模拟将文件添加到Git暂存区：

$ git-sim add filename.ext

模拟从Git暂存区恢复文件：

$ git-sim restore filename.ext

模拟基于当前暂存的更改创建新的提交：

$ git-sim commit -m "提交信息"

模拟将所有工作目录和暂存的更改存入贮藏：

$ git-sim stash

模拟创建新的Git分支：

$ git-sim branch new-branch-name

模拟创建新的Git标签：

$ git-sim tag new-tag-name

模拟将当前分支HEAD硬重置到上一次提交：

$ git-sim reset HEAD^ --hard

模拟撤销较早提交中的更改：

$ git-sim revert HEAD~7

模拟将一个分支合并到活动分支：

$ git-sim merge feature1

模拟将活动分支变基到新的基础上：

$ git-sim rebase main

模拟从另一个分支挑选提交到活动分支：

$ git-sim cherry-pick 0ae641

带有额外选项/标志的命令示例

使用浅色模式以白色背景和黑色文字显示，而不是默认的黑色背景和白色文字：

$ git-sim --light-mode status

将模拟输出制作成.mp4视频文件动画：

$ git-sim --animate add filename.ext

添加带有自定义文本和标志的开场和结束画面（必须包含--animate）：

$ git-sim --animate --show-intro --show-outro --outro-top-text="我的Git仓库" --outro-bottom-text="感谢观看！" --logo=path/to/logo.png status

自定义输出图像/视频目录位置：

$ git-sim --media-dir=path/to/output status

可选地，设置环境变量git_sim_media_dir来设置全局默认媒体目录，在未提供--media-dir时使用。模拟输出的图像/视频将被放置在此位置，位于以相应仓库名称命名的子文件夹中。

$ export git_sim_media_dir=path/to/media/directory
$ git-sim status

注意：--media-dir优先于环境变量。如果你设置了环境变量并仍然提供了参数，你会在--media-dir提供的路径中找到媒体文件。

生成低质量的输出视频以加快渲染时间（对于重复测试很有用，必须包含--animate）：

$ git-sim --animate --low-quality status

安装

有关安装manim和其他依赖项的详细信息，请参阅快速入门部分。然后运行：

$ pip3 install git-sim

Docker安装

1. 克隆git-sim仓库：

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

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

$ docker build -t git-sim .

3. 按如下方式运行git-sim命令：
   • Windows: docker run --rm -v %cd%:/usr/src/git-sim git-sim [全局选项] <子命令> [子命令选项]
   • MacOS / Linux: docker run --rm -v $(pwd):/usr/src/git-sim git-sim [全局选项] <子命令> [子命令选项]

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

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

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

了解更多

在git-sim项目页面上了解更多关于这个工具的信息。

作者

Jacob Stopak - 代表Initial Commit