Skip to content

User Guide

Jump to bottom
Joao Palma edited this page Jan 29, 2026 · 4 revisions

User Guide

← Installation Guide | Home | Script Development →

Table of Contents

Quick Start Tutorial

Let's create and use your first DotRun script:

1. Create a Simple Script

# 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

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

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

3. View Documentation

# View the inline documentation
dr help hello

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

Core Commands

Script Execution

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

Script Management

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

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)
# 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:

# 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

# 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:

#!/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/:

# 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

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

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

Advanced Usage

Script Arguments

Access arguments in your scripts:

#!/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:

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:

# 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:

# 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 best practices
  2. Team Collaboration: Set up Team Workflows
  3. Configure Environment: Explore Configuration Management
  4. Manage Aliases: Use the Alias System
  5. Browse Examples: Check Example Scripts

← Installation Guide | Script Development → | Top ↑

Clone this wiki locally