配置说明

repostack.yaml 是 stack 的声明文件，描述当前开发目录包含哪些 repo 以及它们的分组方式。

最小示例

version: 1

settings:
  shell: zsh
  concurrency: 4
  continueOnError: false

repos:
  - name: foo
    path: foo
    source: git@github.com:example-org/foo.git
    branch: main
    tags: [runtime, core]

views:
  runtime:
    tags: [runtime]

commands: {}

顶层字段

version

当前固定为 1，用于配置格式的版本控制。

settings

全局设置项：

Shell 配置

shell 支持三种配置方式：

1. 不设置（推荐）

自动根据操作系统选择：

• 有 SHELL 环境变量 → 使用环境变量的值
• Windows → cmd.exe
• macOS/Linux → bash

2. 字符串（统一 shell）

所有操作系统使用相同的 shell：

settings:
  shell: /bin/zsh

3. 对象（按操作系统配置）

为不同操作系统指定不同的 shell：

settings:
  shell:
    windows: cmd.exe
    macos: /bin/zsh
    linux: /bin/bash

支持的平台键：

• windows - Windows
• macos - macOS
• linux - Linux

回退规则：

• 如果当前平台未配置，会尝试其他平台的配置
• macOS 会回退到 linux 的配置
• Linux 会回退到 macos 的配置
• 如果都未配置，使用系统自动检测的值

适用场景：

• 团队使用不同操作系统，需要各自配置
• 某些 shell 在特定平台上不可用（如 zsh 在 Windows 上）

repos

Repo 条目数组，每个 repo 包含以下字段：

字段详解

name

• 在 stack 内唯一标识这个 repo
• 用于 repostack remove <name>、-view 等命令中引用
• 建议使用简短、有意义的名称

path

• 相对于 repostack.yaml 所在目录的路径
• 可以嵌套（如 packages/foo）
• 如果 repo 就在当前目录，使用 .

source

• 远程 Git 仓库地址，支持任何 git clone 接受的格式
• 示例：git@github.com:user/repo.git、https://github.com/user/repo.git
• 仅用于 pull 命令，已存在的本地 repo 不会用到

branch

• 当前开发使用的分支（如 main、develop）
• pull 时会 clone 并 checkout 到这个分支
• sync 时，如果 lock 文件有记录，会切换到 lock 中的 revision（但仍属于这个分支的历史）
• 如果团队在不同分支上开发（如 feature/v2），可以配置为对应分支

tags

• 给 repo 打的分类标签（非 Git 的 tag，只是配置中的标记）
• 一个 repo 可以有多个 tags，用于 views 定义和 run --tags 过滤
• tags 是任意的字符串，建议有统一约定（如 runtime、frontend、tooling）
• 注意：这与 git tag 无关，不会影响仓库的 Git 标签

完整示例

repos:
  # 核心运行时库
  - name: foo
    path: packages/foo
    source: git@github.com:example-org/foo.git
    branch: main
    tags: [runtime, core]
    
  # 服务端框架
  - name: bar
    path: packages/bar
    source: git@github.com:example-org/bar.git
    branch: main
    tags: [runtime, server]
    
  # 内部工具（只有 tooling 标签）
  - name: baz
    path: tools/baz
    source: git@github.com:example-org/baz.git
    branch: master
    tags: [tooling]
    
  # 当前目录的 repo
  - name: qux
    path: .
    source: git@github.com:example-org/qux.git
    branch: main
    tags: [docs]

views

命名视图，用于定义 repo 子集的快捷方式。支持以下过滤方式：

示例：

views:
  # 按标签筛选：所有 runtime 相关的 repo
  runtime:
    tags: [runtime]
  
  # 按标签组合：同时有 runtime 和 server 标签的 repo
  server:
    tags: [runtime, server]
  
  # 指定具体 repos
  publishing:
    repos: [baz, bar]
  
  # 混合使用：先按标签筛选，再指定具体 repos
  release:
    repos: [foo, bar]
    tags: [core]

使用场景：

• 避免在命令中重复列出长串 repo 名
• 团队协作时统一操作范围
• CI/CD 配置中稳定引用

commands

预留的命令别名配置，当前版本保留结构但暂未实现执行能力。建议保留为空对象：

commands: {}

相关文件

• Lock 文件 - 了解 repostack.lock.yaml 的工作原理

Tags vs Views 对比

简单记忆：

• Tags = "这是什么类型的 repo"（分类）
• Views = "这次要操作哪些 repo"（快捷选择）