Repository Forks

A fork is an independent copy of an existing Code Storage repository. It starts from one source commit and has its own branches and access. After the copy, a change in one repository does not reach the other.

When to use a fork

Templates: Create new projects from a starter template
Experiments: Test changes in an independent repository
Snapshots: Capture a repository’s state at a specific commit or branch
Isolation: Separate work across a trust or tenant boundary, or give each user an independent project of their own

For per-agent and per-task isolation inside a single repository, use the ephemeral namespace instead. Those branches share the repository’s Git objects and its access, and you can promote the work you keep.

Quick start

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
  },
});

import os
from pierre_storage import GitStorage

storage = GitStorage({
    "name": "your-org",
    "key": os.environ["PIERRE_PRIVATE_KEY"],
})

# Fork at the latest commit (HEAD)
fork = await storage.create_repo(
    id="my-fork",
    base_repo={
        "id": "template-repo",  # Source repository ID
    },
)

# Fork at a specific branch
branch_fork = await storage.create_repo(
    id="feature-fork",
    base_repo={
        "id": "template-repo",
        "ref": "develop",  # Fork from tip of 'develop' branch
    },
)

# Fork at a specific commit
commit_fork = await storage.create_repo(
    id="snapshot-fork",
    base_repo={
        "id": "template-repo",
        "sha": "abc123def456...",  # Fork at exact commit
    },
)

ctx := context.Background()

// Fork at the latest commit (HEAD)
fork, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
	ID: "my-fork",
	BaseRepo: storage.ForkBaseRepo{
		ID: "template-repo",
	},
})

// Fork at a specific branch
branchFork, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
	ID: "feature-fork",
	BaseRepo: storage.ForkBaseRepo{
		ID:  "template-repo",
		Ref: "develop",
	},
})

// Fork at a specific commit
commitFork, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
	ID: "snapshot-fork",
	BaseRepo: storage.ForkBaseRepo{
		ID:  "template-repo",
		SHA: "abc123def456...",
	},
})

baseRepo takes id, ref, and sha. See createRepo() for the full parameter list and resolution order. That page also explains which default branch the fork inherits.

Use cases

Project templates

Create new projects from a starter template:

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: 'system@example.com' },
    })
    .addFileFromString('README.md', `# ${projectName}\n\nCreated by ${userId}`)
    .send();

  return project;
}

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

async def create_project_from_template(
    template_id: str,
    project_name: str,
    user_id: str
):
    project = await storage.create_repo(
        id=f"{user_id}/{project_name}",
        base_repo={"id": template_id},
    )

    # Customize the new project
    commit = project.create_commit(
        target_branch="main",
        commit_message="Initialize project",
        author={"name": "System", "email": "system@example.com"},
    )
    commit.add_file_from_string(
        "README.md",
        f"# {project_name}\n\nCreated by {user_id}"
    )
    await commit.send()

    return project

# Usage
project = await create_project_from_template(
    "templates/react-starter",
    "my-new-app",
    "user-123"
)

func createProjectFromTemplate(ctx context.Context, templateID, projectName, userID string) (*storage.Repo, error) {
	// Fork the template repo
	project, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
		ID:       userID + "/" + projectName,
		BaseRepo: storage.ForkBaseRepo{ID: templateID},
	})
	if err != nil {
		return nil, err
	}

	// Customize the new project
	builder, err := project.CreateCommit(storage.CommitOptions{
		TargetBranch:  "main",
		CommitMessage: "Initialize project",
		Author:        storage.CommitSignature{Name: "System", Email: "system@example.com"},
	})
	if err != nil {
		return nil, err
	}

	_, err = builder.AddFileFromString(
		"README.md",
		"# "+projectName+"\n\nCreated by "+userID,
		nil,
	).Send(ctx)
	if err != nil {
		return nil, err
	}

	return project, nil
}

// Usage
project, err := createProjectFromTemplate(context.Background(), "templates/react-starter", "my-new-app", "user-123")

Point-in-time snapshots

Capture a repository’s state before you make risky changes:

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');

async def create_snapshot(repo_id: str, label: str):
    source = await storage.find_one(id=repo_id)
    commits = await source.list_commits(limit=1)
    head_sha = commits["commits"][0]["sha"]

    snapshot = await storage.create_repo(
        id=f"snapshots/{repo_id}/{label}",
        base_repo={
            "id": repo_id,
            "sha": head_sha,
        },
    )

    return snapshot

# Before a major refactor
backup = await create_snapshot("my-project", "pre-refactor-2024-01")

func createSnapshot(ctx context.Context, repoID, label string) (*storage.Repo, error) {
	// Capture the current HEAD SHA
	source, err := client.FindOne(ctx, storage.FindOneOptions{ID: repoID})
	if err != nil {
		return nil, err
	}
	commits, err := source.ListCommits(ctx, storage.ListCommitsOptions{Limit: 1})
	if err != nil {
		return nil, err
	}
	headSHA := commits.Commits[0].SHA

	// Fork at the captured commit
	return client.CreateRepo(ctx, storage.CreateRepoOptions{
		ID: "snapshots/" + repoID + "/" + label,
		BaseRepo: storage.ForkBaseRepo{
			ID:  repoID,
			SHA: headSHA,
		},
	})
}

// Before a major refactor
backup, err := createSnapshot(context.Background(), "my-project", "pre-refactor-2024-01")

Fork or sync

`operation`	Source	Ongoing connection	Best for
`fork`	A Code Storage repository	No	Templates, snapshots, isolated copies
`sync`	An external Git provider	Yes	Repositories that should stay mirrored

Limitations

Same organization: You can only fork repositories within your own organization
No relationship tracking: Forks are independent. Code Storage keeps no “parent” reference after creation. No route merges a fork back into its source
No upstream: A fork records no upstream, so pullUpstream() on a fork returns HTTP 400 with repository has no upstream configured. To get later changes, add the source repository as a second Git remote. Fetch and merge the changes
Full copy: Forks include all branches and history up to the fork point

Getting Started

Features

Workflows

Reference

When to use a fork

Quick start

Use cases

Project templates

Point-in-time snapshots

Fork or sync

Limitations

​When to use a fork

​Quick start

​Use cases

​Project templates

​Point-in-time snapshots

​Fork or sync

​Limitations

When to use a fork

Quick start

Use cases

Project templates

Point-in-time snapshots

Fork or sync

Limitations