morgankrey and Katie Geer created
This draft PR auto-applies queued documentation suggestions collected
from recently merged PRs.
34 documentation suggestions from merged PRs were processed. See the
commit message for the full list.
Release Notes:
- N/A
---------
Co-authored-by: Katie Geer <katie@zed.dev>docs/src/ai/edit-prediction.md | 2
docs/src/finding-navigating.md | 14 +++++
docs/src/git.md | 27 +++++++++++
docs/src/globs.md | 17 ++++++
docs/src/languages/json.md | 14 ++++
docs/src/languages/yaml.md | 11 +++
docs/src/reference/all-settings.md | 78 +++++++++++++++++++++++++++++--
docs/src/reference/cli.md | 4 +
docs/src/repl.md | 40 +++++++++++++++
docs/src/tasks.md | 49 ++++++++++++++++++++
docs/src/vim.md | 47 ++++++++++--------
11 files changed, 265 insertions(+), 38 deletions(-)
@@ -301,6 +301,8 @@ Edit Prediction also works with other providers.
### GitHub Copilot {#github-copilot}
+> **Changed in Preview (v0.225).** See [release notes](/releases#0.225).
+
To use GitHub Copilot as your provider, set this in your settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
@@ -19,7 +19,19 @@ Open any file in your project with {#kb file_finder::Toggle}. Type part of the f
## Project Search
-Search across all files with {#kb pane::DeploySearch}. Results appear in a [multibuffer](./multibuffers.md), letting you edit matches in place.
+> **Changed in Preview (v0.225).** See [release notes](/releases#0.225).
+
+Search across all files with {#kb pane::DeploySearch}. Start typing in the search field to begin searching—results appear as you type.
+
+Results appear in a [multibuffer](./multibuffers.md), letting you edit matches in place.
+
+To disable automatic search and require pressing Enter instead, open the Settings Editor ({#kb zed::OpenSettings}), search for "search on input", and toggle the setting off. Or add this to your settings.json:
+
+```json
+{
+ "search_on_input": false
+}
+```
## Go to Definition
@@ -70,6 +70,33 @@ To disable word diff for specific languages only, add this to your settings.json
}
```
+### Diff View Styles
+
+> **Changed in Preview (v0.225).** See [release notes](/releases#0.225).
+
+Zed displays diffs in two modes: **split** (side-by-side comparison) or **unified** (inline changes). Split view is the default.
+
+#### Changing the diff view
+
+Open the Settings Editor ({#kb zed::OpenSettings}) and search for "diff view style". Select either **Split** or **Unified**.
+
+To change the default, add this to your `settings.json`:
+
+```json
+{
+ "diff_view_style": "unified"
+}
+```
+
+See [Configuring Zed](./configuring-zed.md) for more about the Settings Editor.
+
+#### Split vs unified
+
+- **Split**: Shows the original and modified versions side by side. Useful for comparing file structure or reviewing large changes.
+- **Unified**: Shows changes inline with additions and deletions in a single view. Useful for focusing on specific line changes.
+
+You can switch between modes at any time. Your preference applies to [Project Diff](#project-diff), [File History](#file-history), and [Stash Diff View](#stash-diff-view). These diff views function as [multibuffers](./multibuffers.md), allowing you to edit multiple excerpts simultaneously.
+
## File History
File History shows the commit history for an individual file. Each entry displays the commit's author, timestamp, and message. Selecting a commit opens a diff view filtered to show only the changes made to that file in that commit.
@@ -5,7 +5,7 @@ description: How glob patterns work in Zed for file matching, search filtering,
# Globs
-Zed supports the use of [glob](<https://en.wikipedia.org/wiki/Glob_(programming)>) patterns that are the formal name for Unix shell-style path matching wildcards like `*.md` or `docs/src/**/*.md` supported by sh, bash, zsh, etc. A glob is similar but distinct from a [regex (regular expression)](https://en.wikipedia.org/wiki/Regular_expression). You may be In Zed these are commonly used when matching filenames.
+Zed supports the use of [glob](<https://en.wikipedia.org/wiki/Glob_(programming)>) patterns that are the formal name for Unix shell-style path matching wildcards like `*.md` or `docs/src/**/*.md` supported by sh, bash, zsh, etc. A glob is similar but distinct from a [regex (regular expression)](https://en.wikipedia.org/wiki/Regular_expression). In Zed, globs are commonly used when matching filenames.
## Glob Flavor
@@ -22,6 +22,19 @@ The `glob` crate is implemented entirely in rust and does not rely on the `glob`
A glob "pattern" is used to match a file name or complete file path. For example, when using "Search all files" {#kb project_search::ToggleFocus} you can click the funnel shaped Toggle Filters" button or {#kb project_search::ToggleFilters} and it will show additional search fields for "Include" and "Exclude" which support specifying glob patterns for matching file paths and file names.
+### Multiple Patterns
+
+> **Changed in Preview (v0.225).** See [release notes](/releases#0.225).
+
+You can specify multiple glob patterns in Project Search filters by separating them with commas. When using comma-separated patterns, Zed correctly handles braces within individual patterns:
+
+- `*.ts, *.tsx` — Match TypeScript and TSX files
+- `src/{components,utils}/**/*.ts, tests/**/*.test.ts` — Match TypeScript files in specific directories plus test files
+
+Each pattern is evaluated independently. Commas inside braces (like `{a,b}`) are treated as part of the pattern, not as separators.
+
+**Important:** While braces are preserved in patterns, Zed does not expand them into multiple patterns. The pattern `src/{a,b}/*.ts` matches the literal path structure, not `src/a/*.ts` OR `src/b/*.ts`. This differs from shell behavior.
+
When creating a glob pattern you can use one or multiple special characters:
| Special Character | Meaning |
@@ -35,7 +48,7 @@ When creating a glob pattern you can use one or multiple special characters:
Notes:
-1. Shell-style brace-expansions like `{a,b,c}` are not supported.
+1. Brace characters `{` and `}` are literal pattern characters, not expansion operators. The pattern `src/{a,b}/*.ts` matches paths containing the literal text `{a,b}`, not paths matching either `src/a/*.ts` or `src/b/*.ts` as in shell globbing.
2. To match a literal `-` character inside brackets it must come first `[-abc]` or last `[abc-]`.
3. To match the literal `[` character use `[[]` or put it as the first character in the group `[[abc]`.
4. To match the literal `]` character use `[]]` or put it as the last character in the group `[abc]]`.
@@ -54,9 +54,9 @@ For example to for a `.luarc.json` for use with [lua-language-server](https://gi
### Schema Specification via Settings
-You can alternatively associate JSON Schemas with file paths by via Zed LSP settings.
+> **Preview:** This feature is available in Zed Preview. It will be included in the next Stable release.
-To
+You can associate JSON Schemas with file paths using relative paths in your language server settings. Zed resolves paths relative to your project root:
```json [settings]
"lsp": {
@@ -64,6 +64,14 @@ To
"settings": {
"json": {
"schemas": [
+ {
+ "fileMatch": ["config/*.json"],
+ "url": "./schemas/custom-schema.json"
+ },
+ {
+ "fileMatch": ["*.config.json"],
+ "url": "~/global-schemas/shared.json"
+ },
{
"fileMatch": ["*/*.luarc.json"],
"url": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json"
@@ -75,6 +83,8 @@ To
}
```
+Paths starting with `./` resolve relative to the worktree root. Paths starting with `~/` expand to your home directory.
+
You can also pass any of the [supported settings](https://github.com/Microsoft/vscode/blob/main/extensions/json-language-features/server/README.md#settings) to json-language-server by specifying them in your Zed settings.json:
<!--
@@ -12,7 +12,11 @@ YAML support is available natively in Zed.
## Configuration
-You can configure various [yaml-language-server settings](https://github.com/redhat-developer/yaml-language-server?tab=readme-ov-file#language-server-settings) by adding them to your Zed settings.json in a `yaml-language-server` block under the `lsp` key. For example:
+> **Preview:** This feature is available in Zed Preview. It will be included in the next Stable release.
+
+You can configure various [yaml-language-server settings](https://github.com/redhat-developer/yaml-language-server?tab=readme-ov-file#language-server-settings) by adding them to your Zed settings.json in a `yaml-language-server` block under the `lsp` key.
+
+You can configure custom YAML schemas using relative paths. Zed resolves paths relative to your project root:
```json [settings]
"lsp": {
@@ -25,7 +29,8 @@ You can configure various [yaml-language-server settings](https://github.com/red
},
"schemas": {
"https://getcomposer.org/schema.json": ["/*"],
- "../relative/path/schema.json": ["/config*.yaml"]
+ "./schemas/kubernetes.yaml": "k8s/**/*.yaml",
+ "~/global-schemas/docker-compose.yaml": "docker-compose*.yml"
}
}
}
@@ -33,6 +38,8 @@ You can configure various [yaml-language-server settings](https://github.com/red
}
```
+Paths starting with `./` resolve relative to the worktree root. Paths starting with `~/` expand to your home directory.
+
Note, settings keys must be nested, so `yaml.keyOrdering` becomes `{"yaml": { "keyOrdering": true }}`.
## Formatting
@@ -508,6 +508,21 @@ Note: Dirty files (files with unsaved changes) will not be automatically closed
}
```
+## Diff View Style
+
+- Description: How to display diffs in the editor.
+- Setting: `diff_view_style`
+- Default: `"split"`
+
+**Options**
+
+- `"unified"`: Show changes inline with added and deleted lines stacked vertically
+- `"split"`: Display old and new versions side by side in separate panes (default)
+
+> **Changed in Preview (v0.225).** Values renamed from `"stacked"`/`"side_by_side"` to `"unified"`/`"split"`.
+
+See [Git documentation](../git.md#diff-view-styles) for more details.
+
## Disable AI
- Description: Whether to disable all AI features in Zed
@@ -2757,6 +2772,33 @@ The following settings can be overridden for each specific language:
These values take in the same options as the root-level settings with the same name.
+### Document Symbols
+
+> **Preview:** This feature is available in Zed Preview. It will be included in the next Stable release.
+
+- Description: Controls the source of document symbols used for outlines and breadcrumbs.
+- Setting: `document_symbols`
+- Default: `off`
+
+**Options**
+
+- `"off"`: Use tree-sitter queries to compute document symbols (default)
+- `"on"`: Use the language server's `textDocument/documentSymbol` LSP response. When enabled, tree-sitter is not used for document symbols
+
+LSP document symbols can provide more accurate symbols for complex language features (e.g., generic types, macros, decorators) that tree-sitter may not handle well. Use this when your language server provides better symbol information than the tree-sitter grammar.
+
+Example:
+
+```json [settings]
+{
+ "languages": {
+ "TypeScript": {
+ "document_symbols": "on"
+ }
+ }
+}
+```
+
## Language Models
- Description: Configuration for language model providers
@@ -3430,13 +3472,7 @@ Non-negative `integer` values
- Description: Whether to search on input in project search.
- Setting: `search_on_input`
-- Default: `false`
-
-### Search On Input Debounce Ms
-
-- Description: Debounce time in milliseconds for search on input in project search. Set to 0 to disable debouncing.
-- Setting: `search_on_input_debounce_ms`
-- Default: `200`
+- Default: `true`
### Center On Match
@@ -5102,6 +5138,34 @@ See the [debugger page](../debugger.md) for more information about debugging sup
- `collapse_untracked_diff`: Whether to collapse untracked files in the diff panel
- `scrollbar`: When to show the scrollbar in the git panel
+## Git Worktree Directory
+
+> **Preview:** This feature is available in Zed Preview. It will be included in the next Stable release.
+
+- Description: Directory where git worktrees are created, relative to the repository working directory.
+- Setting: `git.worktree_directory`
+- Default: `"../worktrees"`
+
+When the resolved directory falls outside the project root, the project's directory name is automatically appended so that sibling repos don't collide. For example, with the default `"../worktrees"` and a project at `~/code/zed`, worktrees are created under `~/code/worktrees/zed/`.
+
+When the resolved directory is inside the project root, no extra component is added (it's already project-scoped).
+
+**Examples**:
+
+- `"../worktrees"` — `~/code/worktrees/<project>/` (default)
+- `".git/zed-worktrees"` — `<project>/.git/zed-worktrees/`
+- `"my-worktrees"` — `<project>/my-worktrees/`
+
+Trailing slashes are ignored.
+
+```json [settings]
+{
+ "git": {
+ "worktree_directory": "../worktrees"
+ }
+}
+```
+
## Git Hosting Providers
- Description: Register self-hosted GitHub, GitLab, or Bitbucket instances so commit hashes, issue references, and permalinks resolve to the right host.
@@ -71,7 +71,9 @@ zed -n ~/projects/myproject
### `-a`, `--add`
-Add paths to the currently focused workspace instead of opening a new window:
+> **Changed in Preview (v0.225).** See [release notes](/releases#0.225).
+
+Add paths to the currently focused workspace instead of opening a new window. When multiple workspace windows are open, files open in the focused window:
```sh
zed -a newfile.txt
@@ -151,8 +151,32 @@ TBD: Improve Julia REPL instructions
## Changing which kernel is used per language {#changing-kernels}
-Zed automatically detects the available kernels on your system. If you need to configure a different default kernel for a
-language, you can assign a kernel for any supported language in your `settings.json`.
+> **Preview:** This feature is available in Zed Preview. It will be included in the next Stable release.
+
+Zed automatically detects available kernels and organizes them in the kernel picker:
+
+- **Recommended**: The Python environment matching your active toolchain (if detected)
+- **Python Environments**: Virtual environments (venv, virtualenv, Poetry, Pipenv, Conda, uv, etc.)
+- **Jupyter Kernels**: Installed Jupyter kernelspecs
+- **Remote Servers**: Connected remote Jupyter servers
+
+### Installing ipykernel
+
+Python environments appear in the picker even if ipykernel is not installed. Environments missing ipykernel are dimmed and labeled "ipykernel not installed." When you select one, Zed automatically runs `pip install ipykernel` in that environment and activates it once installation completes.
+
+### How Zed Recommends Kernels
+
+When you run code, Zed selects a kernel automatically:
+
+1. **Active toolchain match**: If a Python environment matches your active toolchain and has ipykernel, Zed uses it
+2. **First available Python env**: Otherwise, the first Python environment with ipykernel
+3. **Language-based fallback**: If no Python envs are ready, Zed picks a Jupyter kernel matching the code block's language
+
+You can override this by explicitly selecting a kernel from the picker.
+
+### Setting Default Kernels
+
+To configure a different default kernel for a language, you can assign a kernel for any supported language in your `settings.json`:
```json [settings]
{
@@ -167,6 +191,18 @@ language, you can assign a kernel for any supported language in your `settings.j
}
```
+## Interactive Input
+
+> **Preview:** This feature is available in Zed Preview. It will be included in the next Stable release.
+
+When code execution requires user input (such as Python's `input()` function), the REPL displays an input prompt below the cell output.
+
+Type your response in the text field and press `Enter` to submit. The kernel receives your input and continues execution.
+
+For password inputs, characters appear masked with asterisks for security.
+
+If execution is interrupted while an input prompt is active, the prompt automatically clears when the kernel returns to idle state.
+
## Debugging Kernelspecs
Available kernels are shown via the `repl: sessions` command. To refresh the kernels you can run, use the `repl: refresh kernelspecs` command.
@@ -246,3 +246,52 @@ In doing so, you can change which task is shown in the runnables indicator.
## Keybindings to run tasks bound to runnables
When you have a task definition that is bound to the runnable, you can quickly run it using [Code Actions](https://zed.dev/docs/configuring-languages?#code-actions) that you can trigger either via `editor: Toggle Code Actions` command or by the `cmd-.`/`ctrl-.` shortcut. Your task will be the first in the dropdown. The task will run immediately if there are no additional Code Actions for this line.
+
+## Running Bash Scripts
+
+> **Preview:** This feature is available in Zed Preview. It will be included in the next Stable release.
+
+You can run bash scripts directly from Zed. When you open a `.sh` or `.bash` file, Zed automatically detects the script as runnable and makes it available in the task picker.
+
+To run a bash script:
+
+1. Open the command palette with {#kb command_palette::Toggle}
+2. Search for "task" and select **task: spawn**
+3. Select the script from the list
+
+Bash scripts are tagged with `bash-script`, allowing you to filter or reference them in task configurations.
+
+If you need to pass arguments or customize the execution environment, add a task configuration in your `.zed/tasks.json`:
+
+```json
+[
+ {
+ "label": "run my-script.sh with args",
+ "command": "./my-script.sh",
+ "args": ["--verbose", "--output=results.txt"],
+ "tags": ["bash-script"]
+ }
+]
+```
+
+## Shell Initialization
+
+> **Changed in Preview (v0.225).** See [release notes](/releases#0.225).
+
+When Zed runs a task, it launches the command in a login shell. This ensures your shell's initialization files (`.bash_profile`, `.zshrc`, etc.) are sourced before the task executes.
+
+This behavior gives tasks access to the same environment variables, aliases, and PATH modifications you've configured in your shell profile. If a task fails to find a command that works in your terminal, verify your shell configuration files are properly set up.
+
+To override the shell used for tasks, configure the `terminal.shell` setting:
+
+```json
+{
+ "terminal": {
+ "shell": {
+ "program": "/bin/zsh"
+ }
+ }
+}
+```
+
+See [Terminal configuration](./terminal.md) for complete shell options.
@@ -248,29 +248,34 @@ Below, you'll find tables listing the commands you can use in the command palett
### File and window management
+> **Changed in Preview (v0.225).** See [release notes](/releases#0.225).
+>
+> The `:bd[elete]` command now closes the active file across all panes. Previously, it only closed the file in the active pane.
+
This table shows commands for managing windows, tabs, and panes. As commands don't support arguments currently, you cannot specify a filename when saving or creating a new file.
-| Command | Description |
-| -------------- | ---------------------------------------------------- |
-| `:w[rite][!]` | Save the current file |
-| `:wq[!]` | Save the file and close the buffer |
-| `:q[uit][!]` | Close the buffer |
-| `:wa[ll][!]` | Save all open files |
-| `:wqa[ll][!]` | Save all open files and close all buffers |
-| `:qa[ll][!]` | Close all buffers |
-| `:[e]x[it][!]` | Close the buffer |
-| `:up[date]` | Save the current file |
-| `:cq` | Quit completely (close all running instances of Zed) |
-| `:vs[plit]` | Split the pane vertically |
-| `:sp[lit]` | Split the pane horizontally |
-| `:new` | Create a new file in a horizontal split |
-| `:vne[w]` | Create a new file in a vertical split |
-| `:tabedit` | Create a new file in a new tab |
-| `:tabnew` | Create a new file in a new tab |
-| `:tabn[ext]` | Go to the next tab |
-| `:tabp[rev]` | Go to previous tab |
-| `:tabc[lose]` | Close the current tab |
-| `:ls` | Show all buffers |
+| Command | Description |
+| --------------- | ---------------------------------------------------- |
+| `:w[rite][!]` | Save the current file |
+| `:wq[!]` | Save the file and close the buffer |
+| `:q[uit][!]` | Close the buffer |
+| `:wa[ll][!]` | Save all open files |
+| `:wqa[ll][!]` | Save all open files and close all buffers |
+| `:qa[ll][!]` | Close all buffers |
+| `:[e]x[it][!]` | Close the buffer |
+| `:up[date]` | Save the current file |
+| `:cq` | Quit completely (close all running instances of Zed) |
+| `:bd[elete][!]` | Close the active file in all panes |
+| `:vs[plit]` | Split the pane vertically |
+| `:sp[lit]` | Split the pane horizontally |
+| `:new` | Create a new file in a horizontal split |
+| `:vne[w]` | Create a new file in a vertical split |
+| `:tabedit` | Create a new file in a new tab |
+| `:tabnew` | Create a new file in a new tab |
+| `:tabn[ext]` | Go to the next tab |
+| `:tabp[rev]` | Go to previous tab |
+| `:tabc[lose]` | Close the current tab |
+| `:ls` | Show all buffers |
> **Note:** The `!` character is used to force the command to execute without saving changes or prompting before overwriting a file.