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

# Multi-Repo Workspaces

> Set up and work with multiple repositories in a single Tempo workspace using git submodules.

# Multi-Repo Workspaces

Tempo supports working across multiple repositories within a single workspace. This is ideal for projects where your frontend, backend, shared libraries, or other services live in separate repos but need to be developed together.

Multi-repo in Tempo is powered by **git submodules**. This guide walks you through setting everything up and using Tempo's git features across all your repos.

<Info>
  Setup and git operations like commit, push, pull, and PR creation are all done through Tempo's AI chat — you won't need to open a terminal. File-level actions like staging, unstaging, and discarding are done by clicking buttons directly in the Changes panel.
</Info>

***

## What Are Submodules?

A **git submodule** is a way to include one git repository inside another. Think of it like a bookmark — the parent repo doesn't contain the child repo's files directly. Instead, it stores a pointer (a specific commit reference) to the child repo.

### Why submodules are required

When you have multiple repos inside a parent folder, git needs to know how to handle them. There are only two possibilities:

1. **As a submodule** — The child repo stays independent. It has its own branches, commits, and remote. The parent repo just tracks which commit the child is on.
2. **As regular files** — If a child directory is *not* a submodule, git treats its contents as part of the parent repo. All those files get committed directly into the parent.

<Warning>
  If your child repos are not set up as submodules, their entire contents will be committed to the parent repository. This means duplicate code, lost git history in the children, and a broken multi-repo workflow. Always use submodules.
</Warning>

### Submodule structure example

```
my-project/              ← Parent repo
├── .gitmodules          ← Submodule config (auto-generated)
├── frontend/            ← Submodule → points to github.com/org/frontend
├── backend/             ← Submodule → points to github.com/org/backend
└── shared/              ← Submodule → points to github.com/org/shared
```

Each child folder (`frontend/`, `backend/`, `shared/`) is its own git repository with its own remote, branches, and history.

***

## Setting Up Your Project

### Creating a new multi-repo project

If you're starting from scratch, ask the AI to create a parent repo and add your existing repos as submodules.

<Tip>
  **Prompt to send in Tempo:**

  ```
  Create a new git repository in this folder to serve as my multi-repo parent.
  Then add the following repos as git submodules:
  - https://github.com/my-org/frontend as frontend/
  - https://github.com/my-org/backend as backend/
  - https://github.com/my-org/shared-lib as shared/
  ```
</Tip>

The AI will:

1. Initialize a new git repository in the workspace root
2. Run `git submodule add` for each child repo
3. Create the `.gitmodules` file that tracks the submodule URLs and paths
4. Make an initial commit recording the submodule setup

### Adding a submodule to an existing project

If you already have a parent repo and want to add another child repo:

<Tip>
  **Prompt to send in Tempo:**

  ```
  Add https://github.com/my-org/analytics as a git submodule at analytics/
  ```
</Tip>

### Verifying your setup

To confirm everything is wired up correctly:

<Tip>
  **Prompt to send in Tempo:**

  ```
  Check my git submodule setup. List all submodules and verify they're
  properly initialized and pointing to the right remotes.
  ```
</Tip>

The AI will run `git submodule status` and report back the state of each submodule.

***

## Converting Existing Nested Repos to Submodules

If you already have child repos nested inside a parent folder but they were added as regular directories (not submodules), you need to convert them. This is a common situation — perhaps you cloned repos into a shared folder without setting up submodules first.

<Warning>
  Converting nested repos to submodules requires removing the directory from the parent's git tracking and re-adding it as a submodule. The AI will handle this safely, but make sure all work in the child repos is committed and pushed before starting.
</Warning>

<Tip>
  **Prompt to send in Tempo:**

  ```
  The frontend/ directory in my project is a separate git repo but it's
  not set up as a submodule — it's being tracked as regular files in the
  parent repo. Convert it to a proper git submodule pointing to
  https://github.com/my-org/frontend.
  ```
</Tip>

The AI will:

1. Remove the directory from the parent repo's index (without deleting the files)
2. Add it back as a proper submodule with `git submodule add`
3. Commit the conversion

Repeat this for each child repo that needs converting.

***

## Importing into Tempo

When importing a multi-repo project into Tempo, you must **select the parent folder** — not any of the individual child repos.

<Steps>
  <Step title="Open Tempo and create a new workspace">
    Click the "+" button to create a new workspace.
  </Step>

  <Step title="Select the parent folder">
    In the folder picker, navigate to and select your **parent repository folder** — the one that contains all the submodules.
  </Step>

  <Step title="Tempo detects submodules automatically">
    Tempo runs `git submodule status` to discover all child repos. You'll see each repo appear as a separate section in the Changes panel.
  </Step>
</Steps>

<Warning>
  **Always select the parent folder.** If you select an individual child repo instead, Tempo won't have visibility into the other repos. And if any child directories inside the parent are *not* submodules, Tempo will treat them as part of the parent repo — their files will show up in the parent's changes and get committed to it.
</Warning>

***

## Viewing Changes

