forked from chroe/gitlink-cli
336 lines
7.9 KiB
Markdown
336 lines
7.9 KiB
Markdown
# gitlink-cli 新增功能使用指南
|
||
|
||
> 任务B — file / member / watch / star 四大模块，15 个新命令
|
||
|
||
---
|
||
|
||
## 一、file — 仓库文件操作
|
||
|
||
### file +list — 列出仓库文件
|
||
|
||
```bash
|
||
gitlink-cli file +list --owner <owner> --repo <repo> [--ref <分支>] [--search <关键词>]
|
||
```
|
||
|
||
| 参数 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `--owner` | 否* | 仓库拥有者 |
|
||
| `--repo` | 否* | 仓库名 |
|
||
| `--ref`, `-r` | 否 | 分支/标签/commit SHA |
|
||
| `--search`, `-s` | 否 | 搜索关键词 |
|
||
|
||
\* 在 git 仓库目录下运行时自动解析，无需手动指定
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
# 列出根目录文件
|
||
gitlink-cli file +list --owner chroe --repo gitlink-cli
|
||
|
||
# 列出 dev 分支的文件
|
||
gitlink-cli file +list --owner chroe --repo gitlink-cli --ref dev
|
||
|
||
# 搜索包含 "test" 的文件
|
||
gitlink-cli file +list --owner chroe --repo gitlink-cli --search test
|
||
```
|
||
|
||
### file +tree — 查看文件树
|
||
|
||
```bash
|
||
gitlink-cli file +tree --owner <owner> --repo <repo> [--sha <分支>] [--recursive] [--page <n>] [--limit <n>]
|
||
```
|
||
|
||
| 参数 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `--sha`, `-s` | 否 | 分支/标签/commit，默认 `master` |
|
||
| `--recursive` | 否 | 递归展开所有子目录（`true`/`false`） |
|
||
| `--page`, `-p` | 否 | 页码，默认 `1` |
|
||
| `--limit`, `-l` | 否 | 每页条数，默认 `20` |
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
# 默认 tree 输出（table 格式）
|
||
gitlink-cli file +tree --owner chroe --repo gitlink-cli --sha master
|
||
|
||
# 递归列出所有文件（JSON 格式）
|
||
gitlink-cli file +tree --owner chroe --repo gitlink-cli --sha master --recursive true --format json
|
||
```
|
||
|
||
### file +get — 查看文件/目录内容
|
||
|
||
```bash
|
||
gitlink-cli file +get --owner <owner> --repo <repo> --path <路径> [--ref <分支>]
|
||
```
|
||
|
||
| 参数 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `--path`, `-p` | **是** | 文件或目录路径 |
|
||
| `--ref`, `-r` | 否 | 分支/标签/commit，默认 `master` |
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
# 查看 README.md 内容
|
||
gitlink-cli file +get --owner chroe --repo gitlink-cli --path README.md
|
||
|
||
# 查看 src 目录的子条目
|
||
gitlink-cli file +get --owner chroe --repo gitlink-cli --path src
|
||
|
||
# 查看 dev 分支上的文件
|
||
gitlink-cli file +get --owner chroe --repo gitlink-cli --path main.go --ref dev
|
||
```
|
||
|
||
### file +create — 新建文件
|
||
|
||
```bash
|
||
gitlink-cli file +create --owner <owner> --repo <repo> --path <路径> --content <内容> --message <提交信息> [--branch <分支>]
|
||
```
|
||
|
||
| 参数 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `--path`, `-p` | **是** | 文件路径（含文件名） |
|
||
| `--content`, `-c` | **是** | 文件内容（明文，自动 Base64 编码） |
|
||
| `--message`, `-m` | **是** | Git 提交信息 |
|
||
| `--branch`, `-b` | 否 | 目标分支，默认 `master` |
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
gitlink-cli file +create \
|
||
--owner caoweiqiong --repo Aether \
|
||
--path docs/readme.txt \
|
||
--content "Hello GitLink!" \
|
||
--message "添加文档" \
|
||
--branch master
|
||
```
|
||
|
||
### file +delete — 删除文件
|
||
|
||
```bash
|
||
gitlink-cli file +delete --owner <owner> --repo <repo> --path <路径> --sha <BlobSHA> --message <提交信息> [--branch <分支>]
|
||
```
|
||
|
||
| 参数 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `--path`, `-p` | **是** | 要删除的文件路径 |
|
||
| `--sha`, `-s` | **是** | 文件的 blob SHA（从 `file +list` 获取） |
|
||
| `--message`, `-m` | **是** | Git 提交信息 |
|
||
| `--branch`, `-b` | 否 | 目标分支，默认 `master` |
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
# 先列出文件获取 SHA
|
||
gitlink-cli file +list --owner caoweiqiong --repo Aether
|
||
|
||
# 然后删除指定文件
|
||
gitlink-cli file +delete \
|
||
--owner caoweiqiong --repo Aether \
|
||
--path docs/old.txt \
|
||
--sha abc123def456 \
|
||
--message "删除过期文档"
|
||
```
|
||
|
||
---
|
||
|
||
## 二、member — 项目成员管理
|
||
|
||
### member +list — 列出成员
|
||
|
||
```bash
|
||
gitlink-cli member +list --owner <owner> --repo <repo> [--keyword <搜索>]
|
||
```
|
||
|
||
| 参数 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `--keyword`, `-k` | 否 | 按用户名搜索成员 |
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
gitlink-cli member +list --owner chroe --repo gitlink-cli --format table
|
||
|
||
# 搜索特定成员
|
||
gitlink-cli member +list --owner chroe --repo gitlink-cli --keyword caoweiqiong
|
||
```
|
||
|
||
输出示例：
|
||
|
||
```
|
||
id login role_name
|
||
-- ----- ---------
|
||
149027 chroe Manager
|
||
141645 caoweiqiong Developer
|
||
148915 yetja Developer
|
||
```
|
||
|
||
### member +add — 添加成员
|
||
|
||
```bash
|
||
gitlink-cli member +add --owner <owner> --repo <repo> --user-id <数字ID>
|
||
```
|
||
|
||
| 参数 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `--user-id`, `-u` | **是** | 用户的数字 ID（从 `user +info` 获取） |
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
# 先查到目标用户的 user_id
|
||
gitlink-cli user +info --login zhangsan
|
||
|
||
# 然后添加
|
||
gitlink-cli member +add --owner caoweiqiong --repo Aether --user-id 123456
|
||
```
|
||
|
||
### member +remove — 移除成员
|
||
|
||
```bash
|
||
gitlink-cli member +remove --owner <owner> --repo <repo> --user-id <数字ID>
|
||
```
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
gitlink-cli member +remove --owner caoweiqiong --repo Aether --user-id 123456
|
||
```
|
||
|
||
### member +update — 修改成员角色
|
||
|
||
```bash
|
||
gitlink-cli member +update --owner <owner> --repo <repo> --user-id <数字ID> --role <角色>
|
||
```
|
||
|
||
| 参数 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `--user-id`, `-u` | **是** | 用户数字 ID |
|
||
| `--role`, `-r` | **是** | 三种角色之一：`Manager` / `Developer` / `Reporter` |
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
gitlink-cli member +update --owner caoweiqiong --repo Aether --user-id 123456 --role Developer
|
||
```
|
||
|
||
---
|
||
|
||
## 三、watch — 关注仓库
|
||
|
||
### watch +watch — 关注仓库
|
||
|
||
```bash
|
||
gitlink-cli watch +watch --owner <owner> --repo <repo>
|
||
```
|
||
|
||
无需手动传 project-id，命令内部自动解析。
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
gitlink-cli watch +watch --owner chroe --repo gitlink-cli
|
||
# → 返回 {"watched": true}
|
||
```
|
||
|
||
### watch +unwatch — 取消关注
|
||
|
||
```bash
|
||
gitlink-cli watch +unwatch --owner <owner> --repo <repo>
|
||
```
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
gitlink-cli watch +unwatch --owner chroe --repo gitlink-cli
|
||
# → 返回 {"watched": false}
|
||
```
|
||
|
||
### watch +watchers — 查看关注者列表
|
||
|
||
```bash
|
||
gitlink-cli watch +watchers --owner <owner> --repo <repo>
|
||
```
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
gitlink-cli watch +watchers --owner chroe --repo gitlink-cli --format table
|
||
```
|
||
|
||
---
|
||
|
||
## 四、star — 点赞仓库
|
||
|
||
### star +star — 点赞仓库
|
||
|
||
```bash
|
||
gitlink-cli star +star --owner <owner> --repo <repo>
|
||
```
|
||
|
||
无需手动传 project-id，命令内部自动解析。
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
gitlink-cli star +star --owner chroe --repo gitlink-cli
|
||
```
|
||
|
||
### star +unstar — 取消点赞
|
||
|
||
```bash
|
||
gitlink-cli star +unstar --owner <owner> --repo <repo>
|
||
```
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
gitlink-cli star +unstar --owner chroe --repo gitlink-cli
|
||
```
|
||
|
||
### star +stars — 查看点赞者列表
|
||
|
||
```bash
|
||
gitlink-cli star +stars --owner <owner> --repo <repo>
|
||
```
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
gitlink-cli star +stars --owner chroe --repo gitlink-cli --format table
|
||
```
|
||
|
||
---
|
||
|
||
## 全局参数
|
||
|
||
所有命令都支持以下全局参数：
|
||
|
||
| 参数 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| `--owner` | 仓库拥有者（git 目录下自动解析） | `--owner chroe` |
|
||
| `--repo` | 仓库名（git 目录下自动解析） | `--repo gitlink-cli` |
|
||
| `--format` | 输出格式：`json` / `table` / `yaml` | `--format table` |
|
||
| `--debug` | 开启调试输出 | `--debug` |
|
||
|
||
## 使用技巧
|
||
|
||
1. **利用自动解析**：在 git 克隆的目录下直接运行，无需写 `--owner` 和 `--repo`：
|
||
|
||
```bash
|
||
cd my-project
|
||
gitlink-cli file +list # 自动识别当前仓库
|
||
gitlink-cli member +list # 同上
|
||
```
|
||
|
||
2. **JSON 输出用于脚本**：
|
||
|
||
```bash
|
||
gitlink-cli file +tree --owner chroe --repo gitlink-cli --sha master --format json | jq '.data.entries[] | .name'
|
||
```
|
||
|
||
3. **file 创建自动 Base64**：传 `--content` 时直接写明文，命令会自动转为 Base64，不用自己编码。
|
||
|
||
4. **watch/star 透明化**：`watch` 和 `star` 命令会自动查 project-id，你只需关心 owner/repo，与其他命令体验一致。
|
||
|