Verify that dotfiles are properly symlinked and synchronised across the system. Use when the user wants to check symlink status, verify dotfiles setup, diagnose sync issues, find broken links, or ensure configurations are correctly deployed. Triggers include "check sync", "verify symlinks", "dotfiles status", "check setup", or troubleshooting symlink issues.
You are a synchronisation checker for this dotfiles repository. Verify that all configurations are properly symlinked and working correctly.
Check that expected symlinks exist and point to the correct locations:
Expected Symlinks:
~/.zshrc → ~/dotfiles/.zshrc
~/.aliases → ~/dotfiles/.aliases
~/.gitconfig → ~/dotfiles/.gitconfig
~/.claude/settings.json → ~/dotfiles/config/.claude/settings.json
Verification Steps:
ls -la ~/.zshrcFind and report broken symlinks:
Search for broken links:
find ~ -maxdepth 1 -type l ! -exec test -e {} \; -print
Report findings:
Recommend cleanup:
Check file and script permissions:
Script executability:
.sh files should be executablefind ~/dotfiles -name "*.sh" -type f ! -perm -u+xFile ownership:
ls -la ~/dotfilesCorrect permissions:
755 (rwxr-xr-x)644 (rw-r--r--)600 (rw-------)Verify configurations load without errors:
Shell configuration:
zsh -c 'source ~/.zshrc && echo "✓ .zshrc loads successfully"'
Aliases:
zsh -c 'source ~/.zshrc && alias | wc -l'
Environment variables:
Perform full dotfiles health check:
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
Detection:
ls -la ~/.zshrc
# Output: ~/.zshrc -> ~/dotfiles/.zshrc (red, indicating broken)
Diagnosis:
Fix:
# Remove broken link
rm ~/.zshrc
# Recreate correct link
ln -s ~/dotfiles/.zshrc ~/.zshrc
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
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
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 {} \;
Detection:
zsh -c 'source ~/.zshrc'
# Shows error messages
Diagnosis:
Fix:
zsh -n ~/.zshrcUser: "Check if my dotfiles are set up correctly"
Steps:
Check symlinks:
ls -la ~/.zshrc ~/.aliases ~/.gitconfig ~/.claude/settings.json
Report: "✓ All 4 symlinks exist"
Verify targets:
test -f ~/dotfiles/.zshrc && echo "✓ .zshrc target exists"
Report: "✓ All symlink targets exist"
Check for broken links:
find ~ -maxdepth 1 -type l ! -exec test -e {} \; -print
Report: "✓ No broken symlinks found"
Test loading:
zsh -c 'source ~/.zshrc && echo OK'
Report: "✓ Shell configuration loads successfully"
Summary: "All dotfiles are properly synchronised ✓"
User: "My .zshrc isn't working"
Steps:
Check symlink:
ls -la ~/.zshrc
Output: ~/.zshrc -> ~/old-dotfiles/.zshrc (broken)
Diagnose: "Your .zshrc links to '~/old-dotfiles/.zshrc' which doesn't exist"
Fix:
rm ~/.zshrc
ln -s ~/dotfiles/.zshrc ~/.zshrc
Verify:
ls -la ~/.zshrc
zsh -c 'source ~/.zshrc && echo OK'
Confirm: "✓ Fixed! .zshrc now correctly links to ~/dotfiles/.zshrc"
User: "Check my dotfiles"
Steps:
Check scripts:
find ~/dotfiles -name "*.sh" -type f ! -perm -u+x
Found: setup.sh, shell/zsh.sh not executable
Report: "Found 2 scripts without execute permission"
Fix:
chmod +x ~/dotfiles/setup.sh ~/dotfiles/shell/zsh.sh
Verify:
ls -la ~/dotfiles/setup.sh
Output: -rwxr-xr-x ✓
Confirm: "✓ Fixed permissions on 2 scripts"
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
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