Dotfiles Repository - Development Guide

Repository Overview

This is a centralized dotfiles management system for macOS and Linux that provides:

Automatic symlinking of configuration files
Modular shell initialization system
Tool-specific configuration with installation detection
Cross-platform compatibility

Architecture

Core Components

Bootstrap System (
```
script/bootstrap
```
)
- Finds all
```
dot.*
```
  files and creates symlinks in home directory
- Pattern:
```
~/.dotfiles/tool/dot.config
```
  →
```
~/.config
```
- Preserves existing non-symlink files (safety feature)
Shell Initialization
- Bash: Sources all
```
*.sh
```
  and
```
*.bash
```
  files via
```
.bashrc
```
- Zsh: Sources all
```
*.sh
```
  and
```
*.zsh
```
  files via
```
.zshrc
```
- Files are sorted numerically before sourcing (use prefixes like
```
000-
```
  for ordering)
- ```
bin/
```
  directory automatically added to PATH
Tool Organization
- Each tool gets its own directory
- Standard file patterns:
  - ```
  dot.*
```
  - Configuration files to be symlinked
- ```
*.sh
```
    /
```
*.zsh
```
    - Shell scripts to be sourced
  - ```
  alias.sh
```
  - Tool-specific aliases
- ```
path.sh
```
    - PATH modifications
  - ```
  load.sh
```
  - Lazy loading/initialization

Directory Structure

.dotfiles/
├── 000.start/          # Early initialization (runs first)
├── bin/                # Executable scripts (added to PATH)
├── [tool]/             # Tool-specific directory
│   ├── dot.toolrc      # Config file (symlinked to ~/.toolrc)
│   ├── alias.sh        # Tool aliases
│   ├── path.sh         # PATH setup
│   └── load.sh         # Initialization logic
├── system/             # System-wide settings
│   └── 999.*.zsh       # Late initialization (runs last)
└── script/
    └── bootstrap       # Initial setup script

Adding a New Tool

Step 1: Create Tool Directory

mkdir ~/.dotfiles/newtool

Step 2: Add Configuration File (if needed)

# Will be symlinked to ~/.newtoolrc
touch ~/.dotfiles/newtool/dot.newtoolrc

Step 3: Create Initialization Script

⚠️ IMPORTANT: Only create

.sh

.zsh

files that should run on every shell startup. For scripts that should be run manually, use

bin/

directory.

cat > ~/.dotfiles/newtool/load.sh << 'EOF'
#!/usr/bin/env bash
# Tool initialization with installation check

if command -v newtool &> /dev/null; then
    # Tool is installed - set up environment
    export NEWTOOL_HOME="$HOME/.newtool"
    export PATH="$NEWTOOL_HOME/bin:$PATH"
    
    # Enable completions if available
    if [[ -n "$ZSH_VERSION" ]]; then
        eval "$(newtool completions zsh)"
    elif [[ -n "$BASH_VERSION" ]]; then
        eval "$(newtool completions bash)"
    fi
    
    # Tool-specific aliases
    alias nt='newtool'
else
    # Tool not installed - provide installation instructions
    echo "newtool not installed."
    if [[ "$(uname)" == "Darwin" ]]; then
        echo "Install with: brew install newtool"
    elif [[ -f /etc/debian_version ]]; then
        echo "Install with: apt-get install newtool"
    else
        echo "Visit: https://newtool.io/install"
    fi
fi
EOF

Step 4: Run Bootstrap

~/.dotfiles/script/bootstrap

Best Practices

1. Installation Detection Pattern

Always check if a tool is installed before configuring:

if command -v toolname &> /dev/null; then
    # Configuration here
else
    # Installation instructions
fi

2. Platform-Specific Logic

if [[ "$(uname)" == "Darwin" ]]; then
    # macOS specific
elif [[ -f /etc/debian_version ]]; then
    # Debian/Ubuntu specific
else
    # Generic Linux/other
fi

3. Shell Detection

if [[ -n "$ZSH_VERSION" ]]; then
    # Zsh-specific setup
elif [[ -n "$BASH_VERSION" ]]; then
    # Bash-specific setup
fi

4. File Naming Conventions

CRITICAL: Files with

.sh

.zsh

extensions are automatically sourced during shell startup. Only put files here that should run on every shell initialization.

