Alias Management - jvPalma/dotrun GitHub Wiki

Alias Management

← Configuration Management | Home | Developer Experience →

Table of Contents

Overview

DotRun v3.1.0 uses a file-based alias workflow where aliases are defined in plain text .aliases files, not via command-based operations.

Key Features:

  • File-based: Aliases defined in .aliases files in ~/.config/dotrun/aliases/
  • Load Order Control: Two-digit numeric prefix (NN) controls load order
  • Automatic Loading: Files loaded in alphabetical order when shell starts
  • Category Organization: Files can be flat (01-git.aliases) or nested (01-git/shortcuts.aliases)
  • Shell Agnostic: Works with bash, zsh, and fish
  • Flexible Structure: One file can contain multiple related aliases

Storage Location: ~/.config/dotrun/aliases/

Loading Mechanism: All .aliases files are discovered via find and loaded in sorted (alphabetical) order.

File Structure and Naming

Naming Convention

Format: NN-category.aliases

  • NN: Two-digit number (01-99) controlling load order
  • category: Descriptive name (lowercase, no spaces)
  • Extension: .aliases (required)

Examples

Flat Structure:

~/.config/dotrun/aliases/
├── 01-navigation.aliases    # Core navigation (cd shortcuts)
├── 05-git.aliases           # Git operations
├── 07-docker.aliases        # Docker commands
├── 10-kubernetes.aliases    # K8s shortcuts
└── 90-personal.aliases      # Personal overrides

Nested Structure:

~/.config/dotrun/aliases/
├── 01-core.aliases
├── 05-git.aliases
├── 05-git/
│   ├── shortcuts.aliases
│   └── advanced.aliases
├── 10-docker.aliases
└── 10-docker/
    └── compose.aliases

Nested Sorting: Full paths are sorted lexicographically:

  • 05-git.aliases loads before 05-git/shortcuts.aliases (. sorts before /)
  • 10-docker.aliases loads before 10-docker/compose.aliases

Load Order Control

How It Works

Files are loaded using:

find ~/.config/dotrun/aliases -name "*.aliases" -type f | sort

Load Order Rules:

  1. Lower NN loads first (01 before 05, 05 before 10)
  2. Flat files load before nested files in same category
  3. Later files can override earlier aliases by redefining them

Load Order Example

Execution Order (earliest to latest):

01-core.aliases
05-docker.aliases
05-git.aliases
05-git/shortcuts.aliases    # Nested, loads after flat 05-git.aliases
10-kubernetes.aliases
90-personal.aliases          # Last, can override everything

Preview Load Order

Check actual load order:

# Using DotRun command
dr aliases list

# Or manually
find ~/.config/dotrun/aliases -type f -name "*.aliases" | sort

Creating Alias Files

Method 1: Using DotRun Commands

Initialize (run once):

dr aliases init

Create or Edit Files:

# Create/edit flat file
dr aliases set 01-git
# Opens: ~/.config/dotrun/aliases/01-git.aliases

# Create/edit nested file
dr aliases set docker/compose
# Opens: ~/.config/dotrun/aliases/docker/compose.aliases

# With NN prefix in nested path
dr aliases set 05-git/shortcuts
# Opens: ~/.config/dotrun/aliases/05-git/shortcuts.aliases

Method 2: Manual Creation

Create Directory (if needed):

mkdir -p ~/.config/dotrun/aliases

Create File:

# Create with your editor
vim ~/.config/dotrun/aliases/05-git.aliases

# Or use echo
cat >~/.config/dotrun/aliases/05-git.aliases <<'EOF'
# Git shortcuts
alias gs='git status'
alias ga='git add'
alias gc='git commit'
EOF

Requirements:

  • File extension must be .aliases
  • Use standard shell alias syntax: alias name='command'
  • Save with Unix line endings (LF)
  • No shebang needed
  • File must be readable

File Format Examples

Navigation Aliases

File: ~/.config/dotrun/aliases/01-navigation.aliases

# Navigation shortcuts
alias ..='cd ..'
alias ...='cd ../..'
alias ....='cd ../../..'
alias ~='cd ~'

# Quick directories
alias cdd='cd ~/Downloads'
alias cdp='cd ~/Projects'
alias cdc='cd ~/.config'
alias cfg='cd ~/.config/dotrun/aliases'

