-
-
Notifications
You must be signed in to change notification settings - Fork 0
Script Management
Joao Palma edited this page Jan 29, 2026
·
4 revisions
← User Guide | Home | Documentation System →
- Overview
- Creating Scripts
- Organizing Scripts
- Editing and Updating
- Moving and Renaming
- Removing Scripts
- Script Discovery
- Best Practices
- Next Steps
DotRun provides comprehensive script management capabilities:
- Create: Generate new scripts with templates
- Organize: Use categories for logical grouping
- Edit: Modify scripts with automatic validation
- Move: Reorganize without breaking references
- Discover: Find scripts quickly with built-in search
# Create a simple script
dr set hello
# Create with category
dr set git/cleanup
# Create nested categories
dr set deploy/aws/productionDotRun includes built-in templates:
# Use default template
dr set myscript
# Use specific template
dr set deploy/prod --template=deploy
# List available templates
ls ~/.config/dotrun/templates/Create your own templates:
# Create template
cat >~/.config/dotrun/templates/api.sh <<'EOF'
#!/usr/bin/env bash
### DOC
# API Script Template
#
# Description: Template for API interaction scripts
#
# Usage: dr {{SCRIPT_NAME}} [endpoint]
### DOC
API_BASE="${API_BASE:-https://api.example.com}"
API_KEY="${API_KEY:?API_KEY environment variable required}"
curl -H "Authorization: Bearer $API_KEY" \
"$API_BASE/$1"
EOF
# Use custom template
dr set api/users --template=apiOrganize scripts hierarchically:
~/.config/dotrun/bin/
├── git/ # Git workflows
│ ├── branch-cleanup
│ ├── quick-commit
│ └── pr-create
├── docker/ # Container management
│ ├── build
│ ├── cleanup
│ └── logs
├── deploy/ # Deployment scripts
│ ├── staging/
│ │ ├── api
│ │ └── frontend
│ └── production/
│ ├── api
│ └── frontend
└── utils/ # General utilities
├── backup
└── system-info
-
Use descriptive names:
git/,deploy/,test/ -
Keep related scripts together: All git scripts in
git/ - Limit nesting depth: Maximum 3 levels recommended
- Include category READMEs: Document category purpose
# Create category README
cat >~/.config/dotrun/bin/git/README.md <<'EOF'
# Git Scripts
This category contains Git workflow automation scripts.
## Available Scripts
- `branch-cleanup`: Remove merged branches
- `quick-commit`: Fast commit with generated message
- `pr-create`: Create pull request with template
## Shared Functions
Scripts in this category use `_lib.sh` for common functions.
EOF# Edit script (opens in $EDITOR)
dr set deploy/staging
# Edit with specific editor
EDITOR=vim dr set utils/backup
# Edit category README (use your editor directly)
vim ~/.config/dotrun/bin/git/README.md# Edit directly
vim ~/.config/dotrun/bin/deploy/staging
# Validate after editing
shellcheck ~/.config/dotrun/bin/deploy/stagingUpdate multiple scripts:
# Update all scripts in a category
for script in ~/.config/dotrun/bin/git/*; do
[[ -f "$script" ]] || continue
echo "Updating $(basename "$script")..."
# Add your updates here
done
# Add header to all scripts
for script in ~/.config/dotrun/bin/**/*.sh; do
if ! grep -q "set -euo pipefail" "$script"; then
sed -i '2i\set -euo pipefail' "$script"
fi
done# Rename a script
dr mv old-name new-name
# Move to category
dr mv cleanup git/cleanup
# Move between categories
dr mv utils/deploy deploy/staging
# Rename category (move all scripts)
dr mv docker/ containers/When moving scripts, update references:
# Before moving
grep -r "dr oldname" ~/.config/dotrun/
# Move script
dr mv oldname newname
# Update references
find ~/.config/dotrun -type f -exec \
sed -i 's/dr oldname/dr newname/g' {} \;Track moves in version control:
cd ~/.config/dotrun
# Move and track
git mv bin/old-script bin/new-category/new-script
git commit -m "Reorganize: Move old-script to new-category/new-script"# Remove a script
dr rm deploy/old-version
# Remove with confirmation
dr rm deploy/production # Prompts for confirmation
# Remove category (if empty)
dr rm docker/# Backup script before removing
cp ~/.config/dotrun/bin/deploy/old ~/backup/
dr rm deploy/old
# Or use Git
cd ~/.config/dotrun
git rm bin/deploy/old
git commit -m "Remove: Deprecated deployment script"
# Can restore with: git revert# Remove all scripts in category
for script in ~/.config/dotrun/bin/temp/*; do
dr rm "temp/$(basename "$script")"
done
# Remove by pattern
find ~/.config/dotrun/bin -name "*-old" -type f | while read -r script; do
dr rm "${script#~/.config/dotrun/bin/}"
done# List all scripts
dr -l
dr --list
# List with descriptions
dr -L
dr --list-verbose
# List specific category
dr -l git/
dr -L deploy/# Search by name
dr -l | grep deploy
# Search by description
dr -L | grep -i "cleanup"
# Find scripts by content
grep -r "aws" ~/.config/dotrun/bin/
# Find by documentation
grep -r "### DOC" ~/.config/dotrun/bin/ -A 5 | grep -i "docker"Build a searchable index:
#!/usr/bin/env bash
# build-index.sh
echo "# DotRun Script Index" >~/.config/dotrun/INDEX.md
echo "" >>~/.config/dotrun/INDEX.md
find ~/.config/dotrun/bin -type f -executable | sort | while read -r script; do
name="${script#~/.config/dotrun/bin/}"
desc=$(grep -A1 "^### DOC" "$script" | tail -1 | sed 's/^# *//')
echo "- **$name**: $desc" >>~/.config/dotrun/INDEX.md
doneUse clear, descriptive names:
Good:
- git/branch-cleanup
- deploy/staging-api
- test/run-unit-tests
Bad:
- git/bc
- deploy/s
- test/test
Recommended structure:
bin/
├── git/ # Version control
├── docker/ # Containers
├── k8s/ # Kubernetes
├── aws/ # AWS specific
├── deploy/ # Deployment
├── test/ # Testing
├── db/ # Database
├── monitor/ # Monitoring
└── utils/ # Utilities
Always include documentation:
### DOC
# Category: git
# Script: branch-cleanup
# Purpose: Remove local branches that have been merged
# Dependencies: git
### DOC# Commit after changes
cd ~/.config/dotrun
git add -A
git commit -m "Add: New deployment scripts for staging"
# Tag versions
git tag -a v1.0.0 -m "Initial script collection"# Find unused scripts
for script in ~/.config/dotrun/bin/**/*; do
[[ -f "$script" ]] || continue
last_used=$(stat -c %X "$script" 2>/dev/null || stat -f %a "$script")
# Check if unused for 90 days
done
# Validate all scripts
find ~/.config/dotrun/bin -type f -name "*.sh" -exec shellcheck {} \;Now that you understand script management:
- Learn Documentation: Explore Documentation System
- Set Up Team Sharing: Read Team Collaboration
- Improve Scripts: Study Script Development
- Configure Environment: See Configuration Management
- Browse Examples: Check Example Scripts