Troubleshooting

Common Issues

1. Symlink Creation Fails

• Check if parent directories exist
• Verify you have write permissions
• Use --dry-run to preview changes
• Check hidedot status for current symlink state

2. Git Clone Fails

• Verify the repository URL
• Check internet connectivity
• Ensure the target directory doesn't exist

3. Shell Commands Fail

• Verify command exists in your PATH
• Check command permissions
• Use --dry-run to preview commands

4. Profile Not Applied

• Ensure profile name matches exactly (case-sensitive)
• Check that --profile flag is being used
• Configs without a profile are always applied

5. Template Variables Not Expanding

• Verify template syntax: {{ .Variable }}
• Available variables: Hostname, Username, HomeDir, OS, Arch, Date
• Use --verbose to see expanded values

6. Backup Not Created

• Check if backup: true is set in defaults
• Verify you're not using --no-backup flag
• Backups are stored in ~/.hidedot-backups/

7. Restore Not Working

• Ensure backups exist: hidedot backup list
• Use hidedot unlink --restore to restore
• Check backup directory permissions

Symlink Status Meanings

When running hidedot status, you may see:

Status	Meaning
OK	Symlink exists and points to correct target
MISSING	Symlink doesn't exist
BROKEN	Symlink exists but target doesn't exist
MISMATCH	Symlink exists but points to wrong target
NOT_SYMLINK	Path exists but is a regular file/directory

Logging

hideDot provides detailed logging with colored output:

• Normal operation: ==> (cyan)
• Dry run mode: [DRY RUN] ==> (yellow)
• Success: Green text
• Warning: Yellow text
• Error: Red text

Verbosity Levels

# Normal output
hidedot

# Verbose (includes debug info)
hidedot --verbose

# Quiet (errors only)
hidedot --quiet

# No colors (for scripts/CI)
hidedot --no-color

Debugging

# Preview all changes
hidedot --dry-run

# Verbose dry run for maximum detail
hidedot -n -v

# Check current state
hidedot status

# List backups
hidedot backup list

Getting Help

# Show help
hidedot --help

# Show version
hidedot --version

# Subcommand help
hidedot link --help
hidedot status --help
hidedot unlink --help
hidedot backup --help