Skip to content

FAQ

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

Frequently Asked Questions (FAQ)

← Back to README | Home | Troubleshooting →

Table of Contents

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

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:

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

DR_PREFIX=/custom/path ./install.sh

Or set the DR_HOME environment variable:

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:

# 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, Configuration Management, 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:

# 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, Troubleshooting

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:

# 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, Developer Experience

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:

# 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, Developer Experience

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:

# 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, Developer Experience

Script Management

How do I organize scripts into categories?

Use forward slashes to create categories:

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:

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

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

Or use Git:

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:

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

# 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, Script Examples

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:

#!/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, Developer Experience

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:

# 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, Troubleshooting

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:

# 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, Script Examples

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:

# 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, User Guide

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:

#!/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, Developer Experience

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:

# 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, User Guide

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:

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

# 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

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:

# 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

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:

# 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, Troubleshooting

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:

# 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, Configuration Management

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:

# 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

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:

# 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

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:

# 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

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:

# 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, User Guide

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:

# 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, Troubleshooting

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:

# 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, Developer Experience

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:

# 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, User Guide

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:

# 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, Troubleshooting

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:

# 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, Team Workflows

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:

# 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, User Guide

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:

# 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, Developer Experience

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:

# 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

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:

#!/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, Script Examples

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:

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

# 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

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:

# 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, Developer Experience

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:

# 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

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:

# 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, Configuration Management

Team Collaboration

How do we handle script conflicts?

When importing collections with conflicts:

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

~/.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:

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:

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

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

print("Hello from Python!")
#!/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:

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

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

# 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, Developer Experience

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:

# 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, Troubleshooting

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:

# 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

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:

# 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

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:

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

# 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

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:

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

# 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

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:

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

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, Installation Guide

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:

# 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

Still have questions? Check the Troubleshooting Guide or open an issue on GitHub.

← Back to README | Home | Troubleshooting → | Top ↑

Clone this wiki locally