Kochi Repo XML 配置编写教程

# 📝 Kochi Repo XML 配置编写教程

本工具依赖 XML 清单文件来定义需要拉取或复制的项目。每个 XML 文件可包含一个或多个 `<project>` 节点，用于指定仓库位置、拉取方式和本地保存路径等信息。

---

## 📌 基本结构

```xml
<manifest workspace="workspace目录">
    <remote name="origin" fetch="git仓库地址" />
    <default remote="origin" branch="main" />
    
    <project ... />
    <project ... />
</manifest>
```

---

## 📁 顶层属性说明

### `<manifest workspace="...">`

- **含义**：设置所有项目的根目录（即 clone / sparse / copy 的目标基础路径）。
    
- **示例**：`workspace="my_workspace"` 表示所有项目拉取到 `my_workspace` 目录下。

---

### `<remote name="..." fetch="..."/>`

- **name**：远程仓库的标识符（必须唯一）。
    
- **fetch**：实际的 Git 仓库地址（可以是 SSH、HTTP、file 等）。
    
- **示例**：
    
    ```xml
    <remote name="origin" fetch="ssh://git@myhost.com/repo/" />
    ```

---

### `<default remote="..." branch="..."/>`

- **remote**：默认使用的远程仓库名。
    
- **branch**：默认使用的分支名。
    
- 如果 `<project>` 没有指定 `remote` 或 `branch`，则使用这里的默认值。

---

## 📦 `<project>` 节点说明

用于定义一个项目如何被拉取或复制。

| 属性名          | 是否必须 | 含义                                |
| ------------ | ---- | --------------------------------- |
| `name`       | ✅ 必须 | 仓库名（用于拼接 fetch URL）               |
| `method`     | ✅ 必须 | 拉取方式（见下方方法类型）                     |
| `path`       | ✅ 必须 | 在 workspace 下保存的目标路径              |
| `remote`     | 可选   | 使用的 `<remote name>`，默认为 default 的 |
| `branch`     | 可选   | Git 分支名                           |
| `tag`        | 可选   | Git tag，优先级高于 branch              |
| `revision`   | 可选   | Git commit 哈希，仅 `archive` 方法支持    |
| `remote_dir` | 可选   | 仓库中的子目录或文件，用于 sparse/ archive     |
| `local_path` | 可选   | 本地复制路径，仅 `local_copy` 方法使用        |

---

## 🧰 支持的 method 类型

### 1. `clone`：完整克隆仓库

```xml
<project name="repo.git" method="clone" path="full_repo"/>
```

- 支持分支（`branch`）或 tag（`tag`）指定
    
- 不支持 `remote_dir`

---

### 2. `sparse`：只拉取部分目录或文件

```xml
<project 
  name="repo.git"
  method="sparse"
  path="workspace/module"
  branch="dev"
  remote_dir="src/components/ui"
/>
```

- 适用于只需要仓库中某个子目录或单个文件的场景
    
- 支持 `branch` 或 `tag`

---

### 3. `archive`：以快照方式导出 commit 中某目录

```xml
<project
  name="legacy-code.git"
  method="archive"
  path="legacy/"
  remote_dir="legacy_code/"
  revision="abc1234567890..."
/>
```

- 只支持指定 `revision`（commit 哈希）
    
- 不保留 `.git`，直接导出文件内容

---

### 4. `local_copy`：从本地目录复制文件/文件夹

```xml
<project
  name="local_files"
  method="local_copy"
  local_path="Components/SomeModule"
  path="workspace/module"
/>
```

- `local_path` 是相对或绝对路径，支持 Linux/Windows 路径自动兼容
    
- 如果目标目录已存在，自动合并内容，不覆盖 `.git` 文件夹

---

## ⚠️ 注意事项

- 所有路径使用 `/` 或自动处理 `\`，无需手动转换
    
- 如果某个字段拼写错误或遗漏必填项，该项目将被跳过，并显示错误信息
    
- 支持多个 XML 配置文件，所有 `.xml` 文件自动加载处理
    
- `workspace` 必须确保是非敏感路径（如不是 `/`, `~`, 脚本路径等）

---

## ✅ 示例汇总

```xml
<manifest workspace="my_workspace">
    <remote name="origin" fetch="ssh://git@myhost/repo/" />
    <default remote="origin" branch="main"/>

<project name="full.git" path="all" method="clone"/>

<project name="sparse.git" path="some/module" method="sparse" remote_dir="src/mod" branch="dev"/>

<project name="sparse.git" path="some/script" method="sparse" remote_dir="build.sh" tag="v1.2.3"/>

<project name="repo.git" method="archive" revision="abcdef123" remote_dir="src/" path="legacy/"/>

<project name="local_copy" method="local_copy" local_path="data/files" path="workspace/data"/>
</manifest>
```