Auto-sourced files (run at shell startup):

```
000-*.sh
```
- Early initialization (Homebrew, core paths)
```
999-*.sh
```
- Late initialization (final PATH adjustments)
```
alias.sh
```
- Command aliases
```
path.sh
```
- PATH modifications
```
load.sh
```
- Main tool initialization
```
env.sh
```
- Environment variables

Manual-execution files:

Tool-specific scripts: Keep in tool directory without
```
.sh
```
extension (e.g.,
```
ssh/origin-proxy
```
)
General utilities: Put in
```
bin/
```
directory
One-time setup scripts: Put in
```
bin/
```
directory

Examples by location:

```
ssh/origin-proxy
```
- SSH ProxyCommand script (no .sh extension, executable)
```
git/setup-hooks
```
- Git setup script (tool-specific, no .sh extension)
```
bin/backup-dotfiles
```
- General utility script

Examples of what NOT to auto-source:

SSH ProxyCommand scripts (would run on every shell startup!)
Scripts that perform actions (vs setting up environment)
Scripts that might fail or have side effects

5. Lazy Loading

For heavy tools (nvm, rvm, etc.), use lazy loading:

# Instead of loading immediately, create a function
nvm() {
    unset -f nvm
    source "$NVM_DIR/nvm.sh"
    nvm "$@"
}

Common Patterns

Adding to PATH

# Prepend (higher priority)
export PATH="/new/path:$PATH"

# Append (lower priority)
export PATH="$PATH:/new/path"

Sourcing Completions

# Check for completion file
if [[ -f /path/to/completions ]]; then
    source /path/to/completions
fi

Creating Aliases

# In tool/alias.sh
alias ll='ls -la'
alias gs='git status'

# Conditional aliases
command -v hub &> /dev/null && alias git='hub'

Debugging

Check Load Order

# See which files are being sourced and in what order
find ~/.dotfiles -name "*.sh" -o -name "*.zsh" | \
    grep -v "~/.dotfiles/bin/" | \
    awk -F'/' '{print $NF"|"$0}' | \
    sort -t"|" -k1n | \
    cut -f2- -d'|'

Test Bootstrap Without Changes

# Dry run to see what would be linked
find ~/.dotfiles -type f -name 'dot.*' | while read -r file; do
    echo "Would link: $file -> ~/$(basename ${file#dot.})"
done

Reload Configuration

# Reload current shell configuration
source ~/.zshrc  # or ~/.bashrc

Maintenance

Disable a Configuration

Rename the file to exclude

.sh

.zsh

extension:

mv tool/load.sh tool/load.sh.disabled

Clean Broken Symlinks

find ~ -maxdepth 1 -type l ! -exec test -e {} \; -delete

Update All Tools

# Example update script
brew update && brew upgrade  # macOS
apt update && apt upgrade     # Debian/Ubuntu

Security Considerations

Never commit secrets - Use environment variables or secure storage
Check file permissions - Ensure private keys have correct permissions
Review sourced files - Be cautious with third-party shell scripts
Use
command -v
over
which
- More reliable and POSIX compliant

Remote Hosts and tmux Considerations

When configuring remote hosts accessed via SSH, be aware of tmux behavior:

Environment Variable Persistence

Problem: tmux "freezes" environment variables when sessions start. SSH-related variables become stale when reconnecting from different locations.

Affected Variables:

```
SSH_AUTH_SOCK
```
- SSH agent forwarding socket
```
SSH_CLIENT
```
- Origin IP and port information
```
SSH_CONNECTION
```
- Connection details
Custom variables set during SSH connection

Solutions Implemented

1. SSH Agent Socket Symlink

The

tmux-on-ssh.sh

script creates a stable symlink:

# Creates: ~/.ssh/ssh_auth_sock -> /tmp/ssh-agent.12345
export SSH_AUTH_SOCK="$HOME/.ssh/ssh_auth_sock"

This ensures SSH agent forwarding works in existing tmux shells even after reconnecting from different machines.

2. Environment Variable Updates

The script updates tmux session environment on each connection:

tmux setenv -t "$SESSION_NAME" SSH_CLIENT "$SSH_CLIENT"
tmux setenv -t "$SESSION_NAME" SSH_CONNECTION "$SSH_CONNECTION"  
tmux setenv -t "$SESSION_NAME" SSH_AUTH_SOCK "$SSH_AUTH_SOCK_LINK"

