> ## 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 Git source of truth for versioned 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, persist 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>