GitSet CLI

🛡️ Safe & Smart Git Repository Management 🛡️

Enhanced git init with user configuration management - never commit with wrong account details again!

🚀 Features

• 🎯 Smart Git Initialization: Initialize repositories with correct user configuration
• 🛡️ Safe Repository Handling: Detects existing repositories and only updates configuration
• 📁 Directory Auto-Creation: Creates directory paths recursively (like mkdir -p)
• ⚠️ Account Validation: Prevents commits with unintended account information
• 🌍 Cross-Platform Support: Works on macOS, Linux, and Windows
• 🔧 Auto-Installation: Automatically install Git if not present
• 💬 Interactive Prompts: User-friendly configuration workflow with smart defaults
• 🌐 Global Config Integration: Uses existing global settings as defaults, only sets local repository config
• 📍 Absolute Path Display: Shows complete file paths in results

📦 Installation

npm install -g gitset

🎯 Usage

Basic Usage

# Interactive mode - prompts for directory (default: ./my-project)
gitset

# Initialize in specific directory
gitset /path/to/project

# Initialize with relative path
gitset ./my-new-project

# Use global configuration without prompting
gitset --global
gitset -g

# Show help and available options
gitset --help

Interactive Mode

When you run gitset, the tool will:

1. 🎨 Display a welcome screen
2. 🔍 Check if Git is installed (auto-install if needed)
3. 📁 Prompt for directory path (default: ./my-project)
4. 🔍 Check if Git repository already exists in target directory
5. ⚠️ If repository exists: Ask to update user configuration only
6. 👤 Ask for your name and email (with global config as defaults)
7. 📁 Create directory if it doesn't exist (recursive creation)
8. ✅ Initialize repository or update configuration safely
9. 🎉 Show success message with absolute path and next steps

🛠️ Development

Prerequisites

• Node.js 18+
• pnpm package manager

Setup

# Clone the repository
git clone <repository-url>
cd gitset

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the project
pnpm build

# Run in development mode
pnpm dev

Testing

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run specific test file
pnpm test git-detector.test.ts

Code Quality

# Lint code
pnpm lint

# Format code
pnpm format

Docker Testing Environment

For testing Git auto-installation functionality in environments without Git pre-installed, you can use our Docker-based testing setup:

# Make the test script executable
chmod +x run-test-docker.sh

# Run Docker test environment
./run-test-docker.sh

Testing Git Auto-Installation

Once inside the Docker container, you can test various scenarios:

Scenario 1: Verify Git is not installed

# Check Git installation status
git --version
# Expected: bash: git: not found

# Check available package managers
which apk && echo "APK available" || echo "APK not found"

Scenario 2: Test gitset auto-installation

# Run gitset in development mode
pnpm dev

# The tool should:
# 1. Display welcome screen
# 2. Detect Git is not installed
# 3. Prompt for automatic installation
# 4. Use APK package manager to install Git
# 5. Continue with normal workflow

Scenario 3: Manual Git installation test

# Install Git manually first
apk add git

# Verify installation
git --version

# Run gitset again (should skip installation step)
pnpm dev

Scenario 4: Test built version

# Test the compiled version
node dist/cli/index.js

# Or create a test directory
mkdir test-project
cd test-project
node ../dist/cli/index.js

Platform-Specific Testing

The Docker environment uses Alpine Linux, which allows testing:

• APK package manager integration
• Linux platform detection
• Auto-installation workflow in minimal environments
• Error handling for missing dependencies

Expected Behavior

In the Docker environment, gitset should:

1. ✅ Detect Alpine Linux platform
2. ✅ Identify APK as available package manager
3. ✅ Prompt user for Git installation
4. ✅ Execute apk add git command
5. ✅ Verify Git installation success
6. ✅ Continue with repository initialization

Troubleshooting Docker Tests

If you encounter issues:

# Rebuild Docker image
docker build -f Dockerfile -t gitset-test . --no-cache

# Check Docker logs
docker logs <container-id>

# Access container with different shell
docker run -it --rm gitset-test /bin/sh

🏗️ Architecture

src/
├── cli/           # Command line interface & argument parsing
├── config/        # Constants, messages, and configuration
├── core/          # Core business logic
│   ├── config-manager.ts     # Git operations & repository handling
│   ├── git-detector.ts       # Git installation detection
│   ├── git-installer.ts      # Cross-platform Git installation
│   └── workflow-orchestrator.ts # Main workflow coordination
├── types/         # TypeScript type definitions
├── ui/            # User interface components
│   ├── prompts.ts           # Interactive prompts & user input
│   └── welcome.ts           # Welcome screen & result display
└── utils/         # Utility functions
    ├── error-handler.ts     # Error handling & user-friendly messages
    ├── git-command-executor.ts # Git command execution with caching
    └── validation.ts        # Input validation & path resolution