Note: This only affects NEW shells/windows in tmux, not existing ones.

Best Practices for Remote Configuration

Test in Fresh Shells: After changing remote configs, test in new tmux windows
Use Symlinks for Sockets: Follow the SSH agent socket pattern for other persistent resources

Refresh Functions: Create functions to manually update environment when needed:

refresh-ssh() {
    if [[ -n "$TMUX" ]]; then
        export SSH_AUTH_SOCK=$(tmux showenv SSH_AUTH_SOCK | cut -d= -f2-)
        echo "SSH environment refreshed"
    fi
}

Consider Session Scope: Some configurations should be session-wide, others per-connection

Remote Debugging

When things don't work in tmux on remote hosts:

# Check if you're in tmux
echo $TMUX

# Check SSH agent forwarding
ssh-add -l

# Compare tmux env vs current shell
tmux showenv | grep SSH
env | grep SSH

# Test reverse tunnel detection
netstat -ln | grep 127.0.0.1 | grep LISTEN

# Refresh environment manually
source ~/.zshrc  # May not fix tmux-frozen vars

Troubleshooting

Tool Not Loading

Check if file has
```
.sh
```
or
```
.zsh
```
extension
Verify file is executable:
```
chmod +x file.sh
```
Check for syntax errors:
```
bash -n file.sh
```
Ensure tool is installed:
```
command -v toolname
```

Symlink Issues

Check existing file:
```
ls -la ~/.[filename]
```
Remove if broken:
```
rm ~/.[filename]
```
Re-run bootstrap:
```
~/.dotfiles/script/bootstrap
```

PATH Issues

Check current PATH:
```
echo $PATH
```

Find duplicates:

echo $PATH | tr ':' '\n' | sort | uniq -d

Verify order: Earlier entries take precedence

tmux Environment Issues

Check if in tmux:
```
echo $TMUX
```
Compare environments:
```
tmux showenv
```
vs
```
env
```
Create new tmux window to test fresh environment
Use refresh functions to update existing shells
Verify SSH agent forwarding:
```
ssh-add -l
```

Auto-Sourcing Issues

Symptom: Terminal won't start, or errors on shell startup mentioning scripts

Cause: Scripts with

.sh

.zsh

extensions are auto-sourced during shell startup

Emergency Access (when dotfiles break shell startup):

# Start bare-bones shell without sourcing dotfiles
ssh server bash           # Remote access without .bashrc
ssh server sh            # Even more minimal
ssh server "bash --norc"  # Explicit no-rc mode

# Once in, fix the problem:
mv ~/.dotfiles/problematic.sh ~/.dotfiles/problematic.sh.disabled

Solution:

Check for executable scripts in tool directories:
```
find ~/.dotfiles -name "*.sh" -executable
```
For tool-specific scripts: Remove
```
.sh
```
extension:
```
mv tool/script.sh tool/script
```
For general utilities: Move to bin:
```
mv tool/script.sh bin/tool-script
```
Only keep environment setup scripts as
```
.sh
```
files
Test with:
```
bash -x ~/.bashrc
```
or
```
zsh -x ~/.zshrc
```
to see what's being sourced

File naming rules:

```
.sh
```
/
```
.zsh
```
= Auto-sourced at shell startup
No extension + executable = Manual execution
Tool-specific executables stay in tool directory
General executables go to
```
bin/
```

Examples of problematic files:

SSH ProxyCommand scripts
One-time setup scripts
Scripts that perform actions vs setting environment

Contributing

When adding new tools or configurations:

Follow existing patterns and conventions
Include installation instructions for multiple platforms
Test on both macOS and Linux if possible
Document any special requirements or dependencies
Use descriptive commit messages

Quick Reference

# Add new tool
mkdir ~/.dotfiles/newtool
vim ~/.dotfiles/newtool/load.sh
~/.dotfiles/script/bootstrap

# Reload configuration
source ~/.zshrc

# Check what's loaded
echo $DOTFILESDIR
echo $PATH | tr ':' '\n'

# Debug loading
bash -x ~/.bashrc 2>&1 | less

Dotfiles Repository - Development Guide

Repository Overview

