Forking Repositories

Create lightweight copies of existing repositories for experimentation, templates, and isolated development.

Forking creates a new repository from an existing Code Storage repository at a specific point in time. Unlike GitHub sync (which maintains a live connection), forks are independent copies—changes to the original don’t affect the fork, and vice versa.

When to use forking

• Templates: Create new projects from a starter template
• Experimentation: Test changes without affecting the original repository
• Snapshots: Capture a repository’s state at a specific commit or branch
• Isolation: Give each user or agent their own copy to work with

Quick start

TypeScript

import { GitStorage } from '@pierre/storage';

const store = new GitStorage({
  name: 'your-org',
  key: process.env.PIERRE_PRIVATE_KEY,
});

// Fork at the latest commit (HEAD)
const fork = await store.createRepo({
  id: 'my-fork',
  baseRepo: {
    id: 'template-repo',  // Source repository ID
  },
});

// Fork at a specific branch
const branchFork = await store.createRepo({
  id: 'feature-fork',
  baseRepo: {
    id: 'template-repo',
    ref: 'develop',  // Fork from tip of 'develop' branch
  },
});

// Fork at a specific commit
const commitFork = await store.createRepo({
  id: 'snapshot-fork',
  baseRepo: {
    id: 'template-repo',
    sha: 'abc123def456...',  // Fork at exact commit
  },
});

Fork options

Parameter	Type	Description
id	Required	The repository ID (name) to fork from
ref	Optional	Branch or tag name to fork from. Forks the tip of this ref.
sha	Optional	Exact commit SHA to fork at. Overrides ref if both are provided.

Resolution order:

1. If sha is provided, fork at that exact commit
2. If ref is provided, fork at the tip of that branch/tag
3. Otherwise, fork at the source repository’s HEAD

Default branch behavior

The forked repository inherits the default branch from the source:

TypeScript

// Source repo has 'main' as default branch
const fork = await store.createRepo({
  baseRepo: { id: 'source-repo' },
});
console.log(fork.defaultBranch); // 'main' (inherited)

// Override the default branch
const customFork = await store.createRepo({
  baseRepo: { id: 'source-repo' },
  defaultBranch: 'develop',
});
console.log(customFork.defaultBranch); // 'develop'

Use cases

Project templates

Create new projects from a starter template:

TypeScript

async function createProjectFromTemplate(
  templateId: string,
  projectName: string,
  userId: string
) {
  const project = await store.createRepo({
    id: `${userId}/${projectName}`,
    baseRepo: { id: templateId },
  });

  // Customize the new project
  await project.createCommit({
    targetBranch: 'main',
    commitMessage: 'Initialize project',
    author: { name: 'System', email: '[e-mail]' },
  })
    .addFileFromString('README.md', `# ${projectName}\n\nCreated by ${userId}`)
    .send();

  return project;
}

// Usage
const project = await createProjectFromTemplate(
  'templates/react-starter',
  'my-new-app',
  'user-123'
);

Per-agent workspaces

Give each AI agent its own isolated copy:

TypeScript

async function createAgentWorkspace(
  sourceRepo: string,
  agentId: string,
  taskId: string
) {
  // Fork the source repo for this agent's task
  const workspace = await store.createRepo({
    id: `agents/${agentId}/${taskId}`,
    baseRepo: { id: sourceRepo },
  });

  // Agent can now work independently
  const url = await workspace.getRemoteURL({
    permissions: ['git:read', 'git:write'],
    ttl: 3600,
  });

  return { workspace, url };
}

Point-in-time snapshots

Capture a repository’s state before making risky changes:

TypeScript

async function createSnapshot(repoId: string, label: string) {
  const source = await store.findOne({ id: repoId });
  const commits = await source.listCommits({ limit: 1 });
  const headSha = commits.commits[0].sha;

  const snapshot = await store.createRepo({
    id: `snapshots/${repoId}/${label}`,
    baseRepo: {
      id: repoId,
      sha: headSha,
    },
  });

  return snapshot;
}

// Before a major refactor
const backup = await createSnapshot('my-project', 'pre-refactor-2024-01');

Forking vs GitHub sync

Feature	Forking	GitHub Sync
Source	Code Storage repositories	GitHub repositories
Connection	One-time copy	Continuous sync
Updates	Independent after fork	Automatically synced
Use case	Templates, snapshots, isolation	Mirror GitHub repos

Use forking when you want an independent copy. Use GitHub sync when you want to maintain a live connection to a GitHub repository.

Limitations

• Same organization: You can only fork repositories within your own organization
• No relationship tracking: Forks are independent—there’s no “parent” reference after creation
• Full copy: Forks include all branches and history up to the fork point