fakegit v2 使用说明

在 VS Code 中使用的本地版本管理工具。

适用于无法使用 git 的办公终端：在不改变现有工作方式的前提下，为项目提供提交、 历史查看、差异对比与版本回退能力。全部数据保存在项目目录内，不上传、不联网。

• 当前版本：2.0.6
• 支持平台：Windows（VS Code 1.80 及以上）
• 安装方式：双击安装包，或安装 VSIX；使用安装包时无需安装 Node.js

一、适用场景

本工具面向以下情形：

• 办公终端部署了透明加密或 DLP，执行 git 命令时读取到的是密文，无法正常使用 git
• 需要在本地保留可回退的修改历史，但版本记录不应离开本机
• 希望沿用熟悉的操作方式：查看改动、选择性提交、对比差异、回退到某个版本

以下情形不在支持范围内：

• 多人协作、代码评审、远程仓库同步（本工具不提供推送与拉取）
• 与 git 仓库互相转换（两者格式不兼容，且此不兼容属于设计目标）

二、主要功能

三、安装

方式一：双击安装包（推荐）

1. 获取安装包 fakegit-installer.bat（由管理员或同事提供）
2. 双击安装包，等待窗口提示 Done
3. 回到 VS Code，按 Ctrl+R 重载窗口

安装过程不需要联网，也不需要管理员权限，扩展将装入当前用户的扩展目录。

若安全软件拦截脚本执行，可改用方式二；若提示未找到 VS Code， 按窗口给出的命令手动执行即可。

方式二：安装 VSIX 文件

1. 获取 local.fakegit-<版本>.vsix
2. 在 VS Code 中打开扩展面板，点击右上角 ... → 从 VSIX 安装
3. 选择该文件，安装完成后按 Ctrl+R 重载

验证安装

重载后应出现以下两项：

• 活动栏新增「本地版本 v2」图标
• 底部状态栏显示「未初始化」或分支名（默认 main）

如未出现，请先确认 VS Code 版本不低于 1.80，并尝试再次重载窗口。

四、五分钟上手

1. 打开项目文件夹 使用「文件 → 打开文件夹」，选择项目根目录。注意：需打开文件夹，打开单个文件无法使用。

2. 初始化版本库 点击活动栏「本地版本 v2」，在面板中点击「初始化版本库」。 项目根目录将生成 .fakegit 目录，这是版本库，请勿手工修改其中内容。

3. 修改并提交 正常编辑并保存文件。「源代码管理」面板会列出「更改」， 在顶部输入框填写说明后按 Ctrl+Enter 完成提交。

4. 查看历史 在「版本历史」中可看到刚才的提交，展开后可查看本次修改了哪些文件。

提交说明建议写明修改原因，例如「修复登录跳转时令牌丢失」， 其可读性优于「修改 login.js」。

五、日常操作

两点注意事项：

• 恢复操作会覆盖工作区内容，未保存的编辑会丢失，建议先查看差异再执行
• 「更改」与「已暂存」的对比基准不同：前者比较暂存区与工作区，后者比较上次提交与暂存区

六、界面说明

活动栏「本地版本 v2」      版本历史，每个提交可展开
源代码管理面板
├─ 已暂存                  提交时只包含这一组
└─ 更改                    尚未暂存的修改
状态栏                     显示改动数量与分支名，点击可跳转

界面分为两组的原因：已暂存 中的内容会被本次提交带走，更改 中的内容不会。 需要选择性提交时，先将文件暂存，再提交。

七、命令行（可选）

日常使用无需命令行。如需在终端操作或编写脚本，可使用固定入口：

"%LOCALAPPDATA%\fakegit\bin\fakegit.cmd" status

常用命令：

fakegit status                 查看当前改动
fakegit commit "修复登录跳转"   提交（存在暂存内容时仅提交暂存部分）
fakegit log 20                 查看最近 20 条提交
fakegit show HEAD~1 src/a.js   查看上一版本中的文件内容
fakegit restore HEAD~1 src/a.js 将文件恢复到上一版本
fakegit ping                   检查命令行是否可用

