---
title: "Git API"
description: "Read and modify repository data through Freestyle Git APIs."
url: "/docs/git/api"
---

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


## Get File Or Directory Contents

```ts
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:

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

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


## Download Archives

```ts
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

```ts
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:

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

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

Set the default branch:

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


## Commits

List commits:

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

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

Create a commit by writing file changes:

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


## Tags

```ts
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.

```ts
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.