# 概览

> 

`repostack` 是一个面向多仓开发目录的视图编排工具。

它不把多个独立仓库合并成真正的 monorepo，而是在保留 multirepo 发布边界的前提下，为日常开发提供更接近 monorepo 的工作体验。

## 它解决什么问题

当一个开发目录里并排放着多个 Git 仓库时，常见痛点包括：

- 不知道当前 stack 里到底纳入了哪些 repo
- 缺失 repo 需要手动 clone
- 相同命令需要反复进入不同目录执行
- 很难记录"这一组 repo 当前分别停在哪个 revision"

`repostack` 的第一版就是为这些问题服务的。

## 核心概念

### Stack

一个受 `repostack` 管理的开发目录。包含：

- `repostack.yaml` - 声明文件（哪些 repo、如何分组）
- `repostack.lock.yaml` - 锁定文件（精确的 Git 状态）
- 一组并排放置的 Git 仓库

### Repo Entry

纳入 stack 的每个仓库，在配置中称为一个 entry：

- 有名称、本地路径、远程地址
- 可以有多个标签（tags）
- 可以被多个视图（views）引用

### Views & Tags

**Tags** - 给 repo 打分类标签：

```yaml
repos:
  - name: foo
    tags: [runtime, core]
```

**Views** - 预定义的选择规则：

```yaml
views:
  runtime:
    tags: [runtime]  # 选择所有 runtime 标签的 repo
```

区别：

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

## 当前版本可以做什么

- 声明一个 stack 中包含哪些 repo（`use` / `remove`）
- 下载和同步缺失 repo（`pull` / `sync`）
- 列出各 repo 当前的 branch、revision 和 dirty 状态（`list`）
- 在多个 repo 中批量执行 shell 命令（`run`）
- 将当前 stack 的 Git 状态写入 `repostack.lock.yaml`（`snapshot`）
- 多用户配置支持，团队协作更灵活（`users` / `whoami`）
- 诊断 stack 健康状况（`doctor`）

## 快速示例

```bash
# 初始化 stack
repostack init

# 添加 repo（会自动 snapshot）
repostack use foo --yes
repostack use bar --yes

# 批量执行命令
repostack run --view runtime -- pnpm test

# 查看状态
repostack list

# 记录当前状态到 lock 文件
repostack snapshot

# 提交 stack 配置到版本控制
git add repostack.yaml repostack.lock.yaml
git commit -m "update stack"
```

## 推荐阅读顺序

<steps level="4">

#### 先看 [快速开始](/guide/quick-start) - 5 分钟上手



#### 再看 [配置说明](/guide/config) - 了解 `repostack.yaml` 完整格式



#### 了解 [Lock 文件](/guide/lock-file) - 版本锁定的核心机制



#### 如果要理解快照语义，再看 [Snapshot 与 Sync](/guide/snapshot-and-sync)



#### **重要**：理解 [Stack Root 作为 Git 仓库](/guide/stack-root-git) - 时间旅行的基础



#### 需要查命令时，去看 [CLI 总览](/cli) 和 [命令参考](/cli#%E5%BD%93%E5%89%8D%E5%91%BD%E4%BB%A4%E5%88%97%E8%A1%A8)



</steps>