# Script Management

[← User Guide](User-Guide.md) | [Home](Home.md) | [Documentation System →](Documentation-System.md)

---

## Table of Contents

- [Overview](#overview)
- [Creating Scripts](#creating-scripts)
- [Organizing Scripts](#organizing-scripts)
- [Editing and Updating](#editing-and-updating)
- [Moving and Renaming](#moving-and-renaming)
- [Removing Scripts](#removing-scripts)
- [Script Discovery](#script-discovery)
- [Best Practices](#best-practices)
- [Next Steps](#next-steps)

## Overview

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

## Creating Scripts

### Basic Script Creation

```bash
# Create a simple script
dr set hello

# Create with category
dr set git/cleanup

# Create nested categories
dr set deploy/aws/production
```

### Using Templates

DotRun includes built-in templates:

```bash
# Use default template
dr set myscript

# Use specific template
dr set deploy/prod --template=deploy

# List available templates
ls ~/.config/dotrun/templates/
```

### Custom Templates

Create your own templates:

```bash
# 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=api
```

## Organizing Scripts

### Category Structure

Organize 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
```

### Category Guidelines

1. **Use descriptive names**: `git/`, `deploy/`, `test/`
2. **Keep related scripts together**: All git scripts in `git/`
3. **Limit nesting depth**: Maximum 3 levels recommended
4. **Include category READMEs**: Document category purpose

### Creating Category Documentation

```bash
# 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
```

## Editing and Updating

### Interactive Editing

```bash
# 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
```

### Direct File Editing

```bash
# Edit directly
vim ~/.config/dotrun/bin/deploy/staging

# Validate after editing
shellcheck ~/.config/dotrun/bin/deploy/staging
```

### Batch Updates

Update multiple scripts:

```bash
# 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
```

## Moving and Renaming

### Move Commands

```bash
# 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/
```

### Preserving References

When moving scripts, update references:

```bash
# 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' {} \;
```

### Moving with Git

Track moves in version control:

```bash
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"
```

## Removing Scripts

### Safe Removal

```bash
# 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 Before Removal

```bash
# 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
```

### Bulk Removal

```bash
# 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
```

## Script Discovery

### Listing Scripts

```bash
# 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 Functionality

```bash
# 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"
```

### Creating Script Index

Build a searchable index:

```bash
#!/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
done
```

## Best Practices

### 1. Consistent Naming

Use clear, descriptive names:

```
Good:
- git/branch-cleanup
- deploy/staging-api
- test/run-unit-tests

Bad:
- git/bc
- deploy/s
- test/test
```

### 2. Category Organization

```
Recommended structure:
bin/
├── git/          # Version control
├── docker/       # Containers
├── k8s/          # Kubernetes
├── aws/          # AWS specific
├── deploy/       # Deployment
├── test/         # Testing
├── db/           # Database
├── monitor/      # Monitoring
└── utils/        # Utilities
```

### 3. Documentation

Always include documentation:

```bash
### DOC
# Category: git
# Script: branch-cleanup
# Purpose: Remove local branches that have been merged
# Dependencies: git
### DOC
```

### 4. Version Control

```bash
# 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"
```

### 5. Regular Maintenance

```bash
# 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 {} \;
```

## Next Steps

Now that you understand script management:

1. **Learn Documentation**: Explore [Documentation System](Documentation-System.md)
2. **Set Up Team Sharing**: Read [Team Collaboration](Team-Collaboration.md)
3. **Improve Scripts**: Study [Script Development](Script-Development.md)
4. **Configure Environment**: See [Configuration Management](Configuration-Management.md)
5. **Browse Examples**: Check [Example Scripts](Script-Examples.md)

---

[← Back to README](../../README.md) | [Documentation System →](Documentation-System.md) | [Top ↑](#script-management)