# User Guide

[← Installation Guide](Installation-Guide.md) | [Home](Home.md) | [Script Development →](Script-Development.md)

---

## Table of Contents

- [Quick Start Tutorial](#quick-start-tutorial)
- [Core Commands](#core-commands)
- [Script Management](#script-management)
- [Documentation Features](#documentation-features)
- [Working with Categories](#working-with-categories)
- [Best Practices](#best-practices)
- [Advanced Usage](#advanced-usage)
- [Next Steps](#next-steps)

## Quick Start Tutorial

Let's create and use your first DotRun script:

### 1. Create a Simple Script

```bash
# Create a new script called 'hello'
dr set hello

# This opens your editor with a template. Add this content:
#!/usr/bin/env bash
### DOC
# Hello World Script
#
# A simple demonstration script for DotRun
#
# Usage: dr hello [name]
#
# Arguments:
#   name - Optional name to greet (default: World)
#
# Examples:
#   dr hello          # Outputs: Hello, World!
#   dr hello Alice    # Outputs: Hello, Alice!
### DOC

name="${1:-World}"
echo "Hello, $name!"
```

### 2. Run Your Script

```bash
# Run with default
dr hello
# Output: Hello, World!

# Run with argument
dr hello DotRun
# Output: Hello, DotRun!
```

### 3. View Documentation

```bash
# View the inline documentation
dr help hello

# If you have glow installed, it renders as formatted markdown
```

## Core Commands

### Script Execution

```bash
dr <script>           # Run a script
dr <script> [args]    # Run with arguments
dr <category>/<script> # Run categorized script
```

### Script Management

```bash
dr set <name>         # Create new script or edit existing
dr rm <name>          # Remove script
dr mv <old> <new>     # Move/rename script
dr cp <source> <dest> # Copy script
```

### Discovery & Help

```bash
dr -l, --list         # List all scripts
dr -L, --list-verbose # List with descriptions
dr help <script>      # Show script documentation
dr --version          # Show version
dr --info             # Show installation info
```

## Script Management

### Creating Scripts

When you create a script with `dr set`, you get:

- Executable permissions set automatically
- Documentation template included
- ShellCheck linting (if installed)
- Git tracking (automatic commit)

```bash
# Create in a category
dr set git/cleanup

# Create with custom template
dr set deploy/prod --template=deploy
```

### Organizing with Categories

Categories help organize related scripts:

```bash
# Create categorized scripts
dr set git/branch-cleanup
dr set docker/cleanup
dr set deploy/staging

# List scripts by category
dr -l git/    # List only git scripts
dr -L docker/ # Verbose list of docker scripts
```

### Moving and Copying

```bash
# Move to a category
dr mv cleanup git/cleanup

# Rename within category
dr mv git/cleanup git/branch-cleanup

# Copy for modification
dr cp deploy/staging deploy/production
```

## Documentation Features

### Inline Documentation

Every script should include a `### DOC` section:

```bash
#!/usr/bin/env bash
### DOC
# Script Name
#
# Brief description of what this script does
#
# Usage: dr scriptname [options]
#
# Options:
#   -h, --help    Show this help message
#   -v, --verbose Enable verbose output
#
# Examples:
#   dr scriptname
#   dr scriptname --verbose
#
# Dependencies:
#   - tool1: Description
#   - tool2: Description
### DOC

# Script implementation here
```

### Markdown Documentation

Create comprehensive guides in `docs/`:

```bash
# Create documentation
dr doc create git-workflows

# View documentation
dr doc view git-workflows

# List all documentation
dr doc list
```

## Working with Categories

### Standard Categories

Organize scripts by purpose:

- `git/` - Git workflows and utilities
- `docker/` - Container management
- `deploy/` - Deployment scripts
- `test/` - Testing utilities
- `setup/` - Environment setup
- `utils/` - General utilities

### Category Best Practices

1. **Consistent Naming**: Use lowercase, hyphen-separated names
2. **Clear Purpose**: Each category should have a clear theme
3. **Documentation**: Include a README in each category
4. **Shared Functions**: Use `_lib.sh` for shared code

Example structure:

```
~/.config/dotrun/bin/
├── git/
│   ├── _lib.sh          # Shared git functions
│   ├── branch-cleanup
│   ├── quick-commit
│   └── README.md
├── deploy/
│   ├── staging
│   ├── production
│   └── rollback
└── utils/
    ├── backup
    └── clean-logs
```

## Best Practices

### 1. Documentation First

- Always include `### DOC` sections
- Document parameters and examples
- Keep documentation up-to-date

### 2. Error Handling

```bash
set -euo pipefail # Exit on error, undefined vars, pipe failures
```

### 3. Consistent Style

- Use ShellCheck for linting
- Follow naming conventions
- Include progress messages

### 4. Version Control

```bash
# Commit changes regularly
cd ~/.config/dotrun
git add -A
git commit -m "Add deployment scripts"
```

## Advanced Usage

### Script Arguments

Access arguments in your scripts:

```bash
#!/usr/bin/env bash
# All arguments
echo "All args: $@"

# Individual arguments
first_arg="$1"
second_arg="${2:-default}"

# Number of arguments
if [ $# -eq 0 ]; then
  echo "No arguments provided"
fi
```

### Environment Variables

DotRun provides these variables to scripts:

```bash
DR_HOME     # DotRun workspace directory
DR_BIN      # Scripts directory
DR_DOCS     # Documentation directory
DR_SCRIPT   # Current script name
DR_CATEGORY # Current script category (if any)
```

### Shared Libraries

Create reusable functions:

```bash
# In git/_lib.sh
git_current_branch() {
  git rev-parse --abbrev-ref HEAD
}

# In git/push-upstream
source "$(dirname "$0")/_lib.sh"
branch=$(git_current_branch)
git push -u origin "$branch"
```

### Collections

Share script sets with your team:

```bash
# Export a collection
dr collection export git-tools ~/git-tools.tar.gz

# Import a collection
dr collection import ~/git-tools.tar.gz

# List collections
dr collection list
```

## Next Steps

Now that you understand the basics:

1. **Develop Scripts**: Learn [Script Development](Script-Development.md) best practices
2. **Team Collaboration**: Set up [Team Workflows](Team-Workflows.md)
3. **Configure Environment**: Explore [Configuration Management](Configuration-Management.md)
4. **Manage Aliases**: Use the [Alias System](Alias-Management.md)
5. **Browse Examples**: Check [Example Scripts](Script-Examples.md)

---

[← Installation Guide](Installation-Guide.md) | [Script Development →](Script-Development.md) | [Top ↑](#user-guide)