使用前提：VS Code 已打开该项目（服务随扩展启动，无需手动开启）。 若提示找不到命令，执行命令面板中的 fakegit: 安装/修复命令行入口。

八、常用设置

在 VS Code 设置中检索 fakegit。

九、数据、备份与迁移

版本库位于项目根目录下的 .fakegit 目录，包含全部历史记录。

• 备份：复制 .fakegit 目录即可
• 迁移：复制整个项目目录，历史随之迁移
• 占用空间：随提交次数增长，可在资源管理器中查看目录大小

注意事项：

• 请勿将 .fakegit 提交到其它 git 仓库，否则历史会被当作普通文件上传
• 请勿手动删除 .fakegit/objects 目录，该操作等同于删除全部历史
• .fakegit 中的内容为压缩存储而非加密，涉及高敏感信息时请遵循单位规定

十、隐私与安全

• 不联网：扩展不发起任何网络请求，不上传文件、提交记录或使用数据，也不包含遥测
• 本机服务：命令行功能依赖一个仅监听 127.0.0.1 的本地服务，每次启动生成随机令牌； 服务只接受携带该令牌的请求，令牌文件位于 .fakegit/rpc-token
• 写入范围：除项目内的 .fakegit 目录外，仅会在 %LOCALAPPDATA%\fakegit\bin 写入一个用于命令行的转发脚本；不修改系统目录与注册表
• 数据可带走：全部历史保存在项目目录内，复制该目录即可完整迁移或删除
• 明文提示：版本库为压缩存储而非加密，涉及高敏感信息时请遵循单位的数据管理规定

十一、常见问题

图标没有出现，或面板为空

按 Ctrl+R 重载窗口；确认 VS Code 版本不低于 1.80；确认打开的是文件夹而非单个文件。

提示「没有版本库」

在面板中点击「初始化版本库」。若已初始化仍提示，请确认当前打开的是同一项目目录。

提交后历史中没有记录

打开日志（Ctrl+Shift+U → 选择 fakegit）查看是否有报错信息。

界面刷新较慢

项目文件较多时首次扫描较慢，属正常现象。将 node_modules/、dist/、build/ 等目录加入 .gitignore 可显著改善后续速度。

恢复文件后内容没有变化

界面会提示「恢复没有生效」，通常由加密或防泄密软件拦截写入导致。 可执行命令面板中的 fakegit: 诊断：本机能否读到明文，查看「写入能力」一项。

终端命令无法连接

确认 VS Code 已打开该项目；执行 fakegit ping 查看实际连接的目录与端口； 必要时在命令面板执行 fakegit: 启动本地命令服务。

能否与 git 同时使用

两者可安装在同一项目中，但互不读取对方的数据。本工具不提供导出为 git 的功能， 亦不支持推送。

换电脑后历史还在吗

历史保存在项目目录内，复制整个项目即可带走；单独复制源码文件不包含历史。

卸载后历史会删除吗

不会。卸载扩展不影响 .fakegit 目录，如不再需要可手动删除。

十二、卸载

• 在 VS Code 扩展面板中找到「fakegit v2」，选择卸载，随后按 Ctrl+R 重载
• 若使用脚本安装，也可执行 node install.js --uninstall
• 项目中的 .fakegit 目录不会自动删除，需手动移除

十三、获取帮助

遇到问题时，建议按以下顺序排查：

1. 查看日志：按 Ctrl+Shift+U 打开输出面板，选择 fakegit
2. 执行诊断：命令面板（Ctrl+Shift+P）→ fakegit: 诊断：本机能否读到明文， 可判断问题属于环境拦截还是功能异常
3. 查看帮助：命令面板 → fakegit: 帮助：命令在哪敲 / 日志在哪看， 会输出命令入口、命令行路径与当前服务状态
4. 查阅版本变更：扩展详情页的「变更记录」标签（即 CHANGELOG.md）

反馈问题时，请附上日志中的报错文本与诊断结果，以便快速定位。