Migration Guide

This guide helps you migrate from manual PATH management or other tools to pathmaster, and between different versions of pathmaster.

Migrating from Manual PATH Management

If you’ve been managing your PATH manually in shell configuration files, follow these steps to migrate to pathmaster:

  1. Make a backup of your current shell configuration:

cp ~/.bashrc ~/.bashrc.manual-backup
# or for other shells
cp ~/.zshrc ~/.zshrc.manual-backup

  1. Review your current PATH to understand what’s in it:

echo $PATH | tr ':' '\n'

  1. Add your custom directories using pathmaster:

# Add each custom directory you want to keep
pathmaster add ~/bin ~/scripts /opt/custom/bin

  1. Check your PATH to verify everything looks correct:

pathmaster list

  1. Remove any invalid entries:

pathmaster flush

Pathmaster will automatically update your shell configuration file, commenting out or removing your previous PATH declarations and adding its own standardized format.

Migrating from Other PATH Management Tools

If you’re migrating from another PATH management tool:

  1. Disable or uninstall the other tool first

  2. Clean up your shell configuration to remove any entries it added

  3. Follow the steps above to migrate from manual management

Version Migration Notes

Upgrading to 0.2.5

Version 0.2.5 includes:

  • Enhanced documentation

  • Improved error messages

  • Better shell detection

  • Expanded troubleshooting

No special migration steps are needed.

Upgrading from 0.2.1 or earlier to 0.2.3+

Version 0.2.3 introduced configurable backup modes. After upgrading:

  1. Review the new backup options:

pathmaster --help

  1. Choose your preferred backup mode (if you want to change from the default):

# Example: Switch to backing up only PATH entries
pathmaster --backup-mode path

Upgrading from 0.1.x to 0.2.x

The 0.2.x series introduced significant changes to PATH validation and backup systems:

  1. Check for invalid entries with the improved validation:

pathmaster check

  1. Review your backups to ensure they’re working properly:

pathmaster history

  1. Test a restoration to verify backup functionality:

# First make a current backup
pathmaster add . # This creates a backup even if no change is made
# Then try restoring it
pathmaster history # Note the most recent timestamp
pathmaster restore --timestamp <timestamp>

Handling Breaking Changes

If you encounter issues after upgrading:

  1. Restore from backup:

pathmaster restore

  1. Check the documentation for changed behavior

  2. Report issues on GitHub if you believe you’ve found a bug: https://github.com/jwliles/pathmaster/issues

Best Practices for Future Migrations

  1. Always check release notes before upgrading

  2. Create manual backups of shell configuration files before major upgrades

  3. Test in a non-critical environment if possible

  4. Keep note of any custom PATH entries you’ve added manually