# Enhanced ls
alias ll='ls -lah'
alias la='ls -A'
alias l='ls -CF'

Git Aliases

File: ~/.config/dotrun/aliases/05-git.aliases

# Git basics
alias g='git'
alias gst='git status -sb'
alias gco='git checkout'
alias gcb='git checkout -b'
alias ga='git add -A'
alias gcm='git commit -m'
alias gp='git push'
alias gpl='git pull --rebase --autostash'

# Git viewing
alias gl='git log --oneline --graph --decorate --all'
alias gdf='git diff'
alias gdc='git diff --cached'

# Git branch management
alias gb='git branch'
alias gbd='git branch -d'
alias gbD='git branch -D'

Docker Aliases

File: ~/.config/dotrun/aliases/07-docker.aliases

# Docker and Docker Compose
alias d='docker'
alias dc='docker compose'

# Docker PS with formatting
alias dps='docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"'
alias dpsa='docker ps -a --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"'

# Docker images
alias dim='docker images'
alias drmi='docker rmi'

# Docker logs
alias dl='docker logs'
alias dlf='docker logs -f'

# Docker Compose
alias dcu='docker compose up -d'
alias dcd='docker compose down'
alias dcr='docker compose restart'
alias dcl='docker compose logs -f'

# Docker exec
alias dex='docker exec -it'

Kubernetes Aliases

File: ~/.config/dotrun/aliases/10-kubernetes.aliases

# Kubernetes
alias k='kubectl'
alias kg='kubectl get'
alias kd='kubectl describe'
alias kdel='kubectl delete'
alias kap='kubectl apply -f'

# Pods
alias kgp='kubectl get pods'
alias kgpa='kubectl get pods --all-namespaces'
alias kdp='kubectl describe pod'
alias kl='kubectl logs'
alias klf='kubectl logs -f'

# Deployments
alias kgd='kubectl get deployments'
alias kdd='kubectl describe deployment'

# Services
alias kgs='kubectl get services'
alias kds='kubectl describe service'

# Context switching
alias kctx='kubectl config use-context'
alias kns='kubectl config set-context --current --namespace'

Personal Overrides

File: ~/.config/dotrun/aliases/90-personal.aliases

# Personal overrides (loads last)

# Override ls with eza if installed
if command -v eza &>/dev/null; then
  alias ls='eza --group-directories-first --icons=auto -F'
  alias ll='eza -la --group-directories-first --icons=auto'
  alias lt='eza --tree --level=2'
fi

# Override cat with bat if installed
if command -v bat &>/dev/null; then
  alias cat='bat --style=plain'
fi

# Machine-specific shortcuts
alias work='cd ~/work-projects'
alias personal='cd ~/personal-projects'

Nested File Example

File: ~/.config/dotrun/aliases/05-git/advanced.aliases

# Advanced Git shortcuts (loads after 05-git.aliases)

# Git switch (newer syntax)
alias gsw='git switch'
alias gswc='git switch -c'

# Git restore
alias gr='git restore'
alias grs='git restore --staged'

# Git stash
alias gss='git stash -u'
alias gsp='git stash pop'
alias gsl='git stash list'

# Interactive rebase
alias grb='git rebase -i'
alias grbc='git rebase --continue'
alias grba='git rebase --abort'

Managing Aliases

Available Commands

# Initialize system
dr aliases init

# Create or edit alias file
dr aliases set <path/to/file>

# List all alias files
dr aliases list

# List with category information
dr aliases list --categories

# List files in specific category
dr aliases list --category <name>

# Remove alias file
dr aliases remove <path/to/file>

# Reload aliases in current shell
dr aliases reload

Command Examples

List Aliases:

# List all alias files
dr aliases list

# List with categories
dr aliases list --categories

# List git category only
dr aliases list --category git

Edit Aliases:

# Edit existing file
dr aliases set 05-git

# Edit nested file
dr aliases set docker/compose

# Or edit directly
vim ~/.config/dotrun/aliases/05-git.aliases

Remove Aliases:

# Remove entire file
dr aliases remove 07-docker.aliases

