| 📦 Turbo Go 3d7798b k33g 12h ago | 1 | # Reference: snippets |
| 2 | |
| 3 | > Neutral description of the snippets files, the Snippets menu, and how a snippet is inserted. |
| 4 | |
| 5 | ## Files |
| 6 | |
| 7 | Both are read, and both are optional. |
| 8 | |
| 9 | | File | Holds | |
| 10 | | --- | --- | |
| 11 | | `./.turbo-go/snippets.toml` | The project's snippets | |
| 12 | | `$TURBO_GO_SNIPPET_DIR/snippets.toml`, else `<user config>/turbo-go/snippets.toml` | Your own, shared across projects | |
| 13 | |
| 14 | `<user config>` is `os.UserConfigDir()`: `~/.config` on Linux, `~/Library/Application Support` on macOS. |
| 15 | |
| 16 | | Property | Value | |
| 17 | | --- | --- | |
| 18 | | Project search | The working directory only. Parent directories are **not** searched. | |
| 19 | | Read | Every time the Snippets menu opens | |
| 20 | | Order | Your own first, then the project's | |
| 21 | | Name clash | Same `group` **and** `name` → the project's replaces yours | |
| 22 | | Missing file | Not an error | |
| 23 | | Unreadable file | An error, shown in the menu | |
| 24 | |
| 25 | ## File format |
| 26 | |
| 27 | One `[[snippet]]` table per snippet. |
| 28 | |
| 29 | | Key | Type | Required | Description | |
| 30 | | --- | --- | --- | --- | |
| 31 | | `name` | string | yes | What the menu shows | |
| 32 | | `body` | string | yes | The text inserted at the cursor | |
| 33 | | `group` | string | no | The submenu it goes in; absent means `General` | |
| 34 | | `languages` | array of strings | no | Restricts the snippet to those languages; absent means every file | |
| 35 | |
| 36 | `languages` uses the editor's own language names: `go`, `toml`, `yaml`, `markdown`, `javascript`, `html`, `xml`, `dockerfile`, `bash`. See [Languages coloured](languages.md). |
| 37 | |
| 38 | A snippet with no `name` or no `body` makes the whole file an error — it could not be shown or could not be inserted. |
| 39 | |
| 40 | ### Example |
| 41 | |
| 42 | ```toml |
| 43 | [[snippet]] |
| 44 | name = "if err != nil" |
| 45 | group = "Go" |
| 46 | languages = ["go"] |
| 47 | body = """ |
| 48 | if err != nil { |
| 49 | return err |
| 50 | }""" |
| 51 | ``` |
| 52 | |
| 53 | TOML's `"""` strings drop the newline immediately after the opening quotes, and interpret `\t` as a tab. |
| 54 | |
| 55 | ## The menu |
| 56 | |
| 57 | | Item | Condition | |
| 58 | | --- | --- | |
| 59 | | One submenu per group, in the order the groups first appear in the files | A group with at least one snippet applying to the front window | |
| 60 | | `Cannot read snippets`, greyed out | A file is present but unreadable | |
| 61 | | `Create snippets file` | The project has no snippets file | |
| 62 | | `Open snippets file` | The project has one | |
| 63 | |
| 64 | The menu's hot key is `Alt-N`, not `Alt-S`: Search already answers to S. |
| 65 | |
| 66 | Groups, and the snippets inside them, come out in the order they were read, so the menu matches the files. |
| 67 | |
| 68 | A snippet item is greyed out when there is no file open to insert into — a terminal or the project tree in front counts as no file. |
| 69 | |
| 70 | ### Filtering |
| 71 | |
| 72 | | Front window | Snippets offered | |
| 73 | | --- | --- | |
| 74 | | A file of a recognised language | Those naming that language, plus those naming none | |
| 75 | | A file of no recognised language | Those naming none | |
| 76 | | A terminal, the project tree, or nothing | Those naming none | |
| 77 | |
| 78 | ## Insertion |
| 79 | |
| 80 | | Behaviour | Detail | |
| 81 | | --- | --- | |
| 82 | | Position | At the cursor | |
| 83 | | First line | Inserted where the cursor is | |
| 84 | | Later lines | Prefixed with the leading whitespace of the line the cursor was on | |
| 85 | | Blank lines in the body | Left blank, not padded with whitespace | |
| 86 | | Undo | One step for the whole snippet | |
| 87 | | Cursor after | At the end of the inserted text | |
| 88 | | Report | `Snippet inserted` on the status bar | |
| 89 | |
| 90 | The indent copied is the **whitespace prefix of the current line**, tabs or spaces as they were, so a snippet follows whatever the file already uses. |
| 91 | |
| 92 | ## Menu items |
| 93 | |
| 94 | | Item | Menu | Effect | |
| 95 | | --- | --- | --- | |
| 96 | | Create snippets file | Snippets | Writes `.turbo-go/snippets.toml` with worked examples, then opens it. Greyed out once the project has one. | |
| 97 | | Open snippets file | Snippets | Opens `.turbo-go/snippets.toml`. Greyed out until the project has one. Always the project's file, never your own — it is the file the item above it writes. | |
| 98 | |
| 99 | The file is written through a temporary file in the same directory, renamed into place, so an interrupted write leaves the previous file intact. |
| 100 | |
| 101 | ## Errors |
| 102 | |
| 103 | | Message | Cause | |
| 104 | | --- | --- | |
| 105 | | `Cannot read snippets` in the menu | A snippets file is present but not valid TOML, or holds a snippet with no name or no body | |
| 106 | | `Already there: .turbo-go/snippets.toml` | 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. | |
| 107 | | `This project has no .turbo-go/snippets.toml yet.` | Opening in a project that has none, likewise | |
| 108 | | `Cannot tell which directory this is: …` | The working directory could not be read | |
| 109 | |
| 110 | ## See also |
| 111 | |
| 112 | - [How to insert snippets from a menu](../how-to/use-snippets.md) |
| 113 | - [Snippets](../explanation/snippets.md) |
| 114 | - [Keyboard](keyboard.md) |