Dotfile Manager Integration

DotRun is designed to complement your existing dotfile management workflow, not replace it. This guide shows how to integrate DotRun with popular dotfile managers while maintaining clean separation between personal configurations and executable scripts.

Philosophy and Approach

Separation of Concerns

DotRun follows a clear separation principle:

• Dotfile Managers: Handle configuration files (.bashrc, .vimrc, .gitconfig, etc.)
• DotRun: Manages executable scripts and team collaboration tools

This separation provides several benefits:

• Clean Organization: Scripts and configs don't mix
• Team Collaboration: Share scripts without exposing personal settings
• Privacy: Keep personal configurations private while sharing useful tools
• Flexibility: Use any dotfile manager with DotRun

Integration Patterns

DotRun integrates with dotfile managers through several patterns:

1. Symlink Integration: Your dotfile manager manages DotRun as a submodule
2. Direct Integration: DotRun becomes part of your dotfile repository
3. Independent Operation: DotRun runs alongside your dotfile manager
4. Hybrid Approach: Personal scripts in dotfiles, team collections separate

YADM Integration

YADM (Yet Another Dotfiles Manager) is a popular Git-based dotfile manager that integrates seamlessly with DotRun.

Quick YADM Setup

DotRun provides a built-in command for YADM integration:

# One-command integration with existing yadm setup
dr yadm-init

What this command does:

1. Moves your existing DotRun configuration into your yadm-managed directory
2. Creates proper symlinks for seamless operation
3. Sets up .gitignore entries for team collections
4. Configures yadm to track your personal scripts

Manual YADM Integration

For more control over the integration process:

# Step 1: Add DotRun to your yadm repository
cd ~
yadm submodule add https://github.com/jvPalma/dotrun.git .config/dotrun-framework

# Step 2: Set up the DotRun directory structure
mkdir -p ~/.config/dotrun/{bin,docs,helpers}

# Step 3: Create personal scripts directory in yadm
yadm add ~/.config/dotrun/bin
yadm add ~/.config/dotrun/docs

# Step 4: Ignore team collections (not part of personal dotfiles)
echo ".config/dotrun/collections/" >>~/.yadm/gitignore
yadm add ~/.yadm/gitignore

# Step 5: Install DotRun binary
# dr binary already available at ~/.local/bin/dr

# Step 6: Commit the integration
yadm add .config/dotrun-framework
yadm commit -m "Add DotRun script management integration"

YADM Workflow

With YADM integration, your workflow becomes:

# Create personal scripts (tracked by yadm)
dr set git/my-branch-tool

# Import team collections (not tracked by yadm)
dr import https://github.com/team/scripts.git team-tools

# Your personal scripts are automatically backed up with your dotfiles
yadm status # Shows your scripts as part of dotfiles
yadm add ~/.config/dotrun/bin/git/my-branch-tool.sh
yadm commit -m "Add personal branch management tool"

# Team collections remain separate
ls ~/.config/dotrun/collections/ # Team stuff, not in yadm

YADM Configuration Example

Add to your .yadm/gitignore:

# DotRun team collections (not personal dotfiles)
.config/dotrun/collections/