Tempo's Changes panel (in the right sidebar) shows all modified files across your parent repo and every submodule. Files are grouped by repo so you always know which repository a change belongs to.

There are two view modes, and each repo can be set independently.

### Uncommitted Changes View

The **Uncommitted** view shows your working directory state — files you've modified, added, or deleted that haven't been committed yet.

Changes are organized into two sections per repo:

* **Staged** — Files queued for the next commit. These are ready to go.
* **Unstaged** — Files with changes that won't be included in a commit until you stage them.

**File actions** (hover over a file to see these):

* **Stage** — Move an unstaged file to the staged section
* **Unstage** — Move a staged file back to unstaged
* **View diff** — Open the diff for a staged file (file icon button)
* **Discard** — Revert a file to its last committed state (cannot be undone)

Clicking any file opens a diff view showing exactly what changed.

### vs Target Branch View

The **vs. Target Branch** view shows the cumulative diff between your current branch and a target branch (e.g., `main`). This is useful for reviewing everything that will be included in a pull request.

Each repo section has its own **target branch selector** — a compact pill showing the current target branch that opens a searchable dropdown where you pick which branch to compare against. By default, this is the repo's base branch (for submodules, Tempo auto-detects this from the remote's default branch).

When your branch is **behind** its remote upstream, a behind indicator appears with a **Pull** button to pull the latest changes.

### Per-Repo View Mode

When working with submodules, each repo section has its own view mode toggle. This means you can:

* View **uncommitted changes** in your frontend repo while simultaneously viewing the **vs. target branch diff** in your backend repo
* Switch modes per-repo without affecting the others
* Set different target branches for different repos

The toggle appears in each repo section as a dropdown below the section header.

***

## Committing Changes

Commits in a multi-repo workspace are per-repo — staged files in each submodule are committed to that submodule's repository.

### Committing with the header button

1. **Stage files** — In the Uncommitted view, click the **+** button on each file you want to commit
2. **Click "Commit"** in the header split button — This opens an AI chat that reviews your staged changes and creates commits with appropriate messages
3. The AI commits each repo separately — staged files in each submodule are committed to that submodule's repository

### AI-assisted commits

<Tip>
  **Prompt to send in Tempo:**

  ```
  Look at my uncommitted changes across all repos and create
  appropriate commits with good commit messages for each repo.
  ```
</Tip>

The AI knows which repos have uncommitted changes and will commit each repo separately with appropriate messages.

***

## Push and Pull

### Ahead/behind indicators

Tempo tracks how your branch relates to its remote:

* **Ahead** — You have local commits that haven't been pushed. Shown as "X commits ahead of origin".
* **Behind** — The remote has commits you haven't pulled. Shown as "X commits behind origin" with a **Pull** button.

These indicators appear in:

* The **Changes panel** — A behind indicator with a Pull button appears inline for each repo that is behind
* The **workspace sidebar** — A warning triangle icon appears when any repo is ahead or behind, with a tooltip showing the counts. Right-click to see Push/Pull options.
* The **workspace context menu** — Shows "N commits ahead — Push" and "N commits behind — Pull" options (only when applicable)

### Pushing changes

You can push from several places:

* **Header split button** — The "Commit" button in the app header has a dropdown with **Push** and **Create PR** options
* **Workspace context menu** — Right-click a workspace and select "N commits ahead — Push"

<Tip>
  **Prompt to send in Tempo:**

  ```
  Push all my committed changes across all repos to their remotes.
  ```
</Tip>

### Pulling changes

You can pull from several places:

* **Changes panel** — Click the **Pull** button next to the behind indicator for each repo
* **Workspace context menu** — Right-click a workspace and select "N commits behind — Pull"

<Tip>
  **Prompt to send in Tempo:**

  ```
  Pull the latest changes from the remote for all my repos.
  ```
</Tip>

### Publishing a new branch

If your branch doesn't exist on the remote yet, Tempo shows a **Publish** button instead of Push. This creates the remote branch and sets up tracking.

***

## AI-Assisted Workflows

Tempo's AI is aware of your full multi-repo context — all submodules, their branches, staged/unstaged changes, and ahead/behind status. Here are common prompts for multi-repo workflows:

### Generate commit messages

<Tip>
  **Prompt:**

  ```
  Review my changes across all repos and commit them with
  descriptive commit messages.
  ```
</Tip>

### Push everything

<Tip>
  **Prompt:**

  ```
  Push all committed changes in every repo to their remotes.
  ```
</Tip>

### Create a pull request

<Tip>
  **Prompt:**

  ```
  Create a pull request for my current branch. Include a summary
  of all the changes across all repos.
  ```
</Tip>

The AI will generate a PR description that accounts for changes in the parent repo and all submodules.

### Pull from target branch

<Tip>
  **Prompt:**

  ```
  Pull the latest changes from main into my current branch
  for all repos that are behind.
  ```
</Tip>

### Check sync status

<Tip>
  **Prompt:**

  ```
  Show me the git status of all my repos — which ones have
  uncommitted changes, which are ahead or behind their remote?
  ```
</Tip>