turbo-editors/turbo-go · project-settings.md

⑂ main

project-settings.md · 111 lines · 5.5 KBmarkdown    Blame HistoryRaw
   1# Reference: project settings
3> Neutral description of `.turbo-go/settings.toml`: where it is looked for, what it may contain, and what writes to it.
5## Location
7| Property | Value |
8| --- | --- |
9| Directory | `.turbo-go` in the editor's working directory |
10| File | `.turbo-go/settings.toml` |
11| Search | The working directory only. Parent directories are **not** searched. |
12| Read | When the editor starts, and again whenever the file is saved from inside the editor |
13| Required | No. A project without one gets the defaults below. |
17Every key is optional, and every key lives in the `[editor]` table. A key that is absent keeps its default; a key present with any value overrides it, including a value equal to the default.
19| Key | Type | Default | Description |
20| --- | --- | --- | --- |
21| `theme` | string | the editor's own default (`turbo-classic`) | Name of the colour theme to start in, as listed by `turbo-go -list-themes` |
22| `autosave` | boolean | `false` | Whether modified files are written without being asked. The file **Create project settings** writes sets it to `true`; the default here is what applies to a project with no settings file at all. |
23| `autosave_delay` | string | `"2s"` | How long after the last keystroke to wait. A Go duration: `"500ms"`, `"2s"`, `"1m"`. Only consulted when `autosave` is true. |
25### Example
29theme = "turbo-dark"
30autosave = true
31autosave_delay = "500ms"
34## Theme precedence
36Highest first:
38| Source | Wins over |
39| --- | --- |
40| `-theme` on the command line | everything |
41| `theme` in the settings file | the built-in default |
42| The built-in default `turbo-classic` | — |
44An unknown theme name at any level falls back to the built-in default rather than failing.
46## When a change takes effect
48The file is read at start-up, and **again every time it is saved from inside the editor** — so a change made in the editor is in force the moment you press `F2`, with no restart.
50| Key | Re-applied on save | Why |
51| --- | --- | --- |
52| `autosave` | yes | |
53| `autosave_delay` | yes | |
54| `theme` | **no** | Options ▸ Theme is the live way to change it, and already writes the choice back here. A `-theme` flag given on the command line is the more explicit statement for that session and is not overridden by a file being saved. |
56| Outcome | Status bar |
57| --- | --- |
58| Read and applied | `Applied .turbo-go/settings.toml — autosave on (2s)` |
59| Read and applied, autosave off | `Applied .turbo-go/settings.toml — autosave off` |
60| Saved, but no longer valid TOML | `Saved, but not applied: …` — the previous values stay in force |
62Saving is saving, whoever did it: automatic saving writing the settings file re-applies them exactly as `F2` does. Editing the file **outside** the editor is not noticed; nothing watches it.
64## Automatic saving
66| Behaviour | Detail |
67| --- | --- |
68| Trigger | The delay elapsing with no edit in any window |
69| Scope | Every open file with a name, not only the front one |
70| Deadline | One for the whole editor, restarted by any edit in any window |
71| Files with no name | Never saved; never asked about |
72| Report | `Saved <name>` on the status bar |
73| Failure | Reported on the status bar, never in a dialog, and not retried until the next edit |
74| Closing a window | Saves instead of asking, when the file has a name |
75| Leaving the editor | Saves instead of asking, when the file has a name |
77
79The settings file is written by exactly two actions. Nothing else in the editor writes to it, and nothing creates it by itself.
81| Action | Effect |
82| --- | --- |
83| **Options ▸ Create project settings** | Creates `.turbo-go/settings.toml` with the theme in use, `autosave = true`, and explanatory comments. Greyed out once the project has one, so it cannot be chosen twice. |
84| **Options ▸ Theme** | Rewrites the `theme` value **only when the file already exists**. Comments, blank lines, key order and any trailing comment on the theme line are kept. |
86Both write through a temporary file in the same directory, renamed into place, so an interrupted write leaves the previous file intact.
88## Menu items
90| Item | Menu | Needs a file | Effect |
91| --- | --- | --- | --- |
92| Create project settings | Options | refuses the file | As above, then opens the file. Greyed out once the project has one. |
93| Project settings… | Options | requires the file | Opens `.turbo-go/settings.toml`. Greyed out until the project has one. |
95
97| Message | Cause |
98| --- | --- |
99| `turbo-go: reading …/settings.toml: …` on standard error | The file is present but is not valid TOML. The editor opens with its defaults. |
100| `reading …: autosave_delay "x" is not a duration such as "2s"` | `autosave_delay` is not a Go duration |
101| `reading …: autosave_delay must be positive, not "0s"` | `autosave_delay` is zero or negative |
102| `Already there: .turbo-go/settings.toml` on the status bar | Creating in a project that already has one. Unreachable from the menu, which greys the item out; still possible for a caller that is not a menu. |
103| `Saved, but not applied: …` on the status bar | The settings file was written but no longer parses. The previous values stay in force. |
104| `This project has no .turbo-go/settings.toml yet.` | **Project settings…** in a project that has none |
105| `Theme set for this session only: …` | The theme changed but the settings file could not be written |
107## See also
109- [How to give a project its own settings](../how-to/configure-a-project.md)
110- [Project settings](../explanation/project-settings.md)
111- [Theme file format](themes.md) — a different file, in the same language

