dotfiles/docs/ESPANSO.md

Espanso Quick Reference Guide

A comprehensive guide to using espanso text expansion in your dotfiles setup.

🚀 Getting Started

Installation

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

./install.sh

Or install it separately:

# 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

# Fedora
# See: https://espanso.org/install/

Initial Setup

Run the setup wizard to personalize your configuration:

./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

📝 Built-in Snippets

Date & Time

Trigger	Output	Example
:date	Current date	2024-12-13
:time	Current time	14:30:45
:datetime	Date and time	2024-12-13 14:30:45
:now	Formatted datetime	December 13, 2024 at 02:30 PM

Emoticons & Symbols

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

Code Templates

Trigger	Output
:bash	Bash script template with shebang
:python	Python script template
:shebang	#!/usr/bin/env bash
:gitignore	Complete .gitignore template
:mdcode	Markdown code block
:mdtable	Markdown table template

Git Shortcuts

Trigger	Output
:gst	git status
:gco	git checkout
:gcm	git commit -m ""
:glog	git log --oneline --graph --decorate --all

Docker Shortcuts

Trigger	Output
:dps	docker ps
:dcup	docker-compose up -d
:dcdown	docker-compose down

Personal Information (Customizable)

Trigger	Output
:myemail	Your email address
:myname	Your full name
:myphone	Your phone number
:mywebsite	Your website URL
:mygithub	Your GitHub profile
:sig	Your email signature

Text Templates

Trigger	Output
:lorem	Lorem ipsum paragraph
:loremlong	Extended lorem ipsum
:emailhi	Email greeting template
:emailthanks	Thank you email template
:mdheader	Markdown document header
:meeting	Meeting notes template

🎨 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 Variables (Dynamic Content)

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

Multi-line Templates

matches:
  - trigger: ":email"
    replace: |
      Dear {{name}},
      
      
      
      Best regards,
      Your Name
    vars:
      - name: name
        type: form
        params:
          layout: "Recipient name: {{name}}"

With Shell Commands

matches:
  - trigger: ":myip"
    replace: "{{output}}"
    vars:
      - name: output
        type: shell
        params:
          cmd: "curl -s ifconfig.me"

Cursor Positioning

matches:
  - trigger: ":func"
    replace: "function {{name}}() {\n    {{cursor}}\n}"
    vars:
      - name: name
        type: form
        params:
          layout: "Function name: {{name}}"

📦 Package Management

List Installed Packages

espanso package list

Install Packages

# Emoji support
espanso install emoji --force

# Greek letters
espanso install greek-letters --force

# Math symbols
espanso install math --force

# All emojis
espanso install all-emojis --force

Browse Available Packages

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

🔧 Configuration

Main Configuration File

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

Key settings:

# Toggle key
toggle_key: ALT+SHIFT+E

# Search shortcut
search_shortcut: ALT+SPACE

# Backend (Auto, Clipboard, or Inject)
backend: Auto

# Show notifications
show_notifications: true

# Auto-restart on config changes
auto_restart: true

Application-Specific Configs

Create configs for specific applications:

# Only in terminal
vim ~/.config/espanso/match/terminal.yml

filter_title: "Terminal|Konsole|iTerm"

matches:
  - trigger: ":ll"
    replace: "ls -lah"

🛠️ 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)

Conflicts with Other Apps

Some applications may conflict with espanso. Add them to the filter:

# In config/default.yml
filter_exec: "application_name"

Clipboard Issues

Try changing the backend:

# In config/default.yml
backend: Clipboard

📚 Advanced Features

Forms (Interactive Inputs)

matches:
  - trigger: ":invoice"
    replace: |
      Invoice #{{number}}
      Client: {{client}}
      Amount: ${{amount}}
      Due: {{date}}
    vars:
      - name: number
        type: form
        params:
          layout: |
            Invoice Number: {{number}}
            Client Name: {{client}}
            Amount: {{amount}}
            Due Date: {{date}}

Choice Variables

matches:
  - trigger: ":env"
    replace: "{{env}}"
    vars:
      - name: env
        type: choice
        params:
          values:
            - development
            - staging
            - production

Script Variables

matches:
  - trigger: ":weather"
    replace: "{{output}}"
    vars:
      - name: output
        type: script
        params:
          args:
            - python
            - /path/to/weather_script.py

🔄 Backup and Sync

Backup Your Config

# Using the dotfiles system
cd ~/.dotfiles
git add espanso/
git commit -m "Update espanso config"
git push

Restore on New System

# Clone dotfiles
git clone https://github.com/YOUR_USERNAME/dotfiles.git ~/.dotfiles
cd ~/.dotfiles

# Install
./install.sh

# Personalize
./bin/setup-espanso.sh

📖 Resources

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

💡 Tips & Best Practices

1. Use consistent prefixes: Start all triggers with : to avoid accidents
2. Keep it organized: Separate snippets by category in different files
3. Test before committing: Verify new snippets work before adding to git
4. Use descriptive triggers: Make triggers memorable and logical
5. Leverage forms: Use forms for snippets that need customization
6. Back up regularly: Keep your config in version control
7. Share useful snippets: Contribute to the community hub

🎯 Common Use Cases

Developer Workflow

:fixme    → // FIXME: 
:todo     → // TODO: 
:note     → // NOTE: 
:debug    → console.log('DEBUG:', );

Writing & Documentation

:doc      → Documentation template
:readme   → README.md template
:license  → MIT License text
:quote    → > Blockquote

Communication

:ty       → Thank you
:yw       → You're welcome
:lgtm     → Looks good to me
:wip      → Work in progress

---

Happy expanding! 🚀

For questions or issues, check the espanso documentation or open an issue in your dotfiles repository.