trees

Creates, updates, deletes, gets or lists a trees resource.

Overview

Name	trees
Type	Resource
Id	github.git.trees

Fields

The following fields are returned by SELECT queries:

get_tree

Response

Name	Datatype	Description
sha	string
tree	array	Objects specifying a tree structure
truncated	boolean
url	string (uri)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_tree	select	owner, repo, tree_sha	recursive	Returns a single tree using the SHA1 value or ref name for that tree. If truncated is true in the response then the number of items in the tree array exceeded our maximum limit. If you need to fetch more items, use the non-recursive method of fetching trees, and fetch one sub-tree at a time. > [!NOTE] > The limit for the tree array is 100,000 entries with a maximum size of 7 MB when using the recursive parameter.
create_tree	insert	owner, repo, tree		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.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
owner	string	The account owner of the repository. The name is not case sensitive.
repo	string	The name of the repository without the .git extension. The name is not case sensitive.
tree_sha	string	The SHA1 value or ref (branch or tag) name of the tree.
recursive	string	Setting this parameter to any value returns the objects or subtrees referenced by the tree specified in :tree_sha. For example, setting recursive to any of the following will enable returning objects or subtrees: 0, 1, "true", and "false". Omit this parameter to prevent recursively returning objects or subtrees.

SELECT examples

get_tree

Returns a single tree using the SHA1 value or ref name for that tree.

If truncated is true in the response then the number of items in the tree array exceeded our maximum limit. If you need to fetch more items, use the non-recursive method of fetching trees, and fetch one sub-tree at a time.

> [!NOTE]
> The limit for the tree array is 100,000 entries with a maximum size of 7 MB when using the recursive parameter.

SELECT
sha,
tree,
truncated,
url
FROM github.git.trees
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND tree_sha = '{{ tree_sha }}' -- required
AND recursive = '{{ recursive }}'
;

INSERT examples

create_tree

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.

INSERT INTO github.git.trees (
tree,
base_tree,
owner,
repo
)
SELECT 
'{{ tree }}' /* required */,
'{{ base_tree }}',
'{{ owner }}',
'{{ repo }}'
RETURNING
sha,
tree,
truncated,
url
;

Manifest

# Description fields are for documentation purposes
- name: trees
props:
  - name: owner
    value: "{{ owner }}"
    description: Required parameter for the trees resource.
  - name: repo
    value: "{{ repo }}"
    description: Required parameter for the trees resource.
  - name: tree
    description: |
      Objects (of `path`, `mode`, `type`, and `sha`) specifying a tree structure.
    value:
      - path: "{{ path }}"
        mode: "{{ mode }}"
        type: "{{ type }}"
        sha: "{{ sha }}"
        content: "{{ content }}"
  - name: base_tree
    value: "{{ base_tree }}"
    description: |
      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.