FreestyleGetting Started with Git
This document provides a technical introduction to using Freestyle's Git service.
For a high-level overview of the service, its features and why to use it see About Freestyle Git.
Sign up at admin.freestyle.sh, create an api key, and configure it in your environment.
FREESTYLE_API_KEY=your-api-keynpm i freestyle-sandboxes@betaCreating a Git Repository
Calling create in the git.repos namespace will create a new empty git
repository.
import { freestyle } from "freestyle-sandboxes";
const { repo } = await freestyle.git.repos.create();You can also fork an existing repository and all its history by providing the URL and branch.
await freestyle.git.repos.create({
source: {
url: "https://github.com/user/repo.git",
}
});Or you can import a repository's files directly without any history. Raw files,
tar urls, and zip urls are also supported types under import.
Imports require a commit message to be provided for the initial commit.
await freestyle.git.repos.create({
import: {
type: "git",
commitMessage: "import from git",
url: "https://github.com/user/repo.git",
},
});Authentication
By default git repositories are private. To clone one, so you'll need to create a freestyle identity and access token.
const { identity } = await freestyle.identities.create();
await identity.permissions.git.grant({
permission: "write",
repoId: repoId,
});
const { token } = await identity.tokens.create();
console.log(`git clone https://x-access-token:${token}@git.freestyle.sh/${repoId}`);You can also use bearer auth and your freestyle api key to clone a repository. This is mostly useful for testing.
git -c http.extraHeader "Authorization: Bearer <your-api-key>" clone https://git.freestyle.sh/<repo-id>Public repositories can be cloned without authentication, but you'll still need authentication to push changes.
await freestyle.git.repos.create({
public: true,
});Accessing Repository Contents
You can use the contents namespace to read files in a git repository without cloning it.
const repo = freestyle.git.repos.ref({ repoId: "your-repo-id" });
// Get a file's contents (base64 encoded)
const file = await repo.contents.get({ path: "README.md" });
const content = atob(file.content);
// Get contents at a specific branch, tag, or commit
const oldFile = await repo.contents.get({
path: "src/index.ts",
rev: "v1.0.0",
});
// Get a directory listing
const dir = await repo.contents.get({ path: "src" });Download an entire repository as a tarball or zip file.
// Download as tarball
const tarball = await repo.contents.downloadTarball({ rev: "main" });
// Download as zip
const zip = await repo.contents.downloadZip({ rev: "main" });Comparing Commits
Compare two revisions (branches, tags, or commit SHAs) to see the differences.
const repo = freestyle.git.repos.ref({ repoId: "your-repo-id" });
const diff = await repo.compare({
base: "main",
head: "feature-branch",
});
console.log(diff.status); // "identical" | "ahead" | "behind" | "diverged"
console.log(diff.ahead_by); // commits head is ahead of base
console.log(diff.behind_by); // commits head is behind base
console.log(diff.total_commits);
for (const file of diff.files) {
console.log(`${file.status}: ${file.filename} (+${file.additions} -${file.deletions})`);
}