Project

Active contributors: SomeoneToIgnore, Veykril, smitbarmase, ConradIrwin

Purpose

crates/project is the model of "an open project." It owns worktrees, language servers, debug adapters, tasks, terminals, collaborators, search results, and snippets. Every editor view ultimately gets its buffer from a Project. Together with crates/worktree (file watching) and crates/fs (filesystem abstraction), it forms the layer between the OS and the editor.

Directory layout

crates/project/        ~90k LOC
├── Cargo.toml
├── src/
│   ├── project.rs                     # Module root
│   ├── ...                            # ~60 modules: lsp_store, debug_store,
│   │                                  #              git_store, terminals,
│   │                                  #              search, task_store, ...
└── tests/                             # Integration tests using FakeFs

crates/worktree/       ~17k LOC — file watching + entry trees
crates/fs/             — Fs / RealFs / FakeFs / SshFs

Key abstractions

Type / module	File (typical)	Description
Project	crates/project/src/project.rs	The Entity<Project>. Owns everything below
Worktree	crates/worktree/src/worktree.rs	A single root folder with watched entries
Fs, RealFs, FakeFs, SshFs	crates/fs/src/fs.rs	Filesystem trait + impls (local, in-memory, remote)
LspStore	crates/project/src/lsp_store.rs	LSP server registry per project
DebuggerStore	crates/project/src/debugger.rs (and friends)	DAP session registry
TaskStore	crates/project/src/task_store.rs	Tasks (build/run/test) defined per project
GitStore	crates/project/src/git_store.rs	Git status / blame / branch / diff cache
TerminalStore	crates/project/src/terminals.rs	Project-scoped terminal sessions
SearchQuery	crates/project/src/search.rs	Workspace-wide find/replace
Buffer	crates/language/src/buffer.rs	A loaded text document (defined in language, owned via Project)

How it works

graph TD
    Z[zed app] --> WS[Workspace]
    WS --> P[Project]
    P --> WT[Worktree]
    WT --> FS[Fs]
    P --> LSP[LspStore]
    LSP -->|stdio| LS[LSP servers]
    P --> DAP[DebuggerStore]
    DAP -->|stdio| DA[DAP adapters]
    P --> TS[TaskStore]
    P --> TERM[TerminalStore]
    P --> GS[GitStore]
    P --> COL[Collaboration state]
    COL -->|RPC| Server[collab]

Buffer lifecycle

A Buffer is created lazily when you open a path. The Project ensures only one Buffer exists per file path; MultiBuffers and Editors share that buffer via Entity<Buffer> handles. Edits are propagated through GPUI events, with CRDT-flavored anchors that survive concurrent edits from collaborators.

Worktrees and watching

Each open folder becomes a Worktree. The worktree:

• Performs an initial directory scan (parallelised across threads).
• Watches the OS for changes (notify on Linux/Windows, FSEvents on macOS).
• Maintains a snapshot of entries that the rest of the app subscribes to.

The Fs trait abstracts away the difference between a real filesystem and a remote/fake one. For remote development, SshFs (in crates/fs/src/sshfs.rs if present) tunnels filesystem calls over the same RPC channel as the rest of the project.

LSP wiring

LspStore matches files to languages (via crates/language) and starts language servers as needed. Each adapter (crates/lsp per-language code or crates/extension_host adapters from extensions) knows how to install, configure, and translate for one server.

Collaboration

When a project is shared, Project becomes a CRDT-aware view of state mirrored across hosts. Diffs flow over crates/rpc to crates/collab, which fans them out to other clients.

Integration points

• Above: crates/workspace (panes, tabs, docks) and the editor view consume Project.
• Below: crates/worktree, crates/fs, crates/language, crates/lsp, crates/dap, crates/task, crates/terminal, crates/git, crates/rpc.
• Tests: FakeFs plus a fake LSP make up most of the project test fixtures.

Entry points for modification

• New "store" attached to a project — add a module and field on Project, plus initialization in the constructor.
• New filesystem backend — implement Fs for it.
• New worktree behaviour — crates/worktree/src/worktree.rs.
• New protocol message touching projects — define in crates/proto, handle in both crates/project (client) and crates/collab (server).

Related pages

• Editor — the consumer of Project buffers
• LSP — what LspStore orchestrates
• DAP — what DebuggerStore orchestrates
• Remote development — Fs going over the wire
• Collaboration — Project shared across users