This is a centralized dotfiles management system for macOS and Linux that provides:

Automatic symlinking of configuration files
Modular shell initialization system
Tool-specific configuration with installation detection
Cross-platform compatibility

Architecture

Core Components

Bootstrap System (
```
script/bootstrap
```
)
- Finds all
```
dot.*
```
  files and creates symlinks in home directory
- Pattern:
```
~/.dotfiles/tool/dot.config
```
  →
```
~/.config
```
- Preserves existing non-symlink files (safety feature)
Shell Initialization
- Bash: Sources all
```
*.sh
```
  and
```
*.bash
```
  files via
```
.bashrc
```
- Zsh: Sources all
```
*.sh
```
  and
```
*.zsh
```
  files via
```
.zshrc
```
- Files are sorted numerically before sourcing (use prefixes like
```
000-
```
  for ordering)
- ```
bin/
```
  directory automatically added to PATH
Tool Organization
- Each tool gets its own directory
- Standard file patterns:
  - ```
  dot.*
```
  - Configuration files to be symlinked
- ```
*.sh
```
    /
```
*.zsh
```
    - Shell scripts to be sourced
  - ```
  alias.sh
```
  - Tool-specific aliases
- ```
path.sh
```
    - PATH modifications
  - ```
  load.sh
```
  - Lazy loading/initialization

Directory Structure

.dotfiles/
├── 000.start/          # Early initialization (runs first)
├── bin/                # Executable scripts (added to PATH)
├── [tool]/             # Tool-specific directory
│   ├── dot.toolrc      # Config file (symlinked to ~/.toolrc)
│   ├── alias.sh        # Tool aliases
│   ├── path.sh         # PATH setup
│   └── load.sh         # Initialization logic
├── system/             # System-wide settings
│   └── 999.*.zsh       # Late initialization (runs last)
└── script/
    └── bootstrap       # Initial setup script

Adding a New Tool

Step 1: Create Tool Directory

mkdir ~/.dotfiles/newtool

Step 2: Add Configuration File (if needed)

# Will be symlinked to ~/.newtoolrc
touch ~/.dotfiles/newtool/dot.newtoolrc

Step 3: Create Initialization Script

⚠️ IMPORTANT: Only create

.sh

.zsh

files that should run on every shell startup. For scripts that should be run manually, use

bin/

directory.

cat > ~/.dotfiles/newtool/load.sh << 'EOF'
#!/usr/bin/env bash
# Tool initialization with installation check

if command -v newtool &> /dev/null; then
    # Tool is installed - set up environment
    export NEWTOOL_HOME="$HOME/.newtool"
    export PATH="$NEWTOOL_HOME/bin:$PATH"
    
    # Enable completions if available
    if [[ -n "$ZSH_VERSION" ]]; then
        eval "$(newtool completions zsh)"
    elif [[ -n "$BASH_VERSION" ]]; then
        eval "$(newtool completions bash)"
    fi
    
    # Tool-specific aliases
    alias nt='newtool'
else
    # Tool not installed - provide installation instructions
    echo "newtool not installed."
    if [[ "$(uname)" == "Darwin" ]]; then
        echo "Install with: brew install newtool"
    elif [[ -f /etc/debian_version ]]; then
        echo "Install with: apt-get install newtool"
    else
        echo "Visit: https://newtool.io/install"
    fi
fi
EOF

Step 4: Run Bootstrap

~/.dotfiles/script/bootstrap

Best Practices

1. Installation Detection Pattern

Always check if a tool is installed before configuring:

if command -v toolname &> /dev/null; then
    # Configuration here
else
    # Installation instructions
fi

2. Platform-Specific Logic

if [[ "$(uname)" == "Darwin" ]]; then
    # macOS specific
elif [[ -f /etc/debian_version ]]; then
    # Debian/Ubuntu specific
else
    # Generic Linux/other
fi

3. Shell Detection

if [[ -n "$ZSH_VERSION" ]]; then
    # Zsh-specific setup
elif [[ -n "$BASH_VERSION" ]]; then
    # Bash-specific setup
fi

4. File Naming Conventions

CRITICAL: Files with

.sh

.zsh

extensions are automatically sourced during shell startup. Only put files here that should run on every shell initialization.

Auto-sourced files (run at shell startup):

