| 📦 Turbo Golo d710c1b k33g 11h ago | 1 | # Reference: project settings |
| 2 | |
| 3 | > Neutral description of `.turbo-golo/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-golo` in the editor's working directory | |
| 10 | | File | `.turbo-golo/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-golo -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-golo/settings.toml — autosave on (2s)` | |
| 59 | | Read and applied, autosave off | `Applied .turbo-golo/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-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. | |
| 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-golo/settings.toml`. Greyed out until the project has one. | |
| 94 | |
| 95 | ## Errors |
| 96 | |
| 97 | | Message | Cause | |
| 98 | | --- | --- | |
| 99 | | `turbo-golo: 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-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. | |
| 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-golo/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 |