README

pathmaster

Table of Contents

• README
• pathmaster
  • Table of Contents
  • Introduction
• pathmaster
  • New in Version 0.2.3
  • Features
    • Backup Management
  • New in Version 0.2.2
  • Features
    • Core Features (Updated in 0.2.2)
    • Path Management
    • Safety Features
  • Usage
    • Backup Mode Configuration
    • Checking PATH Sources
    • Flushing Invalid Paths
  • Configuration Files
  • Documentation
  • Technical Details
  • Upgrading
  • Known Issues
  • Coming in Future Releases
  • Features
  • Installation
    • Prerequisites
    • Building from Source
  • Usage
    • Command Overview
    • Commands
      • add
      • remove
      • list
      • check
      • flush
      • history
      • restore
    • Examples
  • Configuration
  • Backup Management
    • Backup Modes
    • Backup Storage
  • Contributing
  • License

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:

1. Backup your current configuration
2. Update using your package manager or cargo
3. Review any system-wide PATH modifications
4. 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

1. Clone the Repository

   git clone https://github.com/jwliles/pathmaster.git
   cd pathmaster
   

2. Build the Project

   cargo build --release
   

   This command compiles the project in release mode, producing an optimized binary.

3. 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 your PATH.

remove

Remove a directory from your PATH.

Usage:

pathmaster remove <directory>

Options:

• <directory>: The directory path to remove from your PATH.

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:

1. Creates a backup of current PATH
2. Creates a backup of shell configuration file
3. Identifies invalid directory entries
4. Removes invalid entries from PATH
5. Updates shell configuration for persistence
6. 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 entries
• shell: Back up only shell configuration
• switch: 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

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the Repository

2. Create a Feature Branch

   git checkout -b feature/your-feature
   

3. Commit Your Changes

   git commit -am 'Add your feature'
   

4. Push to the Branch

   git push origin feature/your-feature
   

5. Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.