dotfiles/docs/ESPANSO.md

Espanso Quick Reference Guide

A comprehensive guide to using espanso text expansion with Aaron D. Lee's custom configuration.

Last Updated: 2025-12-14

🚀 Getting Started

Installation

Espanso is automatically installed when you run the main install script:

./install.sh

Or install it separately:

# Arch Linux
paru -S espanso-bin
espanso service register

# Ubuntu/Debian
wget https://github.com/espanso/espanso/releases/latest/download/espanso-debian-x11-amd64.deb
sudo apt install ./espanso-debian-x11-amd64.deb
espanso service register

# macOS
brew tap espanso/espanso
brew install espanso
espanso service register

Initial Setup

Run the setup wizard to personalize your configuration:

cd ~/.dotfiles
./bin/setup-espanso.sh

This will:

• Personalize your snippets with your information
• Install optional espanso packages
• Show you useful triggers and tips

⌨️ Basic Controls

Action	Shortcut
Toggle espanso on/off	ALT+SHIFT+E
Open search menu	ALT+SPACE
Restart espanso	espanso restart
Check status	espanso status

Complete Snippet Reference

All triggers use the .. prefix for consistency and to avoid accidental expansion.

Date & Time Stamps

Trigger	Output	Example
..date	Current date	2025-12-14
..ds	Date stamp (alias)	2025-12-14
..sds	Short date (filename safe)	20251214
..ts	UTC ISO 8601 timestamp	2025-12-14T14:30:45.123Z
..time	Current time	14:30:45
..utime	UTC time	14:30:45
..ztime	Time with timezone	14:30:45.123 EST
..uztime	UTC time with timezone	14:30:45.123 UTC
..dt	Date/time with timezone	2025-12-14 14:30:45 EST
..udt	UTC date/time	2025-12-14 14:30:45 UTC
..utc	Full UTC timestamp	2025-12-14 14:30:45.123 UTC
..month	Current month name	December
..year	Current year	2025
..week	Week number	Week 50
..day	Day of week	Saturday

Unix Timestamps

Trigger	Output	Example
..epoch	Unix timestamp (seconds)	1702573845
..epochms	Unix timestamp (milliseconds)	1702573845123

Git Shortcuts

Trigger	Output
..gstat	git status
..gco	git checkout
..gcm	git commit -m ""
..glog	git log --oneline --graph --decorate --all
..gpush	git push origin
..gpull	git pull origin
..gbranch	git branch -a
..gdiff	git diff
..gadd	git add .
..branch	Current git branch name

Docker Shortcuts

Trigger	Output
..dps	docker ps
..dpsa	docker ps -a
..dcup	docker-compose up -d
..dcdown	docker-compose down
..dlog	docker logs -f
..dexec	docker exec -it
..dim	docker images
..dprune	docker system prune -af

System Information

Trigger	Output	Description
..ip	Your public IP	Via ifconfig.me
..locip	Your local IP	From hostname -i

Code Templates

Trigger	Output
..bash	Bash script template with shebang and error handling
..python	Python script template with main function
..she!	#!/usr/bin/env bash (shebang only)

Bash Template:

#!/usr/bin/env bash

set -euo pipefail

Python Template:

#!/usr/bin/env python3

def main():
    pass

if __name__ == "__main__":
    main()

Markdown Helpers

Trigger	Output
..mdcode	Markdown code block
..mdbash	Bash code block
..mdpy	Python code block
..mdjs	JavaScript code block
..mdtable	Markdown table template
..mdlink	Markdown link (interactive)
..mdimg	Markdown image (interactive)

Table Template:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |

Emoticons & Symbols

Trigger	Output
..shrug	¯\_(ツ)_/¯
..flip	(╯°□°)╯︵ ┻━┻
..unflip	┬─┬ ノ( ゜-゜ノ)
..lenny	( ͡° ͜ʖ ͡°)
..check	✓
..cross	✗
..arrow	→
..larrow	←

Quick Responses

Trigger	Output
..brb	Be right back
..omw	On my way
..tyvm	Thank you very much
..lgtm	Looks good to me
..wfm	Works for me
..ack	Acknowledged
..asap	As soon as possible

File Paths & Navigation

Trigger	Output
..~	cd ~
..tmp	cd /tmp/
..logs	cd /var/log/

Common URLs

Trigger	Output
..gh	https://github.com
..gl	https://gitlab.com
..gist	https://gist.github.com
..so	https://stackoverflow.com
..reddit	https://reddit.com

Programming Comments

