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

# Repos and worktrees

> How ADE maps Git repositories to projects and worktrees to lanes — and what happens when you open a worktree directly.

ADE has one rule for organizing your work: **a repository is one project, and every working tree of that repository is a lane inside it.**

* The repository's main checkout is the project root. It becomes the **primary lane**, which always exists and is edit-protected.
* Lanes ADE creates for you live under `.ade/worktrees/` inside the project.
* Worktrees you created yourself with `git worktree add` can be attached as lanes too, wherever they live on disk.

This is why a worktree should not become its own project: it would split the same repository across two project entries, with separate lanes, chats, and state for what is really one codebase.

## Opening a worktree

If you point ADE at a directory that is a linked worktree, ADE recognizes it and shows you what it found:

* **Already a lane** — the folder is already attached to its project. ADE offers to open that project and jump straight to the lane, including its live status and any agents working in it.
* **Not a lane yet** — ADE offers to attach it as a lane in the owning project and take you there. This is the recommended path.
* **Owning repo not added yet** — ADE offers to add the main repository as the project and open the worktree as a lane in it, in one step.

You can still choose **Open as a separate project** if you really want the worktree to stand alone — for example, if your main clone is a bare repository and there is no primary checkout to open.

## Merging a stray worktree project

If you added a worktree as a standalone project in the past, ADE marks it in the recent projects list with a *worktree of …* badge. From that row you can merge it into the owning project as a lane.

<Warning>
  Merging re-homes the folder as a lane and removes the standalone project entry. Chats and sessions created while it was a standalone project stay under that retired project — they remain searchable, but they do not move into the owning project.
</Warning>

## Bare repositories

Some workflows keep a bare clone plus a set of worktrees, with no main checkout at all. ADE cannot open a bare repository as a project today, so in that layout opening a worktree as its own project is the right call. ADE detects this case and skips the prompt.