#path-environment #path #backup #configuration #restore #env-var #environment

app pathmaster

pathmaster is a powerful command-line tool written in Rust for managing your system's PATH environment variable

4 releases

new 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

Download history 234/week @ 2024-10-19 315/week @ 2024-10-26

549 downloads per month

MIT license

86KB
1.5K SLoC

README

pathmaster

Table of Contents

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.

Dependencies

~5–7.5MB
~130K SLoC