Skip to content
forgit api docs

Create a tree

POST
/repos/{owner}/{repo}/git/trees

The tree creation API accepts nested entries. If you specify both a tree and a nested path modifying that tree, this endpoint will overwrite the contents of the tree with the new path contents, and create a new tree structure.

If you use this endpoint to add, delete, or modify the file contents in a tree, you will need to commit the tree and then update a branch to point to the commit. For more information see “Create a commit” and “Update a reference.”

Returns an error if you try to delete a file that does not exist.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
owner
required
string

The account owner of the repository. The name is not case sensitive.

repo
required
string

The name of the repository without the .git extension. The name is not case sensitive.

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
tree
required

Objects (of path, mode, type, and sha) specifying a tree structure.

Array<object>
object
path

The file referenced in the tree.

string
mode

The file mode; one of 100644 for file (blob), 100755 for executable (blob), 040000 for subdirectory (tree), 160000 for submodule (commit), or 120000 for a blob that specifies the path of a symlink.

string
Allowed values: 100644 100755 040000 160000 120000
type

Either blob, tree, or commit.

string
Allowed values: blob tree commit
sha

The SHA1 checksum ID of the object in the tree. Also called tree.sha. If the value is null then the file will be deleted.

Note: Use either tree.sha or content to specify the contents of the entry. Using both tree.sha and content will return an error.

string
nullable
content

The content you want this file to have. GitHub will write this blob out and use that SHA for this entry. Use either this, or tree.sha.

Note: Use either tree.sha or content to specify the contents of the entry. Using both tree.sha and content will return an error.

string
base_tree

The SHA1 of an existing Git tree object which will be used as the base for the new tree. If provided, a new Git tree object will be created from entries in the Git tree object pointed to by base_tree and entries defined in the tree parameter. Entries defined in the tree parameter will overwrite items from base_tree with the same path. If you’re creating new changes on a branch, then normally you’d set base_tree to the SHA1 of the Git tree object of the current latest commit on the branch you’re working on. If not provided, GitHub will create a new Git tree object from only the entries defined in the tree parameter. If you create a new commit pointing to such a tree, then all files which were a part of the parent commit’s tree and were not defined in the tree parameter will be listed as deleted by the new commit.

string
Examples
Example default 
{
  "base_tree": "9fb037999f264ba9a7fc6274d15fa3ae2ab98312",
  "tree": [
    {
      "path": "file.rb",
      "mode": "100644",
      "type": "blob",
      "sha": "44b4fc6d56897b048c772eb4087f854f46256132"
    }
  ]
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Response

Media type application/json
Git Tree

The hierarchy between files in a Git repository.

object
sha
required
string
url
string format: uri
truncated
required
boolean
tree
required

Objects specifying a tree structure

Array<object>
object
path
required
string
mode
required
string
type
required
string
sha
required
string
size
integer
url
string
Examples
Example default 
{
  "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
}

Headers

Section titled “ Headers ”
Location
string
Example 
https://api.github.com/repos/octocat/Hello-World/trees/cd8274d15fa3ae2ab983129fb037999f264ba9a7

403

Section titled “ 403 ”

Forbidden

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

404

Section titled “ 404 ”

Resource not found

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

409

Section titled “ 409 ”

Conflict

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

422

Section titled “ 422 ”

Validation failed, or the endpoint has been spammed.

Media type application/json
Validation Error

Validation Error

object
message
required
string
documentation_url
required
string
errors
Array<object>
object
resource
string
field
string
message
string
code
required
string
index
integer
value
One of:
string
nullable
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "errors": [
    {
      "resource": "example",
      "field": "example",
      "message": "example",
      "code": "example",
      "index": 1,
      "value": [
        "example"
      ]
    }
  ]
}