@necto-ai/pgit/README.md

Private file tracking with dual git repositories

# PGit - Private Git Tracking CLI

[![npm version](https://img.shields.io/npm/v/@necto-ai/pgit.svg)](https://www.npmjs.com/package/@necto-ai/pgit)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/typescript-5.0%2B-blue.svg)](https://www.typescriptlang.org/)
[![Build Status](https://img.shields.io/github/actions/workflow/status/my-comp/pgit/ci.yml?branch=main)](https://github.com/my-comp/pgit/actions)
[![Coverage Status](https://img.shields.io/codecov/c/github/my-comp/pgit)](https://codecov.io/gh/my-comp/pgit)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/my-comp/pgit/blob/main/docs/CONTRIBUTING.md)

A powerful CLI tool that enables developers to version control private files within team repositories using a dual git repository system. Keep your sensitive configuration files, environment variables, and personal notes tracked privately while maintaining complete isolation from your team's shared repository.

## 📊 Project Status

- **Stability**: Production Ready ✅
- **Maintenance**: Actively Maintained 🔄
- **Version**: See [releases](https://github.com/my-comp/pgit/releases) for latest version
- **Platform Support**: Windows, macOS, Linux ✅
- **Node.js Support**: 18.x, 20.x, 22.x ✅

## � Taable of Contents

- [What is PGit?](#-what-is-pgit)
- [Enhanced Git Protection](#️-enhanced-git-protection)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Command Reference](#-complete-command-reference)
- [Usage Examples](#-usage-examples)
- [Advanced Features](#-advanced-features)
- [Contributing](#️-how-to-contribute)
- [Community & Support](#community--support)
- [Security & Privacy](#-security--privacy)
- [Troubleshooting](#-troubleshooting)
- [License](#-license)

## 🚀 What is PGit?

PGit solves the common problem of managing private files in shared repositories. It creates a separate, isolated git repository for your private files while maintaining their original locations through symbolic links. This allows you to:

- **Version control private files** like `.env`, API keys, personal configurations
- **Keep files accessible** at their original paths for applications
- **Maintain complete isolation** from the main team repository
- **Collaborate seamlessly** without exposing private content
- **Track changes** with full git capabilities (commit, log, branch, etc.)
- **Automatic git protection** - Files added to pgit are automatically removed from main git tracking and protected from future git add operations

### How It Works

```
Your Project Structure:
├── .git/                    # Main team repository (unchanged)
│   └── info/
│       └── exclude         # ← Enhanced: pgit files automatically excluded here
├── .git-pgit/           # Private git repository (hidden from team)
├── .pgit-storage/       # Actual pgit files storage
│   ├── .env               # Real pgit files stored here
│   └── config.json
├── .env                   # → Symbolic link to .pgit-storage/.env
├── config.json           # → Symbolic link to .pgit-storage/config.json
└── .gitignore            # Automatically excludes pgit system files
```

## 🛡️ Enhanced Git Protection

PGit now includes advanced git protection features to ensure your private files never accidentally get committed to the main repository:

### Automatic Git Removal
When you add files to pgit tracking, they are automatically:
- **Removed from git index** (both tracked and untracked files)
- **Added to `.git/info/exclude`** to prevent future `git add` operations
- **Protected from accidental commits** while remaining accessible to your applications

### How It Works
```bash
# Before: File might accidentally be committed
echo "SECRET_KEY=abc123" > .env
git add .env  # ❌ File gets staged for commit

# After: File is automatically protected
pgit add .env  # ✅ File removed from git tracking
git add .env   # ✅ Git ignores the file (protected by .git/info/exclude)
```

### Protection Features
- **Universal Coverage**: Works for tracked, staged, untracked, and modified files
- **Batch Processing**: Efficiently handles multiple files simultaneously
- **Error Resilience**: Continues operation even if some git operations fail
- **Rollback Support**: Can restore original git state if needed
- **Non-Intrusive**: Only affects files you explicitly add to pgit

## 📦 Installation

### Global Installation (Recommended)

```bash
npm install -g @necto-ai/pgit
```

### Local Development Installation

```bash
# Clone the repository
git clone https://github.com/my-comp/pgit.git
cd pgit

# Install dependencies
npm install

# Build the project
npm run build

# Link for global use
npm link
```

### Verify Installation

```bash
pgit --version
pgit --help
```

## 🎯 Quick Start

### 1. Initialize Private Tracking

```bash
# Navigate to your project directory
cd your-project

# Initialize pgit git tracking
pgit init
```

This creates:
- `.git-pgit/` - Hidden pgit git repository
- `.pgit-storage/` - Storage for your pgit files
- `.pgit-config.json` - Configuration file
- Updates `.gitignore` to exclude pgit system files

### 2. Add Private Files

```bash
# Option 1: Use presets for quick setup
pgit preset apply nodejs-dev  # Adds common Node.js files
pgit preset apply claude-flow  # Adds AI workflow files

# Option 2: Add files individually
pgit add .env
pgit add config/secrets.json
pgit add .env.local

# Option 3: Add entire directory
pgit add personal-notes/
```

### 3. Manage Private Repository

```bash
# Check status of both repositories
pgit status

# Stage changes in pgit repository
pgit add-changes --all

# Commit to pgit repository
pgit commit -m "Update environment variables"

# View pgit commit history
pgit log --oneline
```

## 📚 Complete Command Reference

### Initialization Commands

| Command | Description | Example |
|---------|-------------|---------|
| `pgit init` | Initialize dual repository system | `pgit init` |

### File Management Commands

| Command | Description | Options | Example |
|---------|-------------|---------|---------|
| `pgit add <path>` | Add file/directory to pgit tracking with automatic git protection | `<path>` (required) | `pgit add .env` |
| `pgit status` | Show status of both repositories | `--verbose`, `-v` | `pgit status -v` |
| `pgit-status` | Show detailed pgit repository status | `--verbose`, `-v` | `pgit-status -v` |

### Preset Commands

Presets allow you to quickly add common sets of files for specific workflows. PGit includes built-in presets for popular development scenarios, and you can create your own custom presets.

| Command | Description | Options | Example |
|---------|-------------|---------|---------|
| `pgit preset list` | List all available presets (built-in and user-defined) | `--verbose`, `-v` | `pgit preset list -v` |
| `pgit preset show <name>` | Show details about a specific preset | `<name>` (required) | `pgit preset show claude-flow` |
| `pgit preset apply <name>` | Apply a preset by adding all its paths to pgit tracking | `<name>` (required) | `pgit preset apply nodejs-dev` |
| `pgit preset define <name> <paths...>` | Create a custom user preset with specified paths | `<name>`, `<paths...>` (required) | `pgit preset define my-setup .env dist/ logs/` |
| `pgit preset undefine <name>` | Remove a user-defined preset | `<name>` (required) | `pgit preset undefine my-setup` |

#### Built-in Presets

PGit comes with several useful presets for common development workflows:

- **`claude-flow`** - AI agent workflow files (`.claude/`, `CLAUDE.md`, `memory/`, etc.)
- **`nodejs-dev`** - Node.js development artifacts (`node_modules/`, `.env*`, `dist/`, `build/`, etc.)
- **`python-dev`** - Python development files (`__pycache__/`, `.venv/`, `.pytest_cache/`, etc.)
- **`docs-infra`** - Documentation infrastructure (`docs/`, `mkdocs.yml`, `.vitepress/`, etc.)
- **`docker-dev`** - Docker development files (`.docker/`, `docker-compose.override.yml`, etc.)
- **`vscode-workspace`** - VS Code configuration (`.vscode/`, `*.code-workspace`, etc.)

#### Preset Usage Examples

```bash
# Apply a preset for Node.js development
pgit preset apply nodejs-dev

# View available presets
pgit preset list

# Show details about a specific preset
pgit preset show claude-flow

# Create a custom preset for your workflow
pgit preset define backend-secrets .env .env.local secrets/ config/local.json

# Apply your custom preset
pgit preset apply backend-secrets

# Remove a custom preset
pgit preset undefine backend-secrets
```

### Git Operations Commands

| Command | Description | Options | Example |
|---------|-------------|---------|---------|
| `pgit commit` | Commit changes to pgit repository | `-m <message>` | `pgit commit -m "update secrets"` |
| `pgit add-changes` | Stage modifications to tracked files | `--all`, `-A` | `pgit add-changes --all` |
| `pgit log` | Show commit history | `--oneline`, `-n <num>` | `pgit log --oneline` |
| `pgit diff` | Show differences in pgit repository | `--cached`, `--name-only` | `pgit diff --cached` |
| `pgit branch` | List or create branches | `<branch-name>` | `pgit branch feature` |
| `pgit checkout` | Switch branches or restore files | `<branch>`, `<file>` | `pgit checkout main` |

### Maintenance Commands

| Command | Description | Options | Example |
|---------|-------------|---------|---------|
| `pgit cleanup` | Fix and repair pgit git tracking | `--force` | `pgit cleanup` |

## 💡 Usage Examples

### Managing Environment Files

```bash
# Initialize in your project
pgit init

# Add environment files
pgit add .env
pgit add .env.local
pgit add .env.development

# Your app can still read from .env (symbolic link)
# But the actual file is pgitly tracked

# Make changes and commit
pgit add-changes --all
pgit commit -m "Update API endpoints"
```

### Working with Configuration Files

```bash
# Add configuration files
pgit add config/database.json
pgit add config/api-keys.json

# Create a feature branch for testing
pgit branch testing-config
pgit checkout testing-config

# Make changes and commit
pgit add-changes --all
pgit commit -m "Test new database config"

# Switch back to main
pgit checkout main
```

### Using Presets for Quick Setup

```bash
# Set up a Node.js project with common private files
pgit preset apply nodejs-dev

# Output:
# Applying preset 'nodejs-dev'...
# ✔ Added 'node_modules/' to private tracking.
# ✔ Added '.env' to private tracking.
# ✔ Added '.env.local' to private tracking.
# ⚠ 'dist/' does not exist, skipping.
# ✔ Added 'build/' to private tracking.
# 
# Preset 'nodejs-dev' applied successfully.
# 8 added, 0 skipped, 1 failed (9 total).

# Create a custom preset for your specific workflow
pgit preset define my-backend .env .env.local secrets/ logs/ temp/

# Apply your custom preset to another project
pgit preset apply my-backend

# View all available presets
pgit preset list

# Get details about a specific preset
pgit preset show claude-flow
```

### Checking Repository Status

```bash
# Quick status check
pgit status

# Output:
# 📊 Private Git Tracking Status
# ✓ System is healthy
# 📋 Main Repository - Branch: main, Status: Clean
# 🔒 Private Repository - Branch: main, Status: Has changes

# Detailed pgit repository status
pgit-status --verbose

# View commit history
pgit log --oneline
```

### Enhanced Git Protection Examples

```bash
# Add sensitive files with automatic git protection
pgit add .env
pgit add config/api-keys.json
pgit add personal-todos.txt

# Verify protection is active
git status          # ✅ No pgit files appear
git add .env        # ✅ Ignored due to .git/info/exclude protection

# Check what's protected
cat .git/info/exclude

# Output:
# # @necto-ai/pgit managed exclusions
# .env
# config/api-keys.json
# personal-todos.txt

# Files remain accessible to your applications
node -e "console.log(require('fs').readFileSync('.env', 'utf8'))"
```

### Batch Operations with Protection

```bash
# Add multiple files at once with batch git protection
pgit add .env .env.local config/secrets.json

# All files are automatically protected from git tracking
git status  # Clean - no pgit files visible

# Even if you try to add them manually later
git add .env.local  # Still ignored due to exclude rules
```

## 🔧 Advanced Features

### Branch Management

Create separate branches for different environments or configurations:

```bash
# Create development branch
pgit branch development
pgit checkout development

# Make dev-specific changes
echo "DEV_API_URL=http://localhost:3000" >> .env
pgit add-changes --all
pgit commit -m "Add development API URL"

# Switch between configurations
pgit checkout main      # Production config
pgit checkout development # Development config
```

### Collaborative Workflows

While pgit files remain pgit, you can share configurations with trusted team members:

```bash
# Export pgit repository (to share with trusted colleagues)
cd .pgit-storage
git remote add origin git@github.com:your-org/project-pgit.git
git push -u origin main

# Another team member can clone and set up
git clone git@github.com:your-org/project-pgit.git .pgit-storage
pgit cleanup  # Repairs symbolic links
```

### Backup and Recovery

```bash
# Your pgit repository is a full git repository
cd .pgit-storage
git remote add backup git@github.com:your-org/project-backup.git
git push backup main

# To restore after cleanup or system changes
pgit cleanup --force
```

## 🛠️ How to Contribute

We welcome contributions to the Private Git Tracking CLI! Here's how you can help:

### Development Setup

#### Prerequisites

Before contributing, ensure you have the following installed:

- **Node.js**: Version 18.0.0 or higher ([Download](https://nodejs.org/))
- **npm**: Version 8.0.0 or higher (comes with Node.js)
- **Git**: Latest version ([Download](https://git-scm.com/))
- **Code Editor**: VS Code recommended with TypeScript extension

#### 1. Fork and Clone

```bash
# Fork the repository on GitHub, then clone your fork
git clone https://github.com/your-username/pgit.git
cd pgit

# Add upstream remote for syncing
git remote add upstream https://github.com/my-comp/pgit.git
```

#### 2. Environment Setup

```bash
# Install dependencies
npm install

# Verify installation
npm run build
npm test

# Link for local testing
npm link

# Verify CLI works
pgit --version
```

#### 3. Development Workflow

```bash
# Create a feature branch
git checkout -b feature/your-feature-name

# Start development with watch mode
npm run dev:watch

# Run specific command in development
npm run dev -- init --verbose

# Build the project
npm run build

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode during development
npm run test:watch

# Lint and format code
npm run lint
npm run format

# Type checking
npm run type-check
```

#### 4. Testing Your Changes

```bash
# Run full test suite
npm run test:full

# Test specific functionality
npm test -- --testNamePattern="GitService"

# Test CLI commands locally
mkdir /tmp/test-project
cd /tmp/test-project
git init
pgit init
echo "SECRET=test" > .env
pgit add .env
pgit status

# Cross-platform testing (if available)
npm run test:windows
npm run test:linux
npm run test:macos
```

#### 5. Code Quality Checks

```bash
# Run all quality checks (required before PR)
npm run quality:check

# Individual checks
npm run lint:check          # ESLint validation
npm run format:check        # Prettier validation
npm run type-check          # TypeScript validation
npm run test:coverage       # Test coverage validation
npm run build:check         # Build validation
```

### Project Structure

```
pgit/
├── src/
│   ├── commands/              # Command implementations
│   │   ├── init.command.ts
│   │   ├── add.command.ts
│   │   ├── status.command.ts
│   │   └── ...
│   ├── core/                  # Core business logic
│   │   ├── config.manager.ts
│   │   ├── git.service.ts
│   │   ├── symlink.service.ts
│   │   └── filesystem.service.ts
│   ├── types/                 # TypeScript type definitions
│   ├── utils/                 # Utility functions
│   ├── errors/                # Custom error classes
│   └── cli.ts                 # CLI entry point
├── tests/                     # Test files
├── docs/                      # Documentation
└── dist/                      # Built output
```

### Contribution Guidelines

#### 1. Code Standards & Best Practices

**TypeScript Standards:**
- Use strict mode with full type safety (`strict: true` in tsconfig.json)
- Prefer explicit types over `any` - use `unknown` when type is uncertain
- Use proper generic constraints and conditional types where appropriate
- Follow functional programming principles where possible

**Code Style:**
- **ESLint**: Follow established rules (`npm run lint`) - zero warnings policy
- **Prettier**: Consistent formatting (`npm run format`) - automated on commit
- **Naming**: Use descriptive names (camelCase for variables, PascalCase for classes)
- **Comments**: Write JSDoc for public APIs, inline comments for complex logic

**Testing Requirements:**
- **Coverage**: Maintain >90% test coverage (`npm run test:coverage`)
- **Test Types**: Unit tests for all functions, integration tests for workflows
- **Test Structure**: Use AAA pattern (Arrange, Act, Assert)
- **Mocking**: Mock external dependencies, test real logic

**Performance & Security:**
- Avoid blocking operations in CLI commands
- Validate all user inputs with proper error messages
- Handle file system operations with proper error handling
- Use secure file permissions for sensitive operations

#### 2. Development Workflow

**Branch Strategy:**
```bash
# Feature development
git checkout -b feature/add-branch-management
git checkout -b fix/windows-symlink-issue
git checkout -b docs/improve-readme

# Keep branch up to date
git fetch upstream
git rebase upstream/main
```

**Commit Standards (Conventional Commits):**
```bash
# Feature additions
git commit -m "feat: add git branch management commands"
git commit -m "feat(preset): add python development preset"

# Bug fixes
git commit -m "fix: handle Windows junction points correctly"
git commit -m "fix(git): resolve symbolic link creation on NTFS"

# Documentation
git commit -m "docs: update installation instructions"
git commit -m "docs(api): add JSDoc for GitService methods"

# Tests
git commit -m "test: add cross-platform symbolic link tests"
git commit -m "test(integration): add preset application workflow"

# Refactoring
git commit -m "refactor: extract file system operations to service"
git commit -m "refactor(types): improve configuration type safety"
```

**Code Review Checklist:**
- [ ] All tests pass (`npm run test:full`)
- [ ] Code coverage maintained >90%
- [ ] No linting errors (`npm run lint:check`)
- [ ] Code formatted correctly (`npm run format:check`)
- [ ] TypeScript compiles without errors (`npm run type-check`)
- [ ] Documentation updated for new features
- [ ] Breaking changes documented in commit message
- [ ] Cross-platform compatibility considered

#### 3. Pull Request Process

**Before Creating PR:**
```bash
# Sync with upstream
git fetch upstream
git rebase upstream/main

# Run full quality check
npm run quality:check

# Test CLI functionality end-to-end
npm run test:e2e

# Build and test installation
npm run build
npm pack
npm install -g ./necto-ai-pgit-*.tgz
pgit --version
```

**PR Requirements:**
1. **Clear Title**: Use conventional commit format
2. **Detailed Description**: 
   - What changes were made and why
   - How to test the changes
   - Any breaking changes or migration notes
   - Screenshots/examples for UI changes
3. **Issue References**: Link related issues with "Fixes #123" or "Closes #456"
4. **Testing Instructions**: Step-by-step guide for reviewers
5. **Documentation**: Update relevant docs in the same PR

**PR Template Example:**
```markdown
## Description
Brief description of changes and motivation.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Cross-platform testing (if applicable)

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] No breaking changes (or documented)
```

#### 4. Review Process

**For Contributors:**
- Respond to feedback promptly and professionally
- Make requested changes in separate commits (don't squash during review)
- Update tests and documentation as requested
- Be open to suggestions and alternative approaches

**For Reviewers:**
- Focus on code quality, security, and maintainability
- Provide constructive feedback with examples
- Test the changes locally when possible
- Approve only when all requirements are met

#### 4. Testing & Validation Procedures

**Test Categories:**

```bash
# Unit Tests - Test individual functions and classes
npm run test:unit

# Integration Tests - Test component interactions
npm run test:integration

# End-to-End Tests - Test complete user workflows
npm run test:e2e

# Cross-Platform Tests - Test on different operating systems
npm run test:cross-platform

# Performance Tests - Test CLI response times and memory usage
npm run test:performance
```

**Manual Testing Checklist:**

**Core Functionality:**
- [ ] `pgit init` creates proper directory structure
- [ ] `pgit add <file>` creates symbolic links correctly
- [ ] `pgit status` shows accurate repository states
- [ ] `pgit commit` works with proper git operations
- [ ] Git protection prevents accidental commits

**Cross-Platform Testing:**
- [ ] Windows: Test with both Command Prompt and PowerShell
- [ ] macOS: Test with both bash and zsh shells
- [ ] Linux: Test with various distributions (Ubuntu, CentOS, Alpine)
- [ ] Symbolic links work correctly on all platforms
- [ ] File permissions are handled properly

**Edge Cases:**
- [ ] Large files (>100MB) handling
- [ ] Files with special characters in names
- [ ] Deeply nested directory structures
- [ ] Concurrent operations (multiple pgit commands)
- [ ] Network drive and external storage compatibility

**Validation Scripts:**
```bash
# Run comprehensive validation
npm run validate:all

# Validate specific scenarios
npm run validate:symlinks
npm run validate:git-protection
npm run validate:presets
npm run validate:cross-platform
```

#### 5. Areas for Contribution

**🐛 Bug Fixes**
- Cross-platform compatibility issues
- Symbolic link handling edge cases
- Git operation error handling
- Performance optimizations

**✨ New Features**
- Additional git operations (merge, rebase, stash)
- Configuration templates
- Integration with popular development tools
- Backup and sync features

**📚 Documentation**
- Tutorial guides
- Video examples
- API documentation
- Troubleshooting guides

**🧪 Testing**
- Cross-platform test coverage
- Performance benchmarks
- Integration test scenarios
- Error condition testing

#### 5. Development Tips

**Running Local Tests**
```bash
# Test specific functionality
npm test -- --testNamePattern="ConfigManager"

# Test with coverage
npm run test:coverage

# Test in different environments
docker run -v $(pwd):/app -w /app node:18 npm test
```

**Debugging**
```bash
# Enable verbose output
npm run dev -- status --verbose

# Debug with Node.js debugger
npm run dev:debug -- init
```

**Testing Commands Locally**
```bash
# Build and link for testing
npm run build && npm link

# Test in a temporary directory
mkdir /tmp/test-project
cd /tmp/test-project
git init
pgit init
```

### Code of Conduct

We are committed to providing a welcoming and inclusive environment for all contributors. Please:

- Be respectful and constructive in discussions
- Follow the established coding standards
- Write clear commit messages and documentation
- Test your changes thoroughly
- Help others learn and grow

### Community & Support

#### Getting Help

**📞 Questions & Discussions**
- [GitHub Discussions](https://github.com/my-comp/pgit/discussions) - Ask questions, share ideas
- [Discord Community](https://discord.gg/your-server) - Real-time chat with maintainers and users
- [Stack Overflow](https://stackoverflow.com/questions/tagged/pgit) - Technical Q&A with `pgit` tag
- [Wiki](https://github.com/my-comp/pgit/wiki) - Comprehensive guides and tutorials

**🐛 Bug Reports**
- [Open an Issue](https://github.com/my-comp/pgit/issues/new?template=bug_report.md)
- Include reproduction steps and system information
- Use the bug report template for faster resolution
- Check existing issues before creating new ones

**💡 Feature Requests**
- [Feature Request](https://github.com/my-comp/pgit/issues/new?template=feature_request.md)
- Describe the use case and expected behavior
- Discuss implementation approach and alternatives
- Vote on existing feature requests with 👍

**📚 Documentation**
- [API Documentation](https://my-comp.github.io/pgit/api/)
- [User Guide](https://my-comp.github.io/pgit/guide/)
- [Troubleshooting Guide](https://my-comp.github.io/pgit/troubleshooting/)
- [Migration Guide](https://my-comp.github.io/pgit/migration/)

#### Community Guidelines

**Code of Conduct**
We are committed to providing a welcoming and inclusive environment. Please:
- Be respectful and constructive in all interactions
- Follow our [Code of Conduct](https://github.com/my-comp/pgit/blob/main/docs/CODE_OF_CONDUCT.md)
- Help others learn and grow in the community
- Report any violations to the maintainers

**Recognition**
We value all contributions and recognize contributors through:
- [Contributors page](https://github.com/my-comp/pgit/graphs/contributors)
- Release notes acknowledgments
- Community highlights in discussions
- Contributor badges and achievements

## 🔒 Security & Privacy

- **No data collection**: The CLI operates entirely locally
- **No network requests**: All operations are performed on your local machine
- **Private files stay pgit**: Only you control access to your pgit repository
- **Symbolic links are secure**: Files remain in their expected locations for applications

## 📋 System Requirements

- **Node.js**: 18.0.0 or higher
- **Operating System**: macOS, Linux, or Windows
- **Git**: Must be installed and available in PATH
- **File System**: Must support symbolic links (most modern systems do)

## 🔍 Troubleshooting

### Common Issues

**Q: Symbolic links not working on Windows?**
```bash
# Enable Developer Mode or run as Administrator
# Then run cleanup to recreate links
pgit cleanup --force
```

**Q: Files not showing up in pgit repository?**
```bash
# Check status and stage changes
pgit status
pgit add-changes --all
pgit commit -m "Add missing files"
```

**Q: Main repository shows pgit files?**
```bash
# Ensure .gitignore is updated
pgit cleanup
git status  # Should not show pgit files
```

**Q: Git protection not working - files still appear in git status?**
```bash
# Check if .git/info/exclude is properly configured
cat .git/info/exclude

# Re-run pgit add to ensure protection is applied
pgit add .env

# Verify file is now protected
git add .env  # Should show "nothing to commit" or be ignored
```

**Q: Want to remove git protection for a specific file?**
```bash
# Remove from .git/info/exclude manually
# Edit .git/info/exclude and remove the file path
# Then you can git add it normally
git add previously-protected-file.txt
```

**Q: Permission denied errors?**
```bash
# Check file permissions
ls -la .pgit-storage/
# Fix permissions if needed
chmod 644 .pgit-storage/*
```

### Getting Support

1. **Check the logs**: Enable verbose output with `--verbose` flag
2. **Run cleanup**: `pgit cleanup --force` fixes most issues
3. **Check system requirements**: Ensure Node.js 18+ and git are installed
4. **Open an issue**: Include error messages and system information

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [Commander.js](https://github.com/tj/commander.js/) for CLI framework
- Uses [simple-git](https://github.com/steveukx/git-js) for git operations
- Styled with [Chalk](https://github.com/chalk/chalk) for colored output
- File operations powered by [fs-extra](https://github.com/jprichardson/node-fs-extra)
- Type safety with [Zod](https://github.com/colinhacks/zod) schemas

---

**Made with ❤️ by developers, for developers who value privacy and clean git workflows.**