From 6708a25004286fe5da2010a6c819e09ad7689e7b Mon Sep 17 00:00:00 2001 From: Dino Date: Fri, 2 Oct 2026 10:04:50 +0000 Subject: [PATCH] docs: Document default open behavior setting (#64610) # Objective Update https://zed.dev/docs to include documentation for the `default_open_behavior` setting, introduced by #58805, just like we do for `cli_default_open_behavior`. This was discovered while I was revisiting https://github.com/zed-industries/zed/discussions/44355 . ## Solution Update the documentation for the `Windows & Projects > Opening in a New Window > Via Settings` section. ## Testing Used `mdbook serve docs` to build the documentation and review the edits. ## Self-Review Checklist: - [x] I've reviewed my own diff for quality, security, and reliability - [x] Unsafe blocks (if any) have justifying comments - [x] The content adheres to Zed's UI standards ([UX/UI](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md#uiux-checklist) and [icon](https://github.com/zed-industries/zed/blob/main/crates/icons/README.md) guidelines) - [x] Tests cover the new/changed behavior - [x] Performance impact has been considered and is acceptable ## Showcase
Before CleanShot 2026-09-22 at 16 27
41@2x
After CleanShot 2026-09-22 at 16 27
03@2x
--- Release Notes: - N/A --- docs/src/windows-and-projects.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/src/windows-and-projects.md b/docs/src/windows-and-projects.md index 3a821a71f20..d81ee64083f 100644 --- a/docs/src/windows-and-projects.md +++ b/docs/src/windows-and-projects.md @@ -62,20 +62,23 @@ See [CLI Reference](./reference/cli.md) for full details. ### Via Settings -You can change the default CLI behavior with the `cli_default_open_behavior` setting: +You can change the default behavior by setting `cli_default_open_behavior`, which controls CLI opens, and `default_open_behavior`, which controls UI project opens and external open requests, such as macOS Finder's `Open With > Zed`. + +To use separate windows, open the Settings Editor and search for `CLI Default Open Behavior` or `Default Open Behavior`, setting either or both to `new_window`. Or add this to your settings.json: ```json [settings] { + "default_open_behavior": "new_window", "cli_default_open_behavior": "new_window" } ``` -Options: +Both settings accept the same values: -- `existing_window` (default): Open folders in the current window's threads sidebar -- `new_window`: Open folders in a new window +- `existing_window` (default): Open folders in the current window's threads sidebar. Files outside any open project can also open in an existing window. +- `new_window`: Prefer a new window. For external or CLI file opens, a non-ignored file inside an already-open project opens in that project's window while an unrelated file opens in a new window. -This setting affects CLI and double-click behavior, not the File > Open menu. +It's worth noting that explicit flags provided to the CLI will override the CLI setting. In particular, `-n` forces a new window even when a path matches an open project. See [CLI Reference](./reference/cli.md) for the available flags. ## Adding Folders to a Project