diff --git a/README.md b/README.md index eed64785..33b66b12 100644 --- a/README.md +++ b/README.md @@ -204,6 +204,10 @@ gitlink-cli repo +info --owner Gitlink --repo forgeplus # Read repository README gitlink-cli repo +readme --owner Gitlink --repo forgeplus --ref master +# List repository files at root or a directory +gitlink-cli repo +tree --owner Gitlink --repo forgeplus --ref master +gitlink-cli repo +tree --owner Gitlink --repo forgeplus --path src --ref main + # Show language breakdown gitlink-cli repo +languages --owner Gitlink --repo forgeplus diff --git a/README.zh-CN.md b/README.zh-CN.md index 7336d68e..62ce9df8 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -215,6 +215,10 @@ gitlink-cli repo +info --owner Gitlink --repo forgeplus # 读取仓库 README gitlink-cli repo +readme --owner Gitlink --repo forgeplus --ref master +# 列出仓库根目录或指定目录文件 +gitlink-cli repo +tree --owner Gitlink --repo forgeplus --ref master +gitlink-cli repo +tree --owner Gitlink --repo forgeplus --path src --ref main + # 查看语言占比 gitlink-cli repo +languages --owner Gitlink --repo forgeplus diff --git a/doc/design.md b/doc/design.md index d25295b9..3a0e6064 100644 --- a/doc/design.md +++ b/doc/design.md @@ -40,7 +40,7 @@ gitlink-cli/ │ ├── common/ │ │ ├── types.go # Shortcut / Flag / RuntimeContext 定义 │ │ └── runner.go # CallAPI / PaginateAll / ResolveOwnerRepo -│ ├── repo/ # repo +create / +clone / +fork / +list / +info +│ ├── repo/ # repo +create / +clone / +fork / +list / +info / +tree │ ├── issue/ # issue +list / +create / +view / +close / +comment │ ├── pr/ # pr +list / +create / +view / +merge / +review │ ├── release/ # release +list / +create / +download @@ -78,7 +78,7 @@ gitlink-cli/ | 领域 | Shortcuts | 数量 | |------|-----------|------| -| repo | `+create` `+clone` `+fork` `+list` `+info` `+delete` `+settings` | 7 | +| repo | `+create` `+clone` `+fork` `+list` `+info` `+tree` `+delete` `+settings` | 8 | | issue | `+list` `+create` `+view` `+update` `+close` `+comment` `+assign` `+label` | 8 | | pr | `+list` `+create` `+view` `+merge` `+close` `+review` `+files` `+diff` | 8 | | release | `+list` `+create` `+view` `+delete` `+download` | 5 | diff --git a/shortcuts/repo/repo.go b/shortcuts/repo/repo.go index 09c091cd..e57963a8 100644 --- a/shortcuts/repo/repo.go +++ b/shortcuts/repo/repo.go @@ -81,6 +81,31 @@ func Shortcuts(translators ...*i18n.Translator) []*common.Shortcut { return ctx.Output(env) }, }, + { + Name: "tree", + Description: "List repository files and directories", + Flags: []common.Flag{ + {Name: "path", Short: "p", Usage: "Directory path to list (default: repository root)"}, + {Name: "ref", Short: "r", Usage: "Branch, tag, or commit ref", Default: "master"}, + }, + Run: func(ctx *common.RuntimeContext) error { + if err := ctx.ResolveOwnerRepo(); err != nil { + return err + } + q := url.Values{} + ref := ctx.Arg("ref") + if ref == "" { + ref = "master" + } + q.Set("filepath", ctx.Arg("path")) + q.Set("ref", ref) + env, err := ctx.CallAPIWithQuery("GET", ctx.RepoPath()+"/sub_entries", q) + if err != nil { + return err + } + return ctx.Output(env) + }, + }, { Name: "languages", Description: "Show repository language statistics", diff --git a/shortcuts/repo/repo_test.go b/shortcuts/repo/repo_test.go index f3c1a357..38f8ab0e 100644 --- a/shortcuts/repo/repo_test.go +++ b/shortcuts/repo/repo_test.go @@ -152,6 +152,42 @@ func TestRepoReadmeUsesRepositoryReadmeEndpoint(t *testing.T) { } } +func TestRepoTreeListsRootOnDefaultRef(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + assertRequest(t, r, "GET", "/owner/repo/sub_entries.json") + assertEqual(t, r.URL.Query().Get("filepath"), "") + assertEqual(t, r.URL.Query().Get("ref"), "master") + writeJSON(t, w, map[string]interface{}{ + "entries": []map[string]interface{}{ + {"name": "README.md", "type": "file"}, + }, + }) + })) + defer server.Close() + + if err := runShortcut(t, server, "tree", nil); err != nil { + t.Fatalf("tree shortcut failed: %v", err) + } +} + +func TestRepoTreeUsesPathAndRef(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + assertRequest(t, r, "GET", "/owner/repo/sub_entries.json") + assertEqual(t, r.URL.Query().Get("filepath"), "cmd") + assertEqual(t, r.URL.Query().Get("ref"), "main") + writeJSON(t, w, map[string]interface{}{ + "entries": []map[string]interface{}{ + {"name": "main.go", "type": "file"}, + }, + }) + })) + defer server.Close() + + if err := runShortcut(t, server, "tree", map[string]string{"path": "cmd", "ref": "main"}); err != nil { + t.Fatalf("tree shortcut failed: %v", err) + } +} + func TestRepoLanguagesUsesLanguagesEndpoint(t *testing.T) { server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { assertRequest(t, r, "GET", "/owner/repo/languages.json") diff --git a/skills/gitlink-repo/SKILL.md b/skills/gitlink-repo/SKILL.md index bdd75c9e..9db96ebb 100644 --- a/skills/gitlink-repo/SKILL.md +++ b/skills/gitlink-repo/SKILL.md @@ -23,6 +23,7 @@ metadata: | `repo +list` | 仓库列表 | 否（公开项目） | | `repo +info` | 仓库详情 | 否（公开项目） | | `repo +readme` | README 内容 | 否（公开项目） | +| `repo +tree` | 仓库文件树 | 否（公开项目） | | `repo +languages` | 仓库语言统计 | 否（公开项目） | | `repo +contributors` | 仓库贡献者列表 | 否（公开项目） | | `repo +contributor-stats` | 贡献者代码行统计 | 否（公开项目） | @@ -51,6 +52,8 @@ gitlink-cli repo +info gitlink-cli repo +list --user zhangsan # 查看语言占比和贡献者 +gitlink-cli repo +tree --owner Gitlink --repo forgeplus --ref master +gitlink-cli repo +tree --owner Gitlink --repo forgeplus --path src --ref main gitlink-cli repo +languages --owner Gitlink --repo forgeplus gitlink-cli repo +contributors --owner Gitlink --repo forgeplus diff --git a/skills/gitlink-repo/references/gitlink-repo-tree.md b/skills/gitlink-repo/references/gitlink-repo-tree.md new file mode 100644 index 00000000..faabb648 --- /dev/null +++ b/skills/gitlink-repo/references/gitlink-repo-tree.md @@ -0,0 +1,42 @@ +# repo +tree + +> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +列出 GitLink 仓库根目录或指定目录下的文件和子目录。该命令封装 `sub_entries` API，适合项目结构检查、文档检查、科研复现性分析和 Agent 自动化报告。 + +## 命令 + +```bash +# 列出仓库根目录 +gitlink-cli repo +tree --owner someone --repo myrepo + +# 指定分支、标签或提交 +gitlink-cli repo +tree --owner someone --repo myrepo --ref main + +# 列出指定目录 +gitlink-cli repo +tree --owner someone --repo myrepo --path src --ref main + +# 输出为 JSON +gitlink-cli repo +tree --owner someone --repo myrepo --format json +``` + +## 参数 + +| 参数 | 必填 | 说明 | +|------|------|------| +| `--path, -p` | 否 | 要列出的目录路径，默认为仓库根目录 | +| `--ref, -r` | 否 | 分支、标签或提交引用，默认 `master` | +| `--owner` | 否 | 全局参数 - 仓库所有者，可从 git remote 自动解析 | +| `--repo` | 否 | 全局参数 - 仓库名称，可从 git remote 自动解析 | +| `--format` | 否 | 输出格式：`json`/`table`/`yaml` | +| `--debug` | 否 | 启用调试输出 | + +## 注意事项 + +- GitLink 仓库常见默认分支是 `master`，镜像仓库也可能使用 `main`。如果根目录返回不存在，请显式指定 `--ref main` 或从 `repo +info` 的 `default_branch` 字段确认。 +- AI Agent 场景建议使用 `--format json`，便于读取 `data.entries` 中的文件名、路径、类型和 SHA。 + +## 参考 + +- [gitlink-repo](../SKILL.md) +- [gitlink-shared](../../gitlink-shared/SKILL.md)