From 63161d436f1ebc13eb02d1879dc4170b71708204 Mon Sep 17 00:00:00 2001 From: Katie Geer Date: Wed, 17 Dec 2025 14:45:10 -0800 Subject: [PATCH] Add new reference docs --- docs/src/SUMMARY.md | 9 ++ docs/src/reference/all-actions.md | 5 ++ docs/src/reference/all-settings.md | 7 ++ docs/src/reference/cli.md | 75 ++++++++++++++++ docs/src/reference/default-key-bindings.md | 98 +++++++++++++++++++++ docs/src/reference/environment-variables.md | 60 +++++++++++++ docs/src/reference/glob-patterns.md | 51 +++++++++++ 7 files changed, 305 insertions(+) create mode 100644 docs/src/reference/all-actions.md create mode 100644 docs/src/reference/all-settings.md create mode 100644 docs/src/reference/cli.md create mode 100644 docs/src/reference/default-key-bindings.md create mode 100644 docs/src/reference/environment-variables.md create mode 100644 docs/src/reference/glob-patterns.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 5ab34113556c631622139be4051512e440a4028e..94dc389e760fa51b12c2e95908b2e91503a86d6d 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -172,6 +172,15 @@ - [Yarn](./languages/yarn.md) - [Zig](./languages/zig.md) +# Reference + +- [All Settings](./reference/all-settings.md) +- [All Actions](./reference/all-actions.md) +- [Default Key Bindings](./reference/default-key-bindings.md) +- [CLI Reference](./reference/cli.md) +- [Environment Variables](./reference/environment-variables.md) +- [Glob Patterns](./reference/glob-patterns.md) + # Account & Privacy - [Sign In](./authentication.md) diff --git a/docs/src/reference/all-actions.md b/docs/src/reference/all-actions.md new file mode 100644 index 0000000000000000000000000000000000000000..6fe5d8edabd9f8c6d3241bea168460a8552665cc --- /dev/null +++ b/docs/src/reference/all-actions.md @@ -0,0 +1,5 @@ +# All Actions + +This reference lists every action available in Zed. Use these action names in your [keymap](../key-bindings.md) or trigger them directly from the command palette. + +{#ACTIONS_TABLE#} diff --git a/docs/src/reference/all-settings.md b/docs/src/reference/all-settings.md new file mode 100644 index 0000000000000000000000000000000000000000..5d07a244973926cd64c559d25b8981dca1038fb7 --- /dev/null +++ b/docs/src/reference/all-settings.md @@ -0,0 +1,7 @@ +# All Settings + +This is the complete reference for Zed's settings. For an introduction to how settings work, see [Customization](../themes.md). + +To open your settings file, use {#kb zed::OpenSettingsFile} or run `zed: open settings` from the command palette. + +{#SETTINGS_TABLE#} diff --git a/docs/src/reference/cli.md b/docs/src/reference/cli.md new file mode 100644 index 0000000000000000000000000000000000000000..2b44792dace53af1b0081458aafb8d62e5864371 --- /dev/null +++ b/docs/src/reference/cli.md @@ -0,0 +1,75 @@ +# CLI Reference + +Zed includes a command-line interface for opening files, directories, and controlling the editor from your terminal. + +## Installation + +- **macOS**: Run `cli: install` from the command palette to create a symlink at `/usr/local/bin/zed` +- **Linux**: The CLI is included with your distribution's Zed package (binary name may vary) + +## Usage + +```sh +zed [OPTIONS] [PATHS...] +``` + +## Common Commands + +| Command | Description | +|---------|-------------| +| `zed` | Open an empty Zed window | +| `zed .` | Open the current directory as a project | +| `zed /path/to/file` | Open a specific file | +| `zed /path/to/folder` | Open a folder as a project | +| `zed file1.rs file2.rs` | Open multiple files | +| `zed -n /path` | Open in a new window | +| `ps aux \| zed -` | Read from stdin | + +## Options + +| Option | Description | +|--------|-------------| +| `-n`, `--new` | Open in a new window instead of reusing an existing one | +| `-w`, `--wait` | Wait for the file to be closed before returning | +| `-a`, `--add` | Add files to the current workspace | +| `-` | Read from stdin | +| `--foreground` | Start Zed with logs output to the terminal | +| `--dev-server-token ` | Start as a dev server with the given token | +| `--uninstall` | Uninstall Zed and all related files | +| `-h`, `--help` | Show help information | +| `-v`, `--version` | Show version information | + +## Opening Files at a Specific Line + +You can open a file at a specific line and column: + +```sh +zed /path/to/file:42 # Open at line 42 +zed /path/to/file:42:10 # Open at line 42, column 10 +``` + +## Examples + +Open the current directory in Zed: + +```sh +zed . +``` + +Open a file and wait for it to close (useful for Git commit messages): + +```sh +GIT_EDITOR="zed -w" git commit +``` + +Pipe command output into Zed: + +```sh +cat /var/log/system.log | zed - +``` + +Open multiple files in a new window: + +```sh +zed -n src/main.rs src/lib.rs +``` diff --git a/docs/src/reference/default-key-bindings.md b/docs/src/reference/default-key-bindings.md new file mode 100644 index 0000000000000000000000000000000000000000..a2fc1f879babcab4a9ab5d4e16b8a549f68f7450 --- /dev/null +++ b/docs/src/reference/default-key-bindings.md @@ -0,0 +1,98 @@ +# Default Key Bindings + +Zed ships with default key bindings optimized for each platform. You can customize these in your [keymap file](../key-bindings.md). + +## View Default Keymaps + +The complete default keymaps are maintained in the Zed repository: + +| Platform | Keymap File | +|----------|-------------| +| macOS | [default-macos.json](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-macos.json) | +| Windows | [default-windows.json](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-windows.json) | +| Linux | [default-linux.json](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-linux.json) | + +## Essential Bindings + +These are the most commonly used default bindings. Platform-specific keys are shown as `Cmd` (macOS) / `Ctrl` (Linux/Windows). + +### General + +| Action | macOS | Linux/Windows | +|--------|-------|---------------| +| Command palette | `Cmd+Shift+P` | `Ctrl+Shift+P` | +| Settings | `Cmd+,` | `Ctrl+,` | +| File finder | `Cmd+P` | `Ctrl+P` | +| Project search | `Cmd+Shift+F` | `Ctrl+Shift+F` | +| Toggle terminal | `` Ctrl+` `` | `` Ctrl+` `` | +| Toggle left dock | `Cmd+B` | `Ctrl+B` | + +### Editing + +| Action | macOS | Linux/Windows | +|--------|-------|---------------| +| Cut | `Cmd+X` | `Ctrl+X` | +| Copy | `Cmd+C` | `Ctrl+C` | +| Paste | `Cmd+V` | `Ctrl+V` | +| Undo | `Cmd+Z` | `Ctrl+Z` | +| Redo | `Cmd+Shift+Z` | `Ctrl+Shift+Z` | +| Save | `Cmd+S` | `Ctrl+S` | +| Find | `Cmd+F` | `Ctrl+F` | +| Find and replace | `Cmd+H` | `Ctrl+H` | +| Comment line | `Cmd+/` | `Ctrl+/` | +| Format document | `Cmd+Shift+I` | `Ctrl+Shift+I` | + +### Navigation + +| Action | macOS | Linux/Windows | +|--------|-------|---------------| +| Go to line | `Ctrl+G` | `Ctrl+G` | +| Go to definition | `F12` or `Cmd+Click` | `F12` or `Ctrl+Click` | +| Go to references | `Shift+F12` | `Shift+F12` | +| Go to symbol | `Cmd+Shift+O` | `Ctrl+Shift+O` | +| Go back | `Ctrl+-` | `Alt+Left` | +| Go forward | `Ctrl+Shift+-` | `Alt+Right` | + +### Multi-cursor + +| Action | macOS | Linux/Windows | +|--------|-------|---------------| +| Add cursor above | `Cmd+Alt+Up` | `Ctrl+Alt+Up` | +| Add cursor below | `Cmd+Alt+Down` | `Ctrl+Alt+Down` | +| Select next occurrence | `Cmd+D` | `Ctrl+D` | +| Select all occurrences | `Cmd+Shift+L` | `Ctrl+Shift+L` | + +### Panels + +| Action | macOS | Linux/Windows | +|--------|-------|---------------| +| Project panel | `Cmd+Shift+E` | `Ctrl+Shift+E` | +| Outline panel | `Cmd+Shift+O` | `Ctrl+Shift+O` | +| Git panel | `Cmd+Shift+G` | `Ctrl+Shift+G` | +| Agent panel | `Cmd+Shift+A` | `Ctrl+Shift+A` | + +## Predefined Keymaps + +If you prefer another editor's bindings, change the `base_keymap` setting: + +```json +{ + "base_keymap": "VSCode" +} +``` + +Available options: +- `VSCode` (default) +- `Atom` +- `Emacs` +- `JetBrains` +- `SublimeText` +- `TextMate` +- `Cursor` +- `None` + +## See Also + +- [Custom Key Bindings](../key-bindings.md) for creating your own bindings +- [All Actions](./all-actions.md) for the complete list of bindable actions +- [Vim Mode](../vim.md) for modal editing diff --git a/docs/src/reference/environment-variables.md b/docs/src/reference/environment-variables.md new file mode 100644 index 0000000000000000000000000000000000000000..5ac839999eae7f9b65919f6acffa4da0ac20147a --- /dev/null +++ b/docs/src/reference/environment-variables.md @@ -0,0 +1,60 @@ +# Environment Variables + +This page lists environment variables that affect Zed's behavior. + +## Where Zed Gets Environment Variables + +| Launch Method | Environment Source | +|---------------|-------------------| +| CLI (`zed .`) | Inherits from the shell session | +| Dock / Launcher / Window Manager | Spawns a login shell in home directory | +| Per-project | Spawns a login shell in the project directory | + +When launched via the CLI, Zed inherits environment variables from your shell. When launched from the Dock or a launcher, Zed spawns a login shell to obtain a base environment. + +For project-specific environments (e.g., when using `direnv`, `asdf`, or `mise`), Zed spawns an additional login shell in the project directory and stores those variables for use in tasks, terminals, and language servers. + +## Environment Variable Reference + +| Variable | Purpose | +|----------|---------| +| `XDG_CONFIG_HOME` | On Linux, overrides the default config location (`~/.config/zed`) | +| `ZED_LOG_LEVEL` | Sets the log verbosity (`debug`, `info`, `warn`, `error`) | +| `ZED_BUNDLE` | When set, indicates Zed is running as a bundled app | +| `ZED_STATELESS` | When set, Zed won't persist window state between sessions | +| `ZED_ALWAYS_ACTIVE` | When set, Zed behaves as if it's always the active application | +| `http_proxy` / `HTTP_PROXY` | HTTP proxy URL for network requests | +| `https_proxy` / `HTTPS_PROXY` | HTTPS proxy URL for network requests | +| `no_proxy` / `NO_PROXY` | Comma-separated list of hosts to bypass proxy | + +## Variables Set by Zed + +Zed sets these variables in spawned processes (tasks, terminals, language servers): + +| Variable | Value | +|----------|-------| +| `ZED_TERM` | Set in the integrated terminal | +| `TERM` | Set to a terminal type in the integrated terminal | +| `EDITOR` | Set to `zed --wait` when appropriate | +| `VISUAL` | Set to `zed --wait` when appropriate | + +## Usage in Tasks and Terminals + +Environment variables from your project are available in: + +- **Tasks**: All task commands have access to the project environment +- **Terminal**: The integrated terminal inherits project-specific variables +- **Language servers**: Servers spawned for a project use that project's environment + +```json +{ + "tasks": [ + { + "label": "echo env", + "command": "echo $MY_PROJECT_VAR" + } + ] +} +``` + +> **Note:** Environment handling changed in Zed 0.152.0. The CLI now always passes its environment to Zed, even when an instance is already running. diff --git a/docs/src/reference/glob-patterns.md b/docs/src/reference/glob-patterns.md new file mode 100644 index 0000000000000000000000000000000000000000..3bf464e161176c26e3a632101c1ac60a37acd86b --- /dev/null +++ b/docs/src/reference/glob-patterns.md @@ -0,0 +1,51 @@ +# Glob Patterns + +Glob patterns are Unix shell-style wildcards for matching file paths, like `*.md` or `docs/**/*.rs`. Zed uses globs in search filters, file exclusions, and various settings. + +## Syntax Reference + +| Pattern | Matches | Example | +|---------|---------|---------| +| `?` | Any single character | `?.md` matches `a.md`, not `ab.md` | +| `*` | Any sequence of characters (except `/`) | `*.rs` matches `main.rs`, `lib.rs` | +| `**` | Any directory depth (including zero) | `src/**/*.rs` matches `src/main.rs`, `src/lib/utils.rs` | +| `[abc]` | Any one character in brackets | `[abc].txt` matches `a.txt`, `b.txt`, `c.txt` | +| `[a-z]` | Any character in range | `[0-9].log` matches `1.log`, `9.log` | +| `[!abc]` | Any character not in brackets | `[!0-9].txt` matches `a.txt`, not `1.txt` | + +## Common Examples + +```/dev/null/examples.txt#L1-12 +# File extensions +*.rs # All Rust files +*.{rs,toml} # NOT supported - use multiple patterns + +# Directory matching +docs/**/*.md # All Markdown files under docs/ +**/test_*.py # Test files in any directory + +# Case-insensitive matching (globs are case-sensitive) +*.[cC] # Matches .c and .C files +``` + +## Where Globs Are Used + +| Feature | Setting/Location | Notes | +|---------|------------------|-------| +| Project search | Include/Exclude filters | Filter search results by path | +| File excludes | `file_scan_exclusions` | Hide files from project panel | +| Search excludes | `search.exclude` | Exclude from search results | +| Formatter overrides | `languages.*.format_on_save` | Match files for formatting rules | + +## Notes + +- Globs in Zed are **case-sensitive**. On macOS (case-insensitive filesystem), `*.c` won't match `Main.C`. +- Brace expansion (`{a,b,c}`) is **not supported**. Use separate patterns instead. +- Patterns are matched against the full path from the project root. +- To match a literal `-` in brackets, place it first or last: `[-abc]` or `[abc-]`. +- To match a literal `[` or `]`, use `[[]` or `[]]`. + +## See Also + +- [Configuring Zed](../configuring-zed.md) for settings that accept glob patterns +- [gitignore patterns](https://git-scm.com/docs/gitignore#_pattern_format) use similar but not identical syntax