Package: trident-sync
🔱 trident-sync 三叉戟同步三叉戟同步，是一款异构项目同步升级工具，二次开发同步神器。中文1. 简介当我们的项目内部使用了其他项目进行二次开发，那么这个模块就只能停留在当时的版本，无法方便的更新。本工具可以自动获取变更并合并到你的项目仓库，让二次开发项目可以持续升级。本工具适用于所有二次开发需要同步更新的场景：直接copy源项目进行二次开发。源项目与你项目目录结构不一致（异构）。源项目本身的submodule过多，一个个fork、merge太麻烦。源项目只是你项目的一个子模块，但你不想用submodule2. 缘起我有一个certd项目，这是一个自动更新ssl证书的工具，但这不是重点。重点是它一开始只是一个独立的命令行工具。目录结构如下：src
| --packages
    | --core           
    | --plugins某一天我想开发v2版本，把它升级成一个带后台和界面的web项目。恰好我找到了两个模版项目(其实也是我写的🤭),可以帮我快速实现以上需求。fs-admin-antdv（前端admin模版）fs-server-js（服务端）我把这两个项目复制到了certd项目中，进行二次开发。此时certd项目目录结构变成如下：src
| --packages
    | --core
    | --plugins
    | --ui
        | --certd-client   //这是fs-admin-antdv的副本
        | --certd-server   //这是fs-server-js的副本为了使certd-client和certd-server能够随时同步模版项目的更新我将使用本项目trident-sync来自动帮我升级。像不像个三叉戟🔱？3. 原理过程初始化（init）：初始化同步工作仓库（sync_work_repo）clone源仓库（src_repo）和目标仓库（target_repo），添加到同步工作仓库的submodule给目标仓库创建并切换到同步分支（sync_branch）将源仓库内的文件复制到目标仓库对应的目录，然后commit、push此时目标仓库内的sync_branch分支拥有源仓库的副本同步（sync）：当源仓库有变更时、拉取源仓库更新删除目标仓库对应的目录，复制源仓库所有文件到目标仓库对应的目录此时git add . && git commit提交的就是源仓库变更部分至此我们成功将源仓库的更新转化成了目标仓库的commit，后续就是常规的合并操作了。创建target.sync_branch->target.main的PR处理PR，合并到开发主分支，升级完成同步流程图没有冲突的话，同步过程可以全部自动化。解决冲突是唯一需要手动的部分。4. 快速开始4.1 准备工作安装python (3.8+)安装git准备你的项目和要同步的源项目4.2 安装本工具# 安装本工具，安装成功后就可以使用 trident 命令了pipinstalltrident-sync--upgrade4.3 编写配置文件创建一个同步工作目录，你可以任意命名，接下来都在这个目录下进行操作mkdir sync_work_repo