# Remove nested file
dr aliases remove 10-git/shortcuts.aliases

Reload Aliases:

# Apply changes without restarting shell
dr aliases reload

# Or source directly
source ~/.config/dotrun/shell/bash/aliases.sh # bash
source ~/.config/dotrun/shell/zsh/aliases.sh  # zsh

Common Patterns

Navigation Pattern (01-nav.aliases)

# Directory navigation
alias ..='cd ..'
alias ...='cd ../..'
alias ....='cd ../../..'
alias ~='cd ~'
alias -- -='cd -' # Go back to previous directory

# Quick jumps
alias dl='cd ~/Downloads'
alias doc='cd ~/Documents'
alias desk='cd ~/Desktop'

Git Workflow Pattern (05-git.aliases)

# Status and staging
alias gst='git status -sb'
alias ga='git add'
alias gap='git add -p' # Interactive staging

# Committing
alias gc='git commit'
alias gcm='git commit -m'
alias gca='git commit --amend'
alias gcan='git commit --amend --no-edit'

# Branching and switching
alias gco='git checkout'
alias gcb='git checkout -b'
alias gb='git branch'
alias gm='git merge'

# Syncing
alias gp='git push'
alias gpf='git push --force-with-lease'
alias gpl='git pull --rebase --autostash'
alias gf='git fetch --all --prune'

Docker Workflow Pattern (07-docker.aliases)

# Quick commands
alias dps='docker ps'
alias dpsa='docker ps -a'
alias dim='docker images'

# Docker Compose workflow
alias dcu='docker compose up -d'
alias dcd='docker compose down'
alias dcr='docker compose restart'
alias dcl='docker compose logs -f'
alias dcps='docker compose ps'

# Cleanup
alias dprune='docker system prune -af'
alias dvprune='docker volume prune -f'

Load Order Best Practices

Good: Core First, Overrides Last

Strategy: Place foundational aliases early, personal overrides late.

# 01-core.aliases (loads first)
alias ls='ls -F'
alias ll='ls -la'

# 90-personal.aliases (loads last)
# Override with better tool if available
if command -v eza &>/dev/null; then
  alias ls='eza --group-directories-first -F'
  alias ll='eza -la --group-directories-first'
fi

Bad: Overrides Before Core

Problem: Earlier file overrides make later definitions ineffective.

# ❌ BAD: 01-core.aliases
alias ls='ls -F'
alias ll='ls -la'

# ❌ BAD: 50-tools.aliases (loads after core)
# This gets OVERRIDDEN by 01-core because alphabetical sort
# puts 01 before 50, so 50 loads AFTER and wins
alias ls='eza -F' # This actually wins (bad organization)

Fix: Use consistent numbering strategy where lower = foundation, higher = overrides.

Numbering Gaps for Flexibility

Good: Leave gaps for future insertions.

01-core.aliases       # Core utilities
05-git.aliases        # Version control
10-docker.aliases     # Containers
20-kubernetes.aliases # Orchestration
30-cloud.aliases      # Cloud providers
80-work.aliases       # Work-specific
90-personal.aliases   # Personal overrides

Bad: No gaps, hard to insert new categories.

01-core.aliases
02-git.aliases
03-docker.aliases
04-kubernetes.aliases
# Now where do you add cloud aliases between docker and k8s?
# Have to renumber everything!

Dependency Management

Good: Ensure dependencies load first.

# 01-paths.config (sets PATH - config file, not alias file)
export PATH="$HOME/.local/bin:$PATH"

# 10-custom.aliases (uses tools from PATH)
alias mytool='/path/from/custom/bin/tool' # Tool is in PATH

Bad: Using tools before PATH is set.

# 10-custom.aliases (tries to use tool)
alias mytool='custom-tool --flag'

# 50-paths.config (sets PATH too late!)
export PATH="$HOME/.local/bin:$PATH"
# custom-tool might not be found when alias was defined

Migration from v2.x

v2.x Command-Based System

Old Workflow (v2.x):

# Add individual aliases
dr alias add ll "ls -la"
dr alias add gco "git checkout"
dr alias add dps "docker ps"

# List aliases
dr alias list

# Remove alias
dr alias remove ll

Migration Steps

Step 1: Initialize v3.1.0 System

