REST API 现在已版本化。 有关更多信息，请参阅 "关于 API 版本控制."

用于 Git 树的 REST API 端点

使用 REST API 与 GitHub 上 Git 数据库中的树对象进行交互。

关于 Git 树

Git 树对象创建 Git 存储库中文件之间的层次结构。您可以使用 Git 树对象来创建目录与其包含的文件之间的关系。这些端点允许您读取和写入 树对象 到 GitHub 上的 Git 数据库。

创建树

树创建 API 接受嵌套条目。如果您同时指定一个树和一个修改该树的嵌套路径，此端点将用新的路径内容覆盖树的内容，并创建一个新的树结构。

如果您使用此端点添加、删除或修改树中的文件内容，您需要提交树，然后更新分支以指向提交。有关更多信息，请参阅 "创建提交" 和 "更新引用."

如果您尝试删除不存在的文件，则会返回错误。

用于“创建树”的细粒度访问令牌

此端点与以下细粒度令牌类型一起使用

细粒度令牌必须具有以下权限集

  • "内容" 存储库权限（写入）

用于“创建树”的参数

标题
accept string

建议设置为 application/vnd.github+json。

路径参数
owner 字符串 必需

存储库的帐户所有者。名称不区分大小写。

repo 字符串 必需

存储库的名称，不包括 .git 扩展名。名称不区分大小写。

主体参数
tree 对象数组 必需

指定树结构的对象（path、mode、type 和 sha）。

path 字符串

树中引用的文件。

mode 字符串

文件模式；其中之一：100644 表示文件（blob）、100755 表示可执行文件（blob）、040000 表示子目录（树）、160000 表示子模块（提交）或 120000 表示指定符号链接路径的 blob。

可以是以下之一： 100644, 100755, 040000, 160000, 120000

type 字符串

blob、tree 或 commit 之一。

可以是以下之一： blob, tree, commit

sha 字符串或 null

树中对象的 SHA1 校验和 ID。也称为 tree.sha。如果值为 null，则该文件将被删除。

注意：使用 tree.sha 或 content 指定条目的内容。同时使用 tree.sha 和 content 将返回错误。

content 字符串

您希望该文件具有的内容。GitHub 将写入此 blob 并使用该 SHA 用于此条目。使用此项或 tree.sha。

注意：使用 tree.sha 或 content 指定条目的内容。同时使用 tree.sha 和 content 将返回错误。

base_tree 字符串

现有 Git 树对象的 SHA1，将用作新树的基础。如果提供，将从 base_tree 指向的 Git 树对象中的条目和 tree 参数中定义的条目创建新的 Git 树对象。tree 参数中定义的条目将覆盖 base_tree 中具有相同 path 的条目。如果您正在分支上创建新的更改，则通常将 base_tree 设置为正在处理的分支上当前最新提交的 Git 树对象的 SHA1。如果未提供，GitHub 将仅从 tree 参数中定义的条目创建新的 Git 树对象。如果您创建指向此类树的新提交，则父提交树中包含的所有文件，且未在 tree 参数中定义，将被新提交列为已删除。

创建树的 HTTP 响应状态码

状态码描述
201

已创建

403

禁止

404

资源未找到

409

冲突

422

验证失败或端点被刷屏。

创建树的代码示例

请求示例

post/repos/{owner}/{repo}/git/trees
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/git/trees \ -d '{"base_tree":"9fb037999f264ba9a7fc6274d15fa3ae2ab98312","tree":[{"path":"file.rb","mode":"100644","type":"blob","sha":"44b4fc6d56897b048c772eb4087f854f46256132"}]}'

响应

状态：201
{ "sha": "cd8274d15fa3ae2ab983129fb037999f264ba9a7", "url": "https://api.github.com/repos/octocat/Hello-World/trees/cd8274d15fa3ae2ab983129fb037999f264ba9a7", "tree": [ { "path": "file.rb", "mode": "100644", "type": "blob", "size": 132, "sha": "7c258a9869f33c1e1e1f74fbb32f07c86cb5a75b", "url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/7c258a9869f33c1e1e1f74fbb32f07c86cb5a75b" } ], "truncated": true }

获取树

使用该树的 SHA1 值或 ref 名称返回单个树。

如果响应中的 truncated 为 true，则 tree 数组中的项目数量超过了我们的最大限制。如果需要获取更多项目，请使用非递归方法获取树，并一次获取一个子树。

注意：使用 recursive 参数时，tree 数组的限制为 100,000 个条目，最大大小为 7 MB。

获取树的细粒度访问令牌

此端点与以下细粒度令牌类型一起使用

细粒度令牌必须具有以下权限集

  • “内容”存储库权限（读取）

如果仅请求公共资源，则可以使用此端点，无需身份验证或上述权限。

获取树的参数

标题
accept string

建议设置为 application/vnd.github+json。

路径参数
owner 字符串 必需

存储库的帐户所有者。名称不区分大小写。

repo 字符串 必需

存储库的名称，不包括 .git 扩展名。名称不区分大小写。

tree_sha string 必需

树的 SHA1 值或 ref（分支或标签）名称。

查询参数
recursive 字符串

将此参数设置为任何值都会返回由:tree_sha中指定的树引用的对象或子树。例如，将recursive设置为以下任何值将启用返回对象或子树：0、1、"true"和"false"。省略此参数以防止递归返回对象或子树。

“获取树”的 HTTP 响应状态码

状态码描述
200

OK

404

资源未找到

409

冲突

422

验证失败或端点被刷屏。

“获取树”的代码示例

请求示例

get/repos/{owner}/{repo}/git/trees/{tree_sha}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/git/trees/TREE_SHA

默认响应

状态：200
{ "sha": "9fb037999f264ba9a7fc6274d15fa3ae2ab98312", "url": "https://api.github.com/repos/octocat/Hello-World/trees/9fb037999f264ba9a7fc6274d15fa3ae2ab98312", "tree": [ { "path": "file.rb", "mode": "100644", "type": "blob", "size": 30, "sha": "44b4fc6d56897b048c772eb4087f854f46256132", "url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/44b4fc6d56897b048c772eb4087f854f46256132" }, { "path": "subdir", "mode": "040000", "type": "tree", "sha": "f484d249c660418515fb01c2b9662073663c242e", "url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/f484d249c660418515fb01c2b9662073663c242e" }, { "path": "exec_file", "mode": "100755", "type": "blob", "size": 75, "sha": "45b983be36b73c0788dc9cbcb76cbb80fc7bb057", "url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/45b983be36b73c0788dc9cbcb76cbb80fc7bb057" } ], "truncated": false }