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