# ge

**Repository Path**: imjoey/ge

## Basic Information

- **Project Name**: ge
- **Description**: ge（gitee-cli）是一个用 Go 编写的 Gitee 命令行工具，对标 GitHub CLI (gh)
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-12
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: vcs

**Tags**: None

## README

<div align="center">

# ge · Gitee CLI

**Gitee on the command line.**

中文

[![Go Reference](https://pkg.go.dev/badge/gitee.com/imjoey/ge/v5.svg)](https://pkg.go.dev/gitee.com/imjoey/ge/v5)
[![Go Report Card](https://goreportcard.com/badge/gitee.com/imjoey/ge/v5)](https://goreportcard.com/report/gitee.com/imjoey/ge/v5)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

`ge`（也叫 `gitee-cli`）是一个用 Go 编写的 [Gitee](https://gitee.com) 命令行工具。<br/>
它将仓库、Issue、Pull Request、Release 等概念带到你的终端，让你在 `git` 旁边就能完成所有 Gitee 操作。

```bash
$ ge repo create --name my-project --private
$ ge issue create --repo my-project --title "Fix login bug"
$ ge pr list --repo my-project
$ ge release create v1.0.0 --repo my-project --title "First Release"
```

</div>

---

## 为什么需要 ge？

GitHub 有 [`gh`](https://github.com/cli/cli)，GitLab 有 [`glab`](https://gitlab.com/gitlab-org/cli)，**Gitee 一直没有官方 CLI**。

`ge` 填补了这个空白。它的设计目标：

- 🚀 **开箱即用** — 一个二进制文件，零依赖，macOS / Linux / Windows 全平台
- 🔌 **Agent 友好** — 所有命令支持非交互模式，适合 CI/CD 和 AI Agent 调用
- 🏗️ **架构对标 gh** — Factory 模式、IOStreams、httpmock，代码质量经得起考验
- 🌐 **完整 API v5 覆盖** — 279 个 API 方法，覆盖 Gitee API v5 全部 264 个端点（100%+），18 个资源类型
- 🎨 **彩色终端输出** — 自动检测 TTY，脚本模式和交互模式都有好体验

## 安装

### 预编译二进制（推荐）

从 [Releases](https://gitee.com/imjoey/ge/releases) 下载对应平台的二进制文件：

```bash
# Linux / macOS
curl -sL https://gitee.com/imjoey/ge/releases/latest/download/ge-linux-amd64 -o /usr/local/bin/ge
chmod +x /usr/local/bin/ge

# 或者用 go install
go install gitee.com/imjoey/ge/v5@latest
```

### 从源码构建

```bash
git clone https://gitee.com/imjoey/ge.git
cd ge
make build
# 二进制文件在 bin/ge
```

## 快速开始

### 1. 认证

```bash
# 用 Token 登录（推荐）
export GITEE_TOKEN=your_personal_access_token

# 或者保存到配置文件
ge auth login --token your_personal_access_token

# 检查认证状态
ge auth status
```

> 💡 在 [Gitee → 设置 → 私人令牌](https://gitee.com/profile/personal_access_tokens) 生成 Token

### 2. 试试看

```bash
# 查看你的信息
ge user info

# 列出你的仓库
ge repo list

# 创建一个新仓库
ge repo create --name hello-world --private

# 搜索仓库
ge search repos "golang cli"
```

## 命令一览

| 命令 | 说明 |
|------|------|
| `ge auth login/status/logout/token` | 认证管理 |
| `ge repo list/create/delete/fork/view/cat/update` | 仓库管理 |
| `ge repo key-list/key-create/key-delete/key-view/key-available/key-enable/key-disable` | 仓库部署公钥管理 |
| `ge repo comment-list/comment-create/comment-view/comment-update/comment-delete/comment-commit` | 仓库评论 |
| `ge repo download/blame/languages/contributors/subscribers/traffic/raw/readme/forks/clear/open` | 仓库信息查询与操作 |
| `ge repo branch-setting/branch-wildcard/push-config/push-config-update/project-label-*/reviewer` | 仓库配置 |
| `ge repo org-list/org-create/user-list/release-file-list/release-file-upload/release-file-download/release-file-view/release-file-delete/commit-create/baidu-stats*` | 组织仓库、Release 文件等 |
| `ge repo create-file/update-file/delete-file` | 仓库文件操作 |
| `ge repo collaborator-list/collaborator-add/collaborator-remove` | 协作者管理 |
| `ge issue list/create/close/reopen/edit/view/comment/log/label/my-issues/org-list/repo-list/prs` | Issue 管理 |
| `ge issue comment list/create/view/edit/delete` | Issue 评论 |
| `ge issue label add/set/remove/clear` | Issue 标签 |
| `ge pr list/create/merge/close/reopen/edit/view` | Pull Request 管理 |
| `ge pr diff/commits/files/comment/log` | PR 详情、文件变更、评论与操作日志 |
| `ge pr merged` | 检查 PR 是否已合并 |
| `ge pr review/test` | PR 审核与测试 |
| `ge pr assign-reviewer/unassign-reviewer/assign-tester/unassign-tester` | PR 人员指派 |
| `ge pr label list/add/set/remove` | PR 标签管理 |
| `ge branch list/create/delete/view/protect/unprotect/protection` | 分支管理 |
| `ge tag list/create` | 标签管理 |
| `ge commit list/view/compare` | 提交查看 |
| `ge release list/create/view/delete` | Release 管理 |
| `ge milestone list/create/close/delete` | 里程碑管理 |
| `ge label list/create/delete/view/update` | 标签管理 |
| `ge webhook list/create/delete` | Webhook 管理 |
| `ge search repos/issues/users` | 搜索仓库、Issue 和用户 |
| `ge org list/view/create/update/repos/members/membership/membership-update/membership-remove/followers/user-orgs` | 组织管理 |
| `ge user info/update/follow/unfollow/followers/following/keys/key-add/key-delete/email-list/namespace-list` | 用户管理 |
| `ge notification count/list/view/read/read-all/repo-read/message-list/message-view/message-send/message-read/message-delete` | 通知与消息管理 |
| `ge misc emoji-list/gitignore-list/gitignore-view/license-list/license-view/license-raw/repo-license/markdown` | 杂项工具 |
| `ge watch list/add/remove` | 仓库订阅管理 |
| `ge check list/create/update/view/annotations` | Check Run 管理 |
| `ge enterprise list/view/repo-list/repo-create/issue-list/issue-view/issue-update` | 企业管理 |
| `ge enterprise member-list/member-search/member-view/member-add/member-update/member-remove` | 企业成员管理 |
| `ge enterprise week-report-list/week-report-view/week-report-create/week-report-update` | 企业周报 |
| `ge enterprise week-report-comment/week-report-comments/week-report-comment-delete/week-report-user` | 周报评论 |
| `ge enterprise pr-list/label-list/label-view/issue-labels/issue-comments/issue-prs` | 企业 Issue/PR |
| `ge activity events/network-events/org-events/subscribers/user-org-events/user-subs` | 活动事件 |
| `ge git blob/metrics` | Git 数据 |
| `ge config get/set/list` | 配置管理 |
| `ge alias set/list/delete` | 命令别名 |
| `ge completion bash/zsh/fish/powershell` | Shell 自动补全 |
| `ge version` | 版本信息 |

每个命令都支持 `--help` 查看详细用法。

## 使用示例

### 仓库操作

```bash
# 列出仓库
ge repo list

# 创建仓库（非交互，适合 CI/Agent）
ge repo create --name my-project --description "My project" --private

# 删除仓库（需要确认，或用 --yes 跳过）
ge repo delete owner/my-project --yes

# Fork 仓库
ge repo fork owner/some-repo

# 管理协作者
ge repo collaborator-list --repo my-project
ge repo collaborator-add username --repo my-project --permission push
```

### Issue 工作流

```bash
# 列出 Issue
ge issue list --repo my-project
ge issue list --repo my-project --state closed

# 创建 Issue
ge issue create --repo my-project --title "Bug: crash on startup" --body "Steps to reproduce..."

# 关闭 Issue
ge issue close my-project 123
```

### Pull Request 工作流

```bash
# 列出 PR
ge pr list --repo my-project
ge pr list --repo my-project --state merged

# 创建 PR
ge pr create --repo my-project --title "feat: add login page" --source feature/login --target master

# 合并 PR
ge pr merge my-project 42
```

### Release 发布

```bash
# 创建 Release
ge release create v1.0.0 --repo my-project --title "v1.0.0 - First Release" --note "## What's New\n- Feature A\n- Bug fix B"

# 查看 Release
ge release view v1.0.0 --repo my-project

# 删除 Release
ge release delete 1 --repo my-project
```

### CI/CD 和 Agent 场景

`ge` 的所有命令都支持非交互模式，适合在 CI/CD 管道和 AI Agent 中使用：

```bash
# 纯环境变量认证，无需配置文件
export GITEE_TOKEN=${{ secrets.GITEE_TOKEN }}

# 非交互创建仓库、Issue、PR
ge repo create --name auto-project --private
ge issue create --repo auto-project --title "Automated issue" --body "Created by CI"
ge pr create --repo auto-project --title "Auto PR" --source fix-branch

# 删除仓库不确认
ge repo delete owner/auto-project --yes
```

### Shell 补全

```bash
# Bash
ge completion -s bash > /etc/bash_completion.d/ge
echo 'source /etc/bash_completion.d/ge' >> ~/.bashrc

# Zsh
ge completion -s zsh > "${fpath[1]}/_ge"

# Fish
ge completion -s fish > ~/.config/fish/completions/ge.fish
```

## 配置

### Token 优先级

`ge` 按以下顺序查找 Token：

1. `GITEE_TOKEN` 环境变量（最高优先级）
2. `GE_TOKEN` 环境变量
3. 配置文件 `~/.config/ge/config.yml` 中的 `gitee_token`
4. 遗留配置 `~/.gitee.yaml`

### 配置文件

默认位置：`~/.config/ge/config.yml`

```yaml
gitee_token: your_token        # 不推荐，优先用环境变量
owner: your_username           # 默认 owner
git_protocol: https            # https 或 ssh
editor: vim                    # 文本编辑器
```

### 环境变量

| 变量 | 说明 |
|------|------|
| `GITEE_TOKEN` | Gitee 个人访问令牌（最高优先级） |
| `GE_TOKEN` | `GITEE_TOKEN` 的别名 |
| `GE_CONFIG_PATH` | 自定义配置文件路径 |

## 项目架构

`ge` 的架构参照 GitHub CLI ([`gh`](https://github.com/cli/cli)) 的设计模式：

```
ge/
├── main.go                    # 入口
├── internal/
│   ├── cmdutil/               # Factory、错误类型、工具函数
│   ├── config/                # 配置管理（XDG 路径、Token 优先级）
│   ├── build/                 # 版本信息（ldflags + ReadBuildInfo fallback）
│   └── commands/              # 命令实现（每个功能一个目录）
│       ├── auth/              #   认证命令
│       ├── repo/              #   仓库命令
│       ├── issue/             #   Issue 命令
│       ├── pr/                #   PR 命令
│       ├── branch/            #   分支命令
│       ├── release/           #   Release 命令
│       ├── milestone/         #   里程碑命令
│       ├── label/             #   标签命令
│       ├── webhook/           #   Webhook 命令
│       ├── commit/            #   提交命令
│       ├── tag/               #   标签命令
│       ├── search/            #   搜索命令
│       ├── org/               #   组织命令
│       ├── user/              #   用户命令
│       ├── notification/      #   通知命令
│       ├── watch/             #   仓库订阅命令
│       ├── enterprise/       #   企业管理命令
│       ├── check/            #   Check Run 命令
│       ├── activity/         #   活动事件命令
│       ├── git/              #   Git 数据命令
│       ├── config/            #   配置命令
│       ├── completion/        #   Shell 补全
│       └── version/           #   版本命令
├── pkg/
│   ├── gitee/                 # Gitee API v5 客户端（Facade 层）
│   ├── giteeapi/              # go-swagger 生成的 API 客户端
│   ├── iostreams/             # I/O 流抽象（TTY 检测、颜色）
│   └── httpmock/              # HTTP Mock 测试框架
├── tests/                     # 集成测试和 E2E 测试
├── .goreleaser.yml            # 多平台发布配置
└── Makefile                   # 构建任务
```

**核心设计模式**（与 gh 一致）：

- **Factory** — `cmdutil.Factory` 注入 IOStreams、Config、HttpClient
- **Options** — 每个命令有独立的 Options 结构体
- **Test Injection** — `runF` 参数支持测试注入
- **IOStreams** — TTY 检测、颜色支持、测试模式
- **httpmock** — 可验证的 HTTP Mock，确保测试覆盖

## 测试状态

| 指标 | 值 |
|------|-----|
| 测试文件 | 588 个 |
| 测试函数 | 3,622 个 |
| 总覆盖率 | 57.6% |
| golangci-lint | 0 issues ✅ |
| API 覆盖率 | 279/264 端点 (100%+，含超额方法) |

### 各模块覆盖率

| 模块 | 覆盖率 | 模块 | 覆盖率 |
|------|--------|------|--------|
| user | 99.7% | label | 99.3% |
| tag | 98.6% | search | 98.1% |
| commit | 95.9% | notification | 94.6% |
| branch | 77.1% | pr | 76.4% |
| issue | 73.3% | release | 62.9% |
| repo | 61.6% | pkg/gitee | 40.5% |

## Gitee API 注意事项

基于实际开发中踩过的坑，记录 Gitee API v5 与 GitHub API 的关键差异：

### 读写路径分离

Issue 和 PR 的读写操作使用不同的 URL 路径：

| 操作 | 路径 | 说明 |
|------|------|------|
| 读取 Issue 列表 | `GET /repos/{owner}/{repo}/issues` | repo 在 URL 路径中 |
| 获取单个 Issue | `GET /repos/{owner}/{repo}/issues/{number}` | repo 在 URL 路径中 |
| 创建 Issue | `POST /repos/{owner}/issues` | repo 作为 body 参数 |
| 更新/关闭 Issue | `PATCH /repos/{owner}/issues/{number}` | repo 作为 body 参数 |

### 请求格式

Gitee Swagger 文档中写接口的参数类型标注为 `formData`，但**实际上 Gitee 也接受 JSON body**（`Content-Type: application/json`）。当前 ge 统一使用 JSON 格式发送写请求，功能正常。

### Issue 编号

Gitee 的 Issue 编号是**字符串**（如 `IJP3UP`、`IJNVSB`），不是数字。开启企业项目管理的仓库会生成字母数字混合编号。

### 常见错误

- `400 此仓库关闭Issue模块` — 仓库设置中 `has_issues: false`
- `404 project or enterprise` — 仓库开启了企业项目管理，Issue 走了企业子系统的非公开 API 路径

> **经验教训**：不要按 GitHub API 的习惯去假设 Gitee API 的行为。遇到问题先看 [Gitee 官方 Swagger 文档](https://gitee.com/api/v5/swagger)，再实际跑命令验证。

## 开发

```bash
# 构建
make build

# 测试
make test

# 代码检查
make lint

# 多平台构建
make build-all
```

### 运行集成测试

```bash
# 单元测试（不需要 Token）
go test ./...

# 集成测试（需要真实 Gitee API）
GITEE_TOKEN=your_token GE_INTEGRATION_TEST=1 go test ./tests/...
```

---

## 贡献

欢迎贡献代码！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详情。

1. Fork 本仓库
2. 创建功能分支：`git checkout -b feature/amazing-feature`
3. 提交更改：`git commit -m 'feat: add amazing feature'`
4. 推送分支：`git push origin feature/amazing-feature`
5. 创建 Pull Request

## 许可证

[MIT License](LICENSE)

## 链接

- [Gitee API v5 文档](https://gitee.com/api/v5/swagger)
- [GitHub CLI (gh)](https://github.com/cli/cli) — 架构参考
- [问题反馈](https://gitee.com/imjoey/ge/issues)

---

<div align="center">

**如果 ge 对你有帮助，请给个 ⭐ Star 支持一下！**

</div>