k3nny
37db8e97ca
- refuse to release when the clone is shallow and no previous release tag is found: tags beyond the fetch depth would silently restart versioning at X.Y.0; --allow-shallow bypasses the guard for a true first release - new --check preflight validates the release environment without releasing: branch resolution + pattern, working tree, tag discovery, shallow clone, remote origin URL parse (same parse the push performs), push auth method, version files, release target — all problems reported at once, non-zero exit on failure - .releaser.gitlab-ci.yml gains an optional .releaser:check MR-pipeline job; CI examples now set GIT_DEPTH: 0 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
74 lines
2.9 KiB
Markdown
74 lines
2.9 KiB
Markdown
---
|
|
title: CLI Reference
|
|
weight: 20
|
|
---
|
|
|
|
## Common workflows
|
|
|
|
```bash
|
|
# Scaffold a default .releaser.yml
|
|
releaser --init
|
|
|
|
# Preview next version (no side effects)
|
|
releaser --dry-run
|
|
|
|
# Full release: bump versions, commit, tag, push, create release
|
|
releaser
|
|
|
|
# Commit and tag locally — skip push and release creation
|
|
releaser --no-push
|
|
|
|
# Push commit and tag but skip creating the release
|
|
releaser --no-release
|
|
|
|
# Update files but stop before committing
|
|
releaser --no-commit
|
|
# ... review changes, then commit manually and re-run:
|
|
releaser --tag-only
|
|
|
|
# Verbose mode: show config sources, commit analysis, version decision
|
|
releaser --verbose --dry-run
|
|
```
|
|
|
|
## Flags
|
|
|
|
| Flag | Default | Description |
|
|
|------|---------|-------------|
|
|
| `--dry-run` | false | Print next version and exit without making any changes |
|
|
| `--check` | false | Preflight: validate branch, working tree, remote URL, push auth, version files, and release target without releasing |
|
|
| `--branch <name>` | auto-detected | Override branch name (detached HEAD falls back to `CI_COMMIT_BRANCH`, `CI_COMMIT_REF_NAME`, `GITHUB_REF_NAME`) |
|
|
| `--branch-pattern <regex>` | `^(?:.*/)?release/(\d+)\.(\d+)$` | Override branch pattern (two capture groups: major, minor) |
|
|
| `--tag-prefix <prefix>` | `""` | Prefix for version tags (e.g. `v` → `v1.2.3`) |
|
|
| `--pom <path>` | `pom.xml` | Path to pom.xml relative to repo root |
|
|
| `--gradle <path>` | — | Override `gradle.build_file` from config |
|
|
| `--pyproject <path>` | — | Override `python.pyproject_toml` from config |
|
|
| `--changelog-file <path>` | `CHANGELOG.md` | Path to changelog file |
|
|
| `--release-env-file <path>` | `release.env` | Path for dotenv artifact; pass `""` to disable |
|
|
| `--allow-shallow` | false | Proceed in a shallow clone even when no previous release tag is found |
|
|
| `--no-commit` | false | Update version files but stop before committing |
|
|
| `--no-push` | false | Commit and tag locally, skip push and release |
|
|
| `--no-release` | false | Push branch and tag but skip release creation |
|
|
| `--tag-only` | false | Skip version file updates — tag HEAD and push |
|
|
| `--init` | false | Scaffold a default `.releaser.yml` and exit |
|
|
| `--verbose` | false | Print config table, commit analysis, and version decision |
|
|
|
|
## Exit codes
|
|
|
|
| Code | Meaning |
|
|
|------|---------|
|
|
| `0` | Success |
|
|
| `1` | Error (config, git, API, etc.) |
|
|
| `2` | No releasable commits found — nothing to do |
|
|
|
|
## Version bump rules
|
|
|
|
By default all releasable commits bump the **patch** component (minor is pinned to the branch). Override per commit type via `git.bump_rules` in `.releaser.yml`:
|
|
|
|
| Commit type | Default | Configurable via `bump_rules` |
|
|
|-------------|---------|-------------------------------|
|
|
| `fix:` | patch | `fix: "minor"` to bump minor |
|
|
| `feat:` | patch | `feat: "minor"` to bump minor |
|
|
| `feat!:` / `BREAKING CHANGE` | patch | `breaking: "minor"` to bump minor |
|
|
| `chore:`, `docs:`, etc. | none | — |
|
|
| unparseable message | none | non-strict: silently ignored |
|