# Frequently Asked Questions (FAQ)

[← Back to README](../../README.md) | [Home](Home.md) | [Troubleshooting →](Troubleshooting.md)

---

## Table of Contents

- [General Questions](#general-questions)
- [Installation & Setup](#installation--setup)
- [Script Management](#script-management)
- [Aliases & Configs (v3.1.0 File-Based)](#aliases--configs-v310-file-based)
- [Collections](#collections)
- [Advanced Topics](#advanced-topics)
- [Team Collaboration](#team-collaboration)
- [Technical Questions](#technical-questions)
- [Troubleshooting](#troubleshooting)

> **📖 Looking for specific documentation?**  
> Our wiki has been reorganized for better navigation. Find what you need:  
> • **Getting Started**: [Installation](Installation-Guide.md) → [User Guide](User-Guide.md)  
> • **Advanced Features**: [Configuration](Configuration-Management.md) → [Developer Experience](Developer-Experience.md)  
> • **Team Features**: [Team Workflows](Team-Workflows.md) includes collections and sharing  
> • **All Examples**: Consolidated in [Script Examples](Script-Examples.md)

## General Questions

### What is DotRun?

DotRun is a developer productivity tool that provides a unified, Git-backed script management system. It transforms your development workflow into a collection of well-documented, reusable commands accessible from anywhere in your system with the simple `dr` command.

### Who should use DotRun?

DotRun is designed for:

- Solo developers wanting to streamline personal workflows
- Development teams needing to share and standardize common tasks
- DevOps engineers managing complex deployment and maintenance scripts
- Anyone tired of remembering long command sequences

### How is DotRun different from aliases?

While aliases are great for simple commands, DotRun provides:

- **Documentation**: Built-in help for every script
- **Organization**: Category-based structure
- **Sharing**: Easy team collaboration through collections
- **Version Control**: Git integration for history and rollback
- **Validation**: Automatic linting and error checking

### Is DotRun free?

Yes! DotRun is open-source software released under the MIT license.

## Installation & Setup

### What are the system requirements?

- **OS**: Linux, macOS, or Windows (WSL)
- **Shell**: Bash 4.0+, Zsh, or Fish
- **Git**: Version 2.0+ (required)
- **Optional**: ShellCheck for linting, glow for markdown rendering

### Can I install DotRun without root/sudo access?

Yes! DotRun installs entirely in your home directory:

- Scripts go to `~/.local/bin/`
- Workspace is in `~/.config/dotrun/`
- No system-wide changes required

### How do I uninstall DotRun?

To completely remove DotRun:

```bash
# Remove the executable
rm ~/.local/bin/dr

# Remove the workspace
rm -rf ~/.config/dotrun

# Remove shell completions (example for bash)
rm ~/.config/bash_completion.d/dr
```

### Can I change the installation directory?

Yes, use custom paths during installation:

```bash
DR_PREFIX=/custom/path ./install.sh
```

Or set the `DR_HOME` environment variable:

```bash
export DR_HOME=/custom/dotrun/home
```

### How do I upgrade from v2.x to v3.x?

**Quick Answer**: Backup your `~/.config/dotrun` directory, install v3.1.0, then migrate your aliases/configs to the new file-based format using numbered files (NN-category.aliases/config).

**Detailed Explanation**: v3.1.0 continues the file-based aliases/configs approach introduced in v3.0.0, replacing the monolithic v2.x approach. The namespace commands (-s, -a, -c, -col) and helper loading system have also changed. Back up first, then systematically migrate your content.

**Example**:

```bash
# Backup existing configuration
cp -r ~/.config/dotrun ~/.config/dotrun.v2.backup

# Install v3.1.0
curl -fsSL https://raw.githubusercontent.com/jvPalma/dotrun/master/install.sh | bash

# Create new alias files with numbering
echo "alias gs='git status'" >~/.config/dotrun/aliases/10-git.aliases
echo "export PATH=\"\$HOME/.local/bin:\$PATH\"" >~/.config/dotrun/configs/05-path.config

# Reload
dr -a reload
dr -c reload
```

**See Also**: [Installation Guide](Installation-Guide.md), [Configuration Management](Configuration-Management.md), [MIGRATION-v3.0.md](../../MIGRATION-v3.0.md)

### Installation failed with permission error

**Quick Answer**: DotRun installs to user directories by default. Ensure `~/.local/bin` and `~/.config/dotrun` are writable, or use a custom install prefix.

**Detailed Explanation**: If you encounter permission errors, verify directory ownership and try a user-local install. The installer should never require sudo for default installations.

**Example**:

```bash
# Verify permissions
ls -ld ~/.local/bin ~/.config/dotrun

# Install with custom prefix if needed
curl -fsSL https://raw.githubusercontent.com/jvPalma/dotrun/master/install.sh | bash

# Ensure PATH includes install location
echo 'export PATH="$HOME/.local/bin:$PATH"' >>~/.bashrc
source ~/.bashrc
```

**See Also**: [Installation Guide](Installation-Guide.md), [Troubleshooting](Troubleshooting.md)

### Shell integration not working after install

**Quick Answer**: Ensure `~/.drrc` is sourced in your shell config file (~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish), then restart your shell.

**Detailed Explanation**: DotRun creates `~/.drrc` during installation which loads shell-specific configurations. If aliases, configs, or completions aren't working, the shell integration wasn't loaded.

**Example**:

```bash
# For Bash - add to ~/.bashrc
[[ -f ~/.drrc ]] && source ~/.drrc

# For Zsh - add to ~/.zshrc
[[ -f ~/.drrc ]] && source ~/.drrc

# For Fish - add to ~/.config/fish/config.fish
test -f ~/.drrc && source ~/.drrc

# Restart shell
exec $SHELL -l
```

**See Also**: [Installation Guide](Installation-Guide.md), [Developer Experience](Developer-Experience.md)

### EDITOR not set error

**Quick Answer**: Set the `EDITOR` environment variable in your shell config to your preferred editor (e.g., vim, nano, code).

**Detailed Explanation**: DotRun uses `$EDITOR` when running commands like `dr set scriptname` (which creates or opens a script for editing). The installer attempts to auto-detect an editor, but you should explicitly set your preference.

**Example**:

```bash
# Add to your shell config (~/.bashrc, ~/.zshrc)
export EDITOR="vim"     # or nano, emacs, etc.
export VISUAL="$EDITOR" # Some tools use VISUAL

# For VS Code (waits for window close)
export EDITOR="code --wait"

# Reload shell
source ~/.bashrc
```

**See Also**: [User Guide](User-Guide.md), [Developer Experience](Developer-Experience.md)

### Which shells are supported exactly?

**Quick Answer**: DotRun officially supports Bash (4.0+), Zsh (5.0+), and Fish (3.0+) on Linux, macOS, and Windows (WSL).

**Detailed Explanation**: The core `dr` command works in any POSIX-compatible shell, but interactive features (tab completion, alias loading, config sourcing) are optimized for Bash, Zsh, and Fish. Each shell has dedicated completion and integration files.

**Example**:

```bash
# Check your shell version
bash --version # Should be 4.0+
zsh --version  # Should be 5.0+
fish --version # Should be 3.0+

# Shell-specific files are in:
~/.local/share/dotrun/shell/bash/
~/.local/share/dotrun/shell/zsh/
~/.local/share/dotrun/shell/fish/
```

**See Also**: [Installation Guide](Installation-Guide.md), [Developer Experience](Developer-Experience.md)

## Script Management

### How do I organize scripts into categories?

Use forward slashes to create categories:

```bash
dr set git/cleanup    # Creates in git/ category
dr set deploy/staging # Creates in deploy/ category
dr set utils/backup   # Creates in utils/ category
```

### Can I use scripts from other directories?

Yes! You can:

1. Symlink external scripts: `ln -s /path/to/script ~/.config/dotrun/bin/myscript`
2. Import collections: `dr collection import /path/to/collection.tar.gz`
3. Source external scripts in your DotRun scripts

### How do I share scripts with my team?

Use collections:

```bash
# Export scripts
dr collection export team-tools ~/team-tools.tar.gz

# Team members import
dr collection import ~/team-tools.tar.gz
```

Or use Git:

```bash
cd ~/.config/dotrun
git remote add team https://github.com/team/dotrun-scripts
git pull team main
```

### Can scripts call other DotRun scripts?

Yes! Scripts can call each other:

```bash
#!/usr/bin/env bash
# In deploy/production

# First run staging tests
dr test/staging || exit 1

# Then deploy
echo "Deploying to production..."
```

### How do I create my first script?

**Quick Answer**: Create an executable `.sh` file in `~/.config/dotrun/scripts/` with a `### DOC` comment, then run it with `dr scriptname`.

**Detailed Explanation**: DotRun indexes all executable scripts in the scripts directory. The filename (without .sh) becomes the command name. Use `### DOC` markers to add inline documentation.

**Example**:

```bash
# Create script
cat >~/.config/dotrun/scripts/hello.sh <<'EOF'
#!/usr/bin/env bash
### DOC
# hello - Print a greeting message
### DOC
set -euo pipefail

echo "Hello from DotRun v3.0!"
EOF

# Make executable
chmod +x ~/.config/dotrun/scripts/hello.sh

# Run it
dr hello

# View help
dr help hello
```

**See Also**: [User Guide](User-Guide.md), [Script Examples](Script-Examples.md)

### How do I document scripts with DOC tokens?

**Quick Answer**: Add `### DOC` markers around documentation text at the top of your script. Everything between the tokens appears in `dr help scriptname`.

**Detailed Explanation**: The DOC token system provides inline, searchable documentation. Include usage, arguments, examples, and dependencies between the markers.

**Example**:

```bash
#!/usr/bin/env bash
### DOC
# deploy/staging - Deploy application to staging environment
#
# Usage: dr deploy/staging [--skip-tests]
#
# Options:
#   --skip-tests    Skip running tests before deploy
#
# Dependencies:
#   - kubectl
#   - helm
### DOC
set -euo pipefail

# Script implementation...
```

**See Also**: [Script Examples](Script-Examples.md), [Developer Experience](Developer-Experience.md)

### Script not found but I just created it

**Quick Answer**: Ensure the script is executable (`chmod +x`), has a `.sh` extension, and is in `~/.config/dotrun/scripts/` or a subdirectory.

**Detailed Explanation**: DotRun searches for executable files with `.sh` extension. Hidden files (starting with `.`) are ignored. Broken symlinks will also cause issues.

**Example**:

```bash
# Check script location and permissions
ls -lh ~/.config/dotrun/scripts/myscript.sh

# Make executable if needed
chmod +x ~/.config/dotrun/scripts/myscript.sh

# Verify it appears in listing
dr -l | grep myscript

# Test execution
dr myscript
```

**See Also**: [User Guide](User-Guide.md), [Troubleshooting](Troubleshooting.md)

### Helper loading fails

**Quick Answer**: Verify the helper file exists in `~/.config/dotrun/helpers/` or a collection's helpers directory, and use correct syntax in `loadHelpers`.

**Detailed Explanation**: v3.1.0 uses the `loadHelpers` function to source helper modules. Helpers are searched across multiple locations with a specificity hierarchy: local → project → collection → global.

**Example**:

```bash
# In your script
[[ -n "${DR_LOAD_HELPERS:-}" ]] && source "$DR_LOAD_HELPERS"

# Load helpers (pattern-based, no .sh extension)
loadHelpers gcp/workstation
loadHelpers dotrun-anc/utils/common
loadHelpers workstation # Less specific

# List available helpers
ls ~/.config/dotrun/helpers/

# Test with verbose mode
DR_HELPERS_VERBOSE=1 dr myscript
```

**See Also**: [Developer Experience](Developer-Experience.md), [Script Examples](Script-Examples.md)

### How do I pass arguments to scripts?

**Quick Answer**: Pass arguments after the script name: `dr scriptname arg1 arg2`. Access them in your script using `$1`, `$2`, or `"$@"`.

**Detailed Explanation**: DotRun passes all arguments after the script name directly to your script. Use standard bash argument parsing techniques for flags and options.

**Example**:

```bash
# Call with arguments
dr deploy/staging --env prod --skip-tests

# In the script (deploy/staging.sh)
#!/usr/bin/env bash
set -euo pipefail

ENV="staging"
SKIP_TESTS=false

while [[ $# -gt 0 ]]; do
  case "$1" in
    --env)
      ENV="$2"
      shift 2
      ;;
    --skip-tests)
      SKIP_TESTS=true
      shift
      ;;
    *)
      echo "Unknown option: $1"
      exit 1
      ;;
  esac
done

echo "Deploying to $ENV (skip tests: $SKIP_TESTS)"
```

**See Also**: [Script Examples](Script-Examples.md), [User Guide](User-Guide.md)

### What is the script skeleton template?

**Quick Answer**: The skeleton is a standard template with shebang, DOC markers, strict mode, and main function structure that ensures consistency.

**Detailed Explanation**: Using a consistent skeleton improves readability, error handling, and maintainability across all your scripts.

**Example**:

```bash
#!/usr/bin/env bash
### DOC
# scriptname - Brief description of what this script does
### DOC
set -euo pipefail

# Load helpers if needed
[[ -n "${DR_LOAD_HELPERS:-}" ]] && source "$DR_LOAD_HELPERS"
# loadHelpers pattern1 pattern2

main() {
  echo "Script logic here..."
  echo "Arguments: $*"
}

main "$@"
```

**See Also**: [Script Examples](Script-Examples.md), [Developer Experience](Developer-Experience.md)

## Aliases & Configs (v3.1.0 File-Based)

### What's the difference between scripts and aliases?

**Quick Answer**: Scripts are executable files (`~/.config/dotrun/scripts/*.sh`) run via `dr scriptname`. Aliases are shell shortcuts defined in `.aliases` files and loaded into your interactive shell.

**Detailed Explanation**: Use scripts for portable, complex logic with documentation. Use aliases for quick shell-level shortcuts and command abbreviations that work in your terminal.

**Example**:

```bash
# Script (portable, documented, complex logic)
~/.config/dotrun/scripts/deploy/production.sh

# Alias (shell shortcut, simple)
# In ~/.config/dotrun/aliases/10-git.aliases:
alias gs='git status'
alias gp='git pull --rebase'
alias gc='git commit -v'
```

**See Also**: [Configuration Management](Configuration-Management.md), [User Guide](User-Guide.md)

### How do aliases differ in v3.0 vs v2.x?

**Quick Answer**: v3.0 uses multiple ordered files named `NN-category.aliases` instead of a single monolithic aliases file, enabling modular organization and deterministic load order.

**Detailed Explanation**: The file-based approach eliminates merge conflicts, allows team collaboration, and makes it clear what loads when. Each file is independent but numerically ordered.

**Example**:

```bash
# v2.x (old) - single file
~/.config/dotrun/aliases.sh # All aliases in one file

# v3.0 (new) - multiple ordered files
~/.config/dotrun/aliases/
├── 00-core.aliases   # Load first
├── 10-git.aliases    # Then git aliases
├── 20-docker.aliases # Then docker aliases
└── 30-custom.aliases # Then custom aliases
```

**See Also**: [Configuration Management](Configuration-Management.md), [MIGRATION-v3.0.md](../../MIGRATION-v3.0.md)

### What is the NN-category naming convention?

**Quick Answer**: Files are prefixed with 2+ digit numbers (NN) for load order, followed by a dash and descriptive category name, ending with `.aliases` or `.config` extension.

**Detailed Explanation**: The numeric prefix controls when files load (lower numbers load first). The category name is for human readability and organization. This system ensures predictable, conflict-free loading.

**Example**:

```bash
# Valid naming:
00-env.config        # Environment variables (loads first)
05-path.config       # PATH configuration
10-dev.aliases       # Development aliases
20-cloud.aliases     # Cloud tool aliases
100-personal.aliases # Personal overrides (loads last)

# Invalid naming:
env.config     # Missing number prefix
10_dev.aliases # Wrong separator (use dash, not underscore)
10-dev.alias   # Wrong extension (use .aliases plural)
```

**See Also**: [Configuration Management](Configuration-Management.md)

### How do I control load order with numbering?

**Quick Answer**: Lower-numbered files load first. Use ranges to organize: 00-09 for core, 10-29 for tools, 30-49 for services, 50+ for overrides.

**Detailed Explanation**: Reserving numeric ranges makes it easy to insert new files in the right order. Later files can override earlier definitions.

**Example**:

```bash
# Organize by numeric ranges
00-core.config      # Core exports (DR_CONFIG, etc.)
05-path.config      # PATH setup
10-node.config      # Node/npm configuration
11-node.aliases     # Node aliases (depends on 10-node.config)
20-git.aliases      # Git shortcuts
30-docker.aliases   # Docker shortcuts
90-personal.aliases # Personal overrides (loads last)

# Later files override earlier ones:
# 20-git.aliases defines: alias gc='git commit'
# 90-personal.aliases can override: alias gc='git commit -v'
```

**See Also**: [Configuration Management](Configuration-Management.md)

### Why aren't my configs loading?

**Quick Answer**: Verify files end with `.config`, are in `~/.config/dotrun/configs/`, use valid bash syntax, and reload with `dr -c reload`.

**Detailed Explanation**: Common issues include wrong extension, syntax errors, wrong directory, or needing to reload after creation.

**Example**:

```bash
# Check file location and naming
ls -lh ~/.config/dotrun/configs/

# Should show files like:
# 05-path.config
# 10-env.config

# Test for syntax errors
bash -n ~/.config/dotrun/configs/10-env.config

# Reload configs
dr -c reload

# Verify loaded
dr -c list
```

**See Also**: [Configuration Management](Configuration-Management.md), [Troubleshooting](Troubleshooting.md)

### How do I reload aliases without restarting shell?

**Quick Answer**: Run `dr -a reload` (or `dr aliases reload`) to re-source all alias files in order.

**Detailed Explanation**: v3.0 provides a reload command that clears and reloads all aliases from `.aliases` files, applying changes immediately without restarting your shell.

**Example**:

```bash
# Edit alias file
echo "alias k='kubectl'" >>~/.config/dotrun/aliases/20-kubernetes.aliases

# Reload to apply changes
dr -a reload

# Verify it works
k version # Should run kubectl version
```

**See Also**: [User Guide](User-Guide.md), [Configuration Management](Configuration-Management.md)

### Where should I put PATH configuration?

**Quick Answer**: In an early-numbered `.config` file (e.g., `05-path.config`) so later configs and aliases can rely on it being set.

**Detailed Explanation**: PATH should load before tool-specific configurations. Keep it separate from other exports for clarity. Avoid duplicate entries.

**Example**:

```bash
# Create 05-path.config
cat >~/.config/dotrun/configs/05-path.config <<'EOF'
# Add local binaries
export PATH="$HOME/.local/bin:$PATH"

# Add DotRun scripts
export PATH="$HOME/.config/dotrun/scripts:$PATH"

# Add language tools
export PATH="$HOME/.npm/bin:$PATH"
export PATH="$HOME/.cargo/bin:$PATH"
EOF

# Reload
dr -c reload

# Verify
echo $PATH
```

**See Also**: [Configuration Management](Configuration-Management.md)

### Can I have multiple alias files?

**Quick Answer**: Yes! Create as many `NN-category.aliases` files as needed. They all load in numeric order.

**Detailed Explanation**: Multiple files enable modular organization by domain (git, docker, kubernetes) or team (personal, team-shared). Each file is independent.

**Example**:

```bash
# Organize by tool/domain
~/.config/dotrun/aliases/
├── 10-git.aliases            # Git shortcuts
├── 15-git-flow.aliases       # Git flow extensions
├── 20-docker.aliases         # Docker commands
├── 25-docker-compose.aliases # Docker Compose shortcuts
└── 30-kubernetes.aliases     # kubectl aliases

# All load in order (10, 15, 20, 25, 30...)
dr -a reload
dr -a list # Shows all loaded aliases
```

**See Also**: [Configuration Management](Configuration-Management.md)

### What file extension for alias files vs config files?

**Quick Answer**: Use `.aliases` for alias definitions and `.config` for environment variables and configuration exports.

**Detailed Explanation**: Both are sourced as bash scripts, but the naming convention clarifies intent. `.aliases` should only contain alias commands; `.config` should only contain export statements and configuration.

**Example**:

```bash
# Good: 10-git.aliases
alias gs='git status'
alias gp='git pull --rebase'

# Good: 05-env.config
export EDITOR="vim"
export VISUAL="$EDITOR"
export DOTRUN_THEME="dark"

# Bad: mixing in same file
# Don't mix aliases and exports in one file
```

**See Also**: [Configuration Management](Configuration-Management.md)

## Collections

### What are collections and do I need them?

**Quick Answer**: Collections are git repositories containing shareable scripts, helpers, aliases, and configs. They're optional but recommended for teams standardizing workflows.

**Detailed Explanation**: Collections enable version-controlled sharing, dependency management, and conflict resolution. Solo developers can use them for organizing personal toolkits; teams use them for standardization.

**Example**:

```bash
# Install a collection
dr -col add https://github.com/org/devtools.git

# Interactive browser shows available resources
# Select what to import

# Later, update to new version
dr -col update devtools
```

**See Also**: [Team Workflows](Team-Workflows.md), [User Guide](User-Guide.md)

### How do I install a private collection?

**Quick Answer**: Use SSH URLs with configured SSH keys, or HTTPS URLs with credentials. Ensure your git authentication is working first.

**Detailed Explanation**: Private collections require git authentication. SSH is recommended for private repositories. Test access with `ssh -T git@github.com` before installing.

**Example**:

```bash
# Test SSH access first
ssh -T git@github.com
# Should see: "Hi username! You've successfully authenticated..."

# Install private collection via SSH
dr -col add git@github.com:myorg/private-tools.git

# Alternative: HTTPS with token (not recommended)
# dr -col add https://token@github.com/myorg/private-tools.git
```

**See Also**: [Team Workflows](Team-Workflows.md), [Troubleshooting](Troubleshooting.md)

### What happens when I update a collection?

**Quick Answer**: DotRun fetches the latest version, compares SHA256 hashes to detect modified files, then prompts interactively for conflicts: keep local, take remote, or view diff.

**Detailed Explanation**: v3.0 tracks file modifications using SHA256 hashing. Unmodified files update silently; modified files trigger interactive conflict resolution with options to keep, overwrite, backup, or diff.

**Example**:

```bash
# Update a collection
dr -col update devtools

# Example interaction:
# → Fetching updates for devtools...
# → scripts/deploy.sh: MODIFIED (local changes detected)
#   [K]eep local  [O]verwrite  [D]iff  [B]ackup then overwrite  [S]kip
# ? K
# → Keeping local version of scripts/deploy.sh
# → scripts/test.sh: Updating (no local changes)
# → Update complete
```

**See Also**: [Team Workflows](Team-Workflows.md), [Developer Experience](Developer-Experience.md)

### Can I modify imported collection scripts?

**Quick Answer**: Yes, but modifications are tracked via SHA256 hashes. Updates will detect the drift and prompt you to keep or overwrite.

**Detailed Explanation**: It's better to copy collection scripts to your local workspace with a different name/namespace for persistent customization, or contribute changes upstream.

**Example**:

```bash
# Option 1: Copy to local namespace (recommended)
cp ~/.config/dotrun/helpers/01-devtools/gcp/deploy.sh \
  ~/.config/dotrun/scripts/my-deploy.sh

# Customize my-deploy.sh
# Original remains unchanged for updates

# Option 2: Modify in place (will trigger conflict on update)
vim ~/.config/dotrun/helpers/01-devtools/gcp/deploy.sh
# Next update will detect SHA256 mismatch and prompt
```

**See Also**: [Team Workflows](Team-Workflows.md), [User Guide](User-Guide.md)

### Collection sync failing with git errors

**Quick Answer**: Verify internet connection, git credentials, and repository URL. Try `dr -col sync` to check all collections.

**Detailed Explanation**: Common issues include authentication failures (SSH keys, tokens), network problems, or repository access. Git operations have 30-second timeouts.

**Example**:

```bash
# Check sync status for all collections
dr -col sync

# Test git access
ssh -T git@github.com                               # For SSH URLs
git ls-remote https://github.com/org/collection.git # For HTTPS

# View collection details
dr -col list

# Re-clone if corrupt
dr -col remove devtools
dr -col add https://github.com/org/devtools.git
```

**See Also**: [Team Workflows](Team-Workflows.md), [Troubleshooting](Troubleshooting.md)

### What is SHA256 hash tracking?

**Quick Answer**: DotRun stores SHA256 hashes of imported collection files in `~/.config/dotrun/.dr-hashes/` and compares them during updates to detect local modifications.

**Detailed Explanation**: Hash tracking enables precise drift detection beyond timestamps. When you import a file, its hash is stored. During updates, the current hash is compared against the stored hash to determine if you've made local changes.

**Example**:

```bash
# Hashes stored here:
ls ~/.config/dotrun/.dr-hashes/
# deploy.sh.sha256
# test.sh.sha256

# View a hash
cat ~/.config/dotrun/.dr-hashes/deploy.sh.sha256
# e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

# During update:
# 1. Calculate current file hash
# 2. Compare to stored hash
# 3. If different → "locally modified" (prompt user)
# 4. If same → "unmodified" (safe to update)
```

**See Also**: [Developer Experience](Developer-Experience.md), [Team Workflows](Team-Workflows.md)

### Old collection format vs new (dotrun.collection.yml)

**Quick Answer**: v3.0 standardizes on `dotrun.collection.yml` metadata file. The old v2.x format is no longer supported.

**Detailed Explanation**: The new metadata format includes versioning, dependency tracking, and compatibility requirements. Old collections need migration to work with v3.0.

**Example**:

```yaml
# New format: dotrun.collection.yml
name: devtools
version: 1.2.0
description: Development team shared tools
author: Engineering Team
repository: https://github.com/org/devtools.git
license: MIT

# Optional fields:
homepage: https://docs.example.com
dependencies: []
```

**See Also**: [Team Workflows](Team-Workflows.md), [User Guide](User-Guide.md)

### How do I create my own collection?

**Quick Answer**: Create a git repository with `dotrun.collection.yml` metadata, organize scripts/helpers/aliases/configs in subdirectories, tag a version, and share the URL.

**Detailed Explanation**: Collections are standard git repositories with specific structure. Include metadata, organize resources, tag releases with semantic versions (v1.0.0), and share via git URL.

**Example**:

```bash
# Create collection repository
mkdir my-devtools && cd my-devtools
git init

# Create metadata
cat >dotrun.collection.yml <<'EOF'
name: my-devtools
version: 1.0.0
description: Personal development tools
author: Your Name
repository: https://github.com/yourusername/my-devtools.git
EOF

# Organize resources
mkdir -p scripts helpers aliases configs
echo '#!/usr/bin/env bash' >scripts/example.sh
chmod +x scripts/example.sh

# Commit and tag
git add .
git commit -m "Initial collection"
git tag v1.0.0

# Push to GitHub
git remote add origin git@github.com:yourusername/my-devtools.git
git push origin master --tags

# Install your collection
dr -col add git@github.com:yourusername/my-devtools.git
```

**See Also**: [Team Workflows](Team-Workflows.md), [Developer Experience](Developer-Experience.md)

### How do collection version tags work?

**Quick Answer**: Collections use git tags with semantic versioning (vX.Y.Z). The metadata `version` field must match the git tag.

**Detailed Explanation**: Tags enable version pinning and reproducible installations. The `v` prefix in git tags is optional but the metadata version should be numeric only (1.2.3).

**Example**:

```bash
# In dotrun.collection.yml:
version: 1.2.3

# Git tag must match:
git tag v1.2.3 # or git tag 1.2.3

# Install specific version
dr -col add https://github.com/org/tools.git@v1.2.0

# Update checks for newer tags
dr -col sync
# → devtools: v1.2.0 → v1.3.0 available

dr -col update devtools
```

**See Also**: [Team Workflows](Team-Workflows.md)

## Advanced Topics

### How do I use helpers in my scripts?

**Quick Answer**: Source the `loadHelpers` function, then call it with helper names. Helpers are sourced from local, project, collection, or global locations.

**Detailed Explanation**: The helper system in v3.0 uses pattern-based loading with 5 specificity levels. Load helpers early in your script before using their functions.

**Example**:

```bash
#!/usr/bin/env bash
set -euo pipefail

# Load the loadHelpers function
[[ -n "${DR_LOAD_HELPERS:-}" ]] && source "$DR_LOAD_HELPERS"

# Load specific helpers
loadHelpers gcp/workstation
loadHelpers utils/common

# Use helper functions
echo "Current project: $(gcp_current_project)"
log_info "Deployment starting..."
```

**See Also**: [Developer Experience](Developer-Experience.md), [Script Examples](Script-Examples.md)

### What is loadHelpers and how does it work?

**Quick Answer**: `loadHelpers` is a function that searches for and sources helper modules using flexible pattern matching across multiple locations.

**Detailed Explanation**: It supports 5 specificity levels from absolute paths to filename-only matching, searches across collections with namespace normalization, includes de-duplication, circular dependency detection, and security validation.

**Example**:

```bash
# Different specificity levels (all work):
loadHelpers /full/path/to/helper.sh                  # Level 1: Absolute
loadHelpers helpers/01-dotrun-anc/gcp/workstation.sh # Level 2: Exact path
loadHelpers 01-dotrun-anc/gcp/workstation            # Level 3: With extension
loadHelpers dotrun-anc/gcp/workstation               # Level 4: Collection normalized
loadHelpers gcp/workstation                          # Level 4: Path search
loadHelpers workstation                              # Level 5: Filename only

# Load all helpers from a collection
loadHelpers @dotrun-anc

# Preview matches without loading
loadHelpers gcp/workstation --list
```

**See Also**: [Developer Experience](Developer-Experience.md), [CLAUDE.md](../../CLAUDE.md)

### What are the loadHelpers specificity levels?

**Quick Answer**: 5 levels from most to least specific: (1) Absolute path, (2) Exact relative path, (3) Path with auto-.sh, (4) Collection search, (5) Filename only.

**Detailed Explanation**: More specific patterns guarantee unique matches. Less specific patterns may load multiple helpers. Use collection names when possible to avoid ambiguity.

**Example**:

```bash
# Most specific (guaranteed unique)
loadHelpers dotrun-anc/gcp/workstation

# Less specific (may match multiple)
loadHelpers gcp/workstation # Could match in multiple collections

# Least specific (likely multiple matches)
loadHelpers workstation # Might load workstation.sh from all collections

# Best practice: Include collection or full path
loadHelpers dotrun-anc/gcp/workstation # Clear and specific
```

**See Also**: [Developer Experience](Developer-Experience.md)

### How does the namespace system work (-s, -a, -c, -col)?

**Quick Answer**: v3.0 uses namespace flags for management commands: `-s/scripts`, `-a/aliases`, `-c/config`, `-col/collections`. Both flag and subcommand styles work identically.

**Detailed Explanation**: The namespace system organizes commands by domain. You can use short flags (`-s`) or full subcommands (`scripts`) interchangeably.

**Example**:

```bash
# Scripts namespace
dr -s list           # or: dr scripts list
dr -s set scriptname # or: dr scripts set scriptname

# Aliases namespace
dr -a reload # or: dr aliases reload
dr -a list   # or: dr aliases list

# Config namespace
dr -c set KEY value # or: dr config set KEY value
dr -c list          # or: dr config list

# Collections namespace
dr -col sync        # or: dr collections sync
dr -col update name # or: dr collections update name
```

**See Also**: [User Guide](User-Guide.md), [Developer Experience](Developer-Experience.md)

### What are the Zsh completion colors?

**Quick Answer**: Zsh completion uses color coding: green for special commands, yellow for folders, cyan for scripts, purple for alias commands, red for config commands.

**Detailed Explanation**: The color scheme provides visual cues for different command types. Folders show with trailing `/`, scripts appear without `.sh` extension.

**Example**:

```bash
# dr <tab> shows:
# - Special commands (green): help, -l, -L
# - Folders (yellow): git/, docker/, deploy/
# - Scripts (cyan): build, test, deploy
# - Hint (dark gray): (hint: -s/scripts, -a/aliases, -c/config, -col/collections)

# dr -s <tab> shows:
# - Script management (green): add, edit, move, rename, help, list

# dr -a <tab> shows:
# - Alias management (purple): init, add, list, edit, remove, reload

# dr -c <tab> shows:
# - Config management (red): init, set, get, list, edit, unset, reload
```

**See Also**: [Developer Experience](Developer-Experience.md)

### Performance issues with large script libraries

**Quick Answer**: Optimize by using lazy helper loading, organizing scripts in folders, and avoiding heavy operations in config files.

**Detailed Explanation**: Load only needed helpers, keep PATH clean, use numeric ordering to control heavy configs, and minimize shell startup overhead.

**Example**:

```bash
# Good: Load only what you need
loadHelpers gcp/workstation # Just this one

# Bad: Load everything
loadHelpers @dotrun-anc # All helpers from collection

# Optimize PATH (05-path.config)
# Remove duplicates and order by frequency of use
export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"

# Avoid heavy operations in early configs
# Move them to higher-numbered files or scripts
```

**See Also**: [Developer Experience](Developer-Experience.md), [Configuration Management](Configuration-Management.md)

## Team Collaboration

### How do we handle script conflicts?

When importing collections with conflicts:

```bash
# Skip existing scripts
dr collection import tools.tar.gz --skip-existing

# Use prefix to avoid conflicts
dr collection import tools.tar.gz --prefix team-

# Force overwrite (careful!)
dr collection import tools.tar.gz --force
```

### Can we have private and shared scripts?

Yes! Organize scripts by visibility:

```bash
~/.config/dotrun/bin/
├── personal/ # Git-ignored personal scripts
├── team/     # Shared team scripts
└── public/   # Open source scripts
```

Add to `.gitignore`:

```
bin/personal/
```

### How do we version control scripts?

DotRun workspace is a Git repository:

```bash
cd ~/.config/dotrun
git add .
git commit -m "Add deployment scripts"
git tag v1.0.0
git push origin main
```

### Can different team members have different versions?

Yes! Use Git branches:

```bash
# Stable version
git checkout main

# Development version
git checkout develop

# Personal modifications
git checkout -b personal/customizations
```

## Technical Questions

### What shell does DotRun use?

DotRun respects the shebang in your scripts:

- `#!/usr/bin/env bash` - Uses bash
- `#!/usr/bin/env python3` - Uses Python
- `#!/usr/bin/env node` - Uses Node.js

Default is bash if no shebang is specified.

### Can I write scripts in languages other than bash?

Yes! DotRun supports any executable script:

```python
#!/usr/bin/env python3
### DOC
# Python script example
### DOC

print("Hello from Python!")
```

```javascript
#!/usr/bin/env node
### DOC
# Node.js script example
### DOC

console.log("Hello from Node.js!");
```

### How does script discovery work?

DotRun searches for executable files in:

1. `~/.config/dotrun/bin/` (root level)
2. `~/.config/dotrun/bin/*/` (category directories)
3. Follows symlinks to external scripts

### Can I debug DotRun scripts?

Yes! Use standard debugging techniques:

```bash
# Enable debug mode
set -x # In your script

# Or run with bash debug
bash -x ~/.config/dotrun/bin/myscript

# Or add debug flag
if [[ "${DEBUG:-}" == "true" ]]; then
  set -x
fi
```

### How do I handle script dependencies?

Document and check dependencies:

```bash
#!/usr/bin/env bash
### DOC
# Dependencies:
#   - jq: JSON processing
#   - curl: HTTP requests
### DOC

# Check dependencies
for cmd in jq curl; do
  if ! command -v "$cmd" &>/dev/null; then
    echo "Error: $cmd is required but not installed"
    exit 1
  fi
done
```

## Troubleshooting

### Why is tab completion not working?

**Quick Answer**: Ensure `~/.drrc` is sourced in your shell RC file, then restart your shell or run `dr completion install`.

**Detailed Explanation**: v3.0 tab completion is loaded via the `~/.drrc` shell integration file. If completions aren't working, verify the file is sourced and the shell-specific completion files exist.

**Example**:

```bash
# For Bash - check ~/.bashrc contains:
[[ -f ~/.drrc ]] && source ~/.drrc

# For Zsh - check ~/.zshrc contains:
[[ -f ~/.drrc ]] && source ~/.drrc

# Reinstall completions if needed
dr completion install

# Reload shell
exec $SHELL -l

# Test completion
dr <TAB>
```

**See Also**: [Installation Guide](Installation-Guide.md), [Developer Experience](Developer-Experience.md)

### Scripts aren't appearing in `dr -l`

**Quick Answer**: Ensure scripts have `.sh` extension, are executable (`chmod +x`), and are in `~/.config/dotrun/scripts/` or subdirectories.

**Detailed Explanation**: DotRun only lists executable `.sh` files. Hidden files (starting with `.`) and broken symlinks are ignored.

**Example**:

```bash
# Check script location
ls -lh ~/.config/dotrun/scripts/

# Make executable
chmod +x ~/.config/dotrun/scripts/myscript.sh

# Verify extension
mv ~/.config/dotrun/scripts/myscript ~/.config/dotrun/scripts/myscript.sh

# List scripts
dr -l
dr -L # Long format with paths
```

**See Also**: [User Guide](User-Guide.md), [Troubleshooting](Troubleshooting.md)

### How do I fix "command not found: dr"?

**Quick Answer**: Add `~/.local/bin` to your PATH in your shell config, then reload.

**Detailed Explanation**: The `dr` command is installed to `~/.local/bin` by default. Your shell needs this directory in its PATH.

**Example**:

```bash
# Add to ~/.bashrc or ~/.zshrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >>~/.bashrc

# Reload shell
source ~/.bashrc

# Verify installation
which dr
dr --help
```

**See Also**: [Installation Guide](Installation-Guide.md)

### Aliases shadow system commands unexpectedly

**Quick Answer**: Lower the alias file's numeric prefix, remove the conflicting alias, or use `command cmd` to bypass the alias temporarily.

**Detailed Explanation**: Later-loaded aliases override earlier ones. Use `dr -a list` to find which file defines the alias, then adjust the load order or remove it.

**Example**:

```bash
# Find the conflicting alias
dr -a list | grep 'alias ls'

# Option 1: Bypass temporarily
command ls # Runs system ls, not alias

# Option 2: Lower the file's load order
mv ~/.config/dotrun/aliases/20-utils.aliases \
  ~/.config/dotrun/aliases/50-utils.aliases

# Option 3: Remove the alias
# Edit file and remove the alias line

# Reload
dr -a reload
```

**See Also**: [Configuration Management](Configuration-Management.md)

### Collection update keeps resetting my local edits

**Quick Answer**: Use "Keep local" during updates, or copy the script to your local workspace under a different namespace to persist customizations.

**Detailed Explanation**: Collection updates detect modifications via SHA256 hashing. Persistent local changes are better managed by copying to `~/.config/dotrun/scripts/` with your own namespace.

**Example**:

```bash
# Option 1: Keep local during updates
dr -col update devtools
# When prompted for modified file, choose [K]eep local

# Option 2: Copy to local workspace (recommended)
cp ~/.config/dotrun/helpers/01-devtools/gcp/deploy.sh \
  ~/.config/dotrun/scripts/my-deploy.sh

# Customize my-deploy.sh without affecting collection updates
vim ~/.config/dotrun/scripts/my-deploy.sh

# Run your customized version
dr my-deploy
```

**See Also**: [Team Workflows](Team-Workflows.md), [Collections](#collections)

### My PATH is duplicated and long after migration

**Quick Answer**: Consolidate PATH exports into a single early-numbered `.config` file and use a helper function to prevent duplicates.

**Detailed Explanation**: Multiple alias/config files can each append to PATH, creating duplicates. Use a `path_add` helper to check before adding.

**Example**:

```bash
# Create 05-path.config with deduplication
cat >~/.config/dotrun/configs/05-path.config <<'EOF'
# Helper to add to PATH only if not already present
path_add() {
  case ":$PATH:" in
    *":$1:"*) ;;  # Already in PATH
    *) PATH="$1:$PATH" ;;
  esac
}

# Add paths (no duplicates)
path_add "$HOME/.local/bin"
path_add "$HOME/.config/dotrun/scripts"
path_add "$HOME/.cargo/bin"

export PATH
EOF

# Reload and verify
dr -c reload
echo $PATH | tr ':' '\n' # Check for duplicates
```

**See Also**: [Configuration Management](Configuration-Management.md)

### loadHelpers says "helper not found"

**Quick Answer**: Verify helper name case, check it exists with `ls ~/.config/dotrun/helpers/`, and ensure you're not including the `.sh` extension in the pattern.

**Detailed Explanation**: Helper names are case-sensitive. Use verbose mode to see search process and ensure helpers exist in the expected location.

**Example**:

```bash
# Check available helpers
ls -R ~/.config/dotrun/helpers/

# Use verbose mode to debug
DR_HELPERS_VERBOSE=1 loadHelpers gcp/workstation

# Common mistakes:
loadHelpers gcp/workstation.sh # Wrong: don't include .sh
loadHelpers gcp/Workstation    # Wrong: case-sensitive

# Correct:
loadHelpers gcp/workstation
```

**See Also**: [Developer Experience](Developer-Experience.md), [Advanced Topics](#advanced-topics)

### Tab completion shows stale commands after deleting a script

**Quick Answer**: DotRun caches completions. Restart your shell after deleting scripts.

**Detailed Explanation**: Shell completions are loaded at startup. After removing scripts, restart your shell to refresh the completion cache.

**Example**:

```bash
# Delete script
rm ~/.config/dotrun/scripts/old-script.sh

# Restart shell to refresh completions
exec $SHELL -l

# Or reload completions manually (zsh)
compinit

# Verify
dr <TAB>  # old-script should not appear
```

**See Also**: [Developer Experience](Developer-Experience.md)

### Can I use DotRun in CI/CD pipelines?

**Quick Answer**: Yes! Install DotRun in your CI job, add `~/.local/bin` to PATH, install collections, and run scripts.

**Detailed Explanation**: For CI/CD, disable interactive features, pin collection versions, and cache the DotRun installation for faster builds.

**Example**:

```yaml
# GitHub Actions example
steps:
  - name: Install DotRun
    run: |
      curl -fsSL https://raw.githubusercontent.com/jvPalma/dotrun/master/install.sh | bash
      echo "$HOME/.local/bin" >> $GITHUB_PATH

  - name: Install collections
    run: |
      dr -col add https://github.com/org/devtools.git@v1.2.3

  - name: Run deployment
    run: dr deploy/production --ci
```

**GitLab CI Example**:

```yaml
deploy:
  before_script:
    - curl -fsSL https://raw.githubusercontent.com/jvPalma/dotrun/master/install.sh | bash
    - export PATH="$HOME/.local/bin:$PATH"
    - dr -col add git@github.com:org/devtools.git@v1.2.3
  script:
    - dr deploy/production --ci
```

**See Also**: [Team Workflows](Team-Workflows.md), [Installation Guide](Installation-Guide.md)

### How do I report bugs or request features?

**Quick Answer**: Use GitHub Issues for bugs, GitHub Discussions for features, and see CONTRIBUTING.md to contribute code.

**Detailed Explanation**: Provide version info (`dr --version`), steps to reproduce, and expected vs actual behavior for bugs. For features, describe the use case and benefit.

**Example**:

```bash
# Check version first
dr --version

# Report bug:
# https://github.com/jvPalma/dotrun/issues

# Request feature:
# https://github.com/jvPalma/dotrun/discussions

# Contribute:
# See CONTRIBUTING.md in repository
```

**See Also**: [Contributing Guide](../../CONTRIBUTING.md)

---

**Still have questions?** Check the [Troubleshooting Guide](Troubleshooting.md) or open an issue on [GitHub](https://github.com/jvPalma/dotrun/issues).

[← Back to README](../../README.md) | [Home](Home.md) | [Troubleshooting →](Troubleshooting.md) | [Top ↑](#frequently-asked-questions-faq)