📦 Turbo Go 3d7798b k33g 10h ago	1	# Reference: project settings
	2
	3	> Neutral description of `.turbo-go/settings.toml`: where it is looked for, what it may contain, and what writes to it.
	4
	5	## Location
	6
	7	\| Property \| Value \|
	8	\| --- \| --- \|
	9	\| Directory \| `.turbo-go` in the editor's working directory \|
	10	\| File \| `.turbo-go/settings.toml` \|
	11	\| Search \| The working directory only. Parent directories are not searched. \|
	12	\| Read \| When the editor starts, and again whenever the file is saved from inside the editor \|
	13	\| Required \| No. A project without one gets the defaults below. \|
	14
	15	## Keys
	16
	17	Every key is optional, and every key lives in the `[editor]` table. A key that is absent keeps its default; a key present with any value overrides it, including a value equal to the default.
	18
	19	\| Key \| Type \| Default \| Description \|
	20	\| --- \| --- \| --- \| --- \|
	21	\| `theme` \| string \| the editor's own default (`turbo-classic`) \| Name of the colour theme to start in, as listed by `turbo-go -list-themes` \|
	22	\| `autosave` \| boolean \| `false` \| Whether modified files are written without being asked. The file Create project settings writes sets it to `true`; the default here is what applies to a project with no settings file at all. \|
	23	\| `autosave_delay` \| string \| `"2s"` \| How long after the last keystroke to wait. A Go duration: `"500ms"`, `"2s"`, `"1m"`. Only consulted when `autosave` is true. \|
	24
	25	### Example
	26
	27	```toml
	28	[editor]
	29	theme = "turbo-dark"
	30	autosave = true
	31	autosave_delay = "500ms"
	32	```
	33
	34	## Theme precedence
	35
	36	Highest first:
	37
	38	\| Source \| Wins over \|
	39	\| --- \| --- \|
	40	\| `-theme` on the command line \| everything \|
	41	\| `theme` in the settings file \| the built-in default \|
	42	\| The built-in default `turbo-classic` \| — \|
	43
	44	An unknown theme name at any level falls back to the built-in default rather than failing.
	45
	46	## When a change takes effect
	47
	48	The file is read at start-up, and again every time it is saved from inside the editor — so a change made in the editor is in force the moment you press `F2`, with no restart.
	49
	50	\| Key \| Re-applied on save \| Why \|
	51	\| --- \| --- \| --- \|
	52	\| `autosave` \| yes \| \|
	53	\| `autosave_delay` \| yes \| \|
	54	\| `theme` \| no \| Options ▸ Theme is the live way to change it, and already writes the choice back here. A `-theme` flag given on the command line is the more explicit statement for that session and is not overridden by a file being saved. \|
	55
	56	\| Outcome \| Status bar \|
	57	\| --- \| --- \|
	58	\| Read and applied \| `Applied .turbo-go/settings.toml — autosave on (2s)` \|
	59	\| Read and applied, autosave off \| `Applied .turbo-go/settings.toml — autosave off` \|
	60	\| Saved, but no longer valid TOML \| `Saved, but not applied: …` — the previous values stay in force \|
	61
	62	Saving is saving, whoever did it: automatic saving writing the settings file re-applies them exactly as `F2` does. Editing the file outside the editor is not noticed; nothing watches it.
	63
	64	## Automatic saving
65
66	\| Behaviour \| Detail \|
67	\| --- \| --- \|
68	\| Trigger \| The delay elapsing with no edit in any window \|
69	\| Scope \| Every open file with a name, not only the front one \|
70	\| Deadline \| One for the whole editor, restarted by any edit in any window \|
71	\| Files with no name \| Never saved; never asked about \|
72	\| Report \| `Saved <name>` on the status bar \|
73	\| Failure \| Reported on the status bar, never in a dialog, and not retried until the next edit \|
74	\| Closing a window \| Saves instead of asking, when the file has a name \|
75	\| Leaving the editor \| Saves instead of asking, when the file has a name \|
76
77	## Writes
78
79	The settings file is written by exactly two actions. Nothing else in the editor writes to it, and nothing creates it by itself.
80
81	\| Action \| Effect \|
82	\| --- \| --- \|
83	\| Options ▸ Create project settings \| Creates `.turbo-go/settings.toml` with the theme in use, `autosave = true`, and explanatory comments. Greyed out once the project has one, so it cannot be chosen twice. \|
84	\| Options ▸ Theme \| Rewrites the `theme` value only when the file already exists. Comments, blank lines, key order and any trailing comment on the theme line are kept. \|
85
86	Both write through a temporary file in the same directory, renamed into place, so an interrupted write leaves the previous file intact.
87
88	## Menu items
89
90	\| Item \| Menu \| Needs a file \| Effect \|
91	\| --- \| --- \| --- \| --- \|
92	\| Create project settings \| Options \| refuses the file \| As above, then opens the file. Greyed out once the project has one. \|
93	\| Project settings… \| Options \| requires the file \| Opens `.turbo-go/settings.toml`. Greyed out until the project has one. \|
94
95	## Errors
96
97	\| Message \| Cause \|
98	\| --- \| --- \|
99	\| `turbo-go: reading …/settings.toml: …` on standard error \| The file is present but is not valid TOML. The editor opens with its defaults. \|
100	\| `reading …: autosave_delay "x" is not a duration such as "2s"` \| `autosave_delay` is not a Go duration \|
101	\| `reading …: autosave_delay must be positive, not "0s"` \| `autosave_delay` is zero or negative \|
102	\| `Already there: .turbo-go/settings.toml` on the status bar \| Creating in a project that already has one. Unreachable from the menu, which greys the item out; still possible for a caller that is not a menu. \|
103	\| `Saved, but not applied: …` on the status bar \| The settings file was written but no longer parses. The previous values stay in force. \|
104	\| `This project has no .turbo-go/settings.toml yet.` \| Project settings… in a project that has none \|
105	\| `Theme set for this session only: …` \| The theme changed but the settings file could not be written \|
106
107	## See also
108
109	- [How to give a project its own settings](../how-to/configure-a-project.md)
110	- [Project settings](../explanation/project-settings.md)
111	- [Theme file format](themes.md) — a different file, in the same language