Sync Checker

Find and report broken symlinks:

1. Search for broken links:

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

2. Report findings:

   • List broken symlinks
   • Explain why they're broken (target missing/moved)
   • Suggest fixes

3. Recommend cleanup:

   • Remove broken links
   • Recreate with correct targets
   • Update setup scripts if needed

3. Permission Verification

Check file and script permissions:

1. Script executability:

   • All .sh files should be executable
   • Check: find ~/dotfiles -name "*.sh" -type f ! -perm -u+x

2. File ownership:

   • Ensure files are owned by the user
   • Check: ls -la ~/dotfiles

3. Correct permissions:

   • Scripts: 755 (rwxr-xr-x)
   • Configs: 644 (rw-r--r--)
   • Private files: 600 (rw-------)

4. Configuration Loading

Verify configurations load without errors:

1. Shell configuration:

   zsh -c 'source ~/.zshrc && echo "✓ .zshrc loads successfully"'
   

2. Aliases:

   zsh -c 'source ~/.zshrc && alias | wc -l'
   

3. Environment variables:

   • Check PATH includes expected directories
   • Verify tool-specific vars (NODE, PNPM, etc.)

5. Comprehensive System Check

Perform full dotfiles health check:

1. Symlinks: All expected symlinks exist and valid
2. Permissions: Scripts executable, files have correct permissions
3. Loading: Shell config loads without errors
4. Aliases: All aliases loaded and available
5. Crontab: Scheduled tasks configured
6. Git: Repository clean and up to date
7. Homebrew: Brewfile packages can be resolved

Verification Checklist

Symlinks:
□ ~/.zshrc → ~/dotfiles/.zshrc
□ ~/.aliases → ~/dotfiles/.aliases
□ ~/.gitconfig → ~/dotfiles/.gitconfig
□ ~/.claude/settings.json → ~/dotfiles/config/.claude/settings.json

File Integrity:
□ All symlink targets exist
□ No broken symlinks in home directory
□ All .sh scripts are executable
□ File permissions are correct

Configuration:
□ .zshrc loads without errors
□ .aliases loads without errors
□ Aliases are available in shell
□ Environment variables set correctly
□ Crontab is installed

Repository:
□ Git repository clean
□ On main branch (or expected branch)
□ No uncommitted changes (or list them)
□ Remote configured correctly

Common Issues and Fixes

Issue: Broken Symlink

Detection:

ls -la ~/.zshrc
# Output: ~/.zshrc -> ~/dotfiles/.zshrc (red, indicating broken)

Diagnosis:

• Target file doesn't exist
• Path is incorrect
• File was moved or deleted

Fix:

# Remove broken link
rm ~/.zshrc

# Recreate correct link
ln -s ~/dotfiles/.zshrc ~/.zshrc

Issue: Symlink Missing

Detection: ls ~/.zshrc returns "No such file or directory"

Fix:

# Create the symlink
ln -s ~/dotfiles/.zshrc ~/.zshrc

# Or re-run setup
source ~/dotfiles/shell/zsh.sh

Issue: File Instead of Symlink

Detection:

ls -la ~/.zshrc
# Output shows regular file, not link (->)

Fix:

# Backup existing file
mv ~/.zshrc ~/.zshrc.backup

# Create symlink
ln -s ~/dotfiles/.zshrc ~/.zshrc

Issue: Script Not Executable

Detection:

find ~/dotfiles -name "*.sh" -type f ! -perm -u+x
# Lists non-executable scripts

Fix:

chmod +x ~/dotfiles/setup.sh
# Or fix all scripts
find ~/dotfiles -name "*.sh" -exec chmod +x {} \;

Issue: Configuration Won't Load

Detection:

zsh -c 'source ~/.zshrc'
# Shows error messages

Diagnosis:

• Syntax error in config file
• Missing dependency
• Circular source loop

Fix:

• Check syntax: zsh -n ~/.zshrc
• Review error message for specific line
• Comment out problematic sections to isolate issue

Example Workflows

Example 1: Full System Check

User: "Check if my dotfiles are set up correctly"

Steps:

1. Check symlinks:

   ls -la ~/.zshrc ~/.aliases ~/.gitconfig ~/.claude/settings.json
   

   Report: "✓ All 4 symlinks exist"

2. Verify targets:

   test -f ~/dotfiles/.zshrc && echo "✓ .zshrc target exists"
   

   Report: "✓ All symlink targets exist"

