git-bridge
git-bridge 基于 git,用于管理跨 git repo 的多项目之间的依赖关系。它将项目拆分成 lib(一个 git repo 可以存储多个 lib),通过配置文件,规定 lib 依赖其他哪些 lib。根据定义,lib 可以通过配置项中的脚本生成 dist 文件,这部分文件又能被其他依赖它的 lib 拿到。
lib 是一个封闭的文件夹,它透过 git-bridge 拿到依赖 lib 生成的 dist 文件。至于如何拿到 dist,这取决于 git-bridge 的机制。这可能来自 CI 构造并上传到 remote,并在 lib 需要时从 remote 端下载到本地。也可能通过脚本在本地现场构造一个出来。
在本机安装与配置
使用如下命令,在本机安装 git-bridge。
npm install -g git-bridge
之后,使用如下命令登录远端。
gib login --ak XXXXXX \
--sk XXXXXX \
--region XXXXXX \
--bucket XXXXXX \
--namespace XXXXX \
具体配置内容请向管理员申请。
在 git repo 中配置
在 git repo 的 .gitignore
文件中添加如下内容。如果该文件不存在就创建。
.gib
.gib_stage
并在根目录下创建 gib_repo.yaml
文件。
defaultGitRepoPath: git@github.com:netless-io
scripts:
setup: yarn install --frozen-lockfile
didSetup: if test -d ./node_modules; then echo "true"; else echo "false"; fi
其中,defaultGitRepoPath
定义了其依赖 lib 所在的 git repo 从何获取。
scripts
是脚本,其中 setup
定义了如何初始化这个 git repo,didSetup
用于判定当前 git repo 是否需要初始化。
之后,需要定义 lib 文件夹。注意,lib 文件夹必须在 git repo 的次一级文件夹或就是根文件夹。文件夹的名字和 lib 的名字不一定要完全一致。在 lib 文件夹下创建 gib_lib.yaml
文件,并输入如下内容。
name: my-first-lib
path:
dist: ./dist
saveTo: ./node_modules
scripts:
setup: yarn install --frozen-lockfile
didSetup: if test -d ./node_modules; then echo "true"; else echo "false"; fi
buildDev: gjs build
buildProd: gjs prod
check: gjs check
test: gjs test
dependencies:
- /akko/akko-image
- ./akko-proxy
- ../netless-logger/client
之后在 git-repo 下任意路径执行如下命令。
gib
如果看到类似如下内容,而没有报错,说明配置文件没有问题。
name: akko
commit: add6f8b
workspace-commit: add6f8b(active)
dependencies:
- name: akko
commit: dfc213a
state: need-update
- name: netless-logger
commit: ac21a3b
state: need-update
libs:
- name: akko-proxy
on-stage-count: 0
did-setup: true
did-build-dev: true
did-build-prod: true
- name: akko-image
on-stage-count: 0
did-setup: true
did-build-dev: true
did-build-prod: true
单 lib 开发命令
如果修改的代码仅限于一个 lib,那这便是最简单的一种依赖模式。首先,你需要 cd
到你要开发的 lib 所在的文件夹,然后执行如下命令。
gib setup
这个命令会,先确定 git repo 是否已经初始化,如果没有,则初始化;然后,它会确定 lib 是否需要初始化,如果没有,则调用你配置的脚本初始化;随后,找到 lib 所定义的依赖的 dist 文件,并将它们安装到 saveTo
所指示的文件夹中。
你可以通过如下命令构造代码。
gib build
该命令会确定是否需要先调用 gib setup
初始化,然后,调用你配置的脚本构造源代码。脚本应该将目标代码生成到 dist/dev
文件夹中。
你也可以通过如下代码构造 release 级别的代码。
gib build -m prod
该命令会调用你配置的脚本。脚本应该将目标代码生成到 dist/prod
文件夹中。
你也可以通过在配置中添加 test
脚本来定义测试用例。之后,你便可以调用如下命令来跑测试用例。
gib test
该命令会先执行 gib build
构造目标文件到 dist/dev
,在执行 test
中的脚本。
在开发完成后,你可以提一个 PR,在 PR 合并之前,CI 应该执行如下命令一确定该 PR 是否能合并。
gib snapshot --disable-release
该命令会对每一个 lib 执行如下操作。
- 初始化,等效于
gib setup
- 检查源代码是否符合规范,等效于
gib check
- 以 release 模式构造,等效于
gib build -m prod
- 跑测试用例,等效于
gib test
这些操作有些可选的(如果你没有配置脚本),任何一个步骤失败,都会导致整个命令失败,从而导致 CI 不通过。
如果 CI 通过,合并 PR,会触发领一个 CI,该 CI 会执行如下命令。
gib snapshot
该命令会先执行 gib snapshot --disable-release
的操作,如果操作都通过了,会将这次构造的 dist 文件内容全部上传到 remote,并和这次 git commit 记录关联起来。之后,其他人可以通过 git commit 获取这次构造的 dist 内容到本地。
跨 git repo 的单 lib 开发命令
如果某些 lib 依赖了其他 git repo 的 lib,则其他 git repo 会被视为该 git repo 的依赖。使用如下命令。
gib
可以查看当前 git repo 所依赖的其他 git repo,例如。
name: akko
commit: add6f8b
workspace-commit: add6f8b(active)
dependencies:
- name: akko
commit: dfc213a
state: need-update
- name: netless-logger
commit: ac21a3b
state: need-update
注意,你依赖的是某个 git repo 的特定 commit。如果该 git repo 更新,你可能需要修改依赖的 commit 记录以追随更新。
例如,netless-logger
更新到了 231af2
这个 commit,你可以通过如下命令更新它。
gib commit --#netless-logger 231af2
注意,其中 #
是必须的,以和其他 options 的 key 区分。
如果目标 git repo 刚好被 clone
在本地,你可以将它执行 git pull origin master
更新到最新后,直接在依赖它的 git repo 下执行如下命令。
gib commit --auto
来自动更新。
无论你用哪一种更新方式,该命令都会修改本地的 gib_repo_lock.yaml
文件(没有的话会自动生成)。该文件应该被提交到 git,以保证 CI 或其他开发者拿到正确的依赖版本。
特别的,当更新了 ``commit` 之后,依赖关系可能发生变化。你可以在 lib 中执行如下命令重新下载 dist 文件。
gib sync
跨 lib 开发命令
每一个 lib 都有一个 stage
的概念,你可以把它依赖的其他 lib 添加到 stage
中。一旦依赖被添加到 stage
中,该依赖就不会从 remote 端安装,而是通过本地构造。
gib stage-add --libs akko-image --libs akko-proxy
以上命令将 akko-image
、akko-proxy
这两个依赖添加到了 stage
。你可以执行如下命令来查看 stage
的状态。
gib stage
预期输出如下。
stage state of /akko/akko-magix:
found libs on stage
/akko/akko-image dependency=true
/akko/akko-proxy dependency=true
found depdency libs outof stage
/akko/akko-fetcher md5=97b2138bd899dc5d8881822cb6ed6871
在添加的过程中,git-bridge 会构造这两个 lib,并将 dist 内容覆盖到 saveTo
中。如果你修改了依赖库的源代码,还可以直接执行如下命令重新构造,并重新安装。
gib stage-build --libs akko-proxy
这样,依赖 lib akko-proxy
就被重新构造并重新安装。当然你也可以用如下命令简单地把 stage
上的所有依赖 lib 全部重新构造。
gib stage-build
你还可以执行如下命令,仅仅重装,但不执行依赖 lib 的构造脚本。
gib stage-sync --libs akko-proxy
该命令也有针对 stage
上所有依赖 lib 的版本。
gib stage-sync
在跨 lib 开发完毕后,你可以通过如下命令把他们从 stage
上移除。
gib stage-remove --libs akko-proxy --libs akko-image
或者,你也可以通过如下命令清空整个 stage
。
gib stage-remove
之后,执行如下命令。
gib stage
可以看到 stage
已经清空了。
stage state of /akko/akko-magix:
found libs on stage
none
found depdency libs outof stage
/akko/akko-image md5=c2d0a195637eef423be32e2a76e1e812
/akko/akko-proxy md5=d92c722068d6d9a84fa9469a77df421c
/akko/akko-fetcher md5=97b2138bd899dc5d8881822cb6ed6871