# 配置说明

> 

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

## 最小示例

```yaml
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`           | string \| object | 自动检测    | `run` 命令使用的 shell，支持按操作系统配置 |
| `concurrency`     | number           | `4`     | `run` 命令并发执行的 repo 数量       |
| `continueOnError` | boolean          | `false` | 某个 repo 执行失败后是否继续执行其他 repo  |

#### Shell 配置

`shell` 支持三种配置方式：

**1. 不设置（推荐）**

自动根据操作系统选择：

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

**2. 字符串（统一 shell）**

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

```yaml
settings:
  shell: /bin/zsh
```

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

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

```yaml
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`   | string              | ✅   | Repo 名称，在 stack 内唯一，用于命令中引用    |
| `path`   | string              | ✅   | 相对 stack root 的本地路径            |
| `source` | string              | ✅   | 远程 Git 地址，用于 `pull` 克隆         |
| `branch` | string              | ✅   | 当前开发使用的分支（如 `main`），`pull` 时检出 |
| `tags`   | string<span></span> | -   | 分类标签数组（非 Git tag），用于分组和过滤      |

#### 字段详解

**`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 标签

#### 完整示例

```yaml
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 子集的快捷方式。支持以下过滤方式：

| 字段      | 类型                  | 说明                    |
| ------- | ------------------- | --------------------- |
| `repos` | string<span></span> | 指定具体的 repo 名称列表       |
| `tags`  | string<span></span> | 指定标签，匹配包含所有指定标签的 repo |

示例：

```yaml
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`

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

```yaml
commands: {}
```

## 相关文件

- [Lock 文件](./lock-file) - 了解 `repostack.lock.yaml` 的工作原理

## Tags vs Views 对比

| 特性       | Tags                | Views               |
| -------- | ------------------- | ------------------- |
| **作用**   | 给 repo 打分类标签        | 预定义 repo 选择规则       |
| **定义位置** | 在 repo entry 上      | 在 `views` 段独立定义     |
| **使用方式** | `run --tags <tags>` | `run --view <name>` |
| **灵活性**  | 动态组合（交集过滤）          | 固定规则（可复用）           |
| **适用场景** | 临时筛选                | 常用操作快捷方式            |

**简单记忆**：

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