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- Description: Whether or not to automatically type closing characters for you.
311- Setting: `use_autoclose`
312- Default: `true`
313
314**Options**
315
316`boolean` values
317
318## Git
319
320- Description: Configuration for git-related features.
321- Setting: `git`
322- Default:
323
324```json
325"git": {
326 "git_gutter": "tracked_files"
327},
328```
329
330### Git Gutter
331
332- Description: Whether or not to show the git gutter.
333- Setting: `git_gutter`
334- Default: `tracked_files`
335
336**Options**
337
3381. Show git gutter in tracked files
339
340```json
341{
342 "git_gutter": "tracked_files"
343}
344```
345
3462. Hide git gutter
347
348```json
349{
350 "git_gutter": "hide"
351}
352```
353
354## Hard Tabs
355
356- Description: Whether to indent lines using tab characters or multiple spaces.
357- Setting: `hard_tabs`
358- Default: `false`
359
360**Options**
361
362`boolean` values
363
364## Hover Popover Enabled
365
366- Description: Whether or not to show the informational hover box when moving the mouse over symbols in the editor.
367- Setting: `hover_popover_enabled`
368- Default: `true`
369
370**Options**
371
372`boolean` values
373
374## Inlay hints
375
376- Description: Configuration for displaying extra text with hints in the editor.
377- Setting: `inlay_hints`
378- Default:
379
380```json
381"inlay_hints": {
382 "enabled": false,
383 "show_type_hints": true,
384 "show_parameter_hints": true,
385 "show_other_hints": true
386}
387```
388
389**Options**
390
391Inlay hints querying consists of two parts: editor (client) and LSP server.
392With 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.
393At 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.
394
395Use `lsp` section for the server configuration, below are some examples for well known servers:
396
397### Rust
398
399```json
400"lsp": {
401 "rust-analyzer": {
402 "initialization_options": {
403 "inlayHints": {
404 "maxLength": null,
405 "lifetimeElisionHints": {
406 "useParameterNames": true,
407 "enable": "skip_trivial"
408 },
409 "closureReturnTypeHints": {
410 "enable": "always"
411 }
412 }
413 }
414 }
415}
416```
417
418### Typescript
419
420```json
421"lsp": {
422 "typescript-language-server": {
423 "initialization_options": {
424 "preferences": {
425 "includeInlayParameterNameHints": "all",
426 "includeInlayParameterNameHintsWhenArgumentMatchesName": true,
427 "includeInlayFunctionParameterTypeHints": true,
428 "includeInlayVariableTypeHints": true,
429 "includeInlayVariableTypeHintsWhenTypeMatchesName": false,
430 "includeInlayPropertyDeclarationTypeHints": true,
431 "includeInlayFunctionLikeReturnTypeHints": true,
432 "includeInlayEnumMemberValueHints": true
433 }
434 }
435 }
436}
437```
438
439### Go
440
441```json
442"lsp": {
443 "gopls": {
444 "initialization_options": {
445 "hints": {
446 "assignVariableTypes": true,
447 "compositeLiteralFields": true,
448 "compositeLiteralTypes": true,
449 "constantValues": true,
450 "functionTypeParameters": true,
451 "parameterNames": true,
452 "rangeVariableTypes": true
453 }
454 }
455 }
456}
457```
458
459### Svelte
460
461```json
462{
463 "lsp": {
464 "typescript-language-server": {
465 "initialization_options": {
466 "preferences": {
467 "includeInlayParameterNameHints": "all",
468 "includeInlayParameterNameHintsWhenArgumentMatchesName": true,
469 "includeInlayFunctionParameterTypeHints": true,
470 "includeInlayVariableTypeHints": true,
471 "includeInlayVariableTypeHintsWhenTypeMatchesName": false,
472 "includeInlayPropertyDeclarationTypeHints": true,
473 "includeInlayFunctionLikeReturnTypeHints": true,
474 "includeInlayEnumMemberValueHints": true,
475 "includeInlayEnumMemberDeclarationTypes": true
476 }
477 }
478 }
479 }
480}
481```
482
483## Journal
484
485- Description: Configuration for the journal.
486- Setting: `journal`
487- Default:
488
489```json
490"journal": {
491 "path": "~",
492 "hour_format": "hour12"
493}
494```
495
496### Path
497
498- Description: The path of the directory where journal entries are stored.
499- Setting: `path`
500- Default: `~`
501
502**Options**
503
504`string` values
505
506### Hour Format
507
508- Description: The format to use for displaying hours in the journal.
509- Setting: `hour_format`
510- Default: `hour12`
511
512**Options**
513
5141. 12-hour format:
515
516```json
517{
518 "hour_format": "hour12"
519}
520```
521
5222. 24-hour format:
523
524```json
525{
526 "hour_format": "hour24"
527}
528```
529
530## Language Overrides
531
532- Description: Configuration overrides for specific languages.
533- Setting: `language_overrides`
534- Default: `null`
535
536**Options**
537
538To override settings for a language, add an entry for that languages name to the `language_overrides` value. Example:
539
540```json
541"language_overrides": {
542 "C": {
543 "format_on_save": "off",
544 "preferred_line_length": 64,
545 "soft_wrap": "preferred_line_length"
546 },
547 "JSON": {
548 "tab_size": 4
549 }
550}
551```
552
553The following settings can be overridden for each specific language:
554
555- `enable_language_server`
556- `ensure_final_newline_on_save`
557- `format_on_save`
558- `formatter`
559- `hard_tabs`
560- `preferred_line_length`
561- `remove_trailing_whitespace_on_save`
562- `show_copilot_suggestions`
563- `show_whitespaces`
564- `soft_wrap`
565- `tab_size`
566
567These values take in the same options as the root-level settings with the same name.
568
569## Preferred Line Length
570
571- Description: The column at which to soft-wrap lines, for buffers where soft-wrap is enabled.
572- Setting: `preferred_line_length`
573- Default: `80`
574
575**Options**
576
577`integer` values
578
579## Projects Online By Default
580
581- Description: Whether or not to show the online projects view by default.
582- Setting: `projects_online_by_default`
583- Default: `true`
584
585**Options**
586
587`boolean` values
588
589## Remove Trailing Whitespace On Save
590
591- Description: Whether or not to remove any trailing whitespace from lines of a buffer before saving it.
592- Setting: `remove_trailing_whitespace_on_save`
593- Default: `true`
594
595**Options**
596
597`boolean` values
598
599## Semantic Index
600
601- Description: Settings related to semantic index.
602- Setting: `semantic_index`
603- Default:
604
605```json
606"semantic_index": {
607 "enabled": false
608},
609```
610
611### Enabled
612
613- Description: Whether or not to display the `Semantic` mode in project search.
614- Setting: `enabled`
615- Default: `true`
616
617**Options**
618
619`boolean` values
620
621## Show Call Status Icon
622
623- Description: Whether or not to show the call status icon in the status bar.
624- Setting: `show_call_status_icon`
625- Default: `true`
626
627**Options**
628
629`boolean` values
630
631## Show Completions On Input
632
633- Description: Whether or not to show completions as you type.
634- Setting: `show_completions_on_input`
635- Default: `true`
636
637**Options**
638
639`boolean` values
640
641## Show Completion Documentation
642
643- Description: Whether to display inline and alongside documentation for items in the completions menu.
644- Setting: `show_completion_documentation`
645- Default: `true`
646
647**Options**
648
649`boolean` values
650
651## Completion Documentation Debounce Delay
652
653- Description: The debounce delay before re-querying the language server for completion documentation when not included in original completion list.
654- Setting: `completion_documentation_secondary_query_debounce`
655- Default: `300` ms
656
657**Options**
658
659`integer` values
660
661## Show Copilot Suggestions
662
663- Description: Whether or not to show Copilot suggestions as you type or wait for a `copilot::Toggle`.
664- Setting: `show_copilot_suggestions`
665- Default: `true`
666
667**Options**
668
669`boolean` values
670
671## Show Whitespaces
672
673- Description: Whether or not to show render whitespace characters in the editor.
674- Setting: `show_whitespaces`
675- Default: `selection`
676
677**Options**
678
6791. `all`
6802. `selection`
6813. `none`
682
683## Soft Wrap
684
685- Description: Whether or not to automatically wrap lines of text to fit editor / preferred width.
686- Setting: `soft_wrap`
687- Default: `none`
688
689**Options**
690
6911. `editor_width`
6922. `preferred_line_length`
6933. `none`
694
695## Tab Size
696
697- Description: The number of spaces to use for each tab character.
698- Setting: `tab_size`
699- Default: `4`
700
701**Options**
702
703`integer` values
704
705## Telemetry
706
707- Description: Control what info is collected by Zed.
708- Setting: `telemetry`
709- Default:
710
711```json
712"telemetry": {
713 "diagnostics": true,
714 "metrics": true
715},
716```
717
718**Options**
719
720### Diagnostics
721
722- Description: Setting for sending debug-related data, such as crash reports.
723- Setting: `diagnostics`
724- Default: `true`
725
726**Options**
727
728`boolean` values
729
730### Metrics
731
732- Description: Setting for sending anonymized usage data, such what languages you're using Zed with.
733- Setting: `metrics`
734- Default: `true`
735
736**Options**
737
738`boolean` values
739
740## Terminal
741
742- Description: Configuration for the terminal.
743- Setting: `terminal`
744- Default:
745
746```json
747"terminal": {
748 "alternate_scroll": "off",
749 "blinking": "terminal_controlled",
750 "copy_on_select": false,
751 "env": {},
752 "font_family": null,
753 "font_features": null,
754 "font_size": null,
755 "option_as_meta": false,
756 "shell": {},
757 "working_directory": "current_project_directory"
758}
759```
760
761### Alternate Scroll
762
763- 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.
764- Setting: `alternate_scroll`
765- Default: `off`
766
767**Options**
768
7691. Default alternate scroll mode to on
770
771```json
772{
773 "alternate_scroll": "on"
774}
775```
776
7772. Default alternate scroll mode to off
778
779```json
780{
781 "alternate_scroll": "off"
782}
783```
784
785### Blinking
786
787- Description: Set the cursor blinking behavior in the terminal
788- Setting: `blinking`
789- Default: `terminal_controlled`
790
791**Options**
792
7931. Never blink the cursor, ignore the terminal mode
794
795```json
796{
797 "blinking": "off"
798}
799```
800
8012. Default the cursor blink to off, but allow the terminal to turn blinking on
802
803```json
804{
805 "blinking": "terminal_controlled"
806}
807```
808
8093. Always blink the cursor, ignore the terminal mode
810
811```json
812"blinking": "on",
813```
814
815### Copy On Select
816
817- Description: Whether or not selecting text in the terminal will automatically copy to the system clipboard.
818- Setting: `copy_on_select`
819- Default: `false`
820
821**Options**
822
823`boolean` values
824
825### Env
826
827- 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
828- Setting: `env`
829- Default: `{}`
830
831**Example**
832
833```json
834"env": {
835 "ZED": "1",
836 "KEY": "value1:value2"
837}
838```
839
840### Font Size
841
842- Description: What font size to use for the terminal. When not set defaults to matching the editor's font size
843- Setting: `font_size`
844- Default: `null`
845
846**Options**
847
848`integer` values
849
850### Font Family
851
852- Description: What font to use for the terminal. When not set, defaults to matching the editor's font.
853- Setting: `font_family`
854- Default: `null`
855
856**Options**
857
858The name of any font family installed on the user's system
859
860### Font Features
861
862- Description: What font features to use for the terminal. When not set, defaults to matching the editor's font features.
863- Setting: `font_features`
864- Default: `null`
865
866**Options**
867
868See Buffer Font Features
869
870### Option As Meta
871
872- Description: Re-interprets the option keys to act like a 'meta' key, like in Emacs.
873- Setting: `option_as_meta`
874- Default: `true`
875
876**Options**
877
878`boolean` values
879
880### Shell
881
882- Description: What shell to use when launching the terminal.
883- Setting: `shell`
884- Default: `system`
885
886**Options**
887
8881. Use the system's default terminal configuration (usually the `/etc/passwd` file).
889
890```json
891{
892 "shell": "system"
893}
894```
895
8962. A program to launch:
897
898```json
899"shell": {
900 "program": "sh"
901}
902```
903
9043. A program with arguments:
905
906```json
907"shell": {
908 "with_arguments": {
909 "program": "/bin/bash",
910 "args": ["--login"]
911 }
912}
913```
914
915### Working Directory
916
917- Description: What working directory to use when launching the terminal.
918- Setting: `working_directory`
919- Default: `"current_project_directory"`
920
921**Options**
922
9231. Use the current file's project directory. Will Fallback to the first project directory strategy if unsuccessful
924
925```json
926{
927 "working_directory": "current_project_directory"
928}
929```
930
9312. Use the first project in this workspace's directory. Will fallback to using this platform's home directory.
932
933```json
934{
935 "working_directory": "first_project_directory"
936}
937```
938
9393. Always use this platform's home directory (if we can find it)
940
941```json
942{
943 "working_directory": "always_home"
944}
945```
946
9474. 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.
948
949```json
950"working_directory": {
951 "always": {
952 "directory": "~/zed/projects/"
953 }
954}
955```
956
957## Theme
958
959- Description: The name of the Zed theme to use for the UI.
960- Setting: `theme`
961- Default: `One Dark`
962
963**Options**
964
965Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
966
967## Vim
968
969- Description: Whether or not to enable vim mode (work in progress).
970- Setting: `vim_mode`
971- Default: `false`
972
973## Project Panel
974
975- Description: Customise project panel
976- Setting: `project_panel`
977- Default:
978
979```json
980"project_panel": {
981 "dock": "left",
982 "git_status": true,
983 "default_width": "N/A - width in pixels"
984},
985```
986
987### Dock
988
989- Description: Control the position of the dock
990- Setting: `dock`
991- Default: `left`
992
993**Options**
994
9951. Default dock position to left
996
997```json
998{
999 "dock": "left"
1000}
1001```
1002
10032. Default dock position to right
1004
1005```json
1006{
1007 "dock": "right"
1008}
1009```
1010
1011### Git Status
1012
1013- Description: Indicates newly created and updated files
1014- Setting: `git_status`
1015- Default: `true`
1016
10171. Default enable git status
1018
1019```json
1020{
1021 "git_status": true
1022}
1023```
1024
10252. Default disable git status
1026
1027```json
1028{
1029 "git_status": false
1030}
1031```
1032
1033### Default Width
1034
1035- Description: Customise default width taken by project panel
1036- Setting: `default_width`
1037- Default: N/A width in pixels (eg: 420)
1038
1039**Options**
1040
1041`boolean` values
1042
1043## An example configuration:
1044
1045```json
1046// ~/.config/zed/settings.json
1047{
1048 "theme": "cave-light",
1049 "tab_size": 2,
1050 "preferred_line_length": 80,
1051 "soft_wrap": "none",
1052
1053 "buffer_font_size": 18,
1054 "buffer_font_family": "Zed Mono",
1055
1056 "autosave": "on_focus_change",
1057 "format_on_save": "off",
1058 "vim_mode": false,
1059 "projects_online_by_default": true,
1060 "terminal": {
1061 "font_family": "FiraCode Nerd Font Mono",
1062 "blinking": "off"
1063 },
1064 "language_overrides": {
1065 "C": {
1066 "format_on_save": "language_server",
1067 "preferred_line_length": 64,
1068 "soft_wrap": "preferred_line_length"
1069 }
1070 }
1071}
1072```