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

# Repository SDKs

> Create repositories, inspect refs, push worktrees, and merge branches from Python and TypeScript.

Use the repository SDKs to manage Tensorlake Git repositories from application code: create repositories, inspect branches and refs, mint Git credentials, push a local worktree, and run server-side merges.

Use `tl fs` for mounted file-system workflows such as `mount`, `snapshot`, `sync`, and `promote`.

## Install and Configure

The SDKs use a Tensorlake API key from the environment.

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install tensorlake

    export TENSORLAKE_API_KEY=tlk_...
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    npm install tensorlake

    export TENSORLAKE_API_KEY=tlk_...
    ```
  </Tab>
</Tabs>

PATs are CLI-only. Use an API key with the SDKs.

## Create and List Repositories

`RepositoryClient` is the entry point for repository operations.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from tensorlake import RepositoryClient

    with RepositoryClient.from_env() as repos:
        repo = repos.create("agent-outputs", default_branch="main")
        print(repo.url)

        for item in repos.list():
            print(item.name, item.default_branch, item.status)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { RepositoryClient } from "tensorlake";

    const repos = await RepositoryClient.fromEnv();

    const repo = await repos.create("agent-outputs", {
      defaultBranch: "main",
    });
    console.log(repo.url);

    for (const item of await repos.list()) {
      console.log(item.name, item.defaultBranch, item.status);
    }
    ```
  </Tab>
</Tabs>

Later examples assume `repos` is a `RepositoryClient` created with `from_env()` or `await fromEnv()`.

## Inspect Branches and Refs

Use `info` when you want the repository URL, branches, and refs in one call.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from tensorlake import RepositoryClient

    repos = RepositoryClient.from_env()
    info = repos.info("agent-outputs")

    print(info.url)
    for branch in info.branches:
        print(branch.name, branch.oid)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { RepositoryClient } from "tensorlake";

    const repos = await RepositoryClient.fromEnv();
    const info = await repos.info("agent-outputs");

    console.log(info.url);
    for (const branch of info.branches) {
      console.log(branch.name, branch.oid);
    }
    ```
  </Tab>
</Tabs>

## Get a Git Credential

Most SDK methods mint short-lived Git credentials automatically. Call `credential` only when you need to hand a token to `git`, CI, or another HTTP client.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    credential = repos.credential("agent-outputs")

    print(credential.git_username)  # always "t"
    print(credential.token)         # use as the Git HTTP password
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const credential = await repos.credential("agent-outputs");

    console.log(credential.gitUsername); // always "t"
    console.log(credential.token);       // use as the Git HTTP password
    ```
  </Tab>
</Tabs>

## Push a Local Worktree

`push_worktree` creates one commit from a local directory and updates a branch. It skips `.git` and honors `.gitignore`.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    report = repos.push_worktree(
        "agent-outputs",
        root=".",
        branch="main",
        message="sync generated output",
    )

    print(report.commit)
    print(report.ref_name)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const report = await repos.pushWorktree("agent-outputs", {
      path: process.cwd(),
      branch: "main",
      message: "sync generated output",
    });

    console.log(report.commit);
    console.log(report.refName);
    ```
  </Tab>
</Tabs>

Pass `expect_oid` in Python or `expectOid` in TypeScript when you want the push to fail if the branch moved.

## Merge Branches

Use `merge` to merge one branch or commit into another without cloning the repository.

Preflight first when you want to see whether a merge is clean:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    report = repos.merge(
        "agent-outputs",
        "main",
        "feature",
        preflight=True,
        deep=True,
    )

    if report.clean:
        landed = repos.merge(
            "agent-outputs",
            "main",
            "feature",
            message="merge feature into main",
        )
        print(landed.commit)
    else:
        for conflict in report.conflicts:
            print(conflict.kind, conflict.path)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const report = await repos.merge("agent-outputs", "main", "feature", {
      preflight: true,
      deep: true,
    });

    if (report.clean) {
      const landed = await repos.merge("agent-outputs", "main", "feature", {
        message: "merge feature into main",
      });
      console.log(landed.commit);
    } else {
      for (const conflict of report.conflicts) {
        console.log(conflict.kind, conflict.path);
      }
    }
    ```
  </Tab>
</Tabs>

By default, a conflicted commit-mode merge publishes nothing and returns a report with `clean: false` and no `commit`.

Use `materialize` when you want conflicted files to land with standard Git diff3 markers:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    report = repos.merge(
        "agent-outputs",
        "main",
        "feature",
        materialize=True,
        message="merge feature into main",
    )

    if report.commit and not report.clean:
        record = repos.commit_conflicts("agent-outputs", report.commit)
        for path in (record.paths if record else []):
            print(path.kind, path.path)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const report = await repos.merge("agent-outputs", "main", "feature", {
      materialize: true,
      message: "merge feature into main",
    });

    if (report.commit && !report.clean) {
      const record = await repos.commitConflicts("agent-outputs", report.commit);
      for (const path of record?.paths ?? []) {
        console.log(path.kind, path.path);
      }
    }
    ```
  </Tab>
</Tabs>

## API Surface

| Task                | Python                                                        | TypeScript                                                 |
| ------------------- | ------------------------------------------------------------- | ---------------------------------------------------------- |
| Create a repository | `create(repo, default_branch=None)`                           | `create(repo, { defaultBranch })`                          |
| List repositories   | `list()`                                                      | `list()`                                                   |
| Delete a repository | `delete(repo)`                                                | `delete(repo)`                                             |
| Fork a repository   | `fork(repo, base_repo)`                                       | `fork(repo, baseRepo)`                                     |
| Archive or restore  | `archive(repo)`, `restore(repo)`                              | `archive(repo)`, `restore(repo)`                           |
| Repository URL      | `url(repo)`                                                   | `url(repo)`                                                |
| Branches and refs   | `info(repo)`, `branches(repo)`, `refs(repo)`                  | `info(repo)`, `branches(repo)`, `refs(repo)`               |
| Delete a branch     | `delete_branch(repo, branch)`                                 | `deleteBranch(repo, branch)`                               |
| Operation history   | `operations(repo)`                                            | `operations(repo)`                                         |
| Git credential      | `credential(repo=None)`                                       | `credential(repo)`                                         |
| Push local files    | `push_worktree(repo, root, branch, message, expect_oid=None)` | `pushWorktree(repo, { path, branch, message, expectOid })` |
| Push job status     | `commit_status(repo, job_id)`                                 | `commitStatus(repo, jobId)`                                |
| Merge branches      | `merge(repo, ours, theirs, ...)`                              | `merge(repo, ours, theirs, options)`                       |
| Conflict records    | `commit_conflicts(repo, commit)`                              | `commitConflicts(repo, commit)`                            |

## Next Steps

<CardGroup cols={2}>
  <Card title="Git Workflows" icon="code-commit" href="/filesystems/git-repositories">
    Use the same repositories with ordinary `git clone`, `git push`, and `git fetch`.
  </Card>

  <Card title="Generated Code" icon="code-branch" href="/filesystems/store-generated-code">
    Store code, docs, and assets produced by coding agents at repository scale.
  </Card>

  <Card title="Merging Changes" icon="code-merge" href="/filesystems/merging">
    Learn the merge behavior behind SDK and CLI merge operations.
  </Card>
</CardGroup>