Espanso

Note: My personal Espanso text expander configuration files and setup.

This repository is a part of my dotfiles.

---

Espanso Website | EspansoHub | Documentation | Reddit Community | GitHub

---

Contents

• Contents
• What is espanso?
  • What is a Text Expander?
  • Key Features
• Setup
  • Installation
  • Configuration
    • File Structure
• User Configuration
• Matches
• Packages
• Editing
• Toggle
• Application Specific
• Resources

What is espanso?

Espanso is an Open Source, Cross-Platform Text Expander tool written in Rust.

What is a Text Expander?

A text expander is a program that detects when you type a specific keyword and replaces it with something else.

This is useful in many ways, including but not limited to:

• Save a lot of typing, expanding common sentences.
• Create system-wide code snippets.
• Execute custom scripts
• Use emojis like a pro.

Key Features

• Works on Windows, macOS and Linux
• Works with almost any program
• Works with Emojis 😄
• Works with Images
• Includes a powerful Search Bar 🔎
• Date expansion support
• Custom scripts support
• Shell commands support
• App-specific configurations
• Support Forms
• Expandable with packages
• Built-in package manager for espanso hub
• File based configuration
• Support Regex triggers
• Experimental Wayland support

Setup

Installation

Install using your preferred package manager:

• winget
• chocolatey
• scoop

# winget
winget install FedericoTerzi.espanso

# chocolatey
sudo choco inst -y espanso

# scoop
scoop install espanso

espanso should launch at startup, but to check run espanso status, and if it says espanso is not running then run espanso start.

Configuration

espanso uses a file-based configuration approach. Simply run espanso path to determine the configuration folder's path.

On Widows, the default path is %APPDATA%\espanso, and the configuration files are split into two folders:

• config: Contains the main configuration file, default.yml, and any other configuration files.
• match: Contains the match files, which are YAML files that contain the actual text expansions along with any installed packages.

File Structure

├───config
│       default.yml
│
└───match
    │   about.yml
    │   address.yml
    │   base.yml
    │   datetime.yml
    │   dev.yml
    │   emails.yml
    │   excel.yml
    │   git.yml
    │   links.yml
    │   passwords.yml
    │   phones.yml
    │   secrets.yml
    │
    └───packages
        ├───docker-compose
        ├───get-ip
        ├───lorem
        ├───markdown-shortcuts
        ├───rand-tools
        └───wttr

User Configuration

My personal configuration file, default.yml, is located in the config folder.

See User Configuration for more information.

Currently the only settings I specify are:

toggle_key: ALT
search_shortcut: ALT+SHIFT+SPACE
search_trigger: ":search"
show_icon: true

Matches

The match folder contains the match files, which are YAML files that contain the actual text expansions.

I have organized my match files into various categories:

• about.yml: About me
• address.yml: Addresses
• base.yml: Base expansions
• datetime.yml: Date and time expansions
• dev.yml: Development related expansions
• emails.yml: Email addresses
• excel.yml: Excel related expansions
• git.yml: Git related expansions
• links.yml: Links
• passwords.yml: Passwords ¹
• phones.yml: Phone numbers
• secrets.yml: Secrets ¹

Packages

The packages folder contains the packages that I have installed.

See Packages for more information.

Currently, I have the following packages installed:

• docker-compose
• get-ip
• lorem
• markdown-shortcuts
• rand-tools
• wttr

Editing

For quick editing of espanso scripts run espanso edit.

Toggle

To toggle espanso's runtime simply double-tab the Alt key. This makes it useful to temporarily disable then re-enable the service.

Application Specific

Use the filter_title configuration variable to specify expansions that should only apply in windows with a title of the provided value. For example, to only match and trigger the below expansion in Outlook you would use:

filter_title: "Outlook"
matches:
    - trigger: ":signature"
      replace: "Jimmy Briggs"

The following table lays out all possible filter_* configurations:

Filter	Description	Windows Support	MacOS Support	Linux Support
filter_title	Filter based on the current Window title	Full support	Uses the App identifier instead of the Window title	Full support
filter_exec	Filter based on the current application executable path	Full support	Full support	Partial support
filter_class	Filter based on the current Window class	Uses the application executable path instead	Uses the App identifier instead	Full support

---

Resources

Footnotes

1. Passwords and secrets files are encrypted via git-crypt. ↩ ↩²