```
000-*.sh
```
- Early initialization (Homebrew, core paths)
```
999-*.sh
```
- Late initialization (final PATH adjustments)
```
alias.sh
```
- Command aliases
```
path.sh
```
- PATH modifications
```
load.sh
```
- Main tool initialization
```
env.sh
```
- Environment variables

Manual-execution files:

Tool-specific scripts: Keep in tool directory without
```
.sh
```
extension (e.g.,
```
ssh/origin-proxy
```
)
General utilities: Put in
```
bin/
```
directory
One-time setup scripts: Put in
```
bin/
```
directory

Examples by location:

```
ssh/origin-proxy
```
- SSH ProxyCommand script (no .sh extension, executable)
```
git/setup-hooks
```
- Git setup script (tool-specific, no .sh extension)
```
bin/backup-dotfiles
```
- General utility script

Examples of what NOT to auto-source:

SSH ProxyCommand scripts (would run on every shell startup!)
Scripts that perform actions (vs setting up environment)
Scripts that might fail or have side effects

5. Lazy Loading

For heavy tools (nvm, rvm, etc.), use lazy loading:

# Instead of loading immediately, create a function
nvm() {
    unset -f nvm
    source "$NVM_DIR/nvm.sh"
    nvm "$@"
}

Common Patterns

Adding to PATH

# Prepend (higher priority)
export PATH="/new/path:$PATH"

# Append (lower priority)
export PATH="$PATH:/new/path"

Sourcing Completions

# Check for completion file
if [[ -f /path/to/completions ]]; then
    source /path/to/completions
fi

Creating Aliases

# In tool/alias.sh
alias ll='ls -la'
alias gs='git status'

# Conditional aliases
command -v hub &> /dev/null && alias git='hub'

Debugging

Check Load Order

# See which files are being sourced and in what order
find ~/.dotfiles -name "*.sh" -o -name "*.zsh" | \
    grep -v "~/.dotfiles/bin/" | \
    awk -F'/' '{print $NF"|"$0}' | \
    sort -t"|" -k1n | \
    cut -f2- -d'|'

Test Bootstrap Without Changes

# Dry run to see what would be linked
find ~/.dotfiles -type f -name 'dot.*' | while read -r file; do
    echo "Would link: $file -> ~/$(basename ${file#dot.})"
done

Reload Configuration

# Reload current shell configuration
source ~/.zshrc  # or ~/.bashrc

Maintenance

Disable a Configuration

Rename the file to exclude

.sh

.zsh

extension:

mv tool/load.sh tool/load.sh.disabled

Clean Broken Symlinks

find ~ -maxdepth 1 -type l ! -exec test -e {} \; -delete

Update All Tools

# Example update script
brew update && brew upgrade  # macOS
apt update && apt upgrade     # Debian/Ubuntu

Security Considerations

Never commit secrets - Use environment variables or secure storage
Check file permissions - Ensure private keys have correct permissions
Review sourced files - Be cautious with third-party shell scripts
Use
command -v
over
which
- More reliable and POSIX compliant

Remote Hosts and tmux Considerations

When configuring remote hosts accessed via SSH, be aware of tmux behavior:

Environment Variable Persistence

Problem: tmux "freezes" environment variables when sessions start. SSH-related variables become stale when reconnecting from different locations.

Affected Variables:

```
SSH_AUTH_SOCK
```
- SSH agent forwarding socket
```
SSH_CLIENT
```
- Origin IP and port information
```
SSH_CONNECTION
```
- Connection details
Custom variables set during SSH connection

Solutions Implemented

1. SSH Agent Socket Symlink

The

tmux-on-ssh.sh

script creates a stable symlink:

# Creates: ~/.ssh/ssh_auth_sock -> /tmp/ssh-agent.12345
export SSH_AUTH_SOCK="$HOME/.ssh/ssh_auth_sock"

This ensures SSH agent forwarding works in existing tmux shells even after reconnecting from different machines.

2. Environment Variable Updates

The script updates tmux session environment on each connection:

tmux setenv -t "$SESSION_NAME" SSH_CLIENT "$SSH_CLIENT"
tmux setenv -t "$SESSION_NAME" SSH_CONNECTION "$SSH_CONNECTION"  
tmux setenv -t "$SESSION_NAME" SSH_AUTH_SOCK "$SSH_AUTH_SOCK_LINK"

