Template Sync

Template Sync 是一个强大的 Git 历史重建工具。专门用于解决**“由模板创建的项目”与上游模板仓库之间丢失 Git 共同历史**的痛点。

它能够将完全独立的代码拷贝精准物化为有血缘关系的 Git 分支，让您从此告别枯燥且易错的“手工比对复制”，能够优雅地使用标准 git merge 或 git rebase 命令来合并上游模板的最新更新。

核心原理

Template Sync 采用安全、无损、零侵入的分析策略：

1. Tree Hash 精准比对 (寻根与对齐)： 分析项目起点 commit 的文件树 (Tree Hash)，并与模板分支历史中的 commit 节点进行自动比对，智能定位出最精确匹配的模板版本作为基准。
2. Parent 拓扑重构 (重写历史)： 保留模板历史中的提交信息、作者、时间线与分支拓扑结构，动态将 parent 指针重写并指向您的项目起点，完美创建无缝衔接的衍生分支。
3. 安全无损零改动： 重构过程只进行读取和生成操作，绝对不会改写项目现有的分支或历史记录。最终只会为您在本地生成一个独立的新分支，具体的合并或变基完全交由开发者自行控制。

使用场景

日常开发中，我们往往通过下载压缩包或拷贝代码来初始化项目。几个月后，上游模板发布了重大更新（修复了致命 Bug，或推出了新特性）。

由于您的项目脱离了模板的 Git 历史，传统的升级方式极其痛苦：您必须手工逐个比对文件，小心翼翼地把更新内容复制粘贴过来。

Template Sync 就是为了解决这个痛点而生：它可以为您找回丢失的 Git 历史，重新建立血缘关系。

技术栈与运行模式

本项目是一个全栈 TypeScript 应用程序。为了适应不同用户习惯，系统支持多端运行：

• 命令行模式 (CLI)：提供高效的终端命令行工具，支持全局配置默认模板仓库、一键极速同步与交互式向导模式。
• 桌面模式 (Electron)：编译为独立的桌面应用程序，提供更原生的本地文件系统访问体验。

命令行工具 (CLI)

常用命令与配置

# 1. 首次使用：设置全局默认模板仓库路径（及可选默认分支）
lsby-template-sync set-template /path/to/template-repo [分支名]

# 2. 查看当前全局配置
lsby-template-sync config

# 3. 日常使用：在基于该模板的项目目录下直接一键同步
cd /path/to/project-repo
lsby-template-sync

# 4. 一键同步并自动合并到当前分支
lsby-template-sync --merge

命令行选项

lsby-template-sync [项目路径] [模板路径] [选项]

| 选项 | 简写 | 说明 | | ------------------- | ---- | ---------------------------------------------------- | | --project <路径> | -p | 项目仓库路径 (默认: 当前工作目录) | | --template <路径> | -t | 模板仓库路径 (覆盖全局默认配置) | | --branch <分支名> | -b | 模板分支名称 (默认自动检测 main / master) | | --output <分支名> | -o | 输出分支名称 (默认: template-sync/YYYYMMDD-HHMMSS) | | --merge | -m | 嫁接创建完成后直接执行 git merge | | --analyze-only | | 仅执行仓库比对分析，不创建分支 | | --yes | -y | 跳过确认提示直接创建分支 | | --interactive | -i | 强制启用交互式向导模式 | | --version | -v | 显示版本号 | | --help | -h | 显示帮助信息 |

注意事项

• 界面与命令行默认会生成带有时间戳的安全分支名称（如 template-sync/20260731-120000）。您可以自定义名称，系统会保证不会覆盖已存在的同名分支。
• 由于 parent 提交被改写，重建后衍生分支上的所有 commit hash 均会改变，且原有的 GPG 签名将无法保留。
• 本工具旨在生成一条规范的分支供您合入，实际的合并(Merge)和代码冲突解决仍使用您最熟悉的标准 Git 工作流进行。