Git API

Use the Git API when your application needs repository data without cloning locally.

Get File Or Directory Contents

import { freestyle } from "freestyle";

const repo = freestyle.git.repos.ref({
  repoId: "your-repo-id",
});

const file = await repo.contents.get({
  path: "src/index.ts",
  rev: "main",
});

console.log(atob(file.content));

Directory responses include nested entries:

const dir = await repo.contents.get({
  path: "src",
  rev: "main",
});

for (const entry of dir.entries) {
  console.log(entry.path, entry.type);
}

Download Archives

import { writeFile } from "node:fs/promises";

const tarball = await repo.contents.downloadTarball({ rev: "main" });
await writeFile("repo.tar", Buffer.from(tarball));

const zip = await repo.contents.downloadZip({ rev: "main" });
await writeFile("repo.zip", Buffer.from(zip));

Branches

const branch = await repo.branches.get({ branchName: "main" });
console.log(branch.sha);

const branches = await repo.branches.list();
for (const branch of branches) {
  console.log(branch.name);
}

Create a branch:

await repo.branches.create({
  name: "feature/new-flow",
});

await repo.branches.create({
  name: "feature/from-commit",
  sha: "a1b2c3d4e5f6",
});

Set the default branch:

await repo.branches.setDefaultBranch({
  defaultBranch: "main",
});

Commits

List commits:

const commits = await repo.commits.list();

for (const commit of commits) {
  console.log(commit.sha, commit.message);
}

Create a commit by writing file changes:

await repo.commits.create({
  branch: "main",
  message: "Update README",
  files: {
    "README.md": {
      content: "# Updated README\n",
    },
  },
});

Tags

const tags = await repo.tags.list();

const tag = await repo.tags.get({
  tagName: "v1.0.0",
});

console.log(tag.sha);

Raw Git Objects

For tools that need Git internals, Freestyle exposes blobs, trees, commits, and tags by object hash.

const blob = await repo.blobs.get({
  sha: "abc123",
});

const tree = await repo.trees.get({
  sha: "def456",
});

const commit = await repo.commits.get({
  sha: "a1b2c3",
});

Prefer the high-level contents, branches, commits, and tags APIs unless your product needs direct object access.