Key Components

• WorkflowOrchestrator: Coordinates the entire process flow
• ConfigManager: Handles Git repository initialization and configuration updates
• UserPrompts: Manages all user interactions and input validation
• GitDetector: Detects Git installation and retrieves global configuration
• ValidationUtils: Path resolution, directory creation, and input validation

🧪 Testing Strategy

This project follows Test-Driven Development (TDD) principles:

1. Write failing tests for new features
2. Implement minimal code to make tests pass
3. Refactor while keeping tests green

Test coverage includes:

• CLI argument parsing
• Git detection and installation
• User input validation
• Repository initialization
• Error handling scenarios

🌍 Cross-Platform Support

Git Installation Methods

macOS:

• Homebrew: brew install git
• Xcode Command Line Tools: xcode-select --install
• Manual download from official website

Linux:

• APT (Ubuntu/Debian): sudo apt-get install git
• YUM (RHEL/CentOS): sudo yum install git
• DNF (Fedora): sudo dnf install git
• Pacman (Arch): sudo pacman -S git
• Zypper (openSUSE): sudo zypper install git

Windows:

• Windows Package Manager: winget install Git.Git
• Chocolatey: choco install git
• Scoop: scoop install git
• Manual download from official website

🚨 Error Handling

The tool provides comprehensive error handling for:

• Git not installed (with auto-installation options)
• Permission denied (directory access issues)
• Invalid directory paths (path resolution errors)
• Invalid email formats (email validation)
• Network connectivity issues (during Git installation)
• Installation failures (fallback methods provided)
• Directory creation failures (insufficient permissions)
• Existing repository conflicts (safe handling with user choice)

Each error includes:

• Clear error message with context
• Suggested solutions and alternatives
• Troubleshooting steps for common issues
• Recovery options when possible
• Safe exit without data loss

📝 Examples

Standard Workflow

$ git-start

   ____ _ _   ____       _   
  / ___(_) |_/ ___|  ___| |_ 
 | |  _| | __\___ \ / _ \ __|
 | |_| | | |_ ___) |  __/ |_ 
  \____|_|\__|____/ \___|\__|

Enhanced git init with user configuration management

📋 This tool will help you:
   ✅ Initialize a new Git repository
   ✅ Configure your user information correctly
   ✅ Avoid commits with wrong account details
   ✅ Install Git automatically if needed

📁 Enter the directory path for git initialization: (./my-project) ./my-new-project
👤 Configure Git user information:
? 📝 Enter your name: (Global User) John Doe
? 📧 Enter your email: ([email protected]) [email protected]

✅ Successfully initialized git repository in /absolute/path/to/my-new-project
📝 Configured with: John Doe <[email protected]>

💡 Next steps:
   • Add your files: git add .
   • Create initial commit: git commit -m "Initial commit"
   • Add remote origin: git remote add origin <url>
   • Push to remote: git push -u origin main

Existing Repository Workflow

When working with existing repositories:

$ gitset

📁 Enter the directory path for git initialization: (./my-project) ./existing-repo
📁 Git repository already exists in this directory. Do you want to update the user configuration? (y/N) y
👤 Configure Git user information:
? 📝 Enter your name: (Old User) John Doe
? 📧 Enter your email: ([email protected]) [email protected]

✅ Successfully updated git configuration in /absolute/path/to/existing-repo
📝 Configured with: John Doe <[email protected]>

Directory Creation Example

For non-existent paths:

$ gitset

📁 Enter the directory path for git initialization: (./my-project) ./path/to/new/deep/directory
👤 Configure Git user information:
? 📝 Enter your name: John Doe
? 📧 Enter your email: [email protected]

✅ Successfully initialized git repository in /absolute/path/to/new/deep/directory
📝 Configured with: John Doe <[email protected]>

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes following TDD principles
4. Add tests for new functionality
5. Ensure all tests pass: pnpm test
6. Test the built version: pnpm build && node dist/cli/index.js
7. Update documentation if needed
8. Commit your changes: git commit -m 'Add amazing feature'
9. Push to the branch: git push origin feature/amazing-feature
10. Open a Pull Request

Development Guidelines

• Follow the existing code structure and patterns
• Maintain comprehensive test coverage
• Use TypeScript strictly (no any types)
• Handle errors gracefully with user-friendly messages
• Test both new and existing repository scenarios
• Ensure cross-platform compatibility

📄 License

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

🆘 Support

• 🐛 Bug Reports: GitHub Issues
• 📧 Email: [email protected]