git.zone/cli
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(deps,readme): bump dependencies and update README to prefer pnpm and document semantic commit flags

Browse Source
This commit is contained in:
Jürgen Kunz
2026-03-11 19:10:18 +00:00
parent 4ab59609e6
commit b65fac6257
6 changed files with 740 additions and 2960 deletions
Download Patch File Download Diff File Expand all files Collapse all files

455
readme.md
View File

@@ -18,11 +18,11 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
### Installation
```bash
# Install globally via npm
npm install -g @git.zone/cli
# Or with pnpm (recommended)
# Install globally via pnpm (recommended)
pnpm add -g @git.zone/cli
# Or with npm
npm install -g @git.zone/cli
```
Once installed, you can use either `gitzone` or the shorter `gzone` command from anywhere in your terminal.
@@ -33,9 +33,12 @@ Once installed, you can use either `gitzone` or the shorter `gzone` command from
# Create a new TypeScript npm package
gitzone template npm
# Format your entire codebase
# Format your entire codebase (dry-run by default)
gitzone format
# Apply formatting changes
gitzone format --write
# Start local MongoDB and MinIO services
gitzone services start
@@ -45,34 +48,146 @@ gitzone commit
## 🛠️ Core Features
### 🔀 Semantic Commits & Versioning
Create standardized commits with AI-powered suggestions that automatically handle versioning:
```bash
# Interactive commit with AI recommendations
gitzone commit
# Auto-accept AI recommendations (skipped for BREAKING CHANGEs)
gitzone commit -y
# Auto-accept, push, build, and release
gitzone commit -ypbr
```
**Flags:**
| Flag | Long Form | Description |
|------|-----------|-------------|
| `-y` | `--yes` | Auto-accept AI recommendations |
| `-p` | `--push` | Push to remote after commit |
| `-t` | `--test` | Run tests before committing |
| `-b` | `--build` | Build after commit, verify clean tree |
| `-r` | `--release` | Publish to configured npm registries |
| | `--format` | Run format before committing |
**Workflow steps:**
1. 🤖 **AI-powered analysis** — analyzes your changes and suggests commit type, scope, and message
2. 📝 Interactive commit message builder (type: `fix`/`feat`/`BREAKING CHANGE`, scope, description)
3. 📜 Automatic changelog generation
4. 🏷️ Automatic version bumping (major/minor/patch) with git tag creation
5. 🔨 Optional build & verification
6. 🚀 Optional push to origin
7. 📦 Optional publish to npm registries
Supports both npm (`package.json`) and Deno (`deno.json`) projects, including dual-type projects.
### 🎨 Intelligent Code Formatting
Automatically format and standardize your entire codebase. **Dry-run by default** — nothing changes until you explicitly use `--write`:
```bash
# Preview what would change (default behavior)
gitzone format
# Apply changes
gitzone format --write
# Auto-approve without prompts
gitzone format --yes --write
# Show detailed diffs
gitzone format --diff
# Enable verbose logging
gitzone format --verbose
```
**Flags:**
| Flag | Description |
|------|-------------|
| `--write` / `-w` | Apply changes (default is dry-run) |
| `--yes` | Auto-approve without interactive confirmation |
| `--plan-only` | Only show what would be done |
| `--save-plan <file>` | Save the format plan to a file |
| `--from-plan <file>` | Load and execute a saved plan |
| `--detailed` | Show detailed stats and save report |
| `--parallel` / `--no-parallel` | Toggle parallel execution |
| `--verbose` | Enable verbose logging |
| `--diff` | Show file diffs |
**Formatters (executed in order):**
1. 🧹 **Cleanup** — removes obsolete files (yarn.lock, package-lock.json, tslint.json, etc.)
2. ⚙️ **Npmextra** — formats and standardizes `npmextra.json`
3. 📜 **License** — ensures proper licensing and checks dependency licenses
4. 📦 **Package.json** — standardizes package configuration
5. 📋 **Templates** — applies project template updates
6. 🙈 **Gitignore** — updates repository ignore rules
7. 🔧 **Tsconfig** — optimizes TypeScript configuration
8. ✨ **Prettier** — applies code formatting
9. 📖 **Readme** — ensures readme files exist
10. 📂 **Copy** — copies configured files
### 🐳 Development Services Management
Effortlessly manage local MongoDB and MinIO (S3-compatible) services for your development environment:
Effortlessly manage local development services (MongoDB, MinIO S3, Elasticsearch) with Docker:
```bash
gitzone services [command]
```
**Available commands:**
**Commands:**
- **`start [service]`** - Start services (mongo|s3|all)
- **`stop [service]`** - Stop services (mongo|s3|all)
- **`restart [service]`** - Restart services
- **`status`** - Show current service status
- **`config`** - Display configuration details
- **`compass`** - Get MongoDB Compass connection string with network IP
- **`logs [service] [lines]`** - View service logs
- **`remove`** - Remove containers (preserves data)
- **`clean`** - Remove containers AND data (⚠️ destructive)
| Command | Description |
|---------|-------------|
| `start [service]` | Start services (`mongo`\|`s3`\|`elasticsearch`\|`all`) |
| `stop [service]` | Stop services |
| `restart [service]` | Restart services |
| `status` | Show current service status |
| `config` | Display configuration details |
| `compass` | Get MongoDB Compass connection string with network IP |
| `logs [service] [lines]` | View service logs (default: 20 lines) |
| `reconfigure` | Reassign ports and restart all services |
| `remove` | Remove containers (preserves data) |
| `clean` | Remove containers AND data (⚠️ destructive) |
**Service aliases:**
- `mongo` / `mongodb` — MongoDB
- `minio` / `s3` — MinIO (S3-compatible storage)
- `elasticsearch` / `es` — Elasticsearch
- `all` — All services (default)
**Key features:**
- 🎲 **Smart port assignment** - Automatically assigns random ports (20000-30000) to avoid conflicts
- 📦 **Project isolation** - Each project gets its own containers with unique names
- 💾 **Data persistence** - Data stored in `.nogit/` directories survives container restarts
- 🔗 **MongoDB Compass support** - Instantly get connection strings for GUI access
- 🌐 **Network IP detection** - Automatically detects your local network IP for remote connections
- ⚙️ **Auto-configuration** - Creates `.nogit/env.json` with smart defaults
- 🎲 **Smart port assignment** — automatically assigns random ports (20000–30000) to avoid conflicts
- 📦 **Project isolation** — each project gets its own containers with unique names
- 💾 **Data persistence** — data stored in `.nogit/` survives container restarts
- 🔗 **MongoDB Compass support** — instantly get connection strings for GUI access
- 🌐 **Network IP detection** — detects your local network IP for remote connections
- ⚙️ **Auto-configuration** — creates `.nogit/env.json` with smart defaults
**Global operations (`-g` flag):**
```bash
# List all registered projects
gitzone services list -g
# Show status across all projects
gitzone services status -g
# Stop all containers across all projects
gitzone services stop -g
# Remove stale registry entries
gitzone services cleanup -g
```
**Example workflow:**
@@ -94,7 +209,26 @@ gitzone services logs mongo 50
gitzone services stop
```
The services are configured via `.nogit/env.json` which is automatically created with secure defaults and random ports for each project.
### ⚙️ Release & Commit Configuration
Manage release registries and commit settings:
```bash
gitzone config [subcommand]
```
| Command | Description |
|---------|-------------|
| `show` | Display current release config (registries, access level) |
| `add [url]` | Add a registry URL (default: `https://registry.npmjs.org`) |
| `remove [url]` | Remove a registry URL (interactive selection if no URL) |
| `clear` | Clear all registries (with confirmation) |
| `access [public\|private]` | Set npm access level for publishing |
| `commit alwaysTest [true\|false]` | Always run tests before commit |
| `commit alwaysBuild [true\|false]` | Always build after commit |
| `services` | Configure which services are enabled |
Configuration is stored in `npmextra.json` under the `@git.zone/cli` key.
### 📦 Project Templates
@@ -104,12 +238,12 @@ Instantly scaffold production-ready projects with best practices built-in:
gitzone template [template-name]
```
**Available templates:**
**Interactive templates:**
- **`npm`** - TypeScript npm package with testing, CI/CD, and full tooling
- **`service`** - Microservice architecture with Docker support
- **`website`** - Modern web application with LitElement and service workers
- **`wcc`** - Web Component Collection for reusable UI components
- **`npm`** — TypeScript npm package with testing, CI/CD, and full tooling
- **`service`** — Microservice architecture with Docker support
- **`website`** — Modern web application with LitElement and service workers
- **`wcc`** — Web Component Collection for reusable UI components
Each template comes pre-configured with:
@@ -119,94 +253,6 @@ Each template comes pre-configured with:
- ✅ Code formatting and linting
- ✅ Documentation structure
### 🎨 Intelligent Code Formatting
The most powerful feature of gitzone - automatically format and standardize your entire codebase:
```bash
# Preview changes without applying them
gitzone format --dry-run
# Format with automatic approval
gitzone format --yes
# Save formatting plan for later execution
gitzone format --save-plan format-plan.json
# Execute a saved plan
gitzone format --from-plan format-plan.json
# Enable verbose output for debugging
gitzone format --verbose
```
**Format features:**
- 🔄 **Smart caching** - Only processes changed files
- 🛡️ **Rollback support** - Undo formatting changes if needed
- 📊 **Detailed reporting** - See exactly what changed
- ⚡ **Parallel execution** - Format multiple files simultaneously
- 🎯 **Module-specific formatting** - Target specific formatters
**Rollback capabilities:**
```bash
# List all available backups
gitzone format --list-backups
# Rollback to the last operation
gitzone format --rollback
# Rollback to a specific operation
gitzone format --rollback [operation-id]
# Clean old backups
gitzone format --clean-backups
```
**Formatters included:**
- **Prettier** - JavaScript/TypeScript code formatting
- **License** - Ensure proper licensing
- **Package.json** - Standardize package configurations
- **Tsconfig** - TypeScript configuration optimization
- **Readme** - Documentation formatting
- **Gitignore** - Repository ignore rules
- **Templates** - Project template updates
- **Npmextra** - Extended npm configurations
- **Cleanup** - Removes obsolete files (yarn.lock, package-lock.json, tslint.json, etc.)
### 🔀 Semantic Commits & Versioning
Create standardized commits with AI-powered suggestions that automatically handle versioning:
```bash
# Interactive commit with AI recommendations
gitzone commit
# Auto-accept AI recommendations
gitzone commit -y
# Auto-accept and push
gitzone commit -y -p
```
Features:
- 🤖 **AI-powered analysis** - Analyzes your changes and suggests commit type, scope, and message
- 📝 Interactive commit message builder with smart defaults
- 🏷️ Automatic version bumping (major/minor/patch)
- 📜 Changelog generation
- 🚀 Optional auto-push to origin
- 🎯 Conventional commit compliance
The commit wizard guides you through:
1. **Type selection** (fix/feat/BREAKING CHANGE) with AI recommendation
2. **Scope definition** (component/module affected)
3. **Description crafting**
4. **Version bump determination**
### 🏗️ Meta Repository Management
Manage multiple related repositories as a cohesive unit:
@@ -218,36 +264,22 @@ gitzone meta init
# Add a sub-project
gitzone meta add [name] [git-url]
# Update all sub-projects
# Update all sub-projects (clone missing, clean superfluous)
gitzone meta update
# Remove a sub-project
gitzone meta remove [name]
```
Perfect for:
- Monorepo management
- Multi-package projects
- Coordinated deployments
- Synchronized versioning
### 🐳 Docker Management
Streamline your Docker workflow:
```bash
# Clean up all Docker resources
# Clean up all Docker resources (containers, images, volumes, networks)
gitzone docker prune
```
This command removes:
- Stopped containers
- Unused images
- Dangling volumes
- Unused networks
### 🔗 Quick CI/CD Access
Jump directly to your CI/CD configurations:
@@ -270,12 +302,7 @@ Smoothly transition users from old to new packages:
gitzone deprecate
```
Interactive wizard for:
- Setting deprecation notices
- Guiding users to replacements
- Updating registry metadata
- Coordinating migration paths
Interactive wizard that prompts for registry URLs, old package name, and new package name — then runs `npm deprecate` across all specified registries.
### 🚦 Project Initialization
@@ -285,17 +312,10 @@ Prepare existing projects for development:
gitzone start
```
Automatically:
- Checks out master branch
- Pulls latest changes
- Installs dependencies
- Sets up development environment
Automatically checks out master, pulls latest changes, and installs dependencies.
### 🔧 Helper Utilities
Quick utilities for common tasks:
```bash
# Generate a unique short ID
gitzone helpers shortid
@@ -303,31 +323,44 @@ gitzone helpers shortid
## 📋 Configuration
### npmextra.json Configuration
### npmextra.json
Customize gitzone behavior through `npmextra.json`:
```json
{
"@git.zone/cli": {
"projectType": "npm",
"release": {
"registries": [
"https://registry.npmjs.org"
],
"accessLevel": "public"
},
"commit": {
"alwaysTest": false,
"alwaysBuild": false
}
},
"gitzone": {
"format": {
"interactive": true,
"showDiffs": false,
"autoApprove": false,
"parallel": true,
"rollback": {
"showStats": true,
"cache": {
"enabled": true,
"autoRollbackOnError": true,
"backupRetentionDays": 7
"clean": true
},
"modules": {
"skip": ["prettier"],
"only": [],
"order": []
},
"cache": {
"enabled": true,
"clean": true
"licenses": {
"allowed": ["MIT", "Apache-2.0"],
"exceptions": {
"some-package": "GPL-3.0"
}
}
}
}
@@ -336,35 +369,9 @@ Customize gitzone behavior through `npmextra.json`:
### Environment Variables
- `CI` - Detect CI environment for automated workflows
- `DEBUG` - Enable debug output
- `GITZONE_FORMAT_PARALLEL` - Control parallel formatting
## 🏆 Best Practices
### For New Projects
1. Start with a template: `gitzone template npm`
2. Set up local services: `gitzone services start`
3. Customize the generated structure
4. Run initial format: `gitzone format`
5. Set up CI/CD: `gitzone open ci`
### For Existing Projects
1. Initialize: `gitzone start`
2. Format codebase: `gitzone format --dry-run` (preview first!)
3. Apply formatting: `gitzone format --yes`
4. Set up services: `gitzone services start`
5. Commit changes: `gitzone commit`
### For Teams
1. Document format preferences in `npmextra.json`
2. Share `.nogit/env.json` template for consistent service setup
3. Use `--save-plan` for reviewable format changes
4. Enable rollback for safety
5. Standardize commit conventions
- `CI` — Detect CI environment for automated workflows
- `DEBUG` — Enable debug output
- `GITZONE_FORMAT_PARALLEL` — Control parallel formatting
## 🎯 Common Workflows
@@ -383,8 +390,9 @@ gitzone services start
# 4. Check service logs if needed
gitzone services logs mongo
# 5. Format code
# 5. Preview format changes, then apply
gitzone format
gitzone format --write
# 6. Commit with semantic versioning
gitzone commit
@@ -393,6 +401,13 @@ gitzone commit
gitzone services stop
```
### Automated CI/CD Commit
```bash
# Auto-accept, test, build, push, and release in one command
gitzone commit -ytbpr
```
### Multi-Repository Management
```bash
@@ -408,29 +423,26 @@ gitzone meta add shared https://github.com/org/shared.git
gitzone meta update
```
### Safe Formatting with Rollback
### Safe Formatting with Plan Review
```bash
# 1. Preview changes
gitzone format --dry-run
# 1. Preview changes (default)
gitzone format
# 2. Save plan for review
gitzone format --save-plan format-changes.json
# 3. Apply formatting
gitzone format --from-plan format-changes.json
# 4. If something goes wrong, rollback
gitzone format --rollback
# 3. Apply from saved plan
gitzone format --from-plan format-changes.json --write
```
### Database-Driven Development
```bash
# 1. Start MongoDB and MinIO
# 1. Start MongoDB, MinIO, and Elasticsearch
gitzone services start
# 2. Get connection string for your app
# 2. Get connection details
gitzone services config
# 3. Connect with MongoDB Compass
@@ -447,43 +459,44 @@ gitzone services clean # ⚠️ Warning: deletes data
### CI/CD Platforms
- **GitLab CI** - Full pipeline support with templates
- **GitHub Actions** - Automated workflows
- **Docker** - Container-based deployments
- **GitLab CI** — full pipeline support with templates
- **GitHub Actions** — automated workflows
- **Docker** — container-based deployments
### Development Tools
- **TypeScript** - First-class support
- **Prettier** - Code formatting
- **npm/pnpm** - Package management
- **MongoDB** - Local database service
- **MinIO** - S3-compatible object storage
- **MongoDB Compass** - Database GUI integration
- **TypeScript** — first-class support
- **Prettier** — code formatting
- **pnpm** — package management
- **MongoDB** — local database service
- **MinIO** — S3-compatible object storage
- **Elasticsearch** — search and analytics
- **MongoDB Compass** — database GUI integration
### Version Control
- **Git** - Deep integration
- **Semantic Versioning** - Automatic version bumping
- **Conventional Commits** - Standardized commit messages
- **Git** — deep integration
- **Semantic Versioning** — automatic version bumping
- **Conventional Commits** — standardized commit messages
- **AI-Powered Analysis** — intelligent commit suggestions via `@git.zone/tsdoc`
## 💡 Pro Tips
1. **Use aliases**: Add `alias gz='gitzone'` to your shell profile
2. **Combine commands**: `gitzone format --yes && gitzone commit`
2. **Combine flags**: `gitzone commit -ypbr` for the full auto workflow
3. **Leverage templates**: Start projects right with proven structures
4. **Enable caching**: Dramatically speeds up formatting operations
5. **Save format plans**: Review changes before applying in production
5. **Save format plans**: Review changes before applying
6. **Port management**: Let services auto-assign ports to avoid conflicts
7. **Use MongoDB Compass**: `gitzone services compass` for visual DB management
8. **Global service management**: `gitzone services status -g` to see all projects' services at once
## 🐛 Troubleshooting
### Format Command Shows "Cancelled"
If the format command shows cancelled even after confirming:
- Check your `npmextra.json` configuration
- Try with `--yes` flag to skip confirmation
- Try with `--yes --write` flags
- Use `--verbose` for detailed output
### Docker Commands Fail
@@ -496,19 +509,20 @@ docker info
### Services Won't Start
Check for port conflicts:
```bash
# Services auto-assign ports, but you can check the config
cat .nogit/env.json
# Verify Docker is running
docker ps
# Reassign ports if there are conflicts
gitzone services reconfigure
```
### Template Creation Issues
Verify npm/pnpm is properly configured:
Verify pnpm/npm is properly configured:
```bash
npm config get registry
@@ -524,12 +538,11 @@ npm config get registry
gitzone is optimized for speed:
- **Parallel processing** for format operations
- **Smart caching** to avoid redundant work
- **Incremental updates** for meta repositories
- **Minimal dependencies** for fast installation
- **Isolated services** prevent resource conflicts
- **Auto port assignment** eliminates manual configuration
- ⚡ **Parallel processing** for format operations
- 🧠 **Smart caching** to avoid redundant work
- 📊 **Incremental updates** for meta repositories
- 🐳 **Isolated services** prevent resource conflicts
- 🎲 **Auto port assignment** eliminates manual configuration
## License and Legal Information