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: [email protected]: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 # lib 的名字
path:
  dist: ./dist # 脚本生成的 dist 所存储的地址
  saveTo: ./node_modules # 依赖其他 lib 所生成的 dist 所存的路径
scripts:
  setup: yarn install --frozen-lockfile # 初始化脚本（可选）
  didSetup: if test -d ./node_modules; then echo "true"; else echo "false"; fi # 判定初始化是否成功（可选）
  buildDev: gjs build # 构造到 dist 的脚本
  buildProd: gjs prod # 构造到 dist 的脚本（以 release 模式）
  check: gjs check # 检查源代码是否合法的脚本（可选）
  test: gjs test # 测试脚本

dependencies: # 依赖的其他 lib，如果没有可以不写
  - /akko/akko-image # 绝对路径，表明 git repo 名为 akko，lib 名为 akko-image
  - ./akko-proxy # 相对路径，表明 git repo 和我所在的相同，lib 名为 akko-proxy
  - ../netless-logger/client # 相对路径，表明 git repo 为 netless-logger，lib 名为 client

之后在 git-repo 下任意路径执行如下命令。

gib

如果看到类似如下内容，而没有报错，说明配置文件没有问题。

name: akko
commit: add6f8b
workspace-commit: add6f8b(active)
dependencies: # 该 git repo 所依赖的其他 git repo
  - name: akko
    commit: dfc213a
    state: need-update
  - name: netless-logger
    commit: ac21a3b
    state: need-update
libs: # 该 git repo 下所有的 lib
  - 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: # 该 git repo 所依赖的其他 git repo
  - 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