Note: This only affects NEW shells/windows in tmux, not existing ones.

Best Practices for Remote Configuration

Test in Fresh Shells: After changing remote configs, test in new tmux windows
Use Symlinks for Sockets: Follow the SSH agent socket pattern for other persistent resources

Refresh Functions: Create functions to manually update environment when needed:

refresh-ssh() {
    if [[ -n "$TMUX" ]]; then
        export SSH_AUTH_SOCK=$(tmux showenv SSH_AUTH_SOCK | cut -d= -f2-)
        echo "SSH environment refreshed"
    fi
}

Consider Session Scope: Some configurations should be session-wide, others per-connection

Remote Debugging

When things don't work in tmux on remote hosts:

# Check if you're in tmux
echo $TMUX

# Check SSH agent forwarding
ssh-add -l

# Compare tmux env vs current shell
tmux showenv | grep SSH
env | grep SSH

# Test reverse tunnel detection
netstat -ln | grep 127.0.0.1 | grep LISTEN

# Refresh environment manually
source ~/.zshrc  # May not fix tmux-frozen vars

Troubleshooting

Tool Not Loading

Check if file has
```
.sh
```
or
```
.zsh
```
extension
Verify file is executable:
```
chmod +x file.sh
```
Check for syntax errors:
```
bash -n file.sh
```
Ensure tool is installed:
```
command -v toolname
```

Symlink Issues

Check existing file:
```
ls -la ~/.[filename]
```
Remove if broken:
```
rm ~/.[filename]
```
Re-run bootstrap:
```
~/.dotfiles/script/bootstrap
```

PATH Issues

Check current PATH:
```
echo $PATH
```

Find duplicates:

echo $PATH | tr ':' '\n' | sort | uniq -d

Verify order: Earlier entries take precedence

tmux Environment Issues

Check if in tmux:
```
echo $TMUX
```
Compare environments:
```
tmux showenv
```
vs
```
env
```
Create new tmux window to test fresh environment
Use refresh functions to update existing shells
Verify SSH agent forwarding:
```
ssh-add -l
```

Auto-Sourcing Issues

Symptom: Terminal won't start, or errors on shell startup mentioning scripts

Cause: Scripts with

.sh

.zsh

extensions are auto-sourced during shell startup

Emergency Access (when dotfiles break shell startup):

# Start bare-bones shell without sourcing dotfiles
ssh server bash           # Remote access without .bashrc
ssh server sh            # Even more minimal
ssh server "bash --norc"  # Explicit no-rc mode

# Once in, fix the problem:
mv ~/.dotfiles/problematic.sh ~/.dotfiles/problematic.sh.disabled

Solution:

Check for executable scripts in tool directories:
```
find ~/.dotfiles -name "*.sh" -executable
```
For tool-specific scripts: Remove
```
.sh
```
extension:
```
mv tool/script.sh tool/script
```
For general utilities: Move to bin:
```
mv tool/script.sh bin/tool-script
```
Only keep environment setup scripts as
```
.sh
```
files
Test with:
```
bash -x ~/.bashrc
```
or
```
zsh -x ~/.zshrc
```
to see what's being sourced

File naming rules:

```
.sh
```
/
```
.zsh
```
= Auto-sourced at shell startup
No extension + executable = Manual execution
Tool-specific executables stay in tool directory
General executables go to
```
bin/
```

Examples of problematic files:

SSH ProxyCommand scripts
One-time setup scripts
Scripts that perform actions vs setting environment

Contributing

When adding new tools or configurations:

Follow existing patterns and conventions
Include installation instructions for multiple platforms
Test on both macOS and Linux if possible
Document any special requirements or dependencies
Use descriptive commit messages

Quick Reference

# Add new tool
mkdir ~/.dotfiles/newtool
vim ~/.dotfiles/newtool/load.sh
~/.dotfiles/script/bootstrap

# Reload configuration
source ~/.zshrc

# Check what's loaded
echo $DOTFILESDIR
echo $PATH | tr ':' '\n'

# Debug loading
bash -x ~/.bashrc 2>&1 | less

Dotfiles Repository - Development Guide

Related Skills

Nano Banana Pro

Markdown Converter

1password