3. Check for broken links:

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

   Report: "✓ No broken symlinks found"

4. Test loading:

   zsh -c 'source ~/.zshrc && echo OK'
   

   Report: "✓ Shell configuration loads successfully"

5. Summary: "All dotfiles are properly synchronised ✓"

Example 2: Troubleshooting Broken Link

User: "My .zshrc isn't working"

Steps:

1. Check symlink:

   ls -la ~/.zshrc
   

   Output: ~/.zshrc -> ~/old-dotfiles/.zshrc (broken)

2. Diagnose: "Your .zshrc links to '~/old-dotfiles/.zshrc' which doesn't exist"

3. Fix:

   rm ~/.zshrc
   ln -s ~/dotfiles/.zshrc ~/.zshrc
   

4. Verify:

   ls -la ~/.zshrc
   zsh -c 'source ~/.zshrc && echo OK'
   

5. Confirm: "✓ Fixed! .zshrc now correctly links to ~/dotfiles/.zshrc"

Example 3: Permission Issues

User: "Check my dotfiles"

Steps:

1. Check scripts:

   find ~/dotfiles -name "*.sh" -type f ! -perm -u+x
   

   Found: setup.sh, shell/zsh.sh not executable

2. Report: "Found 2 scripts without execute permission"

3. Fix:

   chmod +x ~/dotfiles/setup.sh ~/dotfiles/shell/zsh.sh
   

4. Verify:

   ls -la ~/dotfiles/setup.sh
   

   Output: -rwxr-xr-x ✓

5. Confirm: "✓ Fixed permissions on 2 scripts"

Diagnostic Commands

Useful commands for sync checking:

# Check specific symlink
ls -la ~/.zshrc

# Find all symlinks in home directory
find ~ -maxdepth 1 -type l -ls

# Find broken symlinks
find ~ -maxdepth 1 -type l ! -exec test -e {} \; -print

# Check if file is a symlink
test -L ~/.zshrc && echo "Is a symlink" || echo "Not a symlink"

# Get symlink target
readlink ~/.zshrc

# Check if target exists
test -e ~/dotfiles/.zshrc && echo "Target exists" || echo "Target missing"

# List all dotfiles
ls -la ~/dotfiles/

# Check script permissions
find ~/dotfiles -name "*.sh" -type f -ls

# Test shell config loads
zsh -n ~/.zshrc  # Syntax check
zsh -c 'source ~/.zshrc && echo OK'  # Load test

# Count loaded aliases
zsh -c 'source ~/.zshrc && alias | wc -l'

# Check crontab
crontab -l

Best Practices

• Regular checks: Verify sync after setup or updates
• Test loading: Always ensure configs load without errors
• Fix immediately: Don't ignore broken symlinks or permissions
• Document issues: Note any recurring problems for permanent fixes
• British English: Use British spelling in all output

Report Format

When reporting sync status, use this format:

Dotfiles Sync Status Report
============================

Symlinks:
✓ ~/.zshrc → ~/dotfiles/.zshrc
✓ ~/.aliases → ~/dotfiles/.aliases
✓ ~/.gitconfig → ~/dotfiles/.gitconfig
✓ ~/.claude/settings.json → ~/dotfiles/config/.claude/settings.json

File Integrity:
✓ All symlink targets exist
✓ No broken symlinks detected

Permissions:
✓ All scripts executable
✓ File permissions correct

Configuration:
✓ Shell loads without errors
✓ 47 aliases loaded
✓ Environment variables set

Status: All dotfiles properly synchronised ✓

Or if issues found:

Dotfiles Sync Status Report
============================

Issues Found:
✗ ~/.zshrc is a regular file, not a symlink
✗ setup.sh is not executable
⚠ .aliases loads with warning

Recommendations:
1. Backup ~/.zshrc and recreate as symlink
2. Run: chmod +x ~/dotfiles/setup.sh
3. Review .aliases for syntax issues

Run these commands to fix:
mv ~/.zshrc ~/.zshrc.backup
ln -s ~/dotfiles/.zshrc ~/.zshrc
chmod +x ~/dotfiles/setup.sh

Important Notes

• Non-destructive checks: Default to read-only verification
• Clear reporting: Use ✓ and ✗ symbols for easy scanning
• Actionable advice: Always provide specific fix commands
• British English: All output and messages
• Comprehensive: Check all aspects, don't stop at first issue