alee/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fixed ESPANSO.md docs to reflect current status.

Browse Source
This commit is contained in:
Aaron D. Lee
2025-12-14 02:03:13 -05:00
parent 75a93a7001
commit 30b0b00983
1 changed files with 277 additions and 239 deletions
Download Patch File Download Diff File Expand all files Collapse all files

516
docs/ESPANSO.md
View File

@@ -1,6 +1,8 @@
# Espanso Quick Reference Guide # Espanso Quick Reference Guide
A comprehensive guide to using espanso text expansion in your dotfiles setup. A comprehensive guide to using espanso text expansion with Aaron D. Lee's custom configuration.
> **Last Updated**: 2024-12-14
## 🚀 Getting Started ## 🚀 Getting Started
@@ -15,6 +17,10 @@ Espanso is automatically installed when you run the main install script:
Or install it separately: Or install it separately:
```bash ```bash
# Arch Linux
paru -S espanso-bin
espanso service register
# Ubuntu/Debian # Ubuntu/Debian
wget https://github.com/espanso/espanso/releases/latest/download/espanso-debian-x11-amd64.deb wget https://github.com/espanso/espanso/releases/latest/download/espanso-debian-x11-amd64.deb
sudo apt install ./espanso-debian-x11-amd64.deb sudo apt install ./espanso-debian-x11-amd64.deb
@@ -24,9 +30,6 @@ espanso service register
brew tap espanso/espanso brew tap espanso/espanso
brew install espanso brew install espanso
espanso service register espanso service register
# Fedora
# See: https://espanso.org/install/
``` ```
### Initial Setup ### Initial Setup
@@ -34,6 +37,7 @@ espanso service register
Run the setup wizard to personalize your configuration: Run the setup wizard to personalize your configuration:
```bash ```bash
cd ~/.dotfiles
./bin/setup-espanso.sh ./bin/setup-espanso.sh
``` ```
@@ -51,83 +55,208 @@ This will:
| Restart espanso | `espanso restart` | | Restart espanso | `espanso restart` |
| Check status | `espanso status` | | Check status | `espanso status` |
## 📝 Built-in Snippets ## Complete Snippet Reference
### Date & Time All triggers use the `..` prefix for consistency and to avoid accidental expansion.
### Date & Time Stamps
| Trigger | Output | Example | | Trigger | Output | Example |
|---------|--------|---------| |---------|--------|---------|
| `:date` | Current date | 2024-12-13 | | `..date` | Current date | `2024-12-14` |
| `:time` | Current time | 14:30:45 | | `..ds` | Date stamp (alias) | `2024-12-14` |
| `:datetime` | Date and time | 2024-12-13 14:30:45 | | `..sds` | Short date (filename safe) | `20241214` |
| `:now` | Formatted datetime | December 13, 2024 at 02:30 PM | | `..ts` | UTC ISO 8601 timestamp | `2024-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 | `2024-12-14 14:30:45 EST` |
| `..udt` | UTC date/time | `2024-12-14 14:30:45 UTC` |
| `..utc` | Full UTC timestamp | `2024-12-14 14:30:45.123 UTC` |
| `..month` | Current month name | `December` |
| `..year` | Current year | `2024` |
| `..week` | Week number | `Week 50` |
| `..day` | Day of week | `Saturday` |
### Emoticons & Symbols ### Unix Timestamps
| Trigger | Output | | Trigger | Output | Example |
|---------|--------| |---------|--------|---------|
| `:shrug` | ¯\\\_(ツ)_/¯ | | `..epoch` | Unix timestamp (seconds) | `1702573845` |
| `:flip` | (╯°□°)╯︵ ┻━┻ | | `..epochms` | Unix timestamp (milliseconds) | `1702573845123` |
| `: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 ### Git Shortcuts
| Trigger | Output | | Trigger | Output |
|---------|--------| |---------|--------|
| `:gst` | `git status` | | `..gstat` | `git status` |
| `:gco` | `git checkout ` | | `..gco` | `git checkout ` |
| `:gcm` | `git commit -m ""` | | `..gcm` | `git commit -m ""` |
| `:glog` | `git log --oneline --graph --decorate --all` | | `..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 ### Docker Shortcuts
| Trigger | Output | | Trigger | Output |
|---------|--------| |---------|--------|
| `:dps` | `docker ps` | | `..dps` | `docker ps` |
| `:dcup` | `docker-compose up -d` | | `..dpsa` | `docker ps -a` |
| `:dcdown` | `docker-compose down` | | `..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` |
### Personal Information (Customizable) ### System Information
| Trigger | Output | Description |
|---------|--------|-------------|
| `..ip` | Your public IP | Via ifconfig.me |
| `..locip` | Your local IP | From hostname -i |
### Code Templates
| Trigger | Output | | Trigger | Output |
|---------|--------| |---------|--------|
| `:myemail` | Your email address | | `..bash` | Bash script template with shebang and error handling |
| `:myname` | Your full name | | `..python` | Python script template with main function |
| `:myphone` | Your phone number | | `..she!` | `#!/usr/bin/env bash` (shebang only) |
| `:mywebsite` | Your website URL |
| `:mygithub` | Your GitHub profile |
| `:sig` | Your email signature |
### Text Templates **Bash Template:**
```bash
#!/usr/bin/env bash
set -euo pipefail
```
**Python Template:**
```python
#!/usr/bin/env python3
def main():
pass
if __name__ == "__main__":
main()
```
### Markdown Helpers
| Trigger | Output | | Trigger | Output |
|---------|--------| |---------|--------|
| `:lorem` | Lorem ipsum paragraph | | `..mdcode` | Markdown code block |
| `:loremlong` | Extended lorem ipsum | | `..mdbash` | Bash code block |
| `:emailhi` | Email greeting template | | `..mdpy` | Python code block |
| `:emailthanks` | Thank you email template | | `..mdjs` | JavaScript code block |
| `:mdheader` | Markdown document header | | `..mdtable` | Markdown table template |
| `:meeting` | Meeting notes template | | `..mdlink` | Markdown link (interactive) |
| `..mdimg` | Markdown image (interactive) |
## 🎨 Creating Custom Snippets **Table Template:**
```markdown
| 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 | grep ` |
| `..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: Edit your snippet files:
@@ -143,15 +272,15 @@ vim ~/.config/espanso/match/personal.yml
```yaml ```yaml
matches: matches:
- trigger: ":hw" - trigger: "..hw"
replace: "Hello, World!" replace: "Hello, World!"
``` ```
### With Variables (Dynamic Content) ### With Date Variables
```yaml ```yaml
matches: matches:
- trigger: ":mydate" - trigger: "..today"
replace: "Today is {{mydate}}" replace: "Today is {{mydate}}"
vars: vars:
- name: mydate - name: mydate
@@ -160,52 +289,42 @@ matches:
format: "%B %d, %Y" format: "%B %d, %Y"
``` ```
### Multi-line Templates
```yaml
matches:
- trigger: ":email"
replace: |
Dear {{name}},
Best regards,
Your Name
vars:
- name: name
type: form
params:
layout: "Recipient name: {{name}}"
```
### With Shell Commands ### With Shell Commands
```yaml ```yaml
matches: matches:
- trigger: ":myip" - trigger: "..uptime"
replace: "{{output}}" replace: "{{output}}"
vars: vars:
- name: output - name: output
type: shell type: shell
params: params:
cmd: "curl -s ifconfig.me" cmd: 'uptime -p'
``` ```
### Cursor Positioning ### Multi-line Templates
```yaml ```yaml
matches: matches:
- trigger: ":func" - trigger: "..header"
replace: "function {{name}}() {\n {{cursor}}\n}" replace: |
# ============================================================================
# {{title}}
# Author: Aaron D. Lee
# Date: {{date}}
# ============================================================================
vars: vars:
- name: name - name: title
type: form type: form
params: params:
layout: "Function name: {{name}}" layout: "Title: {{title}}"
- name: date
type: date
params:
format: "%Y-%m-%d"
``` ```
## 📦 Package Management ## Package Management
### List Installed Packages ### List Installed Packages
@@ -213,7 +332,7 @@ matches:
espanso package list espanso package list
``` ```
### Install Packages ### Install Additional Packages
```bash ```bash
# Emoji support # Emoji support
@@ -225,7 +344,7 @@ espanso install greek-letters --force
# Math symbols # Math symbols
espanso install math --force espanso install math --force
# All emojis # Complete emoji collection
espanso install all-emojis --force espanso install all-emojis --force
``` ```
@@ -233,9 +352,9 @@ espanso install all-emojis --force
Visit: https://hub.espanso.org/ Visit: https://hub.espanso.org/
## 🔧 Configuration ## Configuration
### Main Configuration File ### Main Configuration
Location: `~/.config/espanso/config/default.yml` Location: `~/.config/espanso/config/default.yml`
@@ -248,7 +367,7 @@ toggle_key: ALT+SHIFT+E
# Search shortcut # Search shortcut
search_shortcut: ALT+SPACE search_shortcut: ALT+SPACE
# Backend (Auto, Clipboard, or Inject) # Backend
backend: Auto backend: Auto
# Show notifications # Show notifications
@@ -258,24 +377,12 @@ show_notifications: true
auto_restart: true auto_restart: true
``` ```
### Application-Specific Configs ### Match Files
Create configs for specific applications: - `~/.config/espanso/match/base.yml` - Main snippets (100+ triggers)
- `~/.config/espanso/match/personal.yml` - Personal information
```bash ## Troubleshooting
# Only in terminal
vim ~/.config/espanso/match/terminal.yml
```
```yaml
filter_title: "Terminal|Konsole|iTerm"
matches:
- trigger: ":ll"
replace: "ls -lah"
```
## 🛠️ Troubleshooting
### Espanso Not Working ### Espanso Not Working
@@ -301,154 +408,85 @@ matches:
```bash ```bash
espanso match list espanso match list
``` ```
3. Ensure espanso is enabled (not toggled off with ALT+SHIFT+E) 3. Ensure espanso is enabled (not toggled off with `ALT+SHIFT+E`)
### Conflicts with Other Apps ### Test a Specific Trigger
Some applications may conflict with espanso. Add them to the filter:
```yaml
# In config/default.yml
filter_exec: "application_name"
```
### Clipboard Issues
Try changing the backend:
```yaml
# In config/default.yml
backend: Clipboard
```
## 📚 Advanced Features
### Forms (Interactive Inputs)
```yaml
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
```yaml
matches:
- trigger: ":env"
replace: "{{env}}"
vars:
- name: env
type: choice
params:
values:
- development
- staging
- production
```
### Script Variables
```yaml
matches:
- trigger: ":weather"
replace: "{{output}}"
vars:
- name: output
type: script
params:
args:
- python
- /path/to/weather_script.py
```
## 🔄 Backup and Sync
### Backup Your Config
```bash ```bash
# Using the dotfiles system # 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:
```bash
# On system A (after making changes)
cd ~/.dotfiles cd ~/.dotfiles
git add espanso/ git add espanso/
git commit -m "Update espanso config" git commit -m "Update espanso snippets"
git push git push
```
### Restore on New System # On system B (pull changes)
```bash
# Clone dotfiles
git clone https://github.com/YOUR_USERNAME/dotfiles.git ~/.dotfiles
cd ~/.dotfiles cd ~/.dotfiles
git pull
# Install espanso restart
./install.sh
# Personalize
./bin/setup-espanso.sh
``` ```
## 📖 Resources ## Resources
- [Official Documentation](https://espanso.org/docs/) - [Official Documentation](https://espanso.org/docs/)
- [Package Hub](https://hub.espanso.org/) - [Package Hub](https://hub.espanso.org/)
- [GitHub Repository](https://github.com/espanso/espanso) - [GitHub Repository](https://github.com/espanso/espanso)
- [Community Forum](https://github.com/espanso/espanso/discussions) - [Community Forum](https://github.com/espanso/espanso/discussions)
## 💡 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
```yaml
:fixme → // FIXME:
:todo → // TODO:
:note → // NOTE:
:debug → console.log('DEBUG:', );
```
### Writing & Documentation
```yaml
:doc → Documentation template
:readme → README.md template
:license → MIT License text
:quote → > Blockquote
```
### Communication
```yaml
:ty → Thank you
:yw → You're welcome
:lgtm → Looks good to me
:wip → Work in progress
```
--- ---
**Happy expanding!** 🚀 **Configuration Location**: `~/.config/espanso/`
**Total Triggers**: 100+ pre-configured
**Custom Prefix**: `..` (double period)
**Last Updated**: 2024-12-14
For questions or issues, check the [espanso documentation](https://espanso.org/docs/) or open an issue in your dotfiles repository. Add your own snippets to `personal.yml` for custom shortcuts!