# DotRun temporary files
.config/dotrun/*.tmp
.config/dotrun/gpt.out

# Keep personal scripts and docs
!.config/dotrun/bin/
!.config/dotrun/docs/
!.config/dotrun/helpers/

Chezmoi Integration

Chezmoi is a powerful dotfile manager that handles templating and encryption.

Basic Chezmoi Setup

# Add DotRun configuration to chezmoi
chezmoi add ~/.config/dotrun

# Edit the DotRun configuration template
chezmoi edit ~/.config/dotrun

# Apply changes
chezmoi apply

# Optionally, add DotRun as an external source
chezmoi import --strip-components 1 --destination ~/.config/dotrun-framework \
  https://github.com/jvPalma/dotrun/archive/master.tar.gz

Chezmoi with DotRun Scripts

Create a chezmoi template for DotRun setup:

# Create template file
chezmoi edit ~/.config/dotrun/install.sh.tmpl

#!/bin/bash
# Template: ~/.local/share/chezmoi/dot_config/dotrun/install.sh.tmpl

# Install DotRun framework
if [ ! -d "{{ .chezmoi.homeDir }}/.config/dotrun-framework" ]; then
  git clone https://github.com/jvPalma/dotrun.git \
    "{{ .chezmoi.homeDir }}/.config/dotrun-framework"
fi

# Set up DotRun binary
ln -sf "{{ .chezmoi.homeDir }}/.config/dotrun-framework/drun" \
  "{{ .chezmoi.homeDir }}/.local/bin/dr"

# Import team collections based on environment
{{ if eq .work true }}
dr import [email protected]:company/work-scripts.git work
{{ end }}

{{ if eq .personal true }}
dr import https://github.com/personal/utilities.git personal-utils
{{ end }}

Chezmoi Data for DotRun

Use chezmoi's data functionality to customize DotRun:

# ~/.local/share/chezmoi/chezmoi.yaml
data:
  work: true
  personal: true
  dotrun:
    team_repos:
      - name: "devops"
        url: "[email protected]:company/devops-scripts.git"
      - name: "frontend"
        url: "[email protected]:company/frontend-tools.git"

Git-Based Dotfiles Integration

For custom Git-based dotfile setups:

Submodule Approach

# Add DotRun as a submodule to your dotfiles repository
cd ~/dotfiles
git submodule add https://github.com/jvPalma/dotrun.git config/dotrun-framework

# Create symlinks in your dotfiles install script
cat >>install.sh <<'EOF'
# DotRun setup
mkdir -p ~/.config/dotrun
# dr binary already available at ~/.local/bin/dr
ln -sf ~/dotfiles/config/dotrun-framework/* ~/.config/dotrun/

# Set up personal scripts directory
mkdir -p ~/.config/dotrun/{bin,docs,helpers}
EOF

# Ignore team collections in your dotfiles repo
echo "config/dotrun/collections/" >>.gitignore
git add .gitignore

# Commit the integration
git add .
git commit -m "Add DotRun integration as submodule"

Direct Integration Approach

Include DotRun directly in your dotfiles repository:

# Clone DotRun into your dotfiles
cd ~/dotfiles
git clone https://github.com/jvPalma/dotrun.git tools/dotrun
rm -rf tools/dotrun/.git # Remove git history

# Integrate into your dotfiles structure
mkdir -p config/dotrun/{bin,docs,helpers}

# Add to your install script
cat >>install.sh <<'EOF'
# Install DotRun
cp -r ~/dotfiles/tools/dotrun/* ~/.config/dotrun/
chmod +x ~/.local/bin/dr
# dr binary already available at ~/.local/bin/dr

# Set up personal scripts tracking
ln -sf ~/dotfiles/config/dotrun/bin ~/.config/dotrun/bin
ln -sf ~/dotfiles/config/dotrun/docs ~/.config/dotrun/docs
EOF

# Add personal scripts to version control
git add config/dotrun/
git add tools/dotrun/
git commit -m "Add DotRun with personal scripts integration"

Stow Integration

GNU Stow users can integrate DotRun using the package-based approach:

Stow Setup

# Create DotRun package in your stow directory
mkdir -p ~/dotfiles/dotrun/.config/dotrun

# Set up DotRun framework
cd ~/dotfiles/dotrun/.config/dotrun
git clone https://github.com/jvPalma/dotrun.git framework
# dr binary already available at ~/.local/bin/dr

# Create personal scripts directories
mkdir -p {bin,docs,helpers}

# Create collections ignore file
echo "collections/" >.gitignore

# Stow the package
cd ~/dotfiles
stow dotrun

Stow Package Structure

~/dotfiles/dotrun/
├── .config/
│   └── dotrun/
│       ├── framework/          # DotRun framework (git clone)
│       ├── bin/               # Personal scripts (stowed)
│       ├── docs/              # Personal docs (stowed)
│       ├── helpers/           # Personal helpers (stowed)
│       └── .gitignore         # Ignore collections
└── .local/
    └── bin/
        └── dr -> ../../../.config/dotrun/framework/dr

Ansible Integration

For infrastructure-as-code dotfile management:

Ansible Playbook

# dotfiles.yml
---
- name: Set up DotRun
  hosts: localhost
  tasks:
    - name: Clone DotRun repository
      git:
        repo: https://github.com/jvPalma/dotrun.git
        dest: "{{ ansible_env.HOME }}/.config/dotrun"
        update: yes

    - name: Create DotRun binary symlink
      file:
        src: "{{ ansible_env.HOME }}/.local/bin/dr"
        dest: "{{ ansible_env.HOME }}/.local/bin/dr"
        state: link

    - name: Create personal script directories
      file:
        path: "{{ ansible_env.HOME }}/.config/dotrun/{{ item }}"
        state: directory
      loop:
        - bin
        - docs
        - helpers

    - name: Import team collections
      command: "{{ ansible_env.HOME }}/.local/bin/dr import {{ item.url }} {{ item.name }}"
      loop:
        - { name: "devops", url: "[email protected]:company/devops-scripts.git" }
        - { name: "frontend", url: "[email protected]:company/frontend-tools.git" }
      ignore_errors: yes # Collections might already exist

Homebrew Bundle Integration

macOS users with Homebrew can include DotRun in their Brewfile:

# Brewfile
# DotRun dependencies
brew "bash"
brew "git"
brew "shellcheck"
brew "glow"

# Custom tap for DotRun (if available)
# tap "company/dotrun"
# brew "dotrun"

# Manual installation via shell command
# system "curl -fsSL https://raw.githubusercontent.com/jvPalma/dotrun/master/install.sh | sh"

Docker/Container Integration

For containerized development environments:

Dockerfile Integration

# Add to your development container Dockerfile
FROM ubuntu:22.04

# Install dependencies
RUN apt-get update && apt-get install -y \
 bash git curl shellcheck \
 && rm -rf /var/lib/apt/lists/*

# Install DotRun
RUN curl -fsSL https://raw.githubusercontent.com/jvPalma/dotrun/master/install.sh | sh

# Set up team collections
USER developer
RUN dr import https://github.com/company/dev-scripts.git team

# Copy personal scripts from host
COPY --chown=developer:developer dotrun/bin/ /home/developer/.config/dotrun/bin/
COPY --chown=developer:developer dotrun/docs/ /home/developer/.config/dotrun/docs/

Docker Compose for Development

# docker-compose.yml
version: "3.8"
services:
  dev-environment:
    build: .
    volumes:
      - ./dotrun/bin:/home/developer/.config/dotrun/bin
      - ./dotrun/docs:/home/developer/.config/dotrun/docs
      - dotrun-collections:/home/developer/.config/dotrun/collections
    environment:
      - DR_CONFIG=/home/developer/.config/dotrun

volumes:
  dotrun-collections:

Advanced Integration Patterns

Multi-Machine Synchronization

For users with multiple development machines:

# Machine 1: Export personal scripts
dr export personal-tools ~/dotfiles/dotrun-personal.tar.gz

# Machine 2: Import personal scripts
cd ~/dotfiles
tar -xzf dotrun-personal.tar.gz
dr import ./dotrun-personal personal

# Or use git for synchronization
cd ~/.config/dotrun
git init
git remote add origin [email protected]:username/personal-dotrun.git
git add bin/ docs/ helpers/
git commit -m "Sync personal DotRun scripts"
git push -u origin main

# On other machines
cd ~/.config/dotrun
git pull origin main

Environment-Specific Configurations

# Create environment-specific configurations
mkdir -p ~/.config/dotrun/environments/{work,personal,lab}

# Work environment setup
cat >~/.config/dotrun/environments/work/setup.sh <<'EOF'
#!/bin/bash
dr import [email protected]:team/scripts.git work
dr import [email protected]:security/tools.git security
export WORK_ENV=true
EOF

# Personal environment setup
cat >~/.config/dotrun/environments/personal/setup.sh <<'EOF'
#!/bin/bash
dr import https://github.com/personal/utilities.git personal
export PERSONAL_ENV=true
EOF

# Activate environment
source ~/.config/dotrun/environments/work/setup.sh

Profile-Based Integration

For users with multiple profiles or roles:

# Create profile switching
mkdir -p ~/.config/dotrun/profiles/{developer,devops,manager}

# Developer profile
cat >~/.config/dotrun/profiles/developer/.profile <<'EOF'
# Development-focused collections
dr import [email protected]:company/dev-tools.git dev
dr import [email protected]:company/frontend-tools.git frontend
dr import [email protected]:company/testing-tools.git test
EOF

# DevOps profile
cat >~/.config/dotrun/profiles/devops/.profile <<'EOF'
# Operations-focused collections
dr import [email protected]:company/devops-scripts.git ops
dr import [email protected]:company/monitoring-tools.git monitoring
dr import [email protected]:company/deployment-scripts.git deploy
EOF

# Profile switching script
cat >~/.local/bin/dr-profile <<'EOF'
#!/bin/bash
PROFILE="${1:-developer}"
PROFILE_DIR="$HOME/.config/dotrun/profiles/$PROFILE"

if [ -f "$PROFILE_DIR/.profile" ]; then
    echo "Switching to $PROFILE profile..."
    source "$PROFILE_DIR/.profile"
    echo "DOTRUN_PROFILE=$PROFILE" > ~/.config/dotrun/.current-profile
else
    echo "Profile $PROFILE not found"
    exit 1
fi
EOF

chmod +x ~/.local/bin/dr-profile

# Switch profiles
dr-profile developer
dr-profile devops

Best Practices for Integration

Recommended Patterns

1. Keep Personal Scripts in Dotfiles: Use your dotfile manager for personal scripts
2. Separate Team Collections: Don't version control team collections with personal dotfiles
3. Use Symlinks: Create symlinks rather than copying files when possible
4. Document Integration: Include DotRun setup in your dotfiles documentation

What to Track vs. Ignore

Track in your dotfiles:

• Personal scripts (~/.config/dotrun/bin/)
• Personal documentation (~/.config/dotrun/docs/)
• Personal helpers (~/.config/dotrun/helpers/)
• DotRun configuration files

Don't track in your dotfiles:

• Team collections (~/.config/dotrun/collections/)
• Temporary files (*.tmp, gpt.out)
• Cache files
• Downloaded dependencies

Example .gitignore

# DotRun - ignore team collections and temp files
.config/dotrun/collections/
.config/dotrun/*.tmp
.config/dotrun/gpt.out
.config/dotrun/.cache/

# DotRun - track personal content
!.config/dotrun/bin/
!.config/dotrun/docs/
!.config/dotrun/helpers/
# dr binary managed separately at ~/.local/bin/dr
!.config/dotrun/dr_completion.*

Troubleshooting Integration

Common Issues

Symlink Problems

# Check if symlinks are working
ls -la ~/.local/bin/dr
ls -la ~/.config/dotrun

# Recreate broken symlinks
# dr binary already available at ~/.local/bin/dr

Permission Issues

# Fix executable permissions
chmod +x ~/.local/bin/dr
find ~/.config/dotrun/bin -name "*.sh" -exec chmod +x {} \;

Path Issues

# Check if ~/.local/bin is in PATH
echo $PATH | grep -o "$HOME/.local/bin"

# Add to PATH if missing
echo 'export PATH="$HOME/.local/bin:$PATH"' >>~/.bashrc
source ~/.bashrc

Dotfile Manager Conflicts

# For yadm conflicts
yadm status | grep dotrun
yadm diff ~/.config/dotrun

# For chezmoi conflicts
chezmoi diff ~/.config/dotrun
chezmoi apply --dry-run

Migration Issues

When migrating between integration methods:

# Backup existing setup
tar -czf dotrun-backup-$(date +%Y%m%d).tar.gz ~/.config/dotrun

# Clean migration
rm -rf ~/.config/dotrun
# Re-install using new integration method

# Restore personal scripts
tar -xzf dotrun-backup-*.tar.gz
cp -r home/*/.config/dotrun/bin ~/.config/dotrun/
cp -r home/*/.config/dotrun/docs ~/.config/dotrun/

---

Next Steps:

• Script Development Guide - Learn to create and manage scripts
• Team Collaboration - Set up team script sharing
• Best Practices - Follow recommended patterns and conventions