From d61fb68606e09c1dc1be2c9aa965e6c069a4e929 Mon Sep 17 00:00:00 2001 From: Roger Peppe Date: Thu, 11 Dec 2025 16:16:33 +0000 Subject: [PATCH] docs: clarify CreateTree semantics and TreeEntry usage Document the merge behavior when baseTree is provided, how to delete files and directories by setting SHA and Content to nil, and that duplicate paths result in last-entry-wins behavior. Also document on TreeEntry how to use Content vs SHA, referencing CreateBlob for binary files, and that Type/Mode are ignored when deleting. Signed-off-by: Roger Peppe --- github/git_trees.go | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/github/git_trees.go b/github/git_trees.go index 2b701a3c658..2ff0dc592d8 100644 --- a/github/git_trees.go +++ b/github/git_trees.go @@ -30,6 +30,13 @@ func (t Tree) String() string { // TreeEntry represents the contents of a tree structure. TreeEntry can // represent either a blob, a commit (in the case of a submodule), or another // tree. +// +// When used with [GitService.CreateTree], set Content for small text files, +// or set SHA to reference an existing blob (use [GitService.CreateBlob] for +// binary files or large content). To delete an entry, set both Content and SHA +// to nil; the entry will be serialized with `"sha": null` which the API interprets +// as a deletion. When deleting, the Type and Mode fields are ignored; only Path +// is required. type TreeEntry struct { SHA *string `json:"sha,omitempty"` Path *string `json:"path,omitempty"` @@ -127,6 +134,12 @@ type createTree struct { // path modifying that tree are specified, it will overwrite the contents of // that tree with the new path contents and write a new tree out. // +// When baseTree is provided, entries are merged with that tree: paths not +// mentioned in entries are preserved from the base tree. If the same path +// appears multiple times in entries, the last entry wins. To delete an entry, +// include a [TreeEntry] with the path and both SHA and Content set to nil. +// Entire directories can be deleted this way. +// // GitHub API docs: https://docs.github.com/rest/git/trees#create-a-tree // //meta:operation POST /repos/{owner}/{repo}/git/trees