> ## Documentation Index
> Fetch the complete documentation index at: https://code.storage/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

Code.Storage is a managed Git infrastructure layer that provides repository creation, commits, branching, and merge operations through SDK and HTTP interfaces.

See [Quickstart](/getting-started/quickstart) to create your first repository.

## Setup

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"min-dark"}}
  import { GitStorage } from '@pierre/storage';

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

  const repo = await store.createRepo({ id: 'new-workspace' });

  const result = await repo
    .createCommit({
      targetBranch: 'main',
      commitMessage: 'Get Started with Code Storage',
      author: { name: 'Pierre', email: 'pierre@pierre.co' },
    })
    .addFileFromString('README.md', '# Getting Started\n')
    .addFileFromString('main.ts', 'console.log("Hello from Code Storage");')
    .send();

  console.log(result.commitSha);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"min-dark"}}
  from pierre_storage import GitStorage

  storage = GitStorage({
      "name": "your-org",
      "key": "your-private-key",  # PEM format
  })

  repo = await storage.create_repo(id="new-workspace")

  result = await (
      repo.create_commit(
          target_branch="main",
          commit_message="Get Started with Code Storage",
          author={"name": "Pierre", "email": "pierre@pierre.co"},
      )
      .add_file_from_string("README.md", "# Getting Started\n")
      .add_file_from_string("main.py", "print('Hello from Code Storage')")
      .send()
  )

  print(result["commit_sha"])
  ```

  ```go Go theme={"theme":{"light":"github-light","dark":"min-dark"}}
  client, err := storage.NewClient(storage.Options{
      Name: "your-org",
      Key:  os.Getenv("PIERRE_PRIVATE_KEY"),
  })
  if err != nil {
      return fmt.Errorf("failed to create client: %w", err)
  }

  ctx := context.Background() // or from an existing context
  repo, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
      ID: "new-workspace",
  })
  if err != nil {
      return fmt.Errorf("failed to create repository: %w", err)
  }

  builder, err := repo.CreateCommit(storage.CommitOptions{
      TargetBranch:  "main",
      CommitMessage: "Get Started with Code Storage",
      Author:        storage.CommitSignature{
          Name:  "Your Name", 
          Email: "you@example.com",
      },
  })
  if err != nil {
      return fmt.Errorf("failed to create commit: %w", err)
  }

  result, err := builder.
      AddFileFromString("README.md", "# Getting Started\n", nil).
      AddFileFromString("main.go", "package main\n\nfunc main() {}\n", nil).
      Send(ctx)
  if err != nil {
      return fmt.Errorf("failed to add file: %w", err)
  }
  fmt.Println("Commit SHA:", result.CommitSHA)
  ```

  ```bash HTTP theme={"theme":{"light":"github-light","dark":"min-dark"}}
  export CODE_STORAGE_BASE_URL="https://api.your-org.code.storage/api"
  export CODE_STORAGE_TOKEN="YOUR_JWT_TOKEN"

  curl "$CODE_STORAGE_BASE_URL/repos" \
    -X POST \
    -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"default_branch": "main"}'
  ```
</CodeGroup>

Authentication uses ES256 or RS256 JWT tokens signed with your private key. See [Authentication](/getting-started/authentication) for key generation and token minting.

## What Code Storage provides

Every repository is backed by real Git storage with standard semantics:

* **Branches and refs** – create, delete, and list branches; fast-forward and force-push operations
* **Commits** – write files, read tree state, traverse commit history
* [**Git protocol**](/guides/git-operations) – clone, push, and fetch over HTTPS using standard Git clients
* [**Webhooks**](/guides/webhooks) – subscribe to push and repo sync events for CI integration
* [**Integrations**](/guides/integrations) – bidirectional sync with GitHub and other Git providers

Extended features for automation:

* [**Ephemeral branches**](/guides/ephemeral-branches) – temporary branches isolated from your default namespace
* **Direct writes** – create commits without local Git operations
* **Warm/cold tiering** – automatic cost optimization based on access patterns

## Where to go next

* [**Getting Started**](/getting-started/quickstart) – Create your first repository and commit
* [**Core Concepts**](/getting-started/core-concepts) – Repositories, authentication, and permissions
* [**Guides**](/guides/git-operations) – Using Git commands, ephemeral branches, webhooks, and integrations
* [**Reference**](/reference/sdk) – Complete SDK and HTTP API documentation

For technical details on architecture, consistency guarantees, and performance tradeoffs, see the [HTTP API Overview](/reference/api/overview).