1# Configuring Zed
2
3Zed is designed to be configured: we want to fit your workflow and preferences exactly. We provide default settings that are designed to be a comfortable starting point for as many people as possible, but we hope you will enjoy tweaking it to make it feel incredible.
4
5In addition to the settings described here, you may also want to change your [theme](./themes.md), configure your [key bindings](./key-bindings.md), set up [tasks](./tasks.md) or install [extensions](https://github.com/zed-industries/extensions).
6
7## Settings files
8
9<!--
10TBD: Settings files. Rewrite with "remote settings" in mind (e.g. `local settings` on the remote host).
11Consider renaming `zed: Open Local Settings` to `zed: Open Project Settings`.
12
13TBD: Add settings documentation about how settings are merged as overlays. E.g. project>local>default. Note how settings that are maps are merged, but settings that are arrays are replaced and must include the defaults.
14-->
15
16Your settings file can be opened with {#kb zed::OpenSettings}. By default it is located at `~/.config/zed/settings.json`, though if you have XDG_CONFIG_HOME in your environment on Linux it will be at `$XDG_CONFIG_HOME/zed/settings.json` instead.
17
18This configuration is merged with any local configuration inside your projects. You can open the project settings by running {#action zed::OpenLocalSettings} from the command palette. This will create a `.zed` directory containing`.zed/settings.json`.
19
20Although most projects will only need one settings file at the root, you can add more local settings files for subdirectories as needed. Not all settings can be set in local files, just those that impact the behavior of the editor and language tooling. For example you can set `tab_size`, `formatter` etc. but not `theme`, `vim_mode` and similar.
21
22The syntax for configuration files is a super-set of JSON that allows `//` comments.
23
24## Default settings
25
26You can find the default settings for your current Zed by running {#action zed::OpenDefaultSettings} from the command palette.
27
28Extensions that provide language servers may also provide default settings for those language servers.
29
30# Settings
31
32## Active Pane Magnification
33
34- 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.
35- Setting: `active_pane_magnification`
36- Default: `1.0`
37
38**Options**
39
40`float` values
41
42## Autosave
43
44- Description: When to automatically save edited buffers.
45- Setting: `autosave`
46- Default: `off`
47
48**Options**
49
501. To disable autosave, set it to `off`:
51
52```json
53{
54 "autosave": "off"
55}
56```
57
582. To autosave when focus changes, use `on_focus_change`:
59
60```json
61{
62 "autosave": "on_focus_change"
63}
64```
65
663. To autosave when the active window changes, use `on_window_change`:
67
68```json
69{
70 "autosave": "on_window_change"
71}
72```
73
744. To autosave after an inactivity period, use `after_delay`:
75
76```json
77{
78 "autosave": {
79 "after_delay": {
80 "milliseconds": 1000
81 }
82 }
83}
84```
85
86## Auto Update
87
88- Description: Whether or not to automatically check for updates.
89- Setting: `auto_update`
90- Default: `true`
91
92**Options**
93
94`boolean` values
95
96## Buffer Font Family
97
98- Description: The name of a font to use for rendering text in the editor.
99- Setting: `buffer_font_family`
100- Default: `Zed Plex Mono`
101
102**Options**
103
104The name of any font family installed on the user's system
105
106## Buffer Font Features
107
108- Description: The OpenType features to enable for text in the editor.
109- Setting: `buffer_font_features`
110- Default: `null`
111- Platform: macOS and Windows.
112
113**Options**
114
115Zed supports all OpenType features that can be enabled or disabled for a given buffer or terminal font, as well as setting values for font features.
116
117For example, to disable font ligatures, add the following to your settings:
118
119```json
120{
121 "buffer_font_features": {
122 "calt": false
123 }
124}
125```
126
127You can also set other OpenType features, like setting `cv01` to `7`:
128
129```json
130{
131 "buffer_font_features": {
132 "cv01": 7
133 }
134}
135```
136
137## Buffer Font Fallbacks
138
139- Description: Set the buffer text's font fallbacks, this will be merged with the platform's default fallbacks.
140- Setting: `buffer_font_fallbacks`
141- Default: `null`
142- Platform: macOS and Windows.
143
144**Options**
145
146For example, to use `Nerd Font` as a fallback, add the following to your settings:
147
148```json
149{
150 "buffer_font_fallbacks": ["Nerd Font"]
151}
152```
153
154## Buffer Font Size
155
156- Description: The default font size for text in the editor.
157- Setting: `buffer_font_size`
158- Default: `15`
159
160**Options**
161
162`integer` values
163
164## Buffer Font Weight
165
166- Description: The default font weight for text in the editor.
167- Setting: `buffer_font_weight`
168- Default: `400`
169
170**Options**
171
172`integer` values between `100` and `900`
173
174## Buffer Line Height
175
176- Description: The default line height for text in the editor.
177- Setting: `buffer_line_height`
178- Default: `"comfortable"`
179
180**Options**
181
182`"standard"`, `"comfortable"` or `{"custom": float}` (`1` is very compact, `2` very loose)
183
184## Confirm Quit
185
186- Description: Whether or not to prompt the user to confirm before closing the application.
187- Setting: `confirm_quit`
188- Default: `false`
189
190**Options**
191
192`boolean` values
193
194## Centered Layout
195
196- Description: Configuration for the centered layout mode.
197- Setting: `centered_layout`
198- Default:
199
200```json
201"centered_layout": {
202 "left_padding": 0.2,
203 "right_padding": 0.2,
204}
205```
206
207**Options**
208
209The `left_padding` and `right_padding` options define the relative width of the
210left and right padding of the central pane from the workspace when the centered layout mode is activated. Valid values range is from `0` to `0.4`.
211
212## Direnv Integration
213
214- Description: Settings for [direnv](https://direnv.net/) integration. Requires `direnv` to be installed. `direnv` integration currently only means that the environment variables set by a `direnv` configuration can be used to detect some language servers in `$PATH` instead of installing them.
215- Setting: `load_direnv`
216- Default:
217
218```json
219"load_direnv": "shell_hook"
220```
221
222**Options**
223There are two options to choose from:
224
2251. `shell_hook`: Use the shell hook to load direnv. This relies on direnv to activate upon entering the directory. Supports POSIX shells and fish.
2262. `direct`: Use `direnv export json` to load direnv. This will load direnv directly without relying on the shell hook and might cause some inconsistencies. This allows direnv to work with any shell.
227
228## Inline Completions
229
230- Description: Settings for inline completions.
231- Setting: `inline_completions`
232- Default:
233
234```json
235"inline_completions": {
236 "disabled_globs": [
237 ".env"
238 ]
239}
240```
241
242**Options**
243
244### Disabled Globs
245
246- Description: A list of globs representing files that inline completions should be disabled for.
247- Setting: `disabled_globs`
248- Default: `[".env"]`
249
250**Options**
251
252List of `string` values
253
254## Current Line Highlight
255
256- Description: How to highlight the current line in the editor.
257- Setting: `current_line_highlight`
258- Default: `all`
259
260**Options**
261
2621. Don't highlight the current line:
263
264```json
265"current_line_highlight": "none"
266```
267
2682. Highlight the gutter area:
269
270```json
271"current_line_highlight": "gutter"
272```
273
2743. Highlight the editor area:
275
276```json
277"current_line_highlight": "line"
278```
279
2804. Highlight the full line:
281
282```json
283"current_line_highlight": "all"
284```
285
286## Cursor Blink
287
288- Description: Whether or not the cursor blinks.
289- Setting: `cursor_blink`
290- Default: `true`
291
292**Options**
293
294`boolean` values
295
296## Default Dock Anchor
297
298- Description: The default anchor for new docks.
299- Setting: `default_dock_anchor`
300- Default: `bottom`
301
302**Options**
303
3041. Position the dock attached to the bottom of the workspace: `bottom`
3052. Position the dock to the right of the workspace like a side panel: `right`
3063. Position the dock full screen over the entire workspace: `expanded`
307
308## Editor Scrollbar
309
310- Description: Whether or not to show the editor scrollbar and various elements in it.
311- Setting: `scrollbar`
312- Default:
313
314```json
315"scrollbar": {
316 "show": "auto",
317 "cursors": true,
318 "git_diff": true,
319 "search_results": true,
320 "selected_symbol": true,
321 "diagnostics": true
322},
323```
324
325### Show Mode
326
327- Description: When to show the editor scrollbar.
328- Setting: `show`
329- Default: `auto`
330
331**Options**
332
3331. Show the scrollbar if there's important information or follow the system's configured behavior:
334
335```json
336"scrollbar": {
337 "show": "auto"
338}
339```
340
3412. Match the system's configured behavior:
342
343```json
344"scrollbar": {
345 "show": "system"
346}
347```
348
3493. Always show the scrollbar:
350
351```json
352"scrollbar": {
353 "show": "always"
354}
355```
356
3574. Never show the scrollbar:
358
359```json
360"scrollbar": {
361 "show": "never"
362}
363```
364
365### Cursor Indicators
366
367- Description: Whether to show cursor positions in the scrollbar.
368- Setting: `cursors`
369- Default: `true`
370
371**Options**
372
373`boolean` values
374
375### Git Diff Indicators
376
377- Description: Whether to show git diff indicators in the scrollbar.
378- Setting: `git_diff`
379- Default: `true`
380
381**Options**
382
383`boolean` values
384
385### Search Results Indicators
386
387- Description: Whether to show buffer search results in the scrollbar.
388- Setting: `search_results`
389- Default: `true`
390
391**Options**
392
393`boolean` values
394
395### Selected Symbols Indicators
396
397- Description: Whether to show selected symbol occurrences in the scrollbar.
398- Setting: `selected_symbol`
399- Default: `true`
400
401**Options**
402
403`boolean` values
404
405### Diagnostics
406
407- Description: Whether to show diagnostic indicators in the scrollbar.
408- Setting: `diagnostics`
409- Default: `true`
410
411**Options**
412
413`boolean` values
414
415## Editor Tab Bar
416
417- Description: Settings related to the editor's tab bar.
418- Settings: `tab_bar`
419- Default:
420
421```json
422"tab_bar": {
423 "show": true,
424 "show_nav_history_buttons": true
425}
426```
427
428### Show
429
430- Description: Whether or not to show the tab bar in the editor.
431- Setting: `show`
432- Default: `true`
433
434**Options**
435
436`boolean` values
437
438### Navigation History Buttons
439
440- Description: Whether or not to show the navigation history buttons.
441- Setting: `show_nav_history_buttons`
442- Default: `true`
443
444**Options**
445
446`boolean` values
447
448## Editor Tabs
449
450- Description: Configuration for the editor tabs.
451- Setting: `tabs`
452- Default:
453
454```json
455"tabs": {
456 "close_position": "right",
457 "file_icons": false,
458 "git_status": false
459},
460```
461
462### Close Position
463
464- Description: Where to display close button within a tab.
465- Setting: `close_position`
466- Default: `right`
467
468**Options**
469
4701. Display the close button on the right:
471
472```json
473{
474 "close_position": "right"
475}
476```
477
4782. Display the close button on the left:
479
480```json
481{
482 "close_position": "left"
483}
484```
485
486### File Icons
487
488- Description: Whether to show the file icon for a tab.
489- Setting: `file_icons`
490- Default: `false`
491
492### Git Status
493
494- Description: Whether or not to show Git file status in tab.
495- Setting: `git_status`
496- Default: `false`
497
498## Editor Toolbar
499
500- Description: Whether or not to show various elements in the editor toolbar.
501- Setting: `toolbar`
502- Default:
503
504```json
505"toolbar": {
506 "breadcrumbs": true,
507 "quick_actions": true
508},
509```
510
511**Options**
512
513Each option controls displaying of a particular toolbar element. If all elements are hidden, the editor toolbar is not displayed.
514
515## Enable Language Server
516
517- Description: Whether or not to use language servers to provide code intelligence.
518- Setting: `enable_language_server`
519- Default: `true`
520
521**Options**
522
523`boolean` values
524
525## Ensure Final Newline On Save
526
527- Description: Whether or not to ensure there's a single newline at the end of a buffer when saving it.
528- Setting: `ensure_final_newline_on_save`
529- Default: `true`
530
531**Options**
532
533`boolean` values
534
535## LSP
536
537- Description: Configuration for language servers.
538- Setting: `lsp`
539- Default: `null`
540
541**Options**
542
543The following settings can be overridden for specific language servers:
544
545- `initialization_options`
546
547To override settings for a language, add an entry for that language server's name to the `lsp` value. Example:
548
549```json
550"lsp": {
551 "rust-analyzer": {
552 "initialization_options": {
553 "check": {
554 "command": "clippy" // rust-analyzer.check.command (default: "check")
555 }
556 }
557 }
558}
559```
560
561## Format On Save
562
563- Description: Whether or not to perform a buffer format before saving.
564- Setting: `format_on_save`
565- Default: `on`
566
567**Options**
568
5691. `on`, enables format on save obeying `formatter` setting:
570
571```json
572{
573 "format_on_save": "on"
574}
575```
576
5772. `off`, disables format on save:
578
579```json
580{
581 "format_on_save": "off"
582}
583```
584
585## Formatter
586
587- Description: How to perform a buffer format.
588- Setting: `formatter`
589- Default: `auto`
590
591**Options**
592
5931. To use the current language server, use `"language_server"`:
594
595```json
596{
597 "formatter": "language_server"
598}
599```
600
6012. 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):
602
603```json
604{
605 "formatter": {
606 "external": {
607 "command": "sed",
608 "arguments": ["-e", "s/ *$//"]
609 }
610 }
611}
612```
613
6143. Or to use code actions provided by the connected language servers, use `"code_actions"`:
615
616```json
617{
618 "formatter": {
619 "code_actions": {
620 // Use ESLint's --fix:
621 "source.fixAll.eslint": true,
622 // Organize imports on save:
623 "source.organizeImports": true
624 }
625 }
626}
627```
628
6294. Or to use multiple formatters consecutively, use an array of formatters:
630
631```json
632{
633 "formatter": [
634 {"language_server": {"name": "rust-analyzer"}},
635 {"external": {
636 "command": "sed",
637 "arguments": ["-e", "s/ *$//"]
638 }
639 ]
640}
641```
642
643Here `rust-analyzer` will be used first to format the code, followed by a call of sed.
644If any of the formatters fails, the subsequent ones will still be executed.
645
646## Code Actions On Format
647
648- Description: The code actions to perform with the primary language server when formatting the buffer.
649- Setting: `code_actions_on_format`
650- Default: `{}`, except for Go it's `{ "source.organizeImports": true }`
651
652**Examples**
653
654<!--
655TBD: Add Python Ruff source.organizeImports example
656-->
657
6581. Organize imports on format in TypeScript and TSX buffers:
659
660```json
661{
662 "languages": {
663 "TypeScript": {
664 "code_actions_on_format": {
665 "source.organizeImports": true
666 }
667 },
668 "TSX": {
669 "code_actions_on_format": {
670 "source.organizeImports": true
671 }
672 }
673 }
674}
675```
676
6772. Run ESLint `fixAll` code action when formatting:
678
679```json
680{
681 "languages": {
682 "JavaScript": {
683 "code_actions_on_format": {
684 "source.fixAll.eslint": true
685 }
686 }
687 }
688}
689```
690
6913. Run only a single ESLint rule when using `fixAll`:
692
693```json
694{
695 "languages": {
696 "JavaScript": {
697 "code_actions_on_format": {
698 "source.fixAll.eslint": true
699 }
700 }
701 },
702 "lsp": {
703 "eslint": {
704 "settings": {
705 "codeActionOnSave": {
706 "rules": ["import/order"]
707 }
708 }
709 }
710 }
711}
712```
713
714## Auto close
715
716- Description: Whether to automatically add matching closing characters when typing opening parenthesis, bracket, brace, single or double quote characters.
717- Setting: `use_autoclose`
718- Default: `true`
719
720**Options**
721
722`boolean` values
723
724## Always Treat Brackets As Autoclosed
725
726- Description: Controls how the editor handles the autoclosed characters.
727- Setting: `always_treat_brackets_as_autoclosed`
728- Default: `false`
729
730**Options**
731
732`boolean` values
733
734**Example**
735
736If the setting is set to `true`:
737
7381. Enter in the editor: `)))`
7392. Move the cursor to the start: `^)))`
7403. Enter again: `)))`
741
742The result is still `)))` and not `))))))`, which is what it would be by default.
743
744## File Types
745
746- Setting: `file_types`
747- Description: Configure how Zed selects a language for a file based on its filename or extension. Supports glob entries.
748- Default: `{}`
749
750**Examples**
751
752To interpret all `.c` files as C++, files called `MyLockFile` as TOML and files starting with `Dockerfile` as Dockerfile:
753
754```json
755{
756 "file_types": {
757 "C++": ["c"],
758 "TOML": ["MyLockFile"],
759 "Dockerfile": ["Dockerfile*"]
760 }
761}
762```
763
764## Git
765
766- Description: Configuration for git-related features.
767- Setting: `git`
768- Default:
769
770```json
771{
772 "git": {
773 "git_gutter": "tracked_files",
774 "inline_blame": {
775 "enabled": true
776 }
777 }
778}
779```
780
781### Git Gutter
782
783- Description: Whether or not to show the git gutter.
784- Setting: `git_gutter`
785- Default: `tracked_files`
786
787**Options**
788
7891. Show git gutter in tracked files
790
791```json
792{
793 "git": {
794 "git_gutter": "tracked_files"
795 }
796}
797```
798
7992. Hide git gutter
800
801```json
802{
803 "git": {
804 "git_gutter": "hide"
805 }
806}
807```
808
809### Indent Guides
810
811- Description: Configuration related to indent guides. Indent guides can be configured separately for each language.
812- Setting: `indent_guides`
813- Default:
814
815```json
816{
817 "indent_guides": {
818 "enabled": true,
819 "line_width": 1,
820 "active_line_width": 1,
821 "coloring": "fixed",
822 "background_coloring": "disabled"
823 }
824}
825```
826
827**Options**
828
8291. Disable indent guides
830
831```json
832{
833 "indent_guides": {
834 "enabled": false
835 }
836}
837```
838
8392. Enable indent guides for a specific language.
840
841```json
842{
843 "languages": {
844 "Python": {
845 "indent_guides": {
846 "enabled": true
847 }
848 }
849 }
850}
851```
852
8533. Enable indent aware coloring ("rainbow indentation").
854 The colors that are used for different indentation levels are defined in the theme (theme key: `accents`). They can be customized by using theme overrides.
855
856```json
857{
858 "indent_guides": {
859 "enabled": true,
860 "coloring": "indent_aware"
861 }
862}
863```
864
8654. Enable indent aware background coloring ("rainbow indentation").
866 The colors that are used for different indentation levels are defined in the theme (theme key: `accents`). They can be customized by using theme overrides.
867
868```json
869{
870 "indent_guides": {
871 "enabled": true,
872 "coloring": "indent_aware",
873 "background_coloring": "indent_aware"
874 }
875}
876```
877
878### Inline Git Blame
879
880- Description: Whether or not to show git blame information inline, on the currently focused line.
881- Setting: `inline_blame`
882- Default:
883
884```json
885{
886 "git": {
887 "inline_blame": {
888 "enabled": true
889 }
890 }
891}
892```
893
894**Options**
895
8961. Disable inline git blame:
897
898```json
899{
900 "git": {
901 "inline_blame": {
902 "enabled": false
903 }
904 }
905}
906```
907
9082. Only show inline git blame after a delay (that starts after cursor stops moving):
909
910```json
911{
912 "git": {
913 "inline_blame": {
914 "enabled": true,
915 "delay_ms": 500
916 }
917 }
918}
919```
920
921## Hard Tabs
922
923- Description: Whether to indent lines using tab characters or multiple spaces.
924- Setting: `hard_tabs`
925- Default: `false`
926
927**Options**
928
929`boolean` values
930
931## Hover Popover Enabled
932
933- Description: Whether or not to show the informational hover box when moving the mouse over symbols in the editor.
934- Setting: `hover_popover_enabled`
935- Default: `true`
936
937**Options**
938
939`boolean` values
940
941## Inlay hints
942
943- Description: Configuration for displaying extra text with hints in the editor.
944- Setting: `inlay_hints`
945- Default:
946
947```json
948"inlay_hints": {
949 "enabled": false,
950 "show_type_hints": true,
951 "show_parameter_hints": true,
952 "show_other_hints": true,
953 "edit_debounce_ms": 700,
954 "scroll_debounce_ms": 50
955}
956```
957
958**Options**
959
960Inlay hints querying consists of two parts: editor (client) and LSP server.
961With 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.
962At 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.
963
964The following languages have inlay hints preconfigured by Zed:
965
966- [Go](https://docs.zed.dev/languages/go)
967- [Rust](https://docs.zed.dev/languages/rust)
968- [Svelte](https://docs.zed.dev/languages/svelte)
969- [Typescript](https://docs.zed.dev/languages/typescript)
970
971Use the `lsp` section for the server configuration. Examples are provided in the corresponding language documentation.
972
973Hints are not instantly queried in Zed, two kinds of debounces are used, either may be set to 0 to be disabled.
974Settings-related hint updates are not debounced.
975
976## Journal
977
978- Description: Configuration for the journal.
979- Setting: `journal`
980- Default:
981
982```json
983"journal": {
984 "path": "~",
985 "hour_format": "hour12"
986}
987```
988
989### Path
990
991- Description: The path of the directory where journal entries are stored.
992- Setting: `path`
993- Default: `~`
994
995**Options**
996
997`string` values
998
999### Hour Format
1000
1001- Description: The format to use for displaying hours in the journal.
1002- Setting: `hour_format`
1003- Default: `hour12`
1004
1005**Options**
1006
10071. 12-hour format:
1008
1009```json
1010{
1011 "hour_format": "hour12"
1012}
1013```
1014
10152. 24-hour format:
1016
1017```json
1018{
1019 "hour_format": "hour24"
1020}
1021```
1022
1023## Languages
1024
1025- Description: Configuration for specific languages.
1026- Setting: `languages`
1027- Default: `null`
1028
1029**Options**
1030
1031To override settings for a language, add an entry for that languages name to the `languages` value. Example:
1032
1033```json
1034"languages": {
1035 "C": {
1036 "format_on_save": "off",
1037 "preferred_line_length": 64,
1038 "soft_wrap": "preferred_line_length"
1039 },
1040 "JSON": {
1041 "tab_size": 4
1042 }
1043}
1044```
1045
1046The following settings can be overridden for each specific language:
1047
1048- `enable_language_server`
1049- `ensure_final_newline_on_save`
1050- `format_on_save`
1051- `formatter`
1052- `hard_tabs`
1053- `preferred_line_length`
1054- `remove_trailing_whitespace_on_save`
1055- `show_inline_completions`
1056- `show_whitespaces`
1057- `soft_wrap`
1058- `tab_size`
1059- `use_autoclose`
1060- `always_treat_brackets_as_autoclosed`
1061
1062These values take in the same options as the root-level settings with the same name.
1063
1064## Preview tabs
1065
1066- Description:
1067 Preview tabs allow you to open files in preview mode, where they close automatically when you switch to another file unless you explicitly pin them. This is useful for quickly viewing files without cluttering your workspace. Preview tabs display their file names in italics. \
1068 There are several ways to convert a preview tab into a regular tab:
1069
1070 - Double-clicking on the file
1071 - Double-clicking on the tab header
1072 - Using the `project_panel::OpenPermanent` action
1073 - Editing the file
1074 - Dragging the file to a different pane
1075
1076- Setting: `preview_tabs`
1077- Default:
1078
1079```json
1080"preview_tabs": {
1081 "enabled": true,
1082 "enable_preview_from_file_finder": false,
1083 "enable_preview_from_code_navigation": false,
1084}
1085```
1086
1087### Enable preview from file finder
1088
1089- Description: Determines whether to open files in preview mode when selected from the file finder.
1090- Setting: `enable_preview_from_file_finder`
1091- Default: `false`
1092
1093**Options**
1094
1095`boolean` values
1096
1097### Enable preview from code navigation
1098
1099- Description: Determines whether a preview tab gets replaced when code navigation is used to navigate away from the tab.
1100- Setting: `enable_preview_from_code_navigation`
1101- Default: `false`
1102
1103**Options**
1104
1105`boolean` values
1106
1107## Preferred Line Length
1108
1109- Description: The column at which to soft-wrap lines, for buffers where soft-wrap is enabled.
1110- Setting: `preferred_line_length`
1111- Default: `80`
1112
1113**Options**
1114
1115`integer` values
1116
1117## Projects Online By Default
1118
1119- Description: Whether or not to show the online projects view by default.
1120- Setting: `projects_online_by_default`
1121- Default: `true`
1122
1123**Options**
1124
1125`boolean` values
1126
1127## Remove Trailing Whitespace On Save
1128
1129- Description: Whether or not to remove any trailing whitespace from lines of a buffer before saving it.
1130- Setting: `remove_trailing_whitespace_on_save`
1131- Default: `true`
1132
1133**Options**
1134
1135`boolean` values
1136
1137## Show Call Status Icon
1138
1139- Description: Whether or not to show the call status icon in the status bar.
1140- Setting: `show_call_status_icon`
1141- Default: `true`
1142
1143**Options**
1144
1145`boolean` values
1146
1147## Show Completions On Input
1148
1149- Description: Whether or not to show completions as you type.
1150- Setting: `show_completions_on_input`
1151- Default: `true`
1152
1153**Options**
1154
1155`boolean` values
1156
1157## Show Completion Documentation
1158
1159- Description: Whether to display inline and alongside documentation for items in the completions menu.
1160- Setting: `show_completion_documentation`
1161- Default: `true`
1162
1163**Options**
1164
1165`boolean` values
1166
1167## Completion Documentation Debounce Delay
1168
1169- Description: The debounce delay before re-querying the language server for completion documentation when not included in original completion list.
1170- Setting: `completion_documentation_secondary_query_debounce`
1171- Default: `300` ms
1172
1173**Options**
1174
1175`integer` values
1176
1177## Show Inline Completions
1178
1179- Description: Whether to show inline completions as you type or manually by triggering `editor::ShowInlineCompletion`.
1180- Setting: `show_inline_completions`
1181- Default: `true`
1182
1183**Options**
1184
1185`boolean` values
1186
1187## Show Whitespaces
1188
1189- Description: Whether or not to show render whitespace characters in the editor.
1190- Setting: `show_whitespaces`
1191- Default: `selection`
1192
1193**Options**
1194
11951. `all`
11962. `selection`
11973. `none`
11984. `boundary`
1199
1200## Soft Wrap
1201
1202- Description: Whether or not to automatically wrap lines of text to fit editor / preferred width.
1203- Setting: `soft_wrap`
1204- Default: `prefer_line`
1205
1206**Options**
1207
12081. `none` to stop the soft-wrapping
12092. `prefer_line` to avoid wrapping generally, unless the line is too long
12103. `editor_width` to wrap lines that overflow the editor width
12114. `preferred_line_length` to wrap lines that overflow `preferred_line_length` config value
1212
1213## Wrap Guides (Vertical Rulers)
1214
1215- Description: Where to display vertical rulers as wrap-guides. Disable by setting `show_wrap_guides` to `false`.
1216- Setting: `wrap_guides`
1217- Default: []
1218
1219**Options**
1220
1221List of `integer` column numbers
1222
1223## Tab Size
1224
1225- Description: The number of spaces to use for each tab character.
1226- Setting: `tab_size`
1227- Default: `4`
1228
1229**Options**
1230
1231`integer` values
1232
1233## Telemetry
1234
1235- Description: Control what info is collected by Zed.
1236- Setting: `telemetry`
1237- Default:
1238
1239```json
1240"telemetry": {
1241 "diagnostics": true,
1242 "metrics": true
1243},
1244```
1245
1246**Options**
1247
1248### Diagnostics
1249
1250- Description: Setting for sending debug-related data, such as crash reports.
1251- Setting: `diagnostics`
1252- Default: `true`
1253
1254**Options**
1255
1256`boolean` values
1257
1258### Metrics
1259
1260- Description: Setting for sending anonymized usage data, such what languages you're using Zed with.
1261- Setting: `metrics`
1262- Default: `true`
1263
1264**Options**
1265
1266`boolean` values
1267
1268## Terminal
1269
1270- Description: Configuration for the terminal.
1271- Setting: `terminal`
1272- Default:
1273
1274```json
1275{
1276 "terminal": {
1277 "alternate_scroll": "off",
1278 "blinking": "terminal_controlled",
1279 "copy_on_select": false,
1280 "dock": "bottom",
1281 "env": {},
1282 "font_family": null,
1283 "font_features": null,
1284 "font_size": null,
1285 "line_height": "comfortable",
1286 "option_as_meta": true,
1287 "button": false,
1288 "shell": {},
1289 "toolbar": {
1290 "title": true
1291 },
1292 "working_directory": "current_project_directory"
1293 }
1294}
1295```
1296
1297### Terminal: Dock
1298
1299- Description: Control the position of the dock
1300- Setting: `dock`
1301- Default: `bottom`
1302
1303**Options**
1304
1305`"bottom"`, `"left"` or `"right"`
1306
1307### Terminal: Alternate Scroll
1308
1309- 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.
1310- Setting: `alternate_scroll`
1311- Default: `off`
1312
1313**Options**
1314
13151. Default alternate scroll mode to on
1316
1317```json
1318{
1319 "terminal": {
1320 "alternate_scroll": "on"
1321 }
1322}
1323```
1324
13252. Default alternate scroll mode to off
1326
1327```json
1328{
1329 "terminal": {
1330 "alternate_scroll": "off"
1331 }
1332}
1333```
1334
1335### Terminal: Blinking
1336
1337- Description: Set the cursor blinking behavior in the terminal
1338- Setting: `blinking`
1339- Default: `terminal_controlled`
1340
1341**Options**
1342
13431. Never blink the cursor, ignore the terminal mode
1344
1345```json
1346{
1347 "terminal": {
1348 "blinking": "off"
1349 }
1350}
1351```
1352
13532. Default the cursor blink to off, but allow the terminal to turn blinking on
1354
1355```json
1356{
1357 "terminal": {
1358 "blinking": "terminal_controlled"
1359 }
1360}
1361```
1362
13633. Always blink the cursor, ignore the terminal mode
1364
1365```json
1366{
1367 "terminal": {
1368 "blinking": "on"
1369 }
1370}
1371```
1372
1373### Terminal: Copy On Select
1374
1375- Description: Whether or not selecting text in the terminal will automatically copy to the system clipboard.
1376- Setting: `copy_on_select`
1377- Default: `false`
1378
1379**Options**
1380
1381`boolean` values
1382
1383**Example**
1384
1385```json
1386{
1387 "terminal": {
1388 "copy_on_select": true
1389 }
1390}
1391```
1392
1393### Terminal: Env
1394
1395- 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
1396- Setting: `env`
1397- Default: `{}`
1398
1399**Example**
1400
1401```json
1402{
1403 "terminal": {
1404 "env": {
1405 "ZED": "1",
1406 "KEY": "value1:value2"
1407 }
1408 }
1409}
1410```
1411
1412### Terminal: Font Size
1413
1414- Description: What font size to use for the terminal. When not set defaults to matching the editor's font size
1415- Setting: `font_size`
1416- Default: `null`
1417
1418**Options**
1419
1420`integer` values
1421
1422```json
1423{
1424 "terminal": {
1425 "font_size": 15
1426 }
1427}
1428```
1429
1430### Terminal: Font Family
1431
1432- Description: What font to use for the terminal. When not set, defaults to matching the editor's font.
1433- Setting: `font_family`
1434- Default: `null`
1435
1436**Options**
1437
1438The name of any font family installed on the user's system
1439
1440```json
1441{
1442 "terminal": {
1443 "font_family": "Berkeley Mono"
1444 }
1445}
1446```
1447
1448### Terminal: Font Features
1449
1450- Description: What font features to use for the terminal. When not set, defaults to matching the editor's font features.
1451- Setting: `font_features`
1452- Default: `null`
1453- Platform: macOS and Windows.
1454
1455**Options**
1456
1457See Buffer Font Features
1458
1459```jsonc
1460{
1461 "terminal": {
1462 "font_features": {
1463 "calt": false,
1464 // See Buffer Font Features for more features
1465 },
1466 },
1467}
1468```
1469
1470### Terminal: Line Height
1471
1472- Description: Set the terminal's line height.
1473- Setting: `line_height`
1474- Default: `comfortable`
1475
1476**Options**
1477
14781. Use a line height that's `comfortable` for reading, 1.618. (default)
1479
1480```jsonc
1481{
1482 "terminal": {
1483 "line_height": "comfortable",
1484 },
1485}
1486```
1487
14882. Use a `standard` line height, 1.3. This option is useful for TUIs, particularly if they use box characters
1489
1490```jsonc
1491{
1492 "terminal": {
1493 "line_height": "standard",
1494 },
1495}
1496```
1497
14983. Use a custom line height.
1499
1500```jsonc
1501{
1502 "terminal": {
1503 "line_height": {
1504 "custom": 2,
1505 },
1506 },
1507}
1508```
1509
1510### Terminal: Option As Meta
1511
1512- Description: Re-interprets the option keys to act like a 'meta' key, like in Emacs.
1513- Setting: `option_as_meta`
1514- Default: `true`
1515
1516**Options**
1517
1518`boolean` values
1519
1520```json
1521{
1522 "terminal": {
1523 "option_as_meta": true
1524 }
1525}
1526```
1527
1528### Terminal: Shell
1529
1530- Description: What shell to use when launching the terminal.
1531- Setting: `shell`
1532- Default: `system`
1533
1534**Options**
1535
15361. Use the system's default terminal configuration (usually the `/etc/passwd` file).
1537
1538```json
1539{
1540 "terminal": {
1541 "shell": "system"
1542 }
1543}
1544```
1545
15462. A program to launch:
1547
1548```json
1549{
1550 "terminal": {
1551 "shell": {
1552 "program": "sh"
1553 }
1554 }
1555}
1556```
1557
15583. A program with arguments:
1559
1560```json
1561{
1562 "terminal": {
1563 "shell": {
1564 "with_arguments": {
1565 "program": "/bin/bash",
1566 "args": ["--login"]
1567 }
1568 }
1569 }
1570}
1571```
1572
1573## Terminal: Toolbar
1574
1575- Description: Whether or not to show various elements in the terminal toolbar. It only affects terminals placed in the editor pane.
1576- Setting: `toolbar`
1577- Default:
1578
1579```json
1580{
1581 "terminal": {
1582 "toolbar": {
1583 "title": true
1584 }
1585 }
1586}
1587```
1588
1589**Options**
1590
1591At the moment, only the `title` option is available, it controls displaying of the terminal title that can be changed via `PROMPT_COMMAND`. If the title is hidden, the terminal toolbar is not displayed.
1592
1593### Terminal: Button
1594
1595- Description: Control to show or hide the terminal button in the status bar
1596- Setting: `button`
1597- Default: `true`
1598
1599**Options**
1600
1601`boolean` values
1602
1603```json
1604{
1605 "terminal": {
1606 "button": false
1607 }
1608}
1609```
1610
1611### Terminal: Working Directory
1612
1613- Description: What working directory to use when launching the terminal.
1614- Setting: `working_directory`
1615- Default: `"current_project_directory"`
1616
1617**Options**
1618
16191. Use the current file's project directory. Will Fallback to the first project directory strategy if unsuccessful
1620
1621```json
1622{
1623 "terminal": {
1624 "working_directory": "current_project_directory"
1625 }
1626}
1627```
1628
16292. Use the first project in this workspace's directory. Will fallback to using this platform's home directory.
1630
1631```json
1632{
1633 "terminal": {
1634 "working_directory": "first_project_directory"
1635 }
1636}
1637```
1638
16393. Always use this platform's home directory (if we can find it)
1640
1641```json
1642{
1643 "terminal": {
1644 "working_directory": "always_home"
1645 }
1646}
1647```
1648
16494. 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.
1650
1651```json
1652{
1653 "terminal": {
1654 "working_directory": {
1655 "always": {
1656 "directory": "~/zed/projects/"
1657 }
1658 }
1659 }
1660}
1661```
1662
1663## Theme
1664
1665- 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.
1666- Setting: `theme`
1667- Default: `One Dark`
1668
1669### Theme Object
1670
1671- Description: Specify the theme using an object that includes the `mode`, `dark`, and `light` themes.
1672- Setting: `theme`
1673- Default:
1674
1675```json
1676"theme": {
1677 "mode": "system",
1678 "dark": "One Dark",
1679 "light": "One Light"
1680},
1681```
1682
1683### Mode
1684
1685- Description: Specify theme mode.
1686- Setting: `mode`
1687- Default: `system`
1688
1689**Options**
1690
16911. Set the theme to dark mode
1692
1693```json
1694{
1695 "mode": "dark"
1696}
1697```
1698
16992. Set the theme to light mode
1700
1701```json
1702{
1703 "mode": "light"
1704}
1705```
1706
17073. Set the theme to system mode
1708
1709```json
1710{
1711 "mode": "system"
1712}
1713```
1714
1715### Dark
1716
1717- Description: The name of the dark Zed theme to use for the UI.
1718- Setting: `dark`
1719- Default: `One Dark`
1720
1721**Options**
1722
1723Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
1724
1725### Light
1726
1727- Description: The name of the light Zed theme to use for the UI.
1728- Setting: `light`
1729- Default: `One Light`
1730
1731**Options**
1732
1733Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
1734
1735## Vim
1736
1737- Description: Whether or not to enable vim mode (work in progress).
1738- Setting: `vim_mode`
1739- Default: `false`
1740
1741## Project Panel
1742
1743- Description: Customize project panel
1744- Setting: `project_panel`
1745- Default:
1746
1747```json
1748{
1749 "project_panel": {
1750 "button": true,
1751 "default_width": 240,
1752 "dock": "left",
1753 "file_icons": true,
1754 "folder_icons": true,
1755 "git_status": true,
1756 "indent_size": 20,
1757 "auto_reveal_entries": true,
1758 "auto_fold_dirs": true,
1759 "scrollbar": {
1760 "show": "always"
1761 }
1762 }
1763}
1764```
1765
1766### Dock
1767
1768- Description: Control the position of the dock
1769- Setting: `dock`
1770- Default: `left`
1771
1772**Options**
1773
17741. Default dock position to left
1775
1776```json
1777{
1778 "dock": "left"
1779}
1780```
1781
17822. Default dock position to right
1783
1784```json
1785{
1786 "dock": "right"
1787}
1788```
1789
1790### Git Status
1791
1792- Description: Indicates newly created and updated files
1793- Setting: `git_status`
1794- Default: `true`
1795
1796**Options**
1797
17981. Default enable git status
1799
1800```json
1801{
1802 "git_status": true
1803}
1804```
1805
18062. Default disable git status
1807
1808```json
1809{
1810 "git_status": false
1811}
1812```
1813
1814### Default Width
1815
1816- Description: Customize default width taken by project panel
1817- Setting: `default_width`
1818- Default: N/A width in pixels (eg: 420)
1819
1820**Options**
1821
1822`boolean` values
1823
1824### Auto Reveal Entries
1825
1826- Description: Whether to reveal it in the project panel automatically, when a corresponding project entry becomes active. Gitignored entries are never auto revealed.
1827- Setting: `auto_reveal_entries`
1828- Default: `true`
1829
1830**Options**
1831
18321. Enable auto reveal entries
1833
1834```json
1835{
1836 "auto_reveal_entries": true
1837}
1838```
1839
18402. Disable auto reveal entries
1841
1842```json
1843{
1844 "auto_reveal_entries": false
1845}
1846```
1847
1848### Auto Fold Dirs
1849
1850- Description: Whether to fold directories automatically when directory has only one directory inside.
1851- Setting: `auto_fold_dirs`
1852- Default: `true`
1853
1854**Options**
1855
18561. Enable auto fold dirs
1857
1858```json
1859{
1860 "auto_fold_dirs": true
1861}
1862```
1863
18642. Disable auto fold dirs
1865
1866```json
1867{
1868 "auto_fold_dirs": false
1869}
1870```
1871
1872### Indent Size
1873
1874- Description: Amount of indentation (in pixels) for nested items.
1875- Setting: `indent_size`
1876- Default: `20`
1877
1878### Scrollbar
1879
1880- Description: Scrollbar related settings. Possible values: "always", "never".
1881- Setting: `scrollbar`
1882- Default:
1883
1884```json
1885"scrollbar": {
1886 "show": "always"
1887}
1888```
1889
1890**Options**
1891
18921. Show scrollbar in project panel
1893
1894```json
1895{
1896 "scrollbar": {
1897 "show": "always"
1898 }
1899}
1900```
1901
19022. Hide scrollbar in project panel
1903
1904```json
1905{
1906 "scrollbar": {
1907 "show": "never"
1908 }
1909}
1910```
1911
1912## Assistant Panel
1913
1914- Description: Customize assistant panel
1915- Setting: `assistant`
1916- Default:
1917
1918```json
1919"assistant": {
1920 "enabled": true,
1921 "button": true,
1922 "dock": "right",
1923 "default_width": 640,
1924 "default_height": 320,
1925 "provider": "openai",
1926 "version": "1",
1927},
1928```
1929
1930## Outline Panel
1931
1932- Description: Customize outline Panel
1933- Setting: `outline_panel`
1934- Default:
1935
1936```json
1937"outline_panel": {
1938 "button": true,
1939 "default_width": 240,
1940 "dock": "left",
1941 "file_icons": true,
1942 "folder_icons": true,
1943 "git_status": true,
1944 "indent_size": 20,
1945 "auto_reveal_entries": true,
1946 "auto_fold_dirs": true,
1947}
1948```
1949
1950## Calls
1951
1952- Description: Customize behavior when participating in a call
1953- Setting: `calls`
1954- Default:
1955
1956```json
1957"calls": {
1958 // Join calls with the microphone live by default
1959 "mute_on_join": false,
1960 // Share your project when you are the first to join a channel
1961 "share_on_join": false
1962},
1963```
1964
1965## Unnecessary Code Fade
1966
1967- Description: How much to fade out unused code.
1968- Setting: `unnecessary_code_fade`
1969- Default: `0.3`
1970
1971**Options**
1972
1973Float values between `0.0` and `0.9`, where:
1974
1975- `0.0` means no fading (unused code looks the same as used code)
1976- `0.9` means maximum fading (unused code is very faint but still visible)
1977
1978**Example**
1979
1980```json
1981{
1982 "unnecessary_code_fade": 0.5
1983}
1984```
1985
1986## An example configuration:
1987
1988```json
1989// ~/.config/zed/settings.json
1990{
1991 "theme": "cave-light",
1992 "tab_size": 2,
1993 "preferred_line_length": 80,
1994 "soft_wrap": "none",
1995
1996 "buffer_font_size": 18,
1997 "buffer_font_family": "Zed Plex Mono",
1998
1999 "autosave": "on_focus_change",
2000 "format_on_save": "off",
2001 "vim_mode": false,
2002 "projects_online_by_default": true,
2003 "terminal": {
2004 "font_family": "FiraCode Nerd Font Mono",
2005 "blinking": "off"
2006 },
2007 "languages": {
2008 "C": {
2009 "format_on_save": "language_server",
2010 "preferred_line_length": 64,
2011 "soft_wrap": "preferred_line_length"
2012 }
2013 }
2014}
2015```