# **README**
# pathmaster
## **Table of Contents**
- [**README**](#readme)
- [pathmaster](#pathmaster)
- [**Table of Contents**](#table-of-contents)
- [**Introduction**](#introduction)
- [pathmaster](#pathmaster-1)
- [New in Version 0.2.2](#new-in-version-022)
- [Features](#features)
- [Core Features (Updated in 0.2.2)](#core-features-updated-in-022)
- [Path Management](#path-management)
- [Safety Features](#safety-features)
- [Usage](#usage)
- [Checking PATH Sources](#checking-path-sources)
- [Flushing Invalid Paths](#flushing-invalid-paths)
- [Configuration Files](#configuration-files)
- [Documentation](#documentation)
- [Technical Details](#technical-details)
- [Upgrading](#upgrading)
- [Known Issues](#known-issues)
- [Coming in Future Releases](#coming-in-future-releases)
- [**Features**](#features-1)
- [**Installation**](#installation)
- [**Prerequisites**](#prerequisites)
- [**Building from Source**](#building-from-source)
- [**Usage**](#usage-1)
- [**Command Overview**](#command-overview)
- [**Commands**](#commands)
- [**add**](#add)
- [**remove**](#remove)
- [**list**](#list)
- [**check**](#check)
- [**flush**](#flush)
- [**history**](#history)
- [**restore**](#restore)
- [**Examples**](#examples)
- [**Configuration**](#configuration)
- [**Backup Management**](#backup-management)
- [**Backup Modes**](#backup-modes)
- [**Backup Storage**](#backup-storage)
- [**Contributing**](#contributing)
- [**License**](#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.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
### Checking PATH Sources
```bash
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
```bash
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](https://www.rust-lang.org/tools/install):
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
### **Building from Source**
1. **Clone the Repository**
```bash
git clone https://github.com/jwliles/pathmaster.git
cd pathmaster
```
2. **Build the Project**
```bash
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:
```bash
sudo cp target/release/pathmaster /usr/local/bin/
```
Or add it to your `PATH`:
```bash
export PATH="$PATH:$(pwd)/target/release"
```
## **Usage**
### **Command Overview**
```bash
pathmaster [COMMAND] [OPTIONS]
```
### **Commands**
#### **add**
Add a directory to your `PATH`.
**Usage:**
```bash
pathmaster add <directory>
```
**Options:**
- `<directory>`: The directory path to add to your `PATH`.
#### **remove**
Remove a directory from your `PATH`.
**Usage:**
```bash
pathmaster remove <directory>
```
**Options:**
- `<directory>`: The directory path to remove from your `PATH`.
#### **list**
List all current entries in your `PATH`.
**Usage:**
```bash
pathmaster list
```
#### **check**
Validate current PATH entries and identify invalid or missing directories.
**Usage:**
```bash
pathmaster check
```
**Example Output:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
pathmaster history
```
#### **restore**
Restore your `PATH` from a previous backup.
**Usage:**
```bash
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**
```bash
pathmaster add ~/my/custom/bin
```
- **Remove a Directory from PATH**
```bash
pathmaster remove ~/my/old/bin
```
- **List PATH Entries**
```bash
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**
```bash
pathmaster history
```
**Sample Output:**
```
Available backups:
- backup_20231007_120000.json
- backup_20231008_090000.json
```
- **Restore PATH from a Specific Backup**
```bash
pathmaster restore --timestamp 20231007_120000
```
- **Restore PATH from the Most Recent Backup**
```bash
pathmaster restore
```
## **Configuration**
`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:**
```bash
# 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**
```bash
git checkout -b feature/your-feature
```
3. **Commit Your Changes**
```bash
git commit -am 'Add your feature'
```
4. **Push to the Branch**
```bash
git push origin feature/your-feature
```
5. **Create a Pull Request**
## **License**
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.