Files

T

jkunz 0e27d54ad2 feat(cli): split commit and release into target-based workflows

2026-05-10 10:01:09 +00:00

11 KiB

Raw Blame History

@git.zone/cli 🚀

@git.zone/cli is the development workflow CLI behind the gitzone and gzone commands. It helps TypeScript-heavy teams keep projects tidy, create semantic source commits, manage local Docker-backed services, scaffold new modules, and release software through explicit, target-based release configuration.

It is opinionated where that saves time: source commits and releases are separate, changelog entries flow through a standard Pending section, project config lives in .smartconfig.json, and release targets make side effects visible before they happen.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm add -g @git.zone/cli

After installation, both binaries point to the same CLI:

gitzone --help
gzone --help

The Big Idea

gitzone commit handles source history.

gitzone release handles release transactions.

That split is intentional. A commit should not unexpectedly publish npm packages, push Docker images, or trigger remote release pipelines. A release should clearly show which targets it will publish to.

Quick Start

# Preview project standardization work
gitzone format

# Apply formatting changes
gitzone format --write

# Create a semantic source commit
gitzone commit

# Preview the configured release transaction
gitzone release --plan

# Release pending changelog entries to configured targets
gitzone release

Commands

Command	Purpose
`commit`	Analyze changes and create one semantic source commit
`release`	Turn pending changelog entries into a versioned release and publish targets
`format`	Plan or apply project formatting and standardization
`config`	Inspect, update, and migrate `.smartconfig.json`
`services`	Manage local MongoDB, MinIO, and Elasticsearch containers
`template`	Scaffold projects from built-in templates
`meta`	Manage multi-repository workspaces
`open`	Open repository assets like CI pages
`docker`	Run Docker maintenance tasks
`deprecate`	Deprecate npm packages across registries
`start`	Prepare an existing project for local work
`helpers`	Run small helper utilities

Global flags include --help, --json, --plain, --agent, --no-interactive, and --no-check-updates.

Commit Workflow

gitzone commit creates one semantic source commit. It does not bump versions, create tags, publish packages, or push Docker images.

# Interactive semantic commit
gitzone commit

# Read-only AI recommendation
gitzone commit recommend --json

# Auto-accept safe recommendations
gitzone commit -y

# Auto-accept, test, build, and push
gitzone commit -ytbp

# Show the resolved workflow without mutating anything
gitzone commit --plan

The commit flow:

Analyze the working tree.
Suggest commit type, scope, and message.
Write a human-readable entry into changelog.md under ## Pending.
Stage and create one semantic source commit.
Optionally run formatting, tests, build, and push based on flags or config.

Commit flags:

Flag	Meaning
`-y`, `--yes`	Auto-accept safe recommendations
`-t`, `--test`	Add test step
`-b`, `--build`	Add build step
`-p`, `--push`	Push after the source commit
`-f`, `--format`	Run `gitzone format --write` before commit
`--plan`	Show resolved workflow only

-r is intentionally not part of commit anymore. Use gitzone release.

Release Workflow

gitzone release performs the release core once, then publishes to configured targets.

The release core is not configurable plumbing. It always follows the same professional release transaction:

Run configured preflight checks.
Read changelog.md ## Pending entries.
Infer or accept a semver bump.
Update version files and baked commit info.
Move pending changelog entries into the new version section.
Create the local release commit.
Create the local release tag.

Targets decide what happens after that:

Target	What it does
`git`	Pushes the release commit and tags, often triggering remote CI release builds
`npm`	Publishes the package to configured npm registries
`docker`	Builds and pushes configured Docker images

# Preview the resolved release plan
gitzone release --plan

# Release to configured targets
gitzone release

# Release only to npm
gitzone release --target npm

# Release only to git and Docker
gitzone release --target git,docker

# Skip package/container publishing and keep only git target
gitzone release --no-publish

# Override inferred semver level
gitzone release --minor

Release flags:

