A Tour of Zed
Let's start with a tour of Zed's major features. This document should give you a decent understanding Zed's current functionality and how to access it.
If there's one default key binding to remember, it's
cmd-shift-p. This deploys the command palette, which is a gateway to much of the other functionality that Zed offers and a convenient tool for learning key bindings.
Available commands depend of what is focused. For example, if you focus the project panel, you'll see
project panel: add file in the command palette, but you won't see that command if an editor is focused.
To install the
zed command line tool, select
Zed > Install CLI from the application menu. Then you can type
zed my-path on the command line to open a directory or file in Zed. To use Zed as your
$EDITOR to edit Git commits etc, add
export EDITOR="zed --wait" to your shell profile.
Zed comes with an integrated terminal emulator that uses Alacritty as it's backend. You can open the terminal with ctrl-` or by clicking the + icon on the right side of the tab bar.
Choosing a theme
Toggle select a theme, press
cmd-k cmd-t. We don't currently support user-defined themes, but we've tried to include some nice default options.
To fuzzy-search all files in your project by path, use the file finder, which you can toggle with
The project browser is the panel at the left that displays the contents of your project as directory trees. You can toggle focus to and from the project browser with
cmd-shift-e. You can toggle its visibility with
cmd-b. It can also be toggled with the file tree icon in the lower left corner of the workspace.
Every Zed window corresponds to a project, and you can add multiple folders or even individual files to a project. Project-wide interactions apply to all folders that you add.
For now, projects aren't persistent. Once you close the window, your project disappears.
Search your entire project with
cmd-shift-f. This pulls up a dedicated tab in which to search and display your results. You can make your search case-sensitive, regular-expression-based, and apply to whole words only. We don't yet support restricting the search to specific paths.
To create multiple project searches, confirm your search query with
cmd-enter instead of
enter. This will open the results of this new search as an additional tab and leave the old results tab in place.
Search results are presented in a multi-buffer, which is one of Zed's unique features.
Multi-buffers are edited much like ordinary buffers, but they contain editable excerpts from multiple different files. They're used in multiple ways in Zed. In the case of project search, you'll see an excerpt with a few context lines surrounding every match.
Multi-buffers allow you to perform multi-cursor edits that span multiple files. When you save a multi-buffer, every excerpted file is saved.
To jump to the cursor's location in a dedicated buffer for the excerpted file, press
alt-enter. If you have multiple cursors, a tab will be opened for the location of each cursor.
A breadcrumb trail is displayed at the top of multi-buffers and singleton buffers with the path of the file containing the cursor along with a summary of the containing syntax nodes. This can be especially helpful in multi-buffers or within large functions.
To split a pane, press
cmd-k followed by an arrow the direction you want to split. So to split the current tab to the right, it's
cmd-k right. To cycle focus among different panes, press
cmd-k cmd-right to cycle forwards or
cmd-k cmd-left to cycle backwards. Panes can't currently be resized.
The most powerful way to navigate within a buffer is Zed's outline view. When you press
cmd-shift-O with an editor focused, Zed presents a summary of the file based on the syntax tree. This is useful in a few ways.
It can be a good way to understand the layout of a file, which can be helpful when browsing code or when deciding where to insert a new definition. When you first open the outline view, Zed always highlights the entry closest to your current location within the file.
You can also use it to quickly jump to a named definition in a file by fuzzy searching. The file order is preserved, but the best match to your query is automatically selected.
A cool hidden feature is that when your query contains a space, we expand the search to match on contextual keywords. So in Rust, you could type
select to search for any definition whose names matches the word
select. But you could type
pub fn select to search all public methods or functions matching the word
select. You could also type
pub fn to simply see all public functions or
struct to see all struct definitions.
Other ways to navigate within buffer
Within ordinary buffers, there are a few ways to navigate. You can search a buffer with
cmd-f, but we don't currently support replace.
You can also jump to a specific line with
Downloading and starting language servers
When you open first open a file in a specific language, Zed will download and start the appropriate language server if it's supported. Rust remains our primary focus in the short term, but Zed currently has hard-coded language server support for the following languages:
The ability to connect Zed with an arbitrary language server is under active development.
You can jump to the definition under your cursor with
Once you've jumped to a definition or performed any non-local navigation, you can use the navigation history to navigate backward with
ctrl-- and forwards with
ctrl-shift-_. The navigation history is intentionally scoped per-pane, so we'll never switch your focus to another pane when navigating forwards and backwards.
To find all references to the symbol under your cursor, press
alt-shift-f12. References will be displayed in a multi-buffer with excerpts for each occurrence, similar to how project-wide search works.
To use the language server to search for a symbol across the project, press
Whenever you see a lightning bolt next to the gutter, it means a code action is available for the current cursor location from the language server. You can click the lightning bolt or press
cmd-. to reveal available actions.
Code actions affecting multiple files will present the results of the action in a multi-buffer. To undo the action, simply hit
cmd-z in the multi-buffer, although we don't yet support undoing file-system changes. To save the results of a multi-file code action, just save the multi-buffer.
To perform a rename refactoring, place your cursor on the symbol you'd like to rename and press
f2. If the rename impacts multiple files, you'll see the results in a multi-buffer.
When your perfectly-imperfect self introduces an error or warning into the code, you'll see it indicated with a wavy underline. If you place your cursor within the underlined text, you'll see the first line of the error in the status bar.
For more details, you can expand the error by hitting
f8. You can cycle through all errors in the current buffer with
shift-f8 to cycle backwards. Once you fix the error, you'll see it grayed out, at which point you can press
escape to dismiss it.
Zed displays the number of errors and warnings that exist across your entire project in the status bar at the lower left corner of the workspace. If you click this indicator or press
cmd-shift-M, you'll open the project diagnostics multi-buffer.
This multi-buffer contains an excerpt for every error in your project, and its contents will update as you fix errors and save. Sometimes the language server reports multiple errors for the same piece of code. We've chosen to be faithful to the output of the compiler and present an excerpt for each error, even if this means you'll sometimes see multiple excerpts for overlapping sections of a file.
As with any multi-buffer, you can jump to the location of your cursor in an ordinary singleton buffer by pressing
alt-enter. Don't forget you can navigate back to the multi-buffer with
ctrl-- after making your fix.
To fold and unfold code based on the syntax tree, press
To grow and shrink the selection based on the syntax tree, press
To jump to the nearest enclosing bracket or its matching counterpart, press
You can create multiple cursors/selections via the mouse by alt-clicking/dragging.
To add a new selection above or below the current, press
To select the word under the cursor, then the next matching piece of text, press
cmd-d. To skip a word, press
cmd-d to select it, then
cmd-k cmd-d to select the next. To undo your selection, press
Now that we've explored how to use Zed by yourself, let's get into using it collaboratively.
You can add another Zed user as a contact from the contacts panel, deployed from the icon in the lower right corner of the workspace or by pressing
You can add existing Zed users with the "Add Contact" button or invite new Zed users if you have invites by copying an invite link at the bottom of the panel.
We're limiting invites in order to grow our userbase at a sustainable pace, but contact us at
firstname.lastname@example.org with your GitHub login if you're an existing user and need invites. When someone joins via your invite link, they're automatically added as a contact.
Joining a contact's project
You'll see all your online contacts in the contacts panel, along with a list of their online projects. To join a project, click it in the contacts panel.
This will open a new window, and your contact will be notified of your request to join.
Once you join, every collaborator in a project is shown as an avatar at the upper right corner of the workspace. Each avatar is associated with a color which identifies their cursor.
Our goal is to eliminate the distinction between local and remote projects as much as possible. Guests can open, edit, and save files, perform searches, interact with the language server, etc.
Following a collaborator
When you join a project, you'll immediately start following the host as they move within and between files.
You automatically stop following whenever you move the cursor or edit. To start following again, you can click on a collaborator's avatar or cycle through following different participants by pressing
Following is confined to a particular pane. When a pane is following a collaborator, it is outlined in their cursor color. This pane-specific behavior allows you to follow someone in one pane while navigating independently in another, and can be an effective layout for some styles of collaboration.
This concludes our tour
That's it for now. There's a long list of things we want to add, but we've found this to be an effective set of features to let us build Zed in Zed collaboratively. Check out other sections of the docs for specifics on how to configure Zed and customing your key bindings. Happy coding!