Trigger	Output
..todo	// TODO:
..fixme	// FIXME:
..note	// NOTE:
..hack	// HACK:
..debug	// DEBUG:

Common Commands

Trigger	Output
..ll	ls -lah
..la	ls -A
..grep	grep -rni "" .
..find	find . -name ""
..port	lsof -i :
..kill	kill -9
..proc	`ps aux
..disk	df -h
..mem	free -h

Lorem Ipsum

Trigger	Output
..lorem	Single paragraph
..loremlong	Extended lorem ipsum (4 sentences)

Auto-Corrections

These work automatically without the .. prefix:

Typo	Correction
teh	the
recieve	receive
seperator	separator
definately	definitely
occured	occurred
lenght	length
wierd	weird
thier	their

Creating Custom Snippets

Edit your snippet files:

# Base snippets (general use)
vim ~/.config/espanso/match/base.yml

# Personal snippets (your info)
vim ~/.config/espanso/match/personal.yml

Simple Text Replacement

matches:
  - trigger: "..hw"
    replace: "Hello, World!"

With Date Variables

matches:
  - trigger: "..today"
    replace: "Today is {{mydate}}"
    vars:
      - name: mydate
        type: date
        params:
          format: "%B %d, %Y"

With Shell Commands

matches:
  - trigger: "..uptime"
    replace: "{{output}}"
    vars:
      - name: output
        type: shell
        params:
          cmd: 'uptime -p'

Multi-line Templates

matches:
  - trigger: "..header"
    replace: |
      # ============================================================================
      # {{title}}
      # Author: Aaron D. Lee
      # Date: {{date}}
      # ============================================================================
    vars:
      - name: title
        type: form
        params:
          layout: "Title: {{title}}"
      - name: date
        type: date
        params:
          format: "%Y-%m-%d"

Package Management

List Installed Packages

espanso package list

Install Additional Packages

# Emoji support
espanso install emoji --force

# Greek letters
espanso install greek-letters --force

# Math symbols
espanso install math --force

# Complete emoji collection
espanso install all-emojis --force

Browse Available Packages

Visit: https://hub.espanso.org/

Configuration

Main Configuration

Location: ~/.config/espanso/config/default.yml

Key settings:

# Toggle key
toggle_key: ALT+SHIFT+E

# Search shortcut
search_shortcut: ALT+SPACE

# Backend
backend: Auto

# Show notifications
show_notifications: true

# Auto-restart on config changes
auto_restart: true

Match Files

• ~/.config/espanso/match/base.yml - Main snippets (100+ triggers)
• ~/.config/espanso/match/personal.yml - Personal information

Troubleshooting

Espanso Not Working

1. Check if running:

   espanso status
   

2. Restart the service:

   espanso restart
   

3. Check logs:

   espanso log
   

Snippets Not Expanding

1. Verify the trigger syntax in your YAML files
2. Check for YAML syntax errors:

   espanso match list
   

3. Ensure espanso is enabled (not toggled off with ALT+SHIFT+E)

Test a Specific Trigger

# List all matches
espanso match list | grep "..date"

# Check if trigger is recognized
espanso match list | grep "trigger"

Pro Tips

1. Consistent Naming: All triggers use .. prefix to avoid accidents
2. Quick Testing: Type trigger in any text field to test immediately
3. Search Feature: Use ALT+SPACE to search all available snippets
4. Restart After Changes: espanso restart after editing YAML files
5. Check Logs: Use espanso log to debug issues
6. Backup Your Config: Your espanso config is in your dotfiles repo!

Common Workflows

Developer Workflow

..gstat     → Check git status
..gadd      → Stage all changes
..gcm       → Commit with message
..gpush     → Push to remote

Documentation Writing

..date      → Add current date
..mdcode    → Insert code block
..mdtable   → Create table
..todo      → Add TODO comment

System Administration

..dps       → Check running containers
..disk      → Check disk usage
..mem       → Check memory usage
..port      → Check port usage

Syncing Across Systems

Your espanso config is part of your dotfiles:

# On system A (after making changes)
cd ~/.dotfiles
git add espanso/
git commit -m "Update espanso snippets"
git push

# On system B (pull changes)
cd ~/.dotfiles
git pull
espanso restart

Resources

• Official Documentation
• Package Hub
• GitHub Repository
• Community Forum

---

Configuration Location: ~/.config/espanso/
Total Triggers: 100+ pre-configured
Custom Prefix: .. (double period)
Last Updated: 2025-12-14

Add your own snippets to personal.yml for custom shortcuts!