PGit - Private Git Tracking CLI

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 for latest version
• Platform Support: Windows, macOS, Linux ✅
• Node.js Support: 18.x, 20.x, 22.x ✅

� Taable of Contents

• What is PGit?
• Enhanced Git Protection
• Installation
• Quick Start
• Command Reference
• Usage Examples
• Advanced Features
• Contributing
• Community & Support
• Security & Privacy
• Troubleshooting
• 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

# 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)

npm install -g @necto-pro/pgit

Local Development Installation

# 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

pgit --version
pgit --help

🎯 Quick Start

1. Initialize Private Tracking

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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-pro/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

# 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:

# 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:

# Export pgit repository (to share with trusted colleagues)
cd .pgit-storage
git remote add origin [email protected]:your-org/project-pgit.git
git push -u origin main

# Another team member can clone and set up
git clone [email protected]:your-org/project-pgit.git .pgit-storage
pgit cleanup  # Repairs symbolic links

Backup and Recovery

# Your pgit repository is a full git repository
cd .pgit-storage
git remote add backup [email protected]: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)
• npm: Version 8.0.0 or higher (comes with Node.js)
• Git: Latest version (Download)
• Code Editor: VS Code recommended with TypeScript extension

1. Fork and Clone

# 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

# 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

# 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

# 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

# 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:

# 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):

# 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:

# 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-pro-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:

## 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:

# 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:

# 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

# 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

# Enable verbose output
npm run dev -- status --verbose

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

Testing Commands Locally

# 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 - Ask questions, share ideas
• Discord Community - Real-time chat with maintainers and users
• Stack Overflow - Technical Q&A with pgit tag
• Wiki - Comprehensive guides and tutorials

🐛 Bug Reports

• Open an Issue
• 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
• Describe the use case and expected behavior
• Discuss implementation approach and alternatives
• Vote on existing feature requests with 👍

📚 Documentation

• API Documentation
• User Guide
• Troubleshooting Guide
• Migration Guide

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
• 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
• 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?

# Enable Developer Mode or run as Administrator
# Then run cleanup to recreate links
pgit cleanup --force

Q: Files not showing up in pgit repository?

# Check status and stage changes
pgit status
pgit add-changes --all
pgit commit -m "Add missing files"

Q: Main repository shows pgit files?

# Ensure .gitignore is updated
pgit cleanup
git status  # Should not show pgit files

Q: Git protection not working - files still appear in git status?

# 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?

# 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?

# 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 file for details.

🙏 Acknowledgments

• Built with Commander.js for CLI framework
• Uses simple-git for git operations
• Styled with Chalk for colored output
• File operations powered by fs-extra
• Type safety with Zod schemas

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