# repostack use <path>

> 

将本地 repo 纳入当前 stack 管理。

```bash
repostack use <path> [options]
```

## 参数

| 参数     | 说明                               |
| ------ | -------------------------------- |
| `path` | Repo 的本地路径（相对或绝对，相对于 stack root） |

## 选项

| 选项      | 简写   | 说明                      |
| ------- | ---- | ----------------------- |
| `--yes` | `-y` | 跳过所有确认提示，自动创建目录和初始化 git |

## 执行流程

<steps level="4">

#### **用户校验**- 如果 `repostack.yaml` 中定义了 `users`，会强制要求 `.repostackrc` 存在且指向有效用户，否则抛出错误。





#### **读取基础配置**- 加载 `repostack.yaml`（不合并用户覆盖配置，因为接下来要修改并写回）。





#### **路径解析与检查**- 将 `path` 解析为相对于 stack root 的完整路径。
- 如果路径**不存在**：

  - `--yes` 模式：静默创建目录。
  - 非 `--yes` 模式：弹出 `confirm` 提示 `Path "..." does not exist. Create it?`，默认 **否**；拒绝则中断命令。





#### **Git 仓库检查**- 如果目标路径**不是** Git 仓库：

  - `--yes` 模式：自动执行 `git init`。
  - 非 `--yes` 模式：弹出 `confirm` 提示 `"..." is not a git repository. Initialize it?`，默认 **是**；拒绝则中断命令。





#### **确认添加到 stack**- 非 `--yes` 模式：弹出 `confirm` 提示 `Add "..." to repostack?`，默认 **是**；拒绝则中断命令。





#### **更新配置**- 生成新配置：

  - `name` 取自路径的最后一级目录名。
  - `source` 默认为该路径本身。
  - `branch` 默认为 `"main"`。
  - 若 `name` 或 `path` 已存在于 `repostack.yaml` 中，抛出 `Repo already registered: ...`。
- 将新配置写回 `repostack.yaml`。





#### **自动生成 lock 文件**- 读取各 repo 当前 Git 状态并覆盖写入 `repostack.lock.yaml`。





#### **更新 `.gitignore`**- 确保 `.gitignore` 包含 `.repostackrc`。





</steps>

## 涉及文件

| 文件                    | 操作           |
| --------------------- | ------------ |
| `repostack.yaml`      | 读取 / 写入      |
| `.repostackrc`        | 读取（用户校验）     |
| `repostack.lock.yaml` | 写入（覆盖）       |
| `.gitignore`          | 读取 / 追加 / 创建 |

## Git 操作

- `git rev-parse --show-toplevel`（检测是否为仓库）
- `git init`（如路径不是仓库且用户同意 / `--yes`）
- `git rev-parse --abbrev-ref HEAD` 和 `git rev-parse HEAD`（生成 snapshot）

## 错误信息

| 场景                | 错误信息                                                  |
| ----------------- | ----------------------------------------------------- |
| 未提供 `path`        | `Missing repo path for \`repostack use`.`             |
| 用户未配置（且配置了 users） | `This stack requires a user configuration...`         |
| 用户拒绝创建目录          | `Aborted: user declined to create directory`          |
| 用户拒绝初始化 git       | `Aborted: user declined to initialize git repository` |
| 用户拒绝添加            | `Aborted: user declined to add repo`                  |
| 重复注册              | `Repo already registered: ${repoPath}`                |

## 副作用

- 可能创建新的本地目录。
- 可能初始化新的 Git 仓库。
- 在 `repostack.yaml` 中追加一条 repo 记录。
- 覆盖生成 `repostack.lock.yaml`。
- 修改或创建 `.gitignore`。

## 示例

```bash
# 交互模式
repostack use my-repo

# 自动模式（适合脚本）
repostack use my-repo --yes
```