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}
388```
389
390**Options**
391
392Inlay hints querying consists of two parts: editor (client) and LSP server.
393With 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.
394At 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.
395
396The following languages have inlay hints preconfigured by Zed:
397
398- [Go](https://docs.zed.dev/languages/go)
399- [Rust](https://docs.zed.dev/languages/rust)
400- [Svelte](https://docs.zed.dev/languages/svelte)
401- [Typescript](https://docs.zed.dev/languages/typescript)
402
403Use the `lsp` section for the server configuration. Examples are provided in the corresponding language documentation.
404
405## Journal
406
407- Description: Configuration for the journal.
408- Setting: `journal`
409- Default:
410
411```json
412"journal": {
413 "path": "~",
414 "hour_format": "hour12"
415}
416```
417
418### Path
419
420- Description: The path of the directory where journal entries are stored.
421- Setting: `path`
422- Default: `~`
423
424**Options**
425
426`string` values
427
428### Hour Format
429
430- Description: The format to use for displaying hours in the journal.
431- Setting: `hour_format`
432- Default: `hour12`
433
434**Options**
435
4361. 12-hour format:
437
438```json
439{
440 "hour_format": "hour12"
441}
442```
443
4442. 24-hour format:
445
446```json
447{
448 "hour_format": "hour24"
449}
450```
451
452## Language Overrides
453
454- Description: Configuration overrides for specific languages.
455- Setting: `language_overrides`
456- Default: `null`
457
458**Options**
459
460To override settings for a language, add an entry for that languages name to the `language_overrides` value. Example:
461
462```json
463"language_overrides": {
464 "C": {
465 "format_on_save": "off",
466 "preferred_line_length": 64,
467 "soft_wrap": "preferred_line_length"
468 },
469 "JSON": {
470 "tab_size": 4
471 }
472}
473```
474
475The following settings can be overridden for each specific language:
476
477- `enable_language_server`
478- `ensure_final_newline_on_save`
479- `format_on_save`
480- `formatter`
481- `hard_tabs`
482- `preferred_line_length`
483- `remove_trailing_whitespace_on_save`
484- `show_copilot_suggestions`
485- `show_whitespaces`
486- `soft_wrap`
487- `tab_size`
488
489These values take in the same options as the root-level settings with the same name.
490
491## Preferred Line Length
492
493- Description: The column at which to soft-wrap lines, for buffers where soft-wrap is enabled.
494- Setting: `preferred_line_length`
495- Default: `80`
496
497**Options**
498
499`integer` values
500
501## Projects Online By Default
502
503- Description: Whether or not to show the online projects view by default.
504- Setting: `projects_online_by_default`
505- Default: `true`
506
507**Options**
508
509`boolean` values
510
511## Remove Trailing Whitespace On Save
512
513- Description: Whether or not to remove any trailing whitespace from lines of a buffer before saving it.
514- Setting: `remove_trailing_whitespace_on_save`
515- Default: `true`
516
517**Options**
518
519`boolean` values
520
521## Semantic Index
522
523- Description: Settings related to semantic index.
524- Setting: `semantic_index`
525- Default:
526
527```json
528"semantic_index": {
529 "enabled": false
530},
531```
532
533### Enabled
534
535- Description: Whether or not to display the `Semantic` mode in project search.
536- Setting: `enabled`
537- Default: `true`
538
539**Options**
540
541`boolean` values
542
543## Show Call Status Icon
544
545- Description: Whether or not to show the call status icon in the status bar.
546- Setting: `show_call_status_icon`
547- Default: `true`
548
549**Options**
550
551`boolean` values
552
553## Show Completions On Input
554
555- Description: Whether or not to show completions as you type.
556- Setting: `show_completions_on_input`
557- Default: `true`
558
559**Options**
560
561`boolean` values
562
563## Show Completion Documentation
564
565- Description: Whether to display inline and alongside documentation for items in the completions menu.
566- Setting: `show_completion_documentation`
567- Default: `true`
568
569**Options**
570
571`boolean` values
572
573## Completion Documentation Debounce Delay
574
575- Description: The debounce delay before re-querying the language server for completion documentation when not included in original completion list.
576- Setting: `completion_documentation_secondary_query_debounce`
577- Default: `300` ms
578
579**Options**
580
581`integer` values
582
583## Show Copilot Suggestions
584
585- Description: Whether or not to show Copilot suggestions as you type or wait for a `copilot::Toggle`.
586- Setting: `show_copilot_suggestions`
587- Default: `true`
588
589**Options**
590
591`boolean` values
592
593## Show Whitespaces
594
595- Description: Whether or not to show render whitespace characters in the editor.
596- Setting: `show_whitespaces`
597- Default: `selection`
598
599**Options**
600
6011. `all`
6022. `selection`
6033. `none`
604
605## Soft Wrap
606
607- Description: Whether or not to automatically wrap lines of text to fit editor / preferred width.
608- Setting: `soft_wrap`
609- Default: `none`
610
611**Options**
612
6131. `editor_width`
6142. `preferred_line_length`
6153. `none`
616
617## Tab Size
618
619- Description: The number of spaces to use for each tab character.
620- Setting: `tab_size`
621- Default: `4`
622
623**Options**
624
625`integer` values
626
627## Telemetry
628
629- Description: Control what info is collected by Zed.
630- Setting: `telemetry`
631- Default:
632
633```json
634"telemetry": {
635 "diagnostics": true,
636 "metrics": true
637},
638```
639
640**Options**
641
642### Diagnostics
643
644- Description: Setting for sending debug-related data, such as crash reports.
645- Setting: `diagnostics`
646- Default: `true`
647
648**Options**
649
650`boolean` values
651
652### Metrics
653
654- Description: Setting for sending anonymized usage data, such what languages you're using Zed with.
655- Setting: `metrics`
656- Default: `true`
657
658**Options**
659
660`boolean` values
661
662## Terminal
663
664- Description: Configuration for the terminal.
665- Setting: `terminal`
666- Default:
667
668```json
669"terminal": {
670 "alternate_scroll": "off",
671 "blinking": "terminal_controlled",
672 "copy_on_select": false,
673 "env": {},
674 "font_family": null,
675 "font_features": null,
676 "font_size": null,
677 "option_as_meta": false,
678 "shell": {},
679 "working_directory": "current_project_directory"
680}
681```
682
683### Alternate Scroll
684
685- 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.
686- Setting: `alternate_scroll`
687- Default: `off`
688
689**Options**
690
6911. Default alternate scroll mode to on
692
693```json
694{
695 "alternate_scroll": "on"
696}
697```
698
6992. Default alternate scroll mode to off
700
701```json
702{
703 "alternate_scroll": "off"
704}
705```
706
707### Blinking
708
709- Description: Set the cursor blinking behavior in the terminal
710- Setting: `blinking`
711- Default: `terminal_controlled`
712
713**Options**
714
7151. Never blink the cursor, ignore the terminal mode
716
717```json
718{
719 "blinking": "off"
720}
721```
722
7232. Default the cursor blink to off, but allow the terminal to turn blinking on
724
725```json
726{
727 "blinking": "terminal_controlled"
728}
729```
730
7313. Always blink the cursor, ignore the terminal mode
732
733```json
734"blinking": "on",
735```
736
737### Copy On Select
738
739- Description: Whether or not selecting text in the terminal will automatically copy to the system clipboard.
740- Setting: `copy_on_select`
741- Default: `false`
742
743**Options**
744
745`boolean` values
746
747### Env
748
749- 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
750- Setting: `env`
751- Default: `{}`
752
753**Example**
754
755```json
756"env": {
757 "ZED": "1",
758 "KEY": "value1:value2"
759}
760```
761
762### Font Size
763
764- Description: What font size to use for the terminal. When not set defaults to matching the editor's font size
765- Setting: `font_size`
766- Default: `null`
767
768**Options**
769
770`integer` values
771
772### Font Family
773
774- Description: What font to use for the terminal. When not set, defaults to matching the editor's font.
775- Setting: `font_family`
776- Default: `null`
777
778**Options**
779
780The name of any font family installed on the user's system
781
782### Font Features
783
784- Description: What font features to use for the terminal. When not set, defaults to matching the editor's font features.
785- Setting: `font_features`
786- Default: `null`
787
788**Options**
789
790See Buffer Font Features
791
792### Option As Meta
793
794- Description: Re-interprets the option keys to act like a 'meta' key, like in Emacs.
795- Setting: `option_as_meta`
796- Default: `true`
797
798**Options**
799
800`boolean` values
801
802### Shell
803
804- Description: What shell to use when launching the terminal.
805- Setting: `shell`
806- Default: `system`
807
808**Options**
809
8101. Use the system's default terminal configuration (usually the `/etc/passwd` file).
811
812```json
813{
814 "shell": "system"
815}
816```
817
8182. A program to launch:
819
820```json
821"shell": {
822 "program": "sh"
823}
824```
825
8263. A program with arguments:
827
828```json
829"shell": {
830 "with_arguments": {
831 "program": "/bin/bash",
832 "args": ["--login"]
833 }
834}
835```
836
837### Working Directory
838
839- Description: What working directory to use when launching the terminal.
840- Setting: `working_directory`
841- Default: `"current_project_directory"`
842
843**Options**
844
8451. Use the current file's project directory. Will Fallback to the first project directory strategy if unsuccessful
846
847```json
848{
849 "working_directory": "current_project_directory"
850}
851```
852
8532. Use the first project in this workspace's directory. Will fallback to using this platform's home directory.
854
855```json
856{
857 "working_directory": "first_project_directory"
858}
859```
860
8613. Always use this platform's home directory (if we can find it)
862
863```json
864{
865 "working_directory": "always_home"
866}
867```
868
8694. 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.
870
871```json
872"working_directory": {
873 "always": {
874 "directory": "~/zed/projects/"
875 }
876}
877```
878
879## Theme
880
881- 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.
882- Setting: `theme`
883- Default: `One Dark`
884
885### Theme Object
886
887- Description: Specify the theme using an object that includes the `mode`, `dark`, and `light` themes.
888- Setting: `theme`
889- Default:
890
891```json
892"theme": {
893 "mode": "dark",
894 "dark": "One Dark",
895 "light": "One Light"
896},
897```
898
899### Mode
900
901- Description: Specify theme mode.
902- Setting: `mode`
903- Default: `dark`
904
905**Options**
906
9071. Set the theme to dark mode
908
909```json
910{
911 "mode": "dark"
912}
913```
914
9152. Set the theme to light mode
916
917```json
918{
919 "mode": "light"
920}
921```
922
9233. Set the theme to system mode
924
925```json
926{
927 "mode": "system"
928}
929```
930
931### Dark
932
933- Description: The name of the dark Zed theme to use for the UI.
934- Setting: `dark`
935- Default: `One Dark`
936
937**Options**
938
939Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
940
941### Light
942
943- Description: The name of the light Zed theme to use for the UI.
944- Setting: `light`
945- Default: `One Light`
946
947**Options**
948
949Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
950
951## Vim
952
953- Description: Whether or not to enable vim mode (work in progress).
954- Setting: `vim_mode`
955- Default: `false`
956
957## Project Panel
958
959- Description: Customise project panel
960- Setting: `project_panel`
961- Default:
962
963```json
964"project_panel": {
965 "dock": "left",
966 "git_status": true,
967 "default_width": "N/A - width in pixels"
968},
969```
970
971### Dock
972
973- Description: Control the position of the dock
974- Setting: `dock`
975- Default: `left`
976
977**Options**
978
9791. Default dock position to left
980
981```json
982{
983 "dock": "left"
984}
985```
986
9872. Default dock position to right
988
989```json
990{
991 "dock": "right"
992}
993```
994
995### Git Status
996
997- Description: Indicates newly created and updated files
998- Setting: `git_status`
999- Default: `true`
1000
10011. Default enable git status
1002
1003```json
1004{
1005 "git_status": true
1006}
1007```
1008
10092. Default disable git status
1010
1011```json
1012{
1013 "git_status": false
1014}
1015```
1016
1017### Default Width
1018
1019- Description: Customise default width taken by project panel
1020- Setting: `default_width`
1021- Default: N/A width in pixels (eg: 420)
1022
1023**Options**
1024
1025`boolean` values
1026
1027## An example configuration:
1028
1029```json
1030// ~/.config/zed/settings.json
1031{
1032 "theme": "cave-light",
1033 "tab_size": 2,
1034 "preferred_line_length": 80,
1035 "soft_wrap": "none",
1036
1037 "buffer_font_size": 18,
1038 "buffer_font_family": "Zed Mono",
1039
1040 "autosave": "on_focus_change",
1041 "format_on_save": "off",
1042 "vim_mode": false,
1043 "projects_online_by_default": true,
1044 "terminal": {
1045 "font_family": "FiraCode Nerd Font Mono",
1046 "blinking": "off"
1047 },
1048 "language_overrides": {
1049 "C": {
1050 "format_on_save": "language_server",
1051 "preferred_line_length": 64,
1052 "soft_wrap": "preferred_line_length"
1053 }
1054 }
1055}
1056```