Switch from Espanso to Retext
Point Retext at your Espanso match files and it reads the YAML for you. Triggers, replacements, date and clipboard vars, forms and $|$ cursor hints convert. You get a Mac app with a snippet editor instead of a config folder.
- Reads
- Espanso match files (.yml or .yaml)
- Where it runs
- On your Mac. Nothing is uploaded.
- Shortcut
- File → Import Snippets… (⇧⌘I)
Step 1: Export from Espanso
- 1
Find your config folder
Run espanso path in Terminal. On a Mac the folder is usually ~/Library/Application Support/espanso, or ~/.config/espanso if you moved it.
- 2
Open the match folder
Your snippets live in match/. Most people keep them in match/base.yml, plus any other .yml files you've added.
- 3
Import each file
There's nothing to export. Pick a .yml file in Retext's importer, and repeat for each match file. In the file picker, press ⇧⌘G and paste the folder path to get there fast.
Step 2: Import into Retext
- 4
Open the importer
In Retext, choose File → Import Snippets… (⇧⌘I), or go to Settings → Snippets → Import….
- 5
Pick the file
Retext works out the format from the file itself. Everything is read on your Mac. Nothing is uploaded.
- 6
Review the preview
Every snippet gets a row with its new trigger. Rows show placeholders that were kept as text, items that can't be imported and why, and any trigger you already use. Untick anything you don't want.
- 7
Import
Click Import. Your snippets work right away in every app. Type ;trigger to expand.
What carries over
Espanso vars convert when Retext has a field that produces the same text. A date var in any other format becomes the closest Retext field, and the preview notes the change. Shell, script, random and choice vars have no Retext equivalent.
| In Espanso | In Retext | Notes |
|---|---|---|
date var, format %B %-d, %Y | {date} | |
date var, format %-m/%-d/%y | {date:short} | |
date var with offset: 86400 | {date+1}Offsets in whole days | Offsets in whole days |
date var, format %-I:%M %p | {time} | |
date var, format %A | {day} | |
date var, any other format | {time}, {date:short} or {date}Closest match: {time} if it shows a time, {date:short} if it's all numbers | Closest match: {time} if it shows a time, {date:short} if it's all numbers |
clipboard var | {clipboard} | |
$|$ | {cursor} | |
form: with [[name]] | {fill:name} | |
{{form1.name}} | {fill:name} | |
match var (params.trigger) | {snippet:trigger} | |
echo var | Its text, inline |
Kept as text
These import, but the placeholder stays as written. The preview lists them on each row so you can edit them after.
- • shell, script, random and choice vars
- • Date offsets that aren't whole days
Not imported
These show in the preview as "can't import", with the reason.
- • regex: triggers
- • Image matches (image_path)
- • A match whose unconverted var is named like a Retext field, such as a shell var called {{date}}. Kept as text, it would expand as Retext's {date}, so the preview flags it instead.
- • Extra triggers: aliases. Only the first trigger in a triggers: list is kept, and the preview notes it.
Groups and tags
Espanso has no groups, so imported matches have no tags. Add tags in Retext afterwards.
Triggers and conflicts
Espanso's colon convention becomes Retext's semicolon. Leading and trailing punctuation is trimmed and triggers are lowercased.
| Espanso trigger | Retext trigger |
|---|---|
:sig | ;sig |
:date | ;date |
//addr | ;addr |
If you already have a snippet with the same trigger, the preview says so and you choose for each one:
- Keep Both (the default) imports it under a new trigger with a source prefix, so
;sigbecomes;esp-sig. A prefix is used instead of a suffix because;sig-2could never be typed:;sigwould fire first. - Skip leaves your existing snippet alone.
- Replace swaps in the imported content. Your snippet keeps its trigger, and tags are merged.
Two snippets with the same trigger inside one file can be kept (renamed) or skipped. Triggers are also checked against Retext's rules (2 to 40 characters, no line breaks, no snippet that contains its own trigger), and anything that fails shows why.
What you get after switching
Dictation
Hold a key and talk. Retext turns speech into text on your Mac, types it into the app you're in, and takes voice commands (beta) like "insert snippet sig", so your imported snippets work by voice too.
Autocomplete (beta)
Start typing a trigger and Retext shows the snippet as ghost text, with dynamic fields filled in. Press Tab to accept. You don't have to remember every abbreviation you imported.
Per-app snippets
Limit a snippet to the apps it belongs in, or keep it out of others, so the same trigger can say one thing in Mail and another in Slack.
Teams
Share a snippet library with your team, with owner, admin, editor and viewer roles, managed from the Mac app.
When to stay with Espanso
Retext isn't the right move for everyone. Stay if:
- •You need the same snippets on Linux or Windows. Espanso runs on all three.
- •You use regex triggers, shell or script vars, or choice and random lists.
- •You like your snippets as YAML in a git repo, and Espanso being free and open source matters to you.
FAQ
›Do I need to export anything from Espanso?
No. Espanso's match files are already plain YAML. Import match/base.yml and any other .yml files from your config folder (run espanso path to find it).
›What happens to global_vars?
They're read too. A match that uses a global var gets it the same way as a local one, with local vars taking priority.
›Why was one of my matches marked "can't import"?
It's a regex trigger, an image match, or it uses a var Retext can't convert whose name is also a Retext field (like a shell var called {{date}}). The preview names the reason on each row.
›Can I keep using Espanso while I try Retext?
Yes, but turn one of them off for overlapping triggers, or both will try to expand the same text. Retext triggers start with ; and Espanso's usually start with :, so most won't clash.
›How many matches can I import for free?
The free plan holds 5 snippets. The preview shows how many fit and lets you choose. Pro has no limit.
Bring your Espanso snippets with you
Download Retext, press ⇧⌘I, and pick your file. Your snippets work in every app on your Mac in a few minutes.