dr aliases init

Step 2: Export v2.x Aliases (if possible)

# If v2.x has export command
dr alias list >~/old-aliases.txt

Step 3: Create Category Files

# Create files for different categories
dr aliases set 05-git
dr aliases set 07-docker
dr aliases set 10-personal

Step 4: Migrate Aliases to Files

Example Migration:

From v2.x commands:

dr alias add ll "ls -la"
dr alias add gst "git status"
dr alias add gco "git checkout"
dr alias add dps "docker ps"

To v3.1.0 files:

File: ~/.config/dotrun/aliases/01-core.aliases

# Core utilities
alias ll='ls -la'

File: ~/.config/dotrun/aliases/05-git.aliases

# Git shortcuts
alias gst='git status'
alias gco='git checkout'

File: ~/.config/dotrun/aliases/07-docker.aliases

# Docker shortcuts
alias dps='docker ps'

Step 5: Reload and Test

# Reload in current shell
dr aliases reload

# Test aliases
alias ll
alias gst
alias dps

Step 6: Clean Up v2.x

Remove any v2.x alias storage files (location varies by v2.x implementation).

Migration Tips

Quoting Rules: Keep the same quoting from v2.x commands:

  • Single quotes prevent variable expansion: alias mydir='cd ~/projects'
  • Double quotes allow expansion: alias today="date +%Y-%m-%d"

Grouping: Organize migrated aliases into logical categories:

  • Split by tool (git, docker, npm)
  • Split by purpose (navigation, development, system)
  • Use NN prefixes to control load order

Best Practices

1. Use Descriptive Categories

Good:

01-navigation.aliases
05-git.aliases
07-docker.aliases
10-kubernetes.aliases
20-development.aliases
80-work.aliases
90-personal.aliases

Avoid:

01-stuff.aliases
02-more.aliases
03-misc.aliases

2. Leave Numbering Gaps

Good: Gaps allow future insertions

01-core.aliases
05-git.aliases
10-docker.aliases
20-cloud.aliases
# Easy to add 15-kubernetes.aliases later

Avoid: No gaps

01-core.aliases
02-git.aliases
03-docker.aliases
# Hard to insert between 02 and 03

3. Group Related Aliases

Good: Logical grouping within files

# 05-git.aliases

# Status and staging
alias gst='git status -sb'
alias ga='git add'
alias gap='git add -p'

# Committing
alias gc='git commit'
alias gcm='git commit -m'
alias gca='git commit --amend'

# Branching
alias gco='git checkout'
alias gcb='git checkout -b'
alias gb='git branch'

Avoid: Random order

# 05-git.aliases
alias gco='git checkout'
alias gst='git status'
alias ga='git add'
alias gb='git branch'
alias gcm='git commit -m'

4. Comment Sections

Good: Clear section headers

# Git aliases

# Status and viewing
alias gst='git status -sb'
alias gl='git log --oneline --graph'

# Branch management
alias gb='git branch'
alias gco='git checkout'
alias gcb='git checkout -b'

5. Avoid Command Name Conflicts

Good: Check before defining

# Check if name is already a command
command -v ll &>/dev/null && echo "ll exists"

# Use unique prefixes if needed
alias my-ll='ls -la'
alias dr-ll='ls -la'

Risky: Overriding system commands

# Dangerous: overrides system commands
alias rm='rm -i' # Can break scripts expecting standard rm
alias cp='cp -i' # Can break scripts expecting standard cp

6. Prefer Single Quotes

Good: Single quotes prevent early expansion

alias today='date +%Y-%m-%d' # Runs date when alias is used
alias mydir='cd ~/projects'  # Expands ~ when used

Careful: Double quotes expand immediately

alias today="date +%Y-%m-%d"    # Expands when alias is DEFINED
alias mydir="cd $HOME/projects" # Expands $HOME when defined

7. Test After Changes

Workflow:

# 1. Edit alias file
dr aliases set 05-git

# 2. Reload in current shell
dr aliases reload

# 3. Test the alias
alias gst
gst

# 4. Verify it works as expected

8. Version Control Your Aliases

Setup:

cd ~/.config/dotrun
git init
git add aliases/
git commit -m "Initial aliases setup"

Track Changes:

