gitlink-cli/README_TASKB.md

gitlink-cli 新增功能使用指南

任务B — file / member / watch / star 四大模块，15 个新命令

---

一、file — 仓库文件操作

file +list — 列出仓库文件

gitlink-cli file +list --owner <owner> --repo <repo> [--ref <分支>] [--search <关键词>]

参数	必需	说明
--owner	否*	仓库拥有者
--repo	否*	仓库名
--ref, -r	否	分支/标签/commit SHA
--search, -s	否	搜索关键词

* 在 git 仓库目录下运行时自动解析，无需手动指定

示例：

# 列出根目录文件
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 — 查看文件树

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

示例：

# 默认 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 — 查看文件/目录内容

gitlink-cli file +get --owner <owner> --repo <repo> --path <路径> [--ref <分支>]

参数	必需	说明
--path, -p	是	文件或目录路径
--ref, -r	否	分支/标签/commit，默认 master

示例：

# 查看 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 — 新建文件

gitlink-cli file +create --owner <owner> --repo <repo> --path <路径> --content <内容> --message <提交信息> [--branch <分支>]

参数	必需	说明
--path, -p	是	文件路径（含文件名）
--content, -c	是	文件内容（明文，自动 Base64 编码）
--message, -m	是	Git 提交信息
--branch, -b	否	目标分支，默认 master

示例：

gitlink-cli file +create \
  --owner caoweiqiong --repo Aether \
  --path docs/readme.txt \
  --content "Hello GitLink!" \
  --message "添加文档" \
  --branch master

file +delete — 删除文件

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

示例：

# 先列出文件获取 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 — 列出成员

gitlink-cli member +list --owner <owner> --repo <repo> [--keyword <搜索>]

参数	必需	说明
--keyword, -k	否	按用户名搜索成员

示例：

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 — 添加成员

gitlink-cli member +add --owner <owner> --repo <repo> --user-id <数字ID>

参数	必需	说明
--user-id, -u	是	用户的数字 ID（从 user +info 获取）

示例：

# 先查到目标用户的 user_id
gitlink-cli user +info --login zhangsan

# 然后添加
gitlink-cli member +add --owner caoweiqiong --repo Aether --user-id 123456

member +remove — 移除成员

gitlink-cli member +remove --owner <owner> --repo <repo> --user-id <数字ID>

示例：

gitlink-cli member +remove --owner caoweiqiong --repo Aether --user-id 123456

member +update — 修改成员角色

gitlink-cli member +update --owner <owner> --repo <repo> --user-id <数字ID> --role <角色>

参数	必需	说明
--user-id, -u	是	用户数字 ID
--role, -r	是	三种角色之一：Manager / Developer / Reporter

示例：

gitlink-cli member +update --owner caoweiqiong --repo Aether --user-id 123456 --role Developer

---

三、watch — 关注仓库

watch +watch — 关注仓库

gitlink-cli watch +watch --owner <owner> --repo <repo>

无需手动传 project-id，命令内部自动解析。

示例：

gitlink-cli watch +watch --owner chroe --repo gitlink-cli
# → 返回 {"watched": true}

watch +unwatch — 取消关注

gitlink-cli watch +unwatch --owner <owner> --repo <repo>

示例：

gitlink-cli watch +unwatch --owner chroe --repo gitlink-cli
# → 返回 {"watched": false}

watch +watchers — 查看关注者列表

gitlink-cli watch +watchers --owner <owner> --repo <repo>

示例：

gitlink-cli watch +watchers --owner chroe --repo gitlink-cli --format table

---

四、star — 点赞仓库

star +star — 点赞仓库

gitlink-cli star +star --owner <owner> --repo <repo>

无需手动传 project-id，命令内部自动解析。

示例：

gitlink-cli star +star --owner chroe --repo gitlink-cli

star +unstar — 取消点赞

gitlink-cli star +unstar --owner <owner> --repo <repo>

示例：

gitlink-cli star +unstar --owner chroe --repo gitlink-cli

star +stars — 查看点赞者列表

gitlink-cli star +stars --owner <owner> --repo <repo>

示例：

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：

   cd my-project
   gitlink-cli file +list           # 自动识别当前仓库
   gitlink-cli member +list         # 同上
   

2. JSON 输出用于脚本：

   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，与其他命令体验一致。