Flag	Meaning
`-y`, `--yes`	Run without interactive confirmation
`-t`, `--test`	Enable preflight tests
`-b`, `--build`	Enable preflight build
`-p`, `--push`	Enable the `git` target
`--target <csv>`	Use only selected targets, e.g. `git,npm`
`--npm`	Enable the `npm` target
`--docker`	Enable the `docker` target
`--no-publish`	Keep release core and `git` target only
`--no-build`	Disable preflight build for this run
`--major`, `--minor`, `--patch`	Override inferred semver level
`--plan`	Show resolved workflow only

Standard Changelog

The changelog is convention-based and intentionally not configured.

gitzone commit appends entries to:

## Pending

gitzone release moves those pending entries into a dated version section:

## 2026-05-10 - 2.15.0

The standard buckets are Breaking Changes, Features, Fixes, Documentation, and Maintenance.

Configuration

All CLI config lives under @git.zone/cli in .smartconfig.json.

{
  "@git.zone/cli": {
    "schemaVersion": 2,
    "projectType": "npm",
    "commit": {
      "confirmation": "prompt",
      "steps": ["analyze", "test", "build", "changelog", "commit", "push"]
    },
    "release": {
      "confirmation": "prompt",
      "preflight": {
        "requireCleanTree": true,
        "test": false,
        "build": true
      },
      "targets": {
        "git": {
          "enabled": true,
          "remote": "origin",
          "pushBranch": true,
          "pushTags": true
        },
        "npm": {
          "enabled": true,
          "registries": ["https://registry.npmjs.org"],
          "accessLevel": "public",
          "alreadyPublished": "success"
        },
        "docker": {
          "enabled": false,
          "images": []
        }
      }
    }
  }
}

NPM registries belong only here:

@git.zone/cli.release.targets.npm.registries

Useful config commands:

# Show current @git.zone/cli config
gitzone config show --json

# Read the npm release target registries
gitzone config get release.targets.npm.registries

# Add an npm release target registry
gitzone config add https://registry.npmjs.org

# Set npm target access level
gitzone config access public

# Run schema migration to v2
gitzone config migrate 2

Formatting

gitzone format is dry-run by default. That makes it safe to run in any repo.

# Preview changes
gitzone format

# Emit a machine-readable plan
gitzone format plan --json

# Apply changes
gitzone format --write

# Apply without prompt
gitzone format --write --yes

Formatters include cleanup, smartconfig normalization, dependency license checks, package metadata normalization, template updates, .gitignore, TypeScript config, Prettier, README existence checks, and configured copy operations.

Development Services

gitzone services manages local Docker-backed services for development projects.

Supported services:

Service	Aliases
MongoDB	`mongo`, `mongodb`
MinIO	`minio`, `s3`
Elasticsearch	`elasticsearch`, `es`

# Start configured services
gitzone services start

# Enable specific services non-interactively
gitzone services set mongodb,minio

# Check status
gitzone services status

# Print MongoDB Compass connection string
gitzone services compass

# Show logs
gitzone services logs mongo 50

# Stop containers but keep data
gitzone services stop

# Remove containers and data
gitzone services clean

Service config is stored in .nogit/env.json. Data is stored below .nogit/, so it stays out of Git.

Templates

Start new projects with built-in scaffolds:

gitzone template npm
gitzone template service
gitzone template website
gitzone template wcc

Templates are rendered through SmartScaf and then can be normalized with gitzone format.

Meta Repositories

Use gitzone meta when one workspace coordinates multiple repositories.

gitzone meta init
gitzone meta add frontend https://example.com/org/frontend.git
gitzone meta update
gitzone meta remove frontend

Other Utilities

# Docker cleanup
gitzone docker prune

# Open GitLab CI settings or pipelines for the current repo
gitzone open ci
gitzone open pipelines

# Deprecate an old npm package interactively
gitzone deprecate

# Prepare a project for local work
gitzone start

# Generate a short unique ID
gitzone helpers shortid

Troubleshooting

Format only previews changes:

gitzone format --write

Release says there is nothing to release:

# Make sure commits have populated the Pending changelog section
gitzone commit

Docker services fail to start:

docker info
gitzone services status
gitzone services reconfigure

Config looks outdated:

gitzone config migrate 2
gitzone config show --json

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

11 KiB Raw Blame History