yenru0/zed

0 Fork 0

Files

T

morgankrey 508b107537 docs: Add Windows & Projects concept page (#56402 )

## Summary

- Adds a new concept page (`docs/src/windows-and-projects.md`)
explaining how Zed handles multiple projects in windows
- Fixes the VS Code migration guide which incorrectly stated "Zed does
not support multi-root workspaces"
- Adds cross-links from Getting Started, CLI Reference, and Parallel
Agents docs

## Context

With multi-workspace now universally enabled, the default behavior is:
- **File > Open** opens projects in the current window's sidebar (not a
new window)
- **Cmd+Enter** in Open Recent opens in a new window
- **CLI `-n` flag** forces a new window

The VS Code migration guide was telling users the opposite of reality.
This PR fixes that and provides a central concept page that other docs
can link to.

## Changes

| File | Change |
|------|--------|
| `windows-and-projects.md` | New concept page |
| `SUMMARY.md` | Add to Working with Code section |
| `getting-started.md` | Note about sidebar default + link |
| `migrate/vs-code.md` | Fix "no multi-root" claim → explain sidebar
model |
| `reference/cli.md` | Link to concept page from flags section |
| `ai/parallel-agents.md` | Cross-reference in Multiple Projects section
|

## Test plan

- [ ] Verify page renders correctly on docs site
- [ ] Check all internal links resolve
- [ ] Confirm `{#kb projects::OpenRecent}` renders the correct
keybinding

Release Notes:

- N/A

2026-05-11 21:07:13 +00:00

3.5 KiB

Raw Blame History

title, description

title	description
Windows & Projects	How Zed handles multiple projects in windows, including the threads sidebar and options for opening in new windows.

Windows & Projects

Zed lets you work on multiple projects in a single window. Projects appear in the threads sidebar on the left, and you can switch between them while keeping your context intact.

How Projects Open

By default, when you open a folder in Zed, it opens as a new project in your current window's threads sidebar rather than creating a new window. This keeps related work together and preserves your agent threads and layout.

Action	Result
File > Open	Opens in current window (threads sidebar)
File > Open Recent	Opens in current window (threads sidebar)
Drag folder to Zed	Opens in current window (threads sidebar)
`zed ~/project`	Opens in current window (threads sidebar)

Working with Multiple Projects

When you have multiple projects open:

Click a project header to collapse or expand its threads; Cmd+click (macOS) or Ctrl+click (Linux/Windows) to switch to that project
Each project has its own file tree, git state, and search scope
Agent threads are tied to their project context
Your workspace layout (splits, tabs) is preserved per project

Think of projects in the threads sidebar like browser tabs, but for repositories.

Opening in a New Window

Sometimes you want a completely separate window. Here's how:

From Open Recent

When using File > Open Recent ({#kb projects::OpenRecent}):

Enter or click opens in the current window (threads sidebar)
Cmd+Enter or Cmd+click (macOS) / Ctrl+Enter or Ctrl+click (Linux/Windows) opens in a new window

From the CLI

Use the -n flag to force a new window:

zed -n ~/projects/other-project

Other CLI options for controlling window behavior:

Flag	Behavior
`-n`, `--new`	Always open in a new window
`-a`, `--add`	Add to the current window's threads sidebar
`-r`, `--reuse`	Replace the current project in the existing window

See CLI Reference for full details.

Via Settings

You can change the default CLI behavior with the cli_default_open_behavior setting:

{
  "cli_default_open_behavior": "new_window"
}

Options:

existing_window (default): Open folders in the current window's threads sidebar
new_window: Open folders in a new window

This setting affects CLI and double-click behavior, not the File > Open menu.

Adding Folders to a Project

If you want to add a folder to your current project (not as a separate project in the threads sidebar), you have several options:

File menu: File > Add Folder to Project
Project panel: Right-click in the project panel and choose "Add Folders to Project"
Open Recent: Select a recent project and click the "Add Folder to this Project" button

This adds the folder as an additional root in your current project's file tree, similar to VS Code's multi-root workspaces.

3.5 KiB Raw Blame History