1# Configuring Zed
2
3## Folder-specific settings
4
5Folder-specific settings are used to override Zed's global settings for files within a specific directory in the project panel. To get started, create a `.zed` subdirectory and add a `settings.json` within it. It should be noted that folder-specific settings don't need to live only a project's root, but can be defined at multiple levels in the project hierarchy. In setups like this, Zed will find the configuration nearest to the file you are working in and apply those settings to it. In most cases, this level of flexibility won't be needed and a single configuration for all files in a project is all that is required; the `Zed > Settings > Open Local Settings` menu action is built for this case. Running this action will look for a `.zed/settings.json` file at the root of the first top-level directory in your project panel. If it does not exist, it will create it.
6
7The following global settings can be overridden with a folder-specific configuration:
8
9- `copilot`
10- `enable_language_server`
11- `ensure_final_newline_on_save`
12- `format_on_save`
13- `formatter`
14- `hard_tabs`
15- `language_overrides`
16- `preferred_line_length`
17- `remove_trailing_whitespace_on_save`
18- `soft_wrap`
19- `tab_size`
20- `show_copilot_suggestions`
21- `show_whitespaces`
22
23_See the Global settings section for details about these settings_
24
25## Global settings
26
27To get started with editing Zed's global settings, open `~/.config/zed/settings.json` via `⌘` + `,`, the command palette (`zed: open settings`), or the `Zed > Settings > Open Settings` application menu item.
28
29Here are all the currently available settings.
30
31## Active Pane Magnification
32
33- Description: Scale by which to zoom the active pane. When set to `1.0`, the active pane has the same size as others, but when set to a larger value, the active pane takes up more space.
34- Setting: `active_pane_magnification`
35- Default: `1.0`
36
37**Options**
38
39`float` values
40
41## Autosave
42
43- Description: When to automatically save edited buffers.
44- Setting: `autosave`
45- Default: `off`
46
47**Options**
48
491. To disable autosave, set it to `off`
50
51```json
52{
53 "autosave": "off"
54}
55```
56
572. To autosave when focus changes, use `on_focus_change`:
58
59```json
60{
61 "autosave": "on_focus_change"
62}
63```
64
653. To autosave when the active window changes, use `on_window_change`:
66
67```json
68{
69 "autosave": "on_window_change"
70}
71```
72
734. To autosave after an inactivity period, use `after_delay`:
74
75```json
76{
77 "autosave": {
78 "after_delay": {
79 "milliseconds": 1000
80 }
81 }
82}
83```
84
85## Auto Update
86
87- Description: Whether or not to automatically check for updates.
88- Setting: `auto_update`
89- Default: `true`
90
91**Options**
92
93`boolean` values
94
95## Buffer Font Family
96
97- Description: The name of a font to use for rendering text in the editor.
98- Setting: `buffer_font_family`
99- Default: `Zed Mono`
100
101**Options**
102
103The name of any font family installed on the user's system
104
105## Buffer Font Features
106
107- Description: The OpenType features to enable for text in the editor.
108- Setting: `buffer_font_features`
109- Default: `null`
110
111**Options**
112
113Zed supports a subset of OpenType features that can be enabled or disabled for a given buffer or terminal font. The following [OpenType features](https://en.wikipedia.org/wiki/List_of_typographic_features) can be enabled or disabled too: `calt`, `case`, `cpsp`, `frac`, `liga`, `onum`, `ordn`, `pnum`, `ss01`, `ss02`, `ss03`, `ss04`, `ss05`, `ss06`, `ss07`, `ss08`, `ss09`, `ss10`, `ss11`, `ss12`, `ss13`, `ss14`, `ss15`, `ss16`, `ss17`, `ss18`, `ss19`, `ss20`, `subs`, `sups`, `swsh`, `titl`, `tnum`, `zero`.
114
115For example, to disable ligatures for a given font you can add the following to your settings:
116
117```json
118{
119 "buffer_font_features": {
120 "calt": false
121 }
122}
123```
124
125## Buffer Font Size
126
127- Description: The default font size for text in the editor.
128- Setting: `buffer_font_size`
129- Default: `15`
130
131**Options**
132
133`integer` values
134
135## Confirm Quit
136
137- Description: Whether or not to prompt the user to confirm before closing the application.
138- Setting: `confirm_quit`
139- Default: `false`
140
141**Options**
142
143`boolean` values
144
145## Copilot
146
147- Description: Copilot-specific settings.
148- Setting: `copilot`
149- Default:
150
151```json
152"copilot": {
153 "disabled_globs": [
154 ".env"
155 ]
156}
157```
158
159**Options**
160
161### Disabled Globs
162
163- Description: The set of glob patterns for which Copilot should be disabled in any matching file.
164- Setting: `disabled_globs`
165- Default: [".env"]
166
167**Options**
168
169List of `string` values
170
171## Cursor Blink
172
173- Description: Whether or not the cursor blinks.
174- Setting: `cursor_blink`
175- Default: `true`
176
177**Options**
178
179`boolean` values
180
181## Default Dock Anchor
182
183- Description: The default anchor for new docks.
184- Setting: `default_dock_anchor`
185- Default: `bottom`
186
187**Options**
188
1891. Position the dock attached to the bottom of the workspace: `bottom`
1902. Position the dock to the right of the workspace like a side panel: `right`
1913. Position the dock full screen over the entire workspace: `expanded`
192
193## Editor Toolbar
194
195- Description: Whether or not to show various elements in the editor toolbar.
196- Setting: `toolbar`
197- Default:
198
199```json
200"toolbar": {
201 "breadcrumbs": true,
202 "quick_actions": true
203},
204```
205
206**Options**
207
208Each option controls displaying of a particular toolbar element. If all elements are hidden, the editor toolbar is not displayed.
209
210## Enable Language Server
211
212- Description: Whether or not to use language servers to provide code intelligence.
213- Setting: `enable_language_server`
214- Default: `true`
215
216**Options**
217
218`boolean` values
219
220## Ensure Final Newline On Save
221
222- Description: Whether or not to ensure there's a single newline at the end of a buffer when saving it.
223- Setting: `ensure_final_newline_on_save`
224- Default: `true`
225
226**Options**
227
228`boolean` values
229
230## LSP
231
232- Description: Configuration for language servers.
233- Setting: `lsp`
234- Default: `null`
235
236**Options**
237
238The following settings can be overridden for specific language servers:
239
240- `initialization_options`
241
242To override settings for a language, add an entry for that language server's name to the `lsp` value. Example:
243
244```json
245"lsp": {
246 "rust-analyzer": {
247 "initialization_options": {
248 "check": {
249 "command": "clippy" // rust-analyzer.check.command (default: "check")
250 }
251 }
252 }
253}
254```
255
256## Format On Save
257
258- Description: Whether or not to perform a buffer format before saving.
259- Setting: `format_on_save`
260- Default: `on`
261
262**Options**
263
2641. `on`, enables format on save obeying `formatter` setting:
265
266```json
267{
268 "format_on_save": "on"
269}
270```
271
2722. `off`, disables format on save:
273
274```json
275{
276 "format_on_save": "off"
277}
278```
279
280## Formatter
281
282- Description: How to perform a buffer format.
283- Setting: `formatter`
284- Default: `language_server`
285
286**Options**
287
2881. To use the current language server, use `"language_server"`:
289
290```json
291{
292 "formatter": "language_server"
293}
294```
295
2962. Or to use an external command, use `"external"`. Specify the name of the formatting program to run, and an array of arguments to pass to the program. The buffer's text will be passed to the program on stdin, and the formatted output should be written to stdout. For example, the following command would strip trailing spaces using [`sed(1)`](https://linux.die.net/man/1/sed):
297
298```json
299{
300 "formatter": {
301 "external": {
302 "command": "sed",
303 "arguments": ["-e", "s/ *$//"]
304 }
305 }
306}
307```
308
309## Auto close
310
311- Description: Whether or not to automatically type closing characters for you.
312- Setting: `use_autoclose`
313- Default: `true`
314
315**Options**
316
317`boolean` values
318
319## Git
320
321- Description: Configuration for git-related features.
322- Setting: `git`
323- Default:
324
325```json
326"git": {
327 "git_gutter": "tracked_files"
328},
329```
330
331### Git Gutter
332
333- Description: Whether or not to show the git gutter.
334- Setting: `git_gutter`
335- Default: `tracked_files`
336
337**Options**
338
3391. Show git gutter in tracked files
340
341```json
342{
343 "git_gutter": "tracked_files"
344}
345```
346
3472. Hide git gutter
348
349```json
350{
351 "git_gutter": "hide"
352}
353```
354
355## Hard Tabs
356
357- Description: Whether to indent lines using tab characters or multiple spaces.
358- Setting: `hard_tabs`
359- Default: `false`
360
361**Options**
362
363`boolean` values
364
365## Hover Popover Enabled
366
367- Description: Whether or not to show the informational hover box when moving the mouse over symbols in the editor.
368- Setting: `hover_popover_enabled`
369- Default: `true`
370
371**Options**
372
373`boolean` values
374
375## Inlay hints
376
377- Description: Configuration for displaying extra text with hints in the editor.
378- Setting: `inlay_hints`
379- Default:
380
381```json
382"inlay_hints": {
383 "enabled": false,
384 "show_type_hints": true,
385 "show_parameter_hints": true,
386 "show_other_hints": true,
387 "edit_debounce_ms": 700,
388 "scroll_debounce_ms": 50
389}
390```
391
392**Options**
393
394Inlay hints querying consists of two parts: editor (client) and LSP server.
395With the inlay settings above are changed to enable the hints, editor will start to query certain types of hints and react on LSP hint refresh request from the server.
396At this point, the server may or may not return hints depending on its implementation, further configuration might be needed, refer to the corresponding LSP server documentation.
397
398The following languages have inlay hints preconfigured by Zed:
399
400- [Go](https://docs.zed.dev/languages/go)
401- [Rust](https://docs.zed.dev/languages/rust)
402- [Svelte](https://docs.zed.dev/languages/svelte)
403- [Typescript](https://docs.zed.dev/languages/typescript)
404
405Use the `lsp` section for the server configuration. Examples are provided in the corresponding language documentation.
406
407Hints are not instantly queried in Zed, two kinds of debounces are used, either may be set to 0 to be disabled.
408Settings-related hint updates are not debounced.
409
410## Journal
411
412- Description: Configuration for the journal.
413- Setting: `journal`
414- Default:
415
416```json
417"journal": {
418 "path": "~",
419 "hour_format": "hour12"
420}
421```
422
423### Path
424
425- Description: The path of the directory where journal entries are stored.
426- Setting: `path`
427- Default: `~`
428
429**Options**
430
431`string` values
432
433### Hour Format
434
435- Description: The format to use for displaying hours in the journal.
436- Setting: `hour_format`
437- Default: `hour12`
438
439**Options**
440
4411. 12-hour format:
442
443```json
444{
445 "hour_format": "hour12"
446}
447```
448
4492. 24-hour format:
450
451```json
452{
453 "hour_format": "hour24"
454}
455```
456
457## Language Overrides
458
459- Description: Configuration overrides for specific languages.
460- Setting: `language_overrides`
461- Default: `null`
462
463**Options**
464
465To override settings for a language, add an entry for that languages name to the `language_overrides` value. Example:
466
467```json
468"language_overrides": {
469 "C": {
470 "format_on_save": "off",
471 "preferred_line_length": 64,
472 "soft_wrap": "preferred_line_length"
473 },
474 "JSON": {
475 "tab_size": 4
476 }
477}
478```
479
480The following settings can be overridden for each specific language:
481
482- `enable_language_server`
483- `ensure_final_newline_on_save`
484- `format_on_save`
485- `formatter`
486- `hard_tabs`
487- `preferred_line_length`
488- `remove_trailing_whitespace_on_save`
489- `show_copilot_suggestions`
490- `show_whitespaces`
491- `soft_wrap`
492- `tab_size`
493
494These values take in the same options as the root-level settings with the same name.
495
496## Preferred Line Length
497
498- Description: The column at which to soft-wrap lines, for buffers where soft-wrap is enabled.
499- Setting: `preferred_line_length`
500- Default: `80`
501
502**Options**
503
504`integer` values
505
506## Projects Online By Default
507
508- Description: Whether or not to show the online projects view by default.
509- Setting: `projects_online_by_default`
510- Default: `true`
511
512**Options**
513
514`boolean` values
515
516## Remove Trailing Whitespace On Save
517
518- Description: Whether or not to remove any trailing whitespace from lines of a buffer before saving it.
519- Setting: `remove_trailing_whitespace_on_save`
520- Default: `true`
521
522**Options**
523
524`boolean` values
525
526## Semantic Index
527
528- Description: Settings related to semantic index.
529- Setting: `semantic_index`
530- Default:
531
532```json
533"semantic_index": {
534 "enabled": false
535},
536```
537
538### Enabled
539
540- Description: Whether or not to display the `Semantic` mode in project search.
541- Setting: `enabled`
542- Default: `true`
543
544**Options**
545
546`boolean` values
547
548## Show Call Status Icon
549
550- Description: Whether or not to show the call status icon in the status bar.
551- Setting: `show_call_status_icon`
552- Default: `true`
553
554**Options**
555
556`boolean` values
557
558## Show Completions On Input
559
560- Description: Whether or not to show completions as you type.
561- Setting: `show_completions_on_input`
562- Default: `true`
563
564**Options**
565
566`boolean` values
567
568## Show Completion Documentation
569
570- Description: Whether to display inline and alongside documentation for items in the completions menu.
571- Setting: `show_completion_documentation`
572- Default: `true`
573
574**Options**
575
576`boolean` values
577
578## Completion Documentation Debounce Delay
579
580- Description: The debounce delay before re-querying the language server for completion documentation when not included in original completion list.
581- Setting: `completion_documentation_secondary_query_debounce`
582- Default: `300` ms
583
584**Options**
585
586`integer` values
587
588## Show Copilot Suggestions
589
590- Description: Whether or not to show Copilot suggestions as you type or wait for a `copilot::Toggle`.
591- Setting: `show_copilot_suggestions`
592- Default: `true`
593
594**Options**
595
596`boolean` values
597
598## Show Whitespaces
599
600- Description: Whether or not to show render whitespace characters in the editor.
601- Setting: `show_whitespaces`
602- Default: `selection`
603
604**Options**
605
6061. `all`
6072. `selection`
6083. `none`
609
610## Soft Wrap
611
612- Description: Whether or not to automatically wrap lines of text to fit editor / preferred width.
613- Setting: `soft_wrap`
614- Default: `none`
615
616**Options**
617
6181. `editor_width`
6192. `preferred_line_length`
6203. `none`
621
622## Tab Size
623
624- Description: The number of spaces to use for each tab character.
625- Setting: `tab_size`
626- Default: `4`
627
628**Options**
629
630`integer` values
631
632## Telemetry
633
634- Description: Control what info is collected by Zed.
635- Setting: `telemetry`
636- Default:
637
638```json
639"telemetry": {
640 "diagnostics": true,
641 "metrics": true
642},
643```
644
645**Options**
646
647### Diagnostics
648
649- Description: Setting for sending debug-related data, such as crash reports.
650- Setting: `diagnostics`
651- Default: `true`
652
653**Options**
654
655`boolean` values
656
657### Metrics
658
659- Description: Setting for sending anonymized usage data, such what languages you're using Zed with.
660- Setting: `metrics`
661- Default: `true`
662
663**Options**
664
665`boolean` values
666
667## Terminal
668
669- Description: Configuration for the terminal.
670- Setting: `terminal`
671- Default:
672
673```json
674"terminal": {
675 "alternate_scroll": "off",
676 "blinking": "terminal_controlled",
677 "copy_on_select": false,
678 "env": {},
679 "font_family": null,
680 "font_features": null,
681 "font_size": null,
682 "option_as_meta": false,
683 "shell": {},
684 "working_directory": "current_project_directory"
685}
686```
687
688### Alternate Scroll
689
690- Description: Set whether Alternate Scroll mode (DECSET code: `?1007`) is active by default. Alternate Scroll mode converts mouse scroll events into up / down key presses when in the alternate screen (e.g. when running applications like vim or less). The terminal can still set and unset this mode with ANSI escape codes.
691- Setting: `alternate_scroll`
692- Default: `off`
693
694**Options**
695
6961. Default alternate scroll mode to on
697
698```json
699{
700 "alternate_scroll": "on"
701}
702```
703
7042. Default alternate scroll mode to off
705
706```json
707{
708 "alternate_scroll": "off"
709}
710```
711
712### Blinking
713
714- Description: Set the cursor blinking behavior in the terminal
715- Setting: `blinking`
716- Default: `terminal_controlled`
717
718**Options**
719
7201. Never blink the cursor, ignore the terminal mode
721
722```json
723{
724 "blinking": "off"
725}
726```
727
7282. Default the cursor blink to off, but allow the terminal to turn blinking on
729
730```json
731{
732 "blinking": "terminal_controlled"
733}
734```
735
7363. Always blink the cursor, ignore the terminal mode
737
738```json
739"blinking": "on",
740```
741
742### Copy On Select
743
744- Description: Whether or not selecting text in the terminal will automatically copy to the system clipboard.
745- Setting: `copy_on_select`
746- Default: `false`
747
748**Options**
749
750`boolean` values
751
752### Env
753
754- Description: Any key-value pairs added to this object will be added to the terminal's environment. Keys must be unique, use `:` to separate multiple values in a single variable
755- Setting: `env`
756- Default: `{}`
757
758**Example**
759
760```json
761"env": {
762 "ZED": "1",
763 "KEY": "value1:value2"
764}
765```
766
767### Font Size
768
769- Description: What font size to use for the terminal. When not set defaults to matching the editor's font size
770- Setting: `font_size`
771- Default: `null`
772
773**Options**
774
775`integer` values
776
777### Font Family
778
779- Description: What font to use for the terminal. When not set, defaults to matching the editor's font.
780- Setting: `font_family`
781- Default: `null`
782
783**Options**
784
785The name of any font family installed on the user's system
786
787### Font Features
788
789- Description: What font features to use for the terminal. When not set, defaults to matching the editor's font features.
790- Setting: `font_features`
791- Default: `null`
792
793**Options**
794
795See Buffer Font Features
796
797### Option As Meta
798
799- Description: Re-interprets the option keys to act like a 'meta' key, like in Emacs.
800- Setting: `option_as_meta`
801- Default: `true`
802
803**Options**
804
805`boolean` values
806
807### Shell
808
809- Description: What shell to use when launching the terminal.
810- Setting: `shell`
811- Default: `system`
812
813**Options**
814
8151. Use the system's default terminal configuration (usually the `/etc/passwd` file).
816
817```json
818{
819 "shell": "system"
820}
821```
822
8232. A program to launch:
824
825```json
826"shell": {
827 "program": "sh"
828}
829```
830
8313. A program with arguments:
832
833```json
834"shell": {
835 "with_arguments": {
836 "program": "/bin/bash",
837 "args": ["--login"]
838 }
839}
840```
841
842### Working Directory
843
844- Description: What working directory to use when launching the terminal.
845- Setting: `working_directory`
846- Default: `"current_project_directory"`
847
848**Options**
849
8501. Use the current file's project directory. Will Fallback to the first project directory strategy if unsuccessful
851
852```json
853{
854 "working_directory": "current_project_directory"
855}
856```
857
8582. Use the first project in this workspace's directory. Will fallback to using this platform's home directory.
859
860```json
861{
862 "working_directory": "first_project_directory"
863}
864```
865
8663. Always use this platform's home directory (if we can find it)
867
868```json
869{
870 "working_directory": "always_home"
871}
872```
873
8744. Always use a specific directory. This value will be shell expanded. If this path is not a valid directory the terminal will default to this platform's home directory.
875
876```json
877"working_directory": {
878 "always": {
879 "directory": "~/zed/projects/"
880 }
881}
882```
883
884## Theme
885
886- Description: The theme setting can be specified in two forms - either as the name of a theme or as an object containing the `mode`, `dark`, and `light` themes for the Zed UI.
887- Setting: `theme`
888- Default: `One Dark`
889
890### Theme Object
891
892- Description: Specify the theme using an object that includes the `mode`, `dark`, and `light` themes.
893- Setting: `theme`
894- Default:
895
896```json
897"theme": {
898 "mode": "dark",
899 "dark": "One Dark",
900 "light": "One Light"
901},
902```
903
904### Mode
905
906- Description: Specify theme mode.
907- Setting: `mode`
908- Default: `dark`
909
910**Options**
911
9121. Set the theme to dark mode
913
914```json
915{
916 "mode": "dark"
917}
918```
919
9202. Set the theme to light mode
921
922```json
923{
924 "mode": "light"
925}
926```
927
9283. Set the theme to system mode
929
930```json
931{
932 "mode": "system"
933}
934```
935
936### Dark
937
938- Description: The name of the dark Zed theme to use for the UI.
939- Setting: `dark`
940- Default: `One Dark`
941
942**Options**
943
944Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
945
946### Light
947
948- Description: The name of the light Zed theme to use for the UI.
949- Setting: `light`
950- Default: `One Light`
951
952**Options**
953
954Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
955
956## Vim
957
958- Description: Whether or not to enable vim mode (work in progress).
959- Setting: `vim_mode`
960- Default: `false`
961
962## Project Panel
963
964- Description: Customise project panel
965- Setting: `project_panel`
966- Default:
967
968```json
969"project_panel": {
970 "dock": "left",
971 "git_status": true,
972 "default_width": "N/A - width in pixels"
973},
974```
975
976### Dock
977
978- Description: Control the position of the dock
979- Setting: `dock`
980- Default: `left`
981
982**Options**
983
9841. Default dock position to left
985
986```json
987{
988 "dock": "left"
989}
990```
991
9922. Default dock position to right
993
994```json
995{
996 "dock": "right"
997}
998```
999
1000### Git Status
1001
1002- Description: Indicates newly created and updated files
1003- Setting: `git_status`
1004- Default: `true`
1005
10061. Default enable git status
1007
1008```json
1009{
1010 "git_status": true
1011}
1012```
1013
10142. Default disable git status
1015
1016```json
1017{
1018 "git_status": false
1019}
1020```
1021
1022### Default Width
1023
1024- Description: Customise default width taken by project panel
1025- Setting: `default_width`
1026- Default: N/A width in pixels (eg: 420)
1027
1028**Options**
1029
1030`boolean` values
1031
1032## An example configuration:
1033
1034```json
1035// ~/.config/zed/settings.json
1036{
1037 "theme": "cave-light",
1038 "tab_size": 2,
1039 "preferred_line_length": 80,
1040 "soft_wrap": "none",
1041
1042 "buffer_font_size": 18,
1043 "buffer_font_family": "Zed Mono",
1044
1045 "autosave": "on_focus_change",
1046 "format_on_save": "off",
1047 "vim_mode": false,
1048 "projects_online_by_default": true,
1049 "terminal": {
1050 "font_family": "FiraCode Nerd Font Mono",
1051 "blinking": "off"
1052 },
1053 "language_overrides": {
1054 "C": {
1055 "format_on_save": "language_server",
1056 "preferred_line_length": 64,
1057 "soft_wrap": "preferred_line_length"
1058 }
1059 }
1060}
1061```