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