# After modifying aliases
cd ~/.config/dotrun
git add aliases/05-git.aliases
git commit -m "Add git stash aliases"

Troubleshooting

Aliases Not Loading

Symptoms: Aliases don't work after shell start.

Solutions:

Check file location:

ls ~/.config/dotrun/aliases/

Check file extension:

# Must end with .aliases
ls ~/.config/dotrun/aliases/*.aliases

Check file permissions:

# Files must be readable
chmod +r ~/.config/dotrun/aliases/*.aliases

Check line endings:

# Should be LF (Unix), not CRLF (Windows)
file ~/.config/dotrun/aliases/05-git.aliases

Reload shell or run reload:

# Option 1: Reload in current shell
dr aliases reload

# Option 2: Start new shell
exec $SHELL

# Option 3: Source directly
source ~/.drrc

Wrong Load Order

Symptoms: Aliases loaded in unexpected order, overrides not working.

Solutions:

Check numeric prefixes:

# Files should have consistent NN- prefixes
ls -1 ~/.config/dotrun/aliases/
# Should show:
# 01-core.aliases
# 05-git.aliases
# 10-docker.aliases
# 90-personal.aliases

Preview actual load order:

# See order DotRun will use
dr aliases list

# Or check manually
find ~/.config/dotrun/aliases -name "*.aliases" -type f | sort

Fix numbering:

# Rename files to correct order
mv ~/.config/dotrun/aliases/personal.aliases \
  ~/.config/dotrun/aliases/90-personal.aliases

mv ~/.config/dotrun/aliases/git.aliases \
  ~/.config/dotrun/aliases/05-git.aliases

Reload after fixing:

dr aliases reload

Alias Conflicts

Symptoms: Alias doesn't do what you expect, or uses wrong definition.

Solutions:

Check current definition:

# See what alias currently points to
alias gst

Find all definitions:

# Search for alias in all files
grep -R "^alias gst=" ~/.config/dotrun/aliases/

Fix conflicts:

Option 1: Remove earlier definition:

# Edit file with unwanted definition
dr aliases set 05-git
# Remove or comment out: alias gst='old definition'

Option 2: Move intended definition to later file:

# Move to higher NN (loads later, overrides earlier)
# Copy to 90-personal.aliases, remove from 05-git.aliases

Option 3: Use different name:

# Rename to avoid conflict
alias my-gst='git status -sb'

Changes Not Taking Effect

Symptoms: Modified aliases still use old definition.

Solutions:

Reload in current shell:

dr aliases reload

Check you edited correct file:

# Verify file path matches what dr aliases set creates
dr aliases set 05-git
# Should open: ~/.config/dotrun/aliases/05-git.aliases

Check for syntax errors:

# Try sourcing manually to see errors
source ~/.config/dotrun/aliases/05-git.aliases

Check quoting:

# ✅ Good: Matched quotes
alias gst='git status'

# ❌ Bad: Mismatched quotes (won't work)
alias gst='git status"
alias gco="git checkout'

Start new shell:

# If reload doesn't work, start fresh shell
exec $SHELL

Category Filtering Not Working

Symptoms: dr aliases list --category <name> returns nothing or wrong files.

Solutions:

Check category name:

# Category is derived from path after NN-
# 05-git/shortcuts.aliases → category is "git"
# 10-docker.aliases → category is "docker"

# List with categories to see actual names
dr aliases list --categories

Fix file naming:

# Ensure files follow NN-category naming
# ✅ Good: 05-git.aliases
# ❌ Bad: git.aliases (no NN prefix)
# ❌ Bad: 05git.aliases (no dash)

Use correct category name:

# If file is 05-git.aliases
dr aliases list --category git # ✅ Correct

# Not:
dr aliases list --category 05-git # ❌ Wrong

Next Steps

With alias management mastered:

  1. Configuration Management: Learn about Configuration Management for environment variables
  2. Collections: Share aliases via Collections
  3. Shell Integration: Optimize with Developer Experience
  4. Script Integration: Use aliases in Scripts
  5. Troubleshooting: Check Troubleshooting Guide for issues

← Configuration Management | Dotfile Integration → | Top ↑

⚠️ **GitHub.com Fallback** ⚠️