FreestyleAdvanced Database API
Low-level API for working with Git objects (blobs, commits, trees, tags) in Freestyle repositories.
This is a low-level API for working directly with Git objects. For most use cases, the Git Serverless API provides simpler, higher-level methods for reading files, managing branches, and creating commits. Only use this API if you need direct access to Git internals.
The Git Database API provides low-level access to Git objects in your repositories. This API is useful for building tools that need to understand Git repository internals, inspect commit history, traverse directory trees, and read file contents at specific commits.
Overview
Git stores all data as objects of four fundamental types:
- Blobs - Raw file content
- Trees - Directory listings mapping names to blobs or other trees
- Commits - Snapshots of the repository at a specific point in time
- Tags - References to specific commits with additional metadata
This API provides direct access to these Git objects through REST endpoints.
Usage
Blobs
Blobs represent the content of files in Git. When you retrieve a blob, you get the raw file content (always base64 encoded for binary safety).
Get a Blob
import { freestyle } from "freestyle";
// Get reference to an existing repository
const repo = freestyle.git.repos.ref({
repoId: "your-repo-id"
});
// Get a blob by its SHA hash
const blob = await repo.blobs.get({
sha: "abc123..."
});
// Decode the base64 content
const decodedContent = atob(blob.content);
console.log(decodedContent);Response structure:
interface BlobObject {
// The blob content (base64 encoded)
content: string;
// Always "base64"
encoding: "base64";
// The blob's hash
sha: string;
}Commits
Commits represent snapshots of your repository at specific points in time.
Get a Commit
import { freestyle } from "freestyle";
// Get reference to an existing repository
const repo = freestyle.git.repos.ref({
repoId: "your-repo-id"
});
// Get a specific commit by its SHA hash
const commit = await repo.commits.get({
sha: "a1b2c3d4e5f6..."
});
console.log(commit.message); // "feat: add new feature"
console.log(commit.author.name); // "John Doe"
console.log(commit.tree.sha); // Hash of the root treeResponse structure:
interface CommitObject {
// The commit author
author: {
date: string;
name: string;
email: string;
};
// The committer (may be different from author)
committer: {
date: string;
name: string;
email: string;
};
// The commit message
message: string;
// The tree this commit points to
tree: {
sha: string;
};
// Parent commits (usually one, multiple for merge commits)
parents: Array<{
sha: string;
}>;
// The commit's hash
sha: string;
}List Commits
import { freestyle } from "freestyle";
// Get reference to an existing repository
const repo = freestyle.git.repos.ref({
repoId: "your-repo-id"
});
// List recent commits
const commits = await repo.commits.list();
for (const commit of commits) {
console.log(`${commit.sha.slice(0, 7)} - ${commit.message}`);
}Trees
Trees represent directories in Git. A tree object contains a list of entries, each with a name, type (blob or tree), and hash.
Get a Tree
import { freestyle } from "freestyle";
// Get reference to an existing repository
const repo = freestyle.git.repos.ref({
repoId: "your-repo-id"
});
// Get a commit to find its tree hash
const commit = await repo.commits.get({
sha: "a1b2c3d4e5f6..."
});
// Fetch the tree (directory listing) for that commit
const tree = await repo.trees.get({
sha: commit.tree.sha
});
// Inspect files and subdirectories
for (const entry of tree.tree) {
if (entry.type === "blob") {
console.log(`File: ${entry.path}`);
} else if (entry.type === "tree") {
console.log(`Directory: ${entry.path}`);
}
}Response structure:
interface TreeObject {
// The tree's entries (files and subdirectories)
tree: Array<{
// The entry's type: "blob" (file) or "tree" (directory)
type: "blob" | "tree";
// The entry's path (filename or directory name)
path: string;
// The entry's hash
sha: string;
}>;
// The tree's hash
sha: string;
}Tags
Tags are references to specific objects (usually commits) with additional metadata like tagger information and a message.
Get a Tag
Response structure:
interface TagObject {
// The tag name
name: string;
// The tagger (may be null for lightweight tags)
tagger?: {
date: string;
name: string;
email: string;
};
// The tag message (may be null for lightweight tags)
message?: string;
// The object this tag points to (usually a commit)
target: {
sha: string;
};
// The tag's hash
sha: string;
}