cd sync_work_repo编写./sync_work_repo/sync.yaml， 下面是示例，请根据其中注释说明改成你自己的内容# ./sync_work_repo/sync.yamlrepo:# 仓库列表，可以配置多个仓库fs-admin:# 上游项目1，可以任意命名url:"https://github.com/fast-crud/fs-admin-antdv"# 源仓库地址path:"fs-admin-antdv"# submodule保存路径，一般配置仓库名称即可branch:"main"# 要同步过来的分支certd:# 你的项目（接受同步项目），可以任意命名url:"https://github.com/certd/certd"# 目标仓库地址path:"certd"# submodule保存路径，一般配置仓库名称即可branch:"dev"# 你的代码开发主分支（接受合并的分支）例如dev、main、v1、v2等# 以下配置与PR相关，更多关于PR的文档请前往 https://github.com/handsfree-work/trident-sync/tree/main/doc/pr.md# 第一次使用，你可以暂时不配置，同步完之后需要手动操作合并token:""# 仓库的token，用于提交PRtype:github# 仓库类型，用于提交PR，可选项：[github/gitee/gitea]auto_merge:true# 是否自动合并,如果有冲突则需要手动处理# 注意： 初始化之后，不要修改url和path，以免出现意外。但是可以添加新的repo.sync:# 同步配置，可以配置多个同步任务client:# 同步任务1，可以任意命名src:# 源仓库repo:fs-admin# 源仓库名称，上面repo配置的仓库引用dir:'.'# 要同步给target的目录（不能为空目录）target:#接受合并的仓库，就是你的项目repo:certd# 目标仓库名称，上面repo配置的仓库引用dir:'package/ui/certd-client'# 接收src同步过来的目录# ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑    如果你之前已经使用源仓库副本做了一部分特性开发，那么这里配置源仓库副本的目录）branch:'client_sync'# 同步分支名称（需要配置一个未被占用的分支名称）options:#其他选项repo_root:repo# submodule保存根目录push:false# 同步后是否push# ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑  第一次使用，先本地测试，不push，没问题之后再改成truepull_request:true# 是否创建pull request，需要目标仓库配置token和typeproxy_fix:true# 是否将https代理改成http://开头，解决python开启代理时无法发出https请求的问题use_system_proxy:true# 是否使用系统代理4.4 初始化此命令会将sync_work_repo目录初始化成一个git仓库，然后将sync.yaml中配置的repo添加为submodulecdsync_work_repo# 执行初始化操作tridentinit初始化执行效果只需运行一次即可，除非你添加了新的repo初始化过程会将多个仓库添加为submodule，此步骤在网络不好时容易出问题你可以删除目录下除sync.yaml之外的所有文件，重新运行trident init命令4.5 进行同步将根据sync.yaml中sync配置的同步任务进行同步更新，并提交PR，你需要视情况处理PR# 以后你只需要定时运行这个命令，即可保持同步升级tridentsync运行效果root:~/sync_work_repo$ trident sync 
.
.
.
2023-01-28 14:13:41 | INFO    | - refs:[<git.Head "refs/heads/main">]
2023-01-28 14:13:41 | WARNING | - Skip push，The remote address is not set for the current repository. Use the [trident remote <repo_url>] command to set the remote address of the repository and save the synchronization progress
2023-01-28 14:13:41 | INFO    | - ----------------result:✅----------------
 🏹 task            -->  success:✅     copy:✅   change:✅   commit:✅     push:✅       pr:✅    merge:✅
 🔱 sync_work_repo  -->   change:✅   commit:✅     push:🚫 
2023-01-28 14:13:41 | INFO    | - ----------------sync end----------------注意：不要在同步分支内写你自己的任何代码（示例配置中为client_sync分支）4.6 [可选] 保存 sync_work_repo将sync_work_repopush到远程服务器，防止更换电脑丢失同步进度。后续你只需要clonesync_work_repo，然后直接运行trident sync即可继续同步# 给同步仓库设置远程地址，并pushtridentremote--url=<sync_work_repo_git_url># 或者运行如下命令，一样的gitremoteaddorigin<sync_work_repo_git_url>gitpush注意：sync_work_repo_git_url应该是一个新的空的远程仓库如果不是空的，可以加-f选项强制push（sync_work_repo原有的内容会被覆盖）。4.7 [可选] 定时运行你可以将<sync_work_repo>这个远程仓库和trident sync命令配置到任何CI/DI工具（例如jenkins、github
action、drone等）自动定时同步5 合并分支源仓库如果有更新，那么同步完之后，将会有三种情况：启用了PR：如何启用PR？无冲突：自动创建PR，然后自动合并，你无需任何操作有冲突：自动创建PR，然后需要手动处理PR未启用PR：你需要手动合并启用PR要启用PR，你需要如下配置repo:target:token:xxxx# 创建PR的tokentype:github# upstream类型，支持[ github | gitee | gitea ]auto_merge:true# 是否自动合并token如何获取？处理PR当PR有冲突时，就需要手动处理冲突，才能合并进入主分支其中githubgitee支持在web页面直接手动解决冲突gitea需要线下解决，此时你仍然需要手动合并手动合并一般出现冲突了，都建议在IDE上手动进行合并关闭PR（没有PR的话，请无视）本地更新所有分支通过IDE进行分支merge操作（rebase也行，用你平常熟悉的合并分支操作）target:<sync_branch> -------->  target:<main_branch>
    同步分支            merge         开发主分支避免冲突建议我们应该尽量避免冲突，请实际开发中遵循以下原则：尽量不删除、不移动源项目的目录和文件（否则容易造成意想不到的难以解决的冲突）尽量少在源项目的文件上进行修改（可以改，但尽量少）新功能和新特性应该写在自己建立的新目录和新文件中总结就是六个字： 不删、少改、多加。6. 自动化6.1 GitHub ActionsGitHub Actions 可以免费的帮你进行自动化同步操作请参考certd 自动化同步示例