Web Commit Review Tool

A powerful web-based Git commit review tool that provides an intuitive interface for browsing branches, reviewing commits, and managing Git worktrees. Available as both a standalone web application and an Electron desktop app.

Features

• Branch Management: Browse and switch between Git branches with ease
• Commit History: View detailed commit history with diffs and file changes
• Worktree Support: Create and manage Git worktrees for parallel development
• Real-time Updates: WebSocket-based real-time synchronization of Git state
• Cross-platform: Works on Windows, macOS, and Linux
• Multiple Modes: Run as a web server or standalone Electron application
• Developer-friendly: Built with modern web technologies (Vue.js, Express, WebSockets)

Installation

Global Installation (Recommended)

npm install -g @starpower/web-commit-review

Local Installation

npm install @starpower/web-commit-review

Development Setup

# Clone the repository
git clone https://github.com/yourusername/web-commit-review.git
cd web-commit-review

# Install dependencies
pnpm install

# Start development server
make dev

Usage

Command Line Interface

Electron Mode (Default)

Launch the tool as a desktop application:

web-commit-review [options]

Browser Mode

Launch as a web server and open in your default browser:

web-commit-review --browser [options]

CLI Options

Options:
  -p, --port <port>       Port to run the server on (default: 3000)
  -d, --dir <directory>   Git repository directory (default: current directory)
  -b, --browser           Launch in browser mode instead of Electron
  --no-open               Don't automatically open the browser (browser mode only)
  -h, --help              Display help information
  -v, --version           Display version number

Examples

# Open current repository in Electron app
web-commit-review

# Open specific repository
web-commit-review -d /path/to/repo

# Launch in browser on custom port
web-commit-review --browser -p 8080

# Start server without opening browser
web-commit-review --browser --no-open

API Endpoints

The tool exposes a RESTful API for Git operations:

Branches

• GET /api/branches - List all branches
• POST /api/checkout - Checkout a branch
• POST /api/branches - Create a new branch
• DELETE /api/branches/:name - Delete a branch

Commits

• GET /api/commits/:branch - Get commits for a branch
• GET /api/commit/:hash - Get detailed commit information
• GET /api/diff/:hash - Get commit diff

Worktrees

• GET /api/worktrees - List all worktrees
• POST /api/worktrees - Create a new worktree
• DELETE /api/worktrees/:path - Remove a worktree

Repository

• GET /api/status - Get repository status
• GET /api/remotes - List remotes
• POST /api/fetch - Fetch from remote
• POST /api/pull - Pull changes
• POST /api/push - Push changes

Development

Project Structure

web-commit-review/
├── bin/                    # CLI entry points
│   ├── web-commit-review.js
│   └── web-commit-review-electron.js
├── lib/                    # Core application logic
│   ├── server.js          # Express server
│   ├── electron-main.js   # Electron main process
│   └── git-operations.js  # Git command wrapper
├── public/                 # Frontend assets
│   ├── index.html
│   ├── css/
│   └── js/
├── src/                    # Frontend source (if using build tools)
├── package.json
├── Makefile               # Project management commands
└── README.md

Available Make Commands

# Development
make help          # Show all available commands
make install       # Install dependencies
make dev           # Start development server
make build         # Build for production

# Testing & Quality
make lint          # Run code linting
make format        # Format code
make test          # Run tests
make check         # Run all checks

# Version Management
make version       # Display current version
make bump-patch    # Bump patch version (1.0.X)
make bump-minor    # Bump minor version (1.X.0)
make bump-major    # Bump major version (X.0.0)

# Git Operations
make tag           # Create git tag for current version
make push-tag      # Push tag to remote
make changelog     # Generate changelog from commits

# Publishing
make publish       # Publish to npm
make publish-dry   # Dry run of npm publish

# Release Workflows
make release-patch # Complete patch release (bump + tag + publish)
make release-minor # Complete minor release
make release-major # Complete major release

# Cleanup
make clean         # Clean build artifacts
make clean-all     # Deep clean including node_modules

Building from Source

# Install dependencies
make install

# Run development server
make dev

# Build for production
make build

# Run tests and linting
make check

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Commit Convention

We use Conventional Commits specification:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Test additions or modifications
• chore: Maintenance tasks
• perf: Performance improvements

Configuration

Environment Variables

Create a .env file in the project root:

PORT=3000
HOST=localhost
GIT_DIR=/path/to/default/repo
ELECTRON_DISABLE_SECURITY_WARNINGS=true

Git Configuration

The tool respects your global Git configuration. Ensure you have Git properly configured:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Troubleshooting

Common Issues

Port Already in Use

# Kill process on port 3000
lsof -ti:3000 | xargs kill -9

# Or use a different port
web-commit-review -p 3001

Permission Denied

# Fix permissions
chmod +x bin/web-commit-review.js
chmod +x bin/web-commit-review-electron.js

Git Repository Not Found

Ensure you're running the command from within a Git repository or specify the path:

web-commit-review -d /path/to/git/repo

Debug Mode

Enable debug logging:

DEBUG=* web-commit-review

Requirements

• Node.js >= 16.0.0
• Git >= 2.0.0
• npm or pnpm

Browser Support

• Chrome/Chromium (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Security

This tool runs a local web server that executes Git commands. It's designed for local development use only. Do not expose the server to public networks.

Security Features

• CORS protection enabled
• Input sanitization for Git commands
• No authentication (localhost only)
• Read-only mode option available

License

MIT License - see LICENSE file for details.

Acknowledgments

• Built with Vue.js for the frontend
• Express.js for the backend server
• Simple Git for Git operations
• Electron for desktop app packaging
• Commander.js for CLI interface

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

Roadmap

• [ ] Dark mode support
• [ ] Multi-repository management
• [ ] Git LFS support
• [ ] Commit message templates
• [ ] Integration with CI/CD pipelines
• [ ] Plugin system for extensions
• [ ] Mobile responsive design
• [ ] Offline mode with caching
• [ ] Advanced diff visualization
• [ ] Code review annotations

Changelog

See CHANGELOG.md for a detailed history of changes.

Authors

• Your Name - Initial work

Contributors

Thanks to all contributors who have helped improve this project!

Happy Reviewing! 🚀