> ## 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.

# Git Repositories

> Use Tensorlake-hosted repositories with ordinary Git commands.

Tensorlake repositories are the backing store for Git-backed file systems. They speak the standard Git smart HTTP protocol, so you can clone, branch, commit, merge, push, and fetch with ordinary `git`.

This page covers the plain Git interface to the same repository that powers `tl fs` mounts. Use [File System Mounts](/filesystems/filesystem-mounts) when an agent should work inside a mounted directory, checkpoint with snapshots, and promote when ready.

Use [Repository SDKs](/filesystems/repository-sdks) when you want to create repositories, inspect refs, push worktrees, or merge branches from Python or TypeScript.

## Create a Repository

```bash theme={null}
$ tl git create agent-outputs --default-branch main
created https://git.tensorlake.ai/project_9f3c2a1b/agent-outputs
```

`project_9f3c2a1b` is the project your `tl` login is scoped to. You do not pass it to every command.

You can also create a repository lazily by pushing to a repository path that does not exist yet. Lazy creation only applies to `git push`; `git clone` and `git fetch` require the repository to already exist.

## Get a Credential

Tensorlake authenticates Git operations with HTTP Basic Auth, not SSH keys.

First make sure you are logged in:

```bash theme={null}
tl login
```

Then mint a short-lived repository credential:

```bash theme={null}
$ tl git token --repo agent-outputs
project: project_9f3c2a1b
repo: agent-outputs
username: t
password: eyJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJwcm9qZWN0XzlmM2MyYTFiIiwicmVwbyI6ImFnZW50LW91dHB1dHMifQ.Kx9f... (truncated)
expires: 2026-07-07T13:00:00Z
scopes: git:read, git:write
```

The username is always `t`. The password is the token.

## Clone

Use Git's credential store:

```bash theme={null}
git config --global credential.helper store
git clone https://git.tensorlake.ai/project_9f3c2a1b/agent-outputs
Username for 'https://git.tensorlake.ai': t
Password for 'https://t@git.tensorlake.ai': <paste the token>
```

Or embed the token in the URL for scripts and CI:

```bash theme={null}
TOKEN=$(tl git token --repo agent-outputs --json | jq -r .token)
git clone https://t:$TOKEN@git.tensorlake.ai/project_9f3c2a1b/agent-outputs
```

If the token is in a URL, treat the URL as a secret.

## Branch, Commit, and Push

From here, it is ordinary Git:

```bash theme={null}
git checkout -b feature
# edit files
git add .
git commit -m "implement parser"
git push origin feature
```

## Merge Changes

Tensorlake does not add a pull-request layer on top of Git repositories. Merge locally, then push the result:

```bash theme={null}
git checkout main
git pull origin main
git merge feature
git push origin main
```

A non-fast-forward push is rejected. Pull, resolve conflicts, and push again.

## What Plain Git Does Not Cover

* Workspaces, snapshots, and promotion are the `tl fs` model for agent sessions. See [File System Mounts](/filesystems/filesystem-mounts).
* Workspace refs such as `refs/workspaces/...` are reserved on the server and cannot be updated with direct `git push`.
* Archived repositories are read-only until restored with `tl git restore <repo>`.

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="book-open" href="/filesystems/core-concepts">
    Learn how repositories, workspaces, mounts, snapshots, and promotion fit together.
  </Card>

  <Card title="File System Mounts" icon="folder-tree" href="/filesystems/filesystem-mounts">
    Mount repositories as directories for agent sessions.
  </Card>

  <Card title="Repository SDKs" icon="rectangle-code" href="/filesystems/repository-sdks">
    Create repositories, push worktrees, and merge branches from Python or TypeScript.
  </Card>

  <Card title="Authentication" icon="key" href="/filesystems/authentication">
    `tl login`, Git credentials, scopes, and token lifetime.
  </Card>

  <Card title="Architecture" icon="cubes" href="/filesystems/architecture">
    How storage, lazy content delivery, merging, and observability work.
  </Card>
</CardGroup>