pathmaster 0.3.0

pathmaster is a powerful command-line tool written in Rust for managing your system's PATH environment variable.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

# 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:

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

2. **Review your current PATH** to understand what's in it:

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

3. **Add your custom directories** using pathmaster:

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

4. **Check your PATH** to verify everything looks correct:

```bash
pathmaster list
```

5. **Remove any invalid entries**:

```bash
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**:

```bash
pathmaster --help
```

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

```bash
# 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:

```bash
pathmaster check
```

2. **Review your backups** to ensure they're working properly:

```bash
pathmaster history
```

3. **Test a restoration** to verify backup functionality:

```bash
# 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**:

```bash
pathmaster restore
```

2. **Check the documentation** for changed behavior

3. **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