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