4 releases
0.2.3 | Oct 28, 2024 |
---|---|
0.2.2 | Oct 27, 2024 |
0.2.1 | Oct 25, 2024 |
0.1.0 | Oct 23, 2024 |
#100 in Filesystem
573 downloads per month
86KB
1.5K
SLoC
README
pathmaster
Table of Contents
- README
- pathmaster
- pathmaster
Introduction
pathmaster is a powerful command-line tool written in Rust for managing your system's PATH
environment variable. It simplifies the process of adding and removing directories from your PATH
, ensures backups are created automatically, and provides tools to restore previous configurations.
Managing the PATH
variable is crucial for system performance and command execution. pathmaster
provides a safe and efficient way to handle PATH
modifications, with features designed to prevent errors and maintain system stability.
pathmaster
New in Version 0.2.3
- Configurable backup modes for selective backup creation
- Interactive mode switching functionality
- Enhanced shell configuration handling
- Improved backup system flexibility
- Better documentation and user feedback
Features
Backup Management
- Flexible backup modes:
- PATH-only backups
- Shell-only backups
- Combined backups (default)
- Easy mode switching
- Automatic backup creation
- Comprehensive backup history
- Safe configuration preservation
New in Version 0.2.2
- Enhanced PATH validation and scanning capabilities
- Improved detection of PATH modifications across system
- Accurate identification of PATH entry sources
- Better handling of different shell configurations
- Fixed issues with PATH entry detection and validation
Features
Core Features (Updated in 0.2.2)
- Enhanced PATH Scanning: More accurate detection of PATH modifications
- Source Identification: Identifies whether PATH modifications require sudo
- Improved Validation: Better handling of different PATH modification formats
- Shell Support: Enhanced detection of shell-specific configurations
- Framework Integration: Better support for shell framework configurations
- Safety Features: Automatic backups, configuration preservation, validation
Path Management
- Add/remove directories from PATH
- List current PATH entries
- Validate PATH entries
- Automatic backups
- Configuration preservation
- Detailed feedback
Safety Features
- Automatic backups before modifications
- Shell configuration preservation
- Detailed user feedback
- Recovery options
Usage
Backup Mode Configuration
# Only back up PATH when adding a directory
pathmaster --backup-mode path add ~/bin
# Only back up shell config when flushing invalid paths
pathmaster --backup-mode shell flush
# Reset to backing up both
pathmaster --backup-mode default
# Toggle between backup modes
pathmaster --backup-mode switch
Checking PATH Sources
pathmaster check
Now provides enhanced output showing:
- Invalid directories in PATH
- Source of each PATH modification
- Whether sudo is required for changes
- Shell-specific configuration details
Flushing Invalid Paths
pathmaster flush
Improved in v0.2.2 with:
- More accurate invalid path detection
- Better feedback for removed paths
- Enhanced shell configuration handling
- Improved backup creation
Configuration Files
pathmaster now better handles various configuration files:
- Shell-specific files (.bashrc, .zshrc)
- System-wide configurations (/etc/profile, etc.)
- Shell framework configurations
- Distribution-specific locations
Documentation
Please see the man page (man pathmaster
) for detailed information about all commands and features.
Technical Details
For v0.2.2, significant improvements were made to:
- PATH modification detection
- Shell configuration handling
- System vs user file differentiation
- Framework integration
- Error handling and reporting
Upgrading
When upgrading to v0.2.2:
- Backup your current configuration
- Update using your package manager or cargo
- Review any system-wide PATH modifications
- Check shell framework compatibility
Known Issues
None in current release.
Coming in Future Releases
- Backup mode configuration (v0.2.3)
- Additional shell framework support
- Enhanced configuration options
- Performance optimizations
Features
- Effortless Management: Easily add or remove directories from your
PATH
. - Automatic Backups: Creates time-stamped backups of your
PATH
before any changes. - Restoration: Restore your
PATH
from any previous backup. - Listing: View all current entries in your
PATH
. - Cross-Platform: Compatible with Unix/Linux and macOS systems.
- Safe Modifications: Validates directories before adding them to prevent errors.
- Persistent Changes: Updates your shell configuration to make changes permanent.
- Enhanced Path Validation: Robust detection and removal of invalid PATH entries
- Shell Configuration Safety: Automatic backup of shell configuration files before modifications
- Detailed Feedback: Clear reporting of all PATH modifications and their outcomes
- Session and Permanent Changes: Updates both current session and shell configuration files
Installation
Prerequisites
-
Rust Toolchain: Ensure you have Rust installed. You can install Rust using rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Building from Source
-
Clone the Repository
git clone https://github.com/jwliles/pathmaster.git cd pathmaster
-
Build the Project
cargo build --release
This command compiles the project in release mode, producing an optimized binary.
-
Install the Binary
Optionally, you can install the binary system-wide:
sudo cp target/release/pathmaster /usr/local/bin/
Or add it to your
PATH
:export PATH="$PATH:$(pwd)/target/release"
Usage
Command Overview
pathmaster [COMMAND] [OPTIONS]
Commands
add
Add a directory to your PATH
.
Usage:
pathmaster add <directory>
Options:
<directory>
: The directory path to add to yourPATH
.
remove
Remove a directory from your PATH
.
Usage:
pathmaster remove <directory>
Options:
<directory>
: The directory path to remove from yourPATH
.
list
List all current entries in your PATH
.
Usage:
pathmaster list
check
Validate current PATH entries and identify invalid or missing directories.
Usage:
pathmaster check
Example Output:
Invalid directories in PATH:
/home/user/.config/emacs/bin
/home/user/old/scripts
flush
The flush
command provides a safe way to remove invalid directories from your PATH:
Usage:
pathmaster flush
# or
pathmaster -f
Process:
- Creates a backup of current PATH
- Creates a backup of shell configuration file
- Identifies invalid directory entries
- Removes invalid entries from PATH
- Updates shell configuration for persistence
- Provides detailed feedback about changes
Safety Features:
- Automatic PATH backup creation
- Shell configuration file backup
- Detailed removal reporting
- Recovery options via backup system
- Session-only fallback if configuration update fails
Example Output:
Created backup of shell config at: /home/user/.bashrc.bak
Removing invalid path: /home/user/.config/emacs/bin
Removing invalid path: /home/user/old/scripts
Successfully removed 2 invalid path(s) and updated shell configuration.
history
Show the backup history of your PATH
.
Usage:
pathmaster history
restore
Restore your PATH
from a previous backup.
Usage:
pathmaster restore [--timestamp <timestamp>]
Options:
--timestamp <timestamp>
: (Optional) The timestamp of the backup to restore. If not provided, the most recent backup is used.
Examples
-
Add a Directory to PATH
pathmaster add ~/my/custom/bin
-
Remove a Directory from PATH
pathmaster remove ~/my/old/bin
-
List PATH Entries
pathmaster list
Sample Output:
Current PATH entries: - /usr/local/bin - /usr/bin - /bin - /usr/local/sbin - /usr/sbin - /sbin - ~/my/custom/bin
-
Show Backup History
pathmaster history
Sample Output:
Available backups: - backup_20231007_120000.json - backup_20231008_090000.json
-
Restore PATH from a Specific Backup
pathmaster restore --timestamp 20231007_120000
-
Restore PATH from the Most Recent Backup
pathmaster restore
Configuration
pathmaster now supports configurable backup modes to provide more control over what gets backed up during operations. This can be especially useful when:
- You want to focus on PATH management without shell configuration changes
- You need to manage shell configurations separately
- You want to minimize backup file creation
- You're testing different PATH configurations
pathmaster
modifies your shell configuration file to make changes to PATH
persistent across sessions.
- Supported Shells: Bash (
.bashrc
), Zsh (.zshrc
), or a generic.profile
if the shell is not recognized. - Backup Directory: Backups are stored in
~/.pathmaster_backups
.
Note: Always review changes made to your shell configuration files. pathmaster
adds an export command to update your PATH
.
Backup Management
pathmaster provides flexible backup management with configurable backup modes:
Backup Modes
Use the --backup-mode
flag to control what gets backed up:
default
: Back up both PATH and shell configurations (default behavior)path
: Back up only PATH entriesshell
: Back up only shell configurationswitch
: Toggle between PATH-only and shell-only backups
Examples:
# Only back up PATH when adding a directory
pathmaster --backup-mode path add ~/bin
# Only back up shell config when flushing invalid paths
pathmaster --backup-mode shell flush
# Reset to backing up both
pathmaster --backup-mode default
# Toggle between backup modes
pathmaster --backup-mode switch
Backup Storage
- PATH Backups: Stored as JSON files in
~/.pathmaster_backups
- Shell Configuration Backups: Created as
.bak
files alongside your shell config:- Bash:
~/.bashrc.bak
- Zsh:
~/.zshrc.bak
- Generic:
~/.profile.bak
- Bash:
Contributing
Contributions are welcome! Please follow these steps:
-
Fork the Repository
-
Create a Feature Branch
git checkout -b feature/your-feature
-
Commit Your Changes
git commit -am 'Add your feature'
-
Push to the Branch
git push origin feature/your-feature
-
Create a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Dependencies
~5–7.5MB
~127K SLoC