Skip to main content
Version: 2.0.0-alpha ๐Ÿšง

Organizing matches

If you only use a handful of snippets, placing everything in the $CONFIG/match/base.yml file will work perfectly. But as the number of matches increases, you might find yourself struggling to keep the configuration manageable.

To solve this problem, Espanso makes it easy to split your matches across multiple files.

Splitting your matches

Espanso automatically loads all YAML files placed in the $CONFIG/match directory. These files, known as match sets, can contain any number of matches and global variables. To better understand these concepts, let's see an example:

Let's say you would like Espanso to manage your vast collection of email signatures. While you could define them in the $CONFIG/match/base.yml file, you prefer to keep them separate from your other snippets.

For this reason, you create another file $CONFIG/match/emails.yml, with the following content:

- trigger: ":sig"
replace: "Best, John"

- trigger: ":sig"
replace: "All the best, John"

As soon as the configuration is reloaded, you can start using your :sig snippets right away!

That's possible because Espanso loads all match sets contained in the $CONFIG/match folder by default * . In other words, all YAML files defined in that directory (and its sub-folders) are loaded and the result is equivalent to having all matches defined in the $CONFIG/match/base.yml file.

An important exception (*)

The previous statement has one important exception: all files starting with an underscore _ are NOT loaded automatically. This rule is necessary to support some advanced use-cases, such as App-specific configurations.


For advanced users, Espanso also makes it possible to import a match-set from a different location. For example, you could define a $CONFIG/match/company.yml file that imports some matches from external locations:

# Import other matches from external locations
- "/path/to/other/matchsets.yml"
- "/path/to/shared/google/drive/matches.yml"

- trigger: ":company"
replace: "This is just a normal trigger I use at my company"

In other words, imports can be used to load matches from outside your config directory.

Using imports to group private match sets (Advanced)

Another less common use-case would be to use imports to group some private match sets (aka match sets that start with an underscore, and thus are not loaded automatically). This becomes particularly useful for App-specific configurations, where we might want to split matches over multiple files, while making it easy to include in some apps.


This section assumes you already know what App-specific configurations are. If you don't, you might want to read that section first.

For example, you could define a $CONFIG/match/_js_snippets.yml file that includes some code-snippets for JavaScript and a $CONFIG/match/_css_snippets.yml file that contains some CSS snippets. Because both files start with an underscore, they are not loaded automatically.

- trigger: ":log"
replace: "console.log($|$);"
- trigger: ":pad"
replace: "padding: 10px"

Then, you could define a $CONFIG/match/_code_snippets.yml file that imports both of them:

- "./_js_snippets.yml"
- "./_css_snippets.yml"

At this point, you can include all your code snippets in an app-specific configuration:

filter_title: "Visual Studio Code"

- "../match/_code_snippets.yml"

Because the $CONFIG/match/_code_snippets.yml file imports both JS and CSS snippets, you will be able to use both of them in VSCode, even though you haven't included the $CONFIG/match/_js_snippets.yml and $CONFIG/match/_css_snippets.yml directly.


Hi! I'm Federico, the creator of espanso. I develop espanso in my (little) spare time and I decided to make it open source because I thought it could be useful to many people.

If you liked the project, please consider making a small donation, it really helps :)

A special thanks goes to all the wonderful people who supported espanso along the way

Together, we will make espanso the first universal text expander, open to everyone.


Espanso is open source and hosted on GitHub.


If you find a bug or have an idea for a new feature, please open an issue on GitHub.