{"id":34246485,"url":"https://github.com/wislertt/zerv","last_synced_at":"2026-03-11T05:15:24.010Z","repository":{"id":309159546,"uuid":"1035330472","full_name":"wislertt/zerv","owner":"wislertt","description":"Automatic versioning for every commit - Generate semantic versions from any commit across all branches, or dirty working directory, with seamless pre-release handling and flexible format support for any CI/CD workflow.","archived":false,"fork":false,"pushed_at":"2026-02-11T14:13:19.000Z","size":1565,"stargazers_count":14,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-11T17:29:00.438Z","etag":null,"topics":["cicd","cli","cli-tool","devops","pep440","rust","rust-cli-apps","semver","versioning"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wislertt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-10T06:51:21.000Z","updated_at":"2026-02-11T09:49:15.000Z","dependencies_parsed_at":"2026-01-05T16:04:46.763Z","dependency_job_id":null,"html_url":"https://github.com/wislertt/zerv","commit_stats":null,"previous_names":["wisarootl/zerv","wislertt/zerv"],"tags_count":151,"template":false,"template_full_name":null,"purl":"pkg:github/wislertt/zerv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wislertt%2Fzerv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wislertt%2Fzerv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wislertt%2Fzerv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wislertt%2Fzerv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wislertt","download_url":"https://codeload.github.com/wislertt/zerv/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wislertt%2Fzerv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29373837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T08:51:36.827Z","status":"ssl_error","status_checked_at":"2026-02-12T08:51:26.849Z","response_time":55,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cicd","cli","cli-tool","devops","pep440","rust","rust-cli-apps","semver","versioning"],"created_at":"2025-12-16T07:03:28.773Z","updated_at":"2026-02-12T17:00:41.133Z","avatar_url":"https://github.com/wislertt.png","language":"Rust","readme":"[![tests](https://img.shields.io/github/actions/workflow/status/wislertt/zerv/cd.yml?branch=main\u0026label=tests\u0026logo=github)](https://github.com/wislertt/zerv/actions/workflows/cd.yml)\n[![release](https://img.shields.io/github/actions/workflow/status/wislertt/zerv/cd.yml?branch=main\u0026label=release\u0026logo=github)](https://github.com/wislertt/zerv/actions/workflows/cd.yml)\n[![quality gate status](https://sonarcloud.io/api/project_badges/measure?project=wislertt_zerv\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=wislertt_zerv)\n[![security rating](https://sonarcloud.io/api/project_badges/measure?project=wislertt_zerv\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=wislertt_zerv)\n[![vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=wislertt_zerv\u0026metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=wislertt_zerv)\n[![codecov](https://img.shields.io/codecov/c/github/wislertt/zerv?token=549GL6LQBX\u0026label=codecov\u0026logo=codecov)](https://codecov.io/gh/wislertt/zerv)\n[![crates.io](https://img.shields.io/crates/v/zerv?color=green)](https://crates.io/crates/zerv)\n[![pypi](https://img.shields.io/pypi/v/zerv-version.svg?color=blue)](https://pypi.python.org/pypi/zerv-version)\n[![crates.io downloads](https://img.shields.io/crates/d/zerv?label=crates.io%20downloads\u0026color=green)](https://crates.io/crates/zerv)\n[![pypi downloads](https://static.pepy.tech/personalized-badge/zerv-version?period=total\u0026units=international_system\u0026left_color=grey\u0026right_color=blue\u0026left_text=pypi%20downloads)](https://pepy.tech/projects/zerv-version)\n[![python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue?logo=python)](https://github.com/wislertt/zerv/)\n\n# zerv\n\n**Automatic versioning for every commit** - Generate semantic versions from any commit across all branches, or dirty working directory, with seamless pre-release handling and flexible format support for any CI/CD workflow.\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Key Features](#key-features)\n- [Usage Examples](#usage-examples)\n    - [zerv flow: Automated branch-based versions](#zerv-flow-automated-branch-based-versions)\n    - [zerv version: Manual control with 4 main capability areas](#zerv-version-manual-control-with-4-main-capability-areas)\n    - [zerv check: Validate version formats](#zerv-check-validate-version-formats)\n    - [zerv render: Format conversion](#zerv-render-format-conversion)\n    - [Python API](#python-api)\n- [Installation](#installation)\n- [Links](#links)\n\n## Quick Start\n\n**Smart Version Detection**: `zerv flow` automatically generates meaningful SemVer versions from any Git state - no manual configuration required for common workflows.\n\n```bash\n# Install (Python via uv)\nuv tool install zerv-version\n\n# Try automated versioning (current branch determines output)\nzerv flow\n# → 1.0.0 (on main branch with tag v1.0.0)\n# → 1.0.1-rc.1.post.3 (on release branch with pre-release tag)\n# → 1.0.1-beta.1.post.3+develop.3.gf297dd0 (on develop branch)\n# → 1.0.1-alpha.59394.post.1+feature.new.auth.1.g4e9af24 (on feature branch)\n# → 1.0.1-alpha.17015.post.1.dev.1764382150+feature.dirty.work.1.g54c499a (on dirty feature branch)\n```\n\n\u003c!-- Corresponding test: tests/integration_tests/flow/docs/quick_start.rs:test_quick_start_documentation_examples --\u003e\n\n- **Multiple Format Generation**: Transform a single ZERV_RON output into various formats (see [`.github/workflows/shared-zerv-versioning.yml`](.github/workflows/shared-zerv-versioning.yml) for example implementation)\n\n```bash\n# (on dirty feature branch)\nZERV_RON=$(zerv flow --output-format zerv)\n\n# semver\necho $ZERV_RON | zerv version --source stdin --output-format semver\n# → 1.0.1-alpha.17015.post.1.dev.1764382150+feature.dirty.work.1.g54c499a\n\n# pep440\necho $ZERV_RON | zerv version --source stdin --output-format pep440\n# → 1.0.0a17015.post1.dev1764382150+feature.dirty.work.1.g54c499a\n\n# docker_tag\necho $ZERV_RON | zerv version --source stdin --output-template \"{{ semver_obj.docker }}\"\n# → 1.0.1-alpha.17015.post.1.dev.1764382150-feature.dirty.work.1.g54c499a\n\n# v_semver\necho $ZERV_RON | zerv version --source stdin --output-prefix v --output-format semver\n# → v1.0.1-alpha.17015.post.1.dev.1764382150+feature.dirty.work.1.g54c499a\n\n# v_major (schema-based approach)\necho $ZERV_RON | \\\n    zerv version --source stdin \\\n         --schema-ron '(core:[var(Major)], extra_core:[], build:[])' \\\n         --output-prefix v --output-format pep440\n# → v1\n\n# v_major_minor (schema-based approach)\necho $ZERV_RON | \\\n    zerv version --source stdin \\\n         --schema-ron '(core:[var(Major), var(Minor)], extra_core:[], build:[])' \\\n         --output-prefix v --output-format pep440\n# → v1.0\n\n# v_major_custom (custom template-based approach)\necho $ZERV_RON | zerv version --source stdin --output-template \"v{{ major | default(value=\\\"0\\\") }}\"\n# → v1\n\n# v_major_minor_custom (custom template-based approach)\necho $ZERV_RON | zerv version --source stdin --output-template \"v{{ major | default(value=\\\"0\\\") }}{{ prefix_if(value=minor, prefix=\\\".\\\") }}\"\n# → v1.0\n```\n\n\u003c!-- Corresponding test: tests/integration_tests/flow/docs/quick_start.rs:fn test_quick_start_shared_zerv_versioning_github_actions_documentation_examples() {\n --\u003e\n\n## Key Features\n\n- **zerv version**: Flexible, configurable version generation with full control\n- **zerv flow**: Opinionated, automated pre-release management based on Git branches\n- **Smart Schema System**: Auto-detects clean releases, pre-releases, and build context\n- **Multiple Formats**: SemVer, PEP440 (Python), CalVer, custom schemas\n- **CI/CD Integration**: Complements semantic release with branch-based pre-releases and full override control\n\n## Usage Examples\n\n### zerv flow: Automated branch-based versions\n\n**Purpose**: Intelligent pre-release management that automatically generates meaningful versions from any Git state without manual decisions.\n\n#### Core Principles\n\n1. **Semantic state capture** - Extract semantic meaning from ANY Git state (any branch, any commit, uncommitted changes)\n2. **Multi-format output** - Transform semantic meaning into various version formats with customizable format support\n3. **Seamless semantic release integration** - Work with semantic release tools while providing fully automated pre-release versioning\n4. **Build traceability** - Include sufficient context to trace versions back to exact Git states\n\n#### Version Format Explained\n\n**Full Example**: `1.0.1-alpha.12345.post.3.dev.1729924622+feature.auth.1.f4a8b9c`\n\n**Structure**: `\u003cBASE\u003e-\u003cPRE_RELEASE\u003e.\u003cPOST\u003e[.\u003cDEV\u003e][+BUILD_CONTEXT]`\n\n- **`1.0.1`** - Base version (semantic meaning from tags)\n- **`alpha.12345`** - Pre-release type and branch identification\n- **`post.3`** - Commits since reference point\n- **`[.dev.timestamp]`** - Optional dev timestamp for uncommitted changes\n- **`[+BUILD_CONTEXT]`** - Optional build context for traceability\n\n**Key Point**: The core version `\u003cBASE\u003e-\u003cPRE_RELEASE\u003e.\u003cPOST\u003e[.\u003cDEV\u003e]` contains all semantic meaning needed to understand Git state. The build context `[+BUILD_CONTEXT]` is optional and provides additional verbose information for easier interpretation and traceability.\n\n**Version Variations**:\n\n- **Tagged release**: `1.0.1`\n- **Tagged pre-release**: `2.0.1-rc.1.post.2`\n- **Branch from Tagged release**: `1.0.1-alpha.54321.post.1+feature.login.1.f4a8b9c`\n- **Branch from Tagged pre-release**: `2.0.1-alpha.98765.post.3+fix.auth.bug.1.c9d8e7f`\n- **Uncommitted changes**: `2.0.1-alpha.98765.post.4.dev.1729924622+fix.auth.bug.1.c9d8e7f`\n\n#### Pre-release Resolution Strategy\n\n**Default behavior**: All branches start as `alpha.\u003chash-id\u003e` (hash-based identification)\n\n**Configurable branch patterns**: Users can configure specific branches to use custom pre-release types (alpha, beta, rc) with optional numbers:\n\n- Example: `feature/user-auth` branch → `beta.12345` (label only, uses hash-based number)\n- Example: `develop` branch → `beta.1` (label and custom number for stable branches)\n- Any branch can be mapped to any pre-release type (alpha, beta, rc) with hash-based or custom numbers\n\n**Branch name resolution**: Extract pre-release information from branch name patterns:\n\n- Example: `release/1/feature-auth-fix` → `rc.1` (extracts number from branch pattern)\n- Simplified GitFlow-inspired naming conventions\n\n- **Note**: Branch names are conventions, not strict requirements - Zerv provides flexible pattern matching and user configuration.\n\n**Clean branches**: `main`, `master` → No pre-release (clean releases)\n\n**Post-release resolution logic**:\n\n- **Configurable post representation** with two options:\n    - **Tag Distance**: Count commits from last tag\n    - **Commit Distance**: Count commits from branch creation point\n- **Default**: Tag Distance (most common use case)\n- **`post.0`**: Exactly on reference point (no commits since)\n- **`post.N`**: N commits since reference point\n- **Consistent across all branch types** (alpha, beta, rc, etc.)\n\n**Examples**:\n\n**Tag Distance (release branches):**\n\n```\nmain: v1.0.0 (tag)\n└── release/1 (created) → create tag v1.0.1-rc.1.post.1\n    └── 1 commit → 1.0.1-rc.1.post.1.dev.1729924622  (same post, dev timestamp)\n    └── 2 commits → 1.0.1-rc.1.post.1.dev.1729924623  (same post, dev timestamp)\n    └── create tag → 1.0.1-rc.1.post.2  (new tag increments post)\n    └── more commits → 1.0.1-rc.1.post.2.dev.1729924624  (new post, dev timestamp)\n```\n\n**Commit Distance (develop branch):**\n\n```\nmain: v1.0.0 (tag)\n└── develop (created from v1.0.0) → commit 1.0.1-beta.1.post.1  (1 commits since branch creation)\n    └── 5 commits later → 1.0.1-beta.1.post.6  (6 commits since branch creation)\n    └── 1 more commit → 1.0.1-beta.1.post.7  (7 commits since branch creation)\n```\n\n#### Workflow Examples\n\nThis section demonstrates how Zerv Flow works across different branching strategies and Git scenarios.\n\n**Note**: To keep diagrams clean and readable, build context is omitted from version strings in the examples. Dirty state (`.dev.timestamp`) is shown in diagrams when applicable.\n\n**Example**: A commit appears as `1.0.1-alpha.12345.post.3.dev.1729924622` in the diagrams. With build context enabled: `1.0.1-alpha.12345.post.3.dev.1729924622+feature.user-auth.3.a1b2c3d`\n\n##### Trunk-Based Development\n\n**Purpose**: Complex trunk-based workflow with parallel features, nested branches, and synchronization scenarios.\n\n**Scenario**: Development from `v1.0.0` with parallel feature branches, synchronization, and nested development.\n\n \u003c!-- MERMAID_START: git-diagram-trunk-based-development.mmd --\u003e\n\n```mermaid\n---\nconfig:\n  logLevel: 'debug'\n  theme: 'base'\n---\ngitGraph\n    %% Step 1: Initial commit on main with v1.0.0 tag\n    commit id: \"1.0.0\"\n\n    %% Step 2: Create parallel feature branches feature-1 and feature-2 from main\n    branch feature-1 order: 2\n    branch feature-2 order: 3\n\n    %% Step 3: feature-2: Start development with dirty state\n    checkout feature-2\n    commit type:REVERSE id: \"1.0.1-alpha.68031.post.0.dev.{timestamp}\" tag: \"uncommitted\"\n\n    %% Step 4: feature-2: Create first commit\n    commit id: \"1.0.1-alpha.68031.post.1\"\n\n    %% Step 5: feature-1: Create commits (parallel development)\n    checkout feature-1\n    commit id: \"1.0.1-alpha.42954.post.1\"\n    commit id: \"1.0.1-alpha.42954.post.2\"\n\n    %% Step 6: feature-1: Merge to main and release v1.0.1\n    checkout main\n    merge feature-1 id: \"1.0.1\" tag: \"feature-1 released\"\n\n    %% Step 7: feature-2: Sync with main to get feature-1 changes\n    checkout feature-2\n    merge main id: \"1.0.2-alpha.68031.post.2\"\n\n    %% Step 8: feature-2: Create additional commit\n    commit id: \"1.0.2-alpha.68031.post.3\"\n\n    %% Step 9: feature-3: Branch from feature-2 for sub-feature development\n    branch feature-3 order: 4\n    checkout feature-3\n    commit id: \"1.0.2-alpha.14698.post.4\"\n\n    %% Step 10: feature-3: Continue development with dirty state\n    commit type:REVERSE id: \"1.0.2-alpha.14698.post.4.dev.{timestamp}\" tag: \"uncommitted\"\n\n    %% Step 11: feature-3: Continue development with commits\n    commit id: \"1.0.2-alpha.14698.post.5\"\n    commit id: \"1.0.2-alpha.14698.post.6\"\n\n    %% Step 12: feature-2: Merge feature-3 back to continue development\n    checkout feature-2\n    merge feature-3 id: \"1.0.2-alpha.68031.post.6\" tag: \"feature-3 merged\"\n\n    %% Step 13: feature-2: Final development before release\n    commit id: \"1.0.2-alpha.68031.post.7\"\n\n    %% Step 14: Final release: feature-2 merges to main and releases v1.1.0\n    checkout main\n    merge feature-2 id: \"1.1.0\" tag: \"feature-2 released\"\n```\n\n\u003c!-- MERMAID_END --\u003e\n\n**Key behaviors demonstrated**:\n\n- **Parallel development**: `feature-1` and `feature-2` get unique hash IDs (`42954`, `68031`)\n- **Version progression**: Base version updates when syncing (`1.0.1` → `1.0.2`)\n- **Dirty state**: Uncommitted changes show `.dev.timestamp` suffix\n- **Nested branches**: `feature-3` branches from `feature-2` with independent versioning\n- **Clean releases**: Main branch maintains semantic versions on merges\n\n\u003c!-- Corresponding test: tests/integration_tests/flow/scenarios/trunk_based.rs:test_trunk_based_development --\u003e\n\n##### GitFlow Branching Strategy\n\n**Purpose**: GitFlow methodology with proper pre-release type mapping and merge patterns.\n\n**Scenario**: Main branch with `v1.0.0`, develop branch integration, feature development, hotfix emergency flow, and release preparation.\n\n\u003c!-- MERMAID_START: git-diagram-gitflow-development-flow.mmd --\u003e\n\n```mermaid\n---\nconfig:\n  logLevel: 'debug'\n  theme: 'base'\n---\ngitGraph\n    %% Step 1: Initial state: main and develop branches\n    commit id: \"1.0.0\"\n\n    %% Step 2: Create develop branch with initial development commit\n    branch develop order: 3\n    checkout develop\n    commit id: \"1.0.1-beta.1.post.1\"\n\n    %% Step 3: Feature development from develop branch\n    branch feature/auth order: 4\n    checkout feature/auth\n    commit id: \"1.0.1-alpha.92409.post.2\"\n    commit id: \"1.0.1-alpha.92409.post.3\"\n\n    checkout develop\n    %% Step 4: Merge feature/auth back to develop\n    merge feature/auth id: \"1.0.1-beta.1.post.3\" tag: \"feature merged\"\n\n    %% Step 5: Hotfix emergency flow from main\n    checkout main\n    branch hotfix/critical order: 1\n    checkout hotfix/critical\n    commit id: \"1.0.1-alpha.11477.post.1\"\n\n    checkout main\n    %% Step 6: Merge hotfix to main and release v1.0.1\n    merge hotfix/critical id: \"1.0.1\" tag: \"hotfix released\"\n\n    %% Step 7: Sync develop with main changes and continue development\n    checkout develop\n    merge main id: \"1.0.2-beta.1.post.4\" tag: \"sync main\"\n\n    %% Step 8: Continue development on develop branch\n    commit id: \"1.0.2-beta.1.post.5\"\n\n    %% Step 9: Release branch preparation\n    branch release/1 order: 2\n    checkout release/1\n    commit id: \"1.0.2-rc.1.post.1\"\n    commit id: \"1.0.2-rc.1.post.2\"\n    commit type:REVERSE id: \"1.0.2-rc.1.post.3.dev.{timestamp}\" tag: \"uncommitted\"\n    commit id: \"1.0.2-rc.1.post.3\"\n\n    checkout main\n    %% Step 10: Final release: merge release/1 to main\n    merge release/1 id: \"1.1.0\" tag: \"release 1.1.0\"\n\n    %% Step 11: Sync develop with release and prepare for next cycle\n    checkout develop\n    merge main id: \"1.1.1-beta.1.post.1\" tag: \"sync release\"\n```\n\n\u003c!-- MERMAID_END --\u003e\n\n**Key behaviors demonstrated**:\n\n- **Beta pre-releases**: Develop branch uses `beta` for integration builds\n- **Alpha pre-releases**: Feature branches use `alpha` with hash-based identification\n- **RC pre-releases**: Release branches use `rc` for release candidates\n- **Clean releases**: Main branch maintains clean versions without pre-release suffixes\n- **Hotfix flow**: Emergency fixes from main with proper version propagation\n- **Branch synchronization**: Develop branch syncs with main releases\n\n\u003c!-- Corresponding test: tests/integration_tests/flow/scenarios/gitflow.rs:test_gitflow_development_flow --\u003e\n\n##### Complex Release Management\n\n**Purpose**: Complex release branch scenarios including branch abandonment and cascading release preparation.\n\n**Scenario**: Main branch with `v1.0.0`, release branch preparation with critical issues leading to abandonment, and selective branch creation for successful release.\n\n\u003c!-- MERMAID_START: git-diagram-complex-release-branch.mmd --\u003e\n\n```mermaid\n---\nconfig:\n  logLevel: 'debug'\n  theme: 'base'\n---\ngitGraph\n    %% Step 1: Initial state: main branch with v1.0.0 tag\n    commit id: \"1.0.0\" tag: \"v1.0.0\"\n\n    %% Step 2: Create release/1 from main for next release preparation\n    branch release/1 order: 2\n    checkout release/1\n    commit id: \"1.0.1-rc.1.post.1\"\n    commit id: \"1.0.1-rc.1.post.2\"\n\n    %% Step 3: Create release/2 from the second commit of release/1 (before issues)\n    %% release/1 at this point: 1.0.1-rc.1.post.2, so release/2 continues from there\n    checkout release/1\n    branch release/2 order: 1\n    checkout release/2\n    commit id: \"1.0.1-rc.2.post.3\"\n\n    %% Step 4: Go back to release/1 and add the problematic third commit (issues found)\n    checkout release/1\n    commit id: \"1.0.1-rc.1.post.3\" tag: \"issues found\"\n\n    %% Step 5: release/2 completes preparation successfully\n    checkout release/2\n    commit id: \"1.0.1-rc.2.post.4\"\n\n    %% Step 6: Merge release/2 to main and release v1.1.0\n    checkout main\n    merge release/2 id: \"1.1.0\" tag: \"v1.1.0\"\n\n```\n\n\u003c!-- MERMAID_END --\u003e\n\n**Version progression details**:\n\n- **release/1**: `1.0.1-rc.1.post.1` → `1.0.1-rc.1.post.2` → `1.0.1-rc.1.post.3` (abandoned)\n- **release/2**: Created from `release/1`'s second commit (`1.0.1-rc.1.post.2`), continues as `1.0.1-rc.2.post.3` → `1.0.1-rc.2.post.4`\n- **Main**: Clean progression `1.0.0` → `1.1.0` (only from successful `release/2` merge)\n\n**Key behaviors demonstrated**:\n\n- **Branch isolation**: Each release branch maintains independent versioning regardless of parent/child relationships\n- **Selective branching**: Zerv Flow correctly handles branches created from specific historical commits\n- **Abandonment handling**: Unmerged branches don't affect final release versions on main\n- **Cascade management**: Complex branching scenarios where releases feed into other releases are handled transparently\n- **Clean main branch**: Main only receives versions from successfully merged releases, maintaining clean semantic versioning\n\n\u003c!-- Corresponding test: tests/integration_tests/flow/scenarios/complex_release_branch.rs:test_complex_release_branch_abandonment --\u003e\n\n#### Schema Variants: 10+ Standard Schema Presets\n\n**Purpose**: Complete control over version generation with 20+ schema presets and extensive customization options.\n\n**Schema Selection Examples**:\n\n```bash\nzerv flow --schema standard-base\n# → 1.0.1 (test case 1)\n\nzerv flow --schema standard-base-context\n# → 1.0.1+branch.name.g4e9af24 (test case 2)\n\nzerv flow --schema standard-base-prerelease\n# → 1.0.1-alpha.10192 (test case 3)\n\nzerv flow --schema standard-base-prerelease-context\n# → 1.0.1-alpha.10192+branch.name.1.g4e9af24 (test case 4)\n\nzerv flow --schema standard-base-prerelease-post\n# → 1.0.1-alpha.10192.post.1 (test case 5)\n\nzerv flow --schema standard-base-prerelease-post-context\n# → 1.0.1-alpha.10192.post.1+branch.name.1.g4e9af24 (test case 6)\n\nzerv flow --schema standard-base-prerelease-post-dev\n# → 1.0.1-alpha.10192.post.1.dev.1764382150 (test case 7)\n\nzerv flow --schema standard-base-prerelease-post-dev-context\n# → 1.0.1-alpha.10192.post.1.dev.1764382150+branch.name.1.g4e9af24 (test case 8)\n\nzerv flow --schema standard\n# → 1.0.0 (clean main - test case 9)\n# → 1.0.1-rc.1 (release branch - test case 10)\n# → 1.0.1-alpha.10192.post.1+branch.name.1.g4e9af24 (feature branch - test case 11)\n# → 1.0.1-alpha.10192.post.1.dev.1764382150+branch.name.1.g4e9af24 (dirty feature branch - test case 12)\n\nzerv flow --schema standard-no-context\n# → 1.0.0 (clean main - test case 13)\n# → 1.0.1-rc.1 (release branch - test case 14)\n# → 1.0.1-alpha.10192.post.1 (feature branch - test case 15)\n# → 1.0.1-alpha.10192.post.1.dev.1764382150 (dirty feature branch - test case 16)\n\nzerv flow --schema standard-context\n# → 1.0.0+main.g4e9af24 (clean main - test case 17)\n# → 1.0.1-rc.1+release.1.do.something.g4e9af24 (release branch - test case 18)\n# → 1.0.1-alpha.10192.post.1+branch.name.1.g4e9af24 (feature branch - test case 19)\n# → 1.0.1-alpha.10192.post.1.dev.1764382150+branch.name.1.g4e9af24 (dirty feature branch - test case 20)\n```\n\n\u003c!-- Corresponding test: tests/integration_tests/flow/docs/schema_variants.rs:test_schema_variants_documentation_examples --\u003e\n\n#### Branch Rules: Configurable Pattern Matching\n\n**Purpose**: Map branch names to pre-release labels, numbers, and post modes for automated version generation.\n\n**Default GitFlow Rules**:\n\n```ron\n[\n    (pattern: \"develop\", pre_release_label: beta, pre_release_num: 1, post_mode: commit),\n    (pattern: \"release/*\", pre_release_label: rc, post_mode: tag)\n]\n```\n\n**Pattern Matching**:\n\n- **Exact**: `\"develop\"` matches only `\"develop\"`\n- **Wildcard**: `\"release/*\"` matches `\"release/1\"`, `\"release/42\"`, `\"release/1/feature\"`, etc.\n- **Number extraction**:\n    - With numbers: `release/1` → `rc.1`, `release/1/feature` → `rc.1`\n    - Without numbers: `release/feature` → `rc.\u003chash-id\u003e` (fallback to hash-based identification)\n- **Other branches**: `*`, `feature/*`, `hotfix/*`, `bugfix/*`, etc. → `alpha.\u003chash-id\u003e` (fallback to hash-based identification)\n\n**Examples**:\n\n```bash\n# Default GitFlow behavior\nzerv flow\n# → 1.0.1-rc.1.post.1+release.1.do.something.1.g3a2b1c4 (release/1/do-something branch - test case 1)\n# → 1.0.1-beta.1.post.1+develop.1.g8f7e6d5 (develop branch - test case 2)\n# → 1.0.1-alpha.10192.post.1+branch.name.1.g9d8c7b6 (feature branch - test case 3)\n# → 1.0.1-rc.48993.post.1+release.do.something.1.g5e4f3a2 (release/do-something branch - test case 4)\n\n# Custom branch rules\nzerv flow --branch-rules '[\n    (pattern: \"staging\", pre_release_label: rc, pre_release_num: 1, post_mode: commit),\n    (pattern: \"qa/*\", pre_release_label: beta, post_mode: tag)\n]'\n# → 1.0.1-rc.1.post.1+staging.1.g2c3d4e5 (staging branch - test case 5)\n# → 1.0.1-beta.123.post.1+qa.123.1.g7b8c9d0 (qa branch - test case 6)\n# → 1.0.1-alpha.20460.post.1+feature.new.feature.1.g1d2e3f4 (feature branch - test case 7)\n```\n\n**Configuration**:\n\n- **`pattern`**: Branch name (exact) or wildcard (`/*`)\n- **`pre_release_label`**: `alpha`, `beta`, or `rc`\n- **`pre_release_num`**: Explicit number (exact) or extracted (wildcard)\n- **`post_mode`**: `commit` (count commits) or `tag` (count tags)\n\n\u003c!-- Corresponding test: tests/integration_tests/flow/docs/branch_rules.rs:test_branch_rules_documentation_examples --\u003e\n\n#### Override Controls: Complete Version Customization\n\n**Override Options**: VCS, version components, and pre-release controls\n\n```bash\n# VCS Overrides\nzerv flow --tag-version \"v2.1.0-beta.1\"           # Override tag version\n# → 2.1.0\n\nzerv flow --distance 42                           # Override distance from tag\n# → 1.0.1-alpha.60124.post.42+feature.test.42.g8f4e3a2\n\nzerv flow --dirty                                 # Force dirty=true\n# → 1.0.1-alpha.18373.dev.1729927845+feature.dirty.ga1b2c3d\n\nzerv flow --no-dirty                              # Force dirty=false\n# → 1.0.0+feature.clean.g4d5e6f7\n\nzerv flow --clean                                 # Force clean state (distance=0, dirty=false)\n# → 1.0.0+feature.clean.force.g8a9b0c1\n\nzerv flow --bumped-branch \"release/42\"           # Override branch name\n# → 1.0.1-rc.42.post.1+release.42.1.g2c3d4e5\n\nzerv flow --bumped-commit-hash \"a1b2c3d\"         # Override commit hash\n# → 1.0.1-alpha.48498.post.1+feature.hash.1.a1b2c3d\n\nzerv flow --bumped-timestamp 1729924622          # Override timestamp\n# → 1.0.1-alpha.18321.dev.1764598322+feature.timestamp.g7f8e9a0\n\n# Version Component Overrides\nzerv flow --major 2                              # Override major\n# → 2.0.0\n\nzerv flow --minor 5                              # Override minor\n# → 1.5.0\n\nzerv flow --patch 3                              # Override patch\n# → 1.0.3\n\nzerv flow --epoch 1                              # Override epoch\n# → 1.0.0-epoch.1\n\nzerv flow --post 7                               # Override post\n# → 1.0.1-alpha.15355.post.8+feature.post.1.g6b7c8d9 (post affects build context)\n\n# Pre-release Controls\nzerv flow --pre-release-label rc                  # Set pre-release type\n# → 1.0.1-rc.10180.post.1+feature.pr.label.1.g3d4e5f6\n\nzerv flow --pre-release-num 3                    # Set pre-release number\n# → 1.0.1-alpha.3.post.1+feature.pr.num.1.g9a0b1c2\n\nzerv flow --post-mode commit                     # Set distance calculation method\n# → 1.0.1-alpha.17003.post.1+feature.post.mode.1.g1d2e3f4\n```\n\n\u003c!-- Corresponding test: tests/integration_tests/flow/docs/override_controls.rs:test_individual_override_options --\u003e\n\n**Usage Examples**:\n\n```bash\n# VCS overrides\nzerv flow --tag-version \"v2.0.0\" --distance 5 --bumped-branch \"release/candidate\"\n# → 2.0.1-rc.71808.post.1+release.candidate.5.gb2c3d4e\n\n# Version component overrides\nzerv flow --major 2 --minor 5 --patch 3\n# → 2.5.3\n\n# Mixed overrides: VCS + version components\nzerv flow --distance 3 --major 2 --minor 1\n# → 2.1.1-alpha.60124.post.3+feature.test.3.g8f4e3a2\n\n# Clean release with overrides\nzerv flow --clean --major 2 --minor 0 --patch 0\n# → 2.0.0+feature.clean.force.g8a9b0c1\n\n# Complex multi-override scenario\nzerv flow --tag-version \"v1.5.0-rc.1\" --bumped-commit-hash \"f4a8b9c\" --major 1 --minor 6\n# → 1.6.0-alpha.11178.post.2+dev.branch.2.f4a8b9c\n```\n\n\u003c!-- Corresponding test: tests/integration_tests/flow/docs/override_controls.rs:test_override_controls_documentation_examples --\u003e\n\n### zerv version: Manual control with 4 main capability areas\n\n**Purpose**: Complete manual control over version generation with flexible schema variants and granular customization options.\n\n**Note**: Unlike `zerv flow`, `zerv version` generates versions as-is without opinionated auto-bumping logic. It does not automatically increment post-counts based on commits or tags, nor does it derive pre-release labels and numbers from branch patterns. This is general-purpose version generation without opinionated logic.\n\n#### Schema Variants: 20+ presets (standard, calver families) and custom RON schemas\n\n**Purpose**: Choose from 20+ predefined version schemas or create custom RON-based schemas for complete format control.\n\n**Schema Selection Examples**:\n\n```bash\nzerv version --schema standard-base\n# → 1.0.0 (test case 1)\n\nzerv version --schema standard-base-context\n# → 1.0.0+branch.name.1.g4e9af24 (test case 2)\n\nzerv version --schema standard-base-prerelease\n# → 1.0.0-alpha.1 (test case 3)\n\nzerv version --schema standard-base-prerelease-post-dev-context\n# → 1.0.0-alpha.1.post.5.dev.123+branch.name.1.g4e9af24 (test case 4)\n\nzerv version --schema calver-base-prerelease-post-dev-context\n# → 2025.12.4-0.alpha.1.post.5.dev.123+branch.name.1.g4e9af24 (test case 5)\n\n# Custom RON Schemas\nzerv version --schema-ron '(core:[var(Major), var(Minor), var(Patch)], extra_core:[], build:[])'\n# → 1.0.0 (test case 6)\n\nzerv version --schema-ron '(core:[var(Major), var(Minor), var(Patch)], extra_core:[], build:[str(\"build.id\")])'\n# → 1.0.0+build.id (test case 7)\n\nzerv version --schema-ron '(\n    core: [var(Major), var(Minor), var(Patch)],\n    extra_core: [var(PreRelease), var(Post), var(Dev)],\n    build: [var(BumpedBranch), var(Distance), var(BumpedCommitHashShort)]\n)'\n# → 1.0.0-alpha.1.post.5.dev.123+branch.name.1.g4e9af24 (test case 8, equivalent to standard-base-prerelease-post-dev-context)\n\nzerv version --schema-ron '(\n    core: [var(ts(\"YYYY\")), var(ts(\"MM\")), var(ts(\"DD\"))],\n    extra_core: [var(PreRelease), var(Post), var(Dev)],\n    build: [var(BumpedBranch), var(Distance), var(BumpedCommitHashShort)]\n)'\n# → 2025.12.4-0.alpha.1.post.5.dev.123+branch.name.1.g{hex:7} (test case 9, equivalent to calver-base-prerelease-post-dev-context)\n```\n\n**Schema Architecture**: All schemas resolve to the internal `ZervSchema` struct with three required components:\n\n- **`core`**: Primary version components (e.g., `[Major, Minor, Patch]` for SemVer)\n- **`extra_core`**: Additional version components (e.g., pre-release, post-release, dev)\n- **`build`**: Build metadata components (e.g., commit hash, branch name, build info)\n\n**Schema Resolution**: Preset schemas (`standard-base`, `calver-*`, etc.) are predefined `ZervSchema` objects that adapt based on repository state. RON schemas are parsed from text into the same `ZervSchema` structure, providing identical functionality with custom definitions.\n\n**Examples**:\n\n- Test case 8: RON schema equivalent to `standard-base-prerelease-post-dev-context` (test case 4)\n- Test case 9: RON schema equivalent to `calver-base-prerelease-post-dev-context` (test case 5), demonstrating date formatting with `var(ts(\"YYYY\"))`\n\n#### VCS Overrides: Override tag version, distance, dirty state, branch, commit data\n\n**Purpose**: Override any VCS (Version Control System) detected values for complete control over version components.\n\n```bash\nzerv version --tag-version \"v2.1.0-beta.1\"\n# → 2.1.0-beta.1+branch.name.1.g4e9af24 (test case 1)\n\nzerv version --distance 42\n# → 1.0.0-alpha.1.post.5.dev.123+branch.name.42.g8f4e3a2 (test case 2)\n\nzerv version --dirty\n# → 1.0.0-alpha.1.post.5.dev.123+branch.name.1.g4e9af24 (test case 3)\n\nzerv version --bumped-branch \"release/42\"\n# → 1.0.0-alpha.1.post.5.dev.123+release.42.1.g4e9af24 (test case 4)\n```\n\n\u003c!-- Corresponding test: tests/integration_tests/version/docs/vcs_overrides.rs:test_zerv_version_vcs_overrides_documentation_examples --\u003e\n\n#### Version Bumping: Field-based bumps (major/minor/patch) and schema-based bumps\n\n**Purpose**: Increment version components using field-based or schema-based strategies.\n\n```bash\nzerv version --bump-major\n# → 2.0.0 (test case 1)\n\nzerv version --bump-minor\n# → 1.1.0 (test case 2)\n\nzerv version --bump-patch\n# → 1.0.1 (test case 3)\n\nzerv version --bump-major --bump-minor\n# → 2.1.0 (test case 4)\n\nzerv version --bump-core 0\n# → 2.0.0 (test case 5, schema-based bump targeting core component index 0/major)\n\nzerv version --bump-major --bump-minor --bump-patch\n# → 2.1.1 (test case 6)\n\nzerv version --bump-major 2\n# → 3.0.0 (test case 7)\n```\n\n\u003c!-- Corresponding test: tests/integration_tests/version/docs/version_bumping.rs:test_zerv_version_version_bumping_documentation_examples --\u003e\n\n#### Component Overrides: Fine-grained control over individual version components\n\n**Purpose**: Override specific version components while preserving all other detected values for precise version control.\n\n**Override Categories**: Individual components, pre-release controls, and custom variables\n\n```bash\n# Version component overrides (major, minor, patch)\nzerv version --major 2 --minor 5\n# → 2.5.0+branch.name.1.g{hex:7} (test case 1)\n\n# Pre-release component overrides (label and number)\nzerv version --schema standard-base-prerelease-post-context --pre-release-label rc --pre-release-num 3\n# → 1.0.0-rc.3+branch.name.1.g{hex:7} (test case 2)\n\n# Additional component overrides (epoch, post, dev)\nzerv version --schema standard-base-prerelease-post-dev-context --epoch 1 --post 7 --dev 456\n# → 1.0.0-epoch.1.post.7.dev.456+branch.name.1.g{hex:7} (test case 3)\n\n# Custom variables in schema-ron (requires schema-ron)\nzerv version --schema-ron '(\n    core: [var(Major), var(Minor), var(Patch)],\n    extra_core: [],\n    build: [var(custom(\"build_id\")), var(custom(\"environment\"))]\n)' --custom '{\"build_id\": \"prod-123\", \"environment\": \"staging\"}'\n# → 1.0.0+prod.123.staging (test case 4)\n```\n\n\u003c!-- Corresponding test: tests/integration_tests/version/docs/component_overrides.rs:test_zerv_version_component_overrides_documentation_examples --\u003e\n\n#### Version Check: Validate version strings for different formats\n\n**Purpose**: Validate that version strings conform to specific format requirements with support for multiple version standards.\n\n```bash\n# Check complex SemVer format validation\nzerv check --format semver 1.0.0-rc.1.something.complex+something.complex\n# → Version: 1.0.0-rc.1.something.complex+something.complex\n#   ✓ Valid SemVer format (test case 1)\n\n# Check PEP440 format validation with build metadata\nzerv check --format pep440 1.0.0a2.post5.dev3+something.complex\n# → Version: 1.0.0a2.post5.dev3+something.complex\n#   ✓ Valid PEP440 format (test case 2)\n\n# Check PEP440 format validation with normalization\nzerv check --format pep440 1.0.0-alpha.2.post.5.dev.3+something.complex\n# → Version: 1.0.0-alpha.2.post.5.dev.3+something.complex\n#   ✓ Valid PEP440 format (normalized: 1.0.0a2.post5.dev3+something.complex) (test case 3)\n\n# Invalid version handling (fails with exit code 1)\nzerv check --format semver invalid\n# → Error: Invalid version: invalid - Invalid SemVer format (test case 4)\n\n# Auto-detect and validate multiple formats\nzerv check 2.1.0-beta.1\n# → Version: 2.1.0-beta.1\n#   ✓ Valid PEP440 format (normalized: 2.1.0b1)\n#   ✓ Valid SemVer format (test case 5)\n```\n\n\u003c!-- Corresponding test: tests/integration_tests/version/docs/version_validation.rs:test_zerv_check_documentation_examples --\u003e\n\n#### Input/Output \u0026 Piping: Shared capabilities for both commands\n\n**Purpose**: Flexible input handling and output formatting with pipeline support for both `zerv version` and `zerv flow` commands.\n\n```bash\n# Source options - Use Git VCS or stdin for version data\nzerv flow --source git\n# → 1.0.1-alpha.10192.post.1.dev.1764382150+branch.name.1.g4e9af24 (VCS auto-detection)\n# (test case 1)\n\n# zerv RON format - Internal/debugging output and intermediate representation\n# Used as stdin input for zerv version and zerv flow commands\nzerv flow --output-format zerv\n# → (\n#     schema: (\n#         core: [var(Major), var(Minor), var(Patch)],\n#         extra_core: [var(Epoch), var(PreRelease), ...],\n#         build: [var(BumpedBranch), var(Distance), ...]\n#     ),\n#     vars: (\n#         major: Some(1), minor: Some(0), patch: Some(1),\n#         pre_release: Some((label: Alpha, number: Some(123))),\n#         bumped_branch: Some(\"feature-branch\"),\n#         bumped_commit_hash: Some(\"gabc123def\"),\n#         ...\n#     )\n#   )\n# (test case 2)\n\n# Pipeline chaining - Multiple transformations\n# Note: Upstream command must output --output-format zerv for stdin piping to work\nzerv flow --source git --output-format zerv | zerv version --source stdin --major 4 --output-format semver\n# → 4.0.1-alpha.10192.post.1.dev.1764382150+branch.name.1.g4e9af24\n# (test case 3)\n\nzerv flow --output-format pep440\n# 1.0.1a10192.post1.dev1764382150+branch.name.1.g4e9af24\n# (test case 4)\n\nzerv flow --output-format semver\n# 1.0.1-alpha.10192.post.1.dev.1764902466+branch.name.1.g4e9af24\n# (test case 5)\n\nzerv flow --output-prefix v --output-format semver\n# v1.0.1-alpha.10192.post.1.dev.1764902466+branch.name.1.g4e9af24\n# (test case 6)\n\nzerv flow --output-template \"app:{{ major }}.{{ minor }}.{{ patch }}\"\n# app:1.0.1\n# (test case 7)\n\nzerv flow --output-template \"{{ semver_obj.docker }}\"\n# 1.0.1-alpha.10192.post.1.dev.1764902466-branch.name.1.g4e9af24\n# (test case 8)\n\nzerv flow --output-template \"{{ semver_obj.base_part }}++{{ semver_obj.pre_release_part }}++{{ semver_obj.build_part }}\"\n# 1.0.1++alpha.10192.post.1.dev.1764902466++branch.name.1.g4e9af24\n# (test case 9)\n\n# Comprehensive template examples\nzerv flow --output-template \"Build: {{ major }}.{{ minor }}.{{ patch }}-{{ pre_release.label | default(value='release') }}{% if pre_release.number %}{{ pre_release.number }}{% endif %} ({{ bumped_branch }}@{{ bumped_commit_hash_short }})\"\n# → Build: 1.0.1-alpha59394 (feature.new.auth@g4e9af24)\n# (test case 10)\n\nzerv flow --output-template \"Version: {{ semver_obj.docker }}, Branch: {{ bumped_branch | upper }}, Clean: {% if dirty %}No{% else %}Yes{% endif %}\"\n# → Version: 1.0.1-alpha.59394.post.1.dev.1764382150-branch.name.1.g54c499a, Branch: DIRTY.FEATURE.WORK, Clean: No\n# (test case 11)\n\nzerv flow --output-template \"{% if distance %}{{ distance }} commits since {% if last_timestamp %}{{ format_timestamp(value=last_timestamp, format='%Y-%m-%d') }}{% else %}beginning{% endif %}{% else %}Exact tag{% endif %}\"\n# → 1 commits since 2025-12-05\n# (test case 12)\n\nzerv flow --output-template \"App-{{ major }}{{ minor }}{{ patch }}{% if pre_release %}-{{ pre_release.label }}{% endif %}{% if dirty %}-SNAPSHOT{% endif %}-{{ hash(value=bumped_branch, length=4) }}\"\n# → App-101-alpha-SNAPSHOT-a1b2\n# (test case 13)\n\nzerv flow --output-template \"PEP440: {{ pep440 }}\"\n# → PEP440: 1.0.1a10192.post1.dev1764909598+branch.name.1.g4e9af24\n# (test case 14)\n\nzerv flow --output-template \"Release: v{{ major }}.{{ minor }}.{{ patch }}, Pre: {{ pre_release.label_code | default(value='release') }}, Hash: {{ bumped_commit_hash_short }}\"\n# → Release: v1.0.1, Pre: a, Hash: g4e9af24\n# (test case 15)\n```\n\n\u003c!-- Corresponding test: tests/integration_tests/flow/docs/io.rs:test_io_documentation_examples --\u003e\n\n- **Smart Source Detection**: Auto-detects input source (stdin if piped, git otherwise)\n\n```bash\n# Implicit source detection (auto: git if no stdin, stdin if piped)\nzerv version\n\n# Explicit git source\nzerv version --source git\n\n# Pipe between commands (implicit stdin detection)\nzerv version --output-format zerv | zerv version\n\n# Pipe between commands (explicit stdin source)\nzerv version --output-format zerv | zerv version --source stdin\n\n# No VCS - use overrides only\nzerv version --source none --tag-version 1.2.3 --distance 5\n```\n\n##### Template System: Advanced custom formatting\n\n**Purpose**: Complete control over version output using Tera templating with extensive variables, functions, and logical operations.\n\n**Note**: Zerv uses the [Tera templating engine](https://keats.github.io/tera/docs/), which provides powerful template features including conditionals, loops, filters, and custom functions.\n\n###### Available Template Variables\n\n**Core Version Fields**:\n\n- `major`, `minor`, `patch` - Version numbers\n- `epoch` - Epoch version (optional)\n- `post`, `dev` - Post-release and dev identifiers\n\n**Pre-release Context**:\n\n- `pre_release.label` - Pre-release type (\"alpha\", \"beta\", \"rc\")\n- `pre_release.number` - Pre-release number\n- `pre_release.label_code` - Short code (\"a\", \"b\", \"rc\")\n- `pre_release.label_pep440` - PEP440 format (\"a\", \"b\", \"rc\")\n\n**VCS/Metadata Fields**:\n\n- `distance` - Commits from reference point\n- `dirty` - Working directory dirty state\n- `bumped_branch` - Branch name\n- `bumped_commit_hash` - Full commit hash\n- `bumped_commit_hash_short` - Short commit hash\n- `bumped_timestamp` - Commit timestamp\n- `last_commit_hash` - Last tag commit hash\n- `last_commit_hash_short` - Short last tag commit hash\n- `last_timestamp` - Last tag timestamp\n\n**Parsed Version Objects**:\n\n- `semver_obj.base_part` - \"1.2.3\"\n- `semver_obj.pre_release_part` - \"alpha.1.post.3.dev.5\"\n- `semver_obj.build_part` - \"build.456\"\n- `semver_obj.docker` - \"1.2.3-alpha.1-build.456\"\n- `pep440_obj.base_part` - \"1.2.3\"\n- `pep440_obj.pre_release_part` - \"a1.post3.dev5\"\n- `pep440_obj.build_part` - \"build.456\"\n\n**Formatted Versions**:\n\n- `semver` - Full SemVer string\n- `pep440` - Full PEP440 string\n- `current_timestamp` - Current Unix timestamp\n\n###### Custom Template Functions\n\n**String Manipulation**:\n\n- `sanitize(value=variable, preset='dotted')` - Sanitize with presets: \"semver\", \"pep440\", \"uint\"\n- `sanitize(value=variable, separator='-', lowercase=true, max_length=10)` - Custom sanitization\n- `prefix(value=variable, length=10)` - Extract first N characters\n- `prefix_if(value=variable, prefix=\"+\")` - Add prefix only if value not empty\n\n**Hashing \u0026 Formatting**:\n\n- `hash(value=variable, length=7)` - Generate hex hash\n- `hash_int(value=variable, length=7, allow_leading_zero=false)` - Numeric hash\n- `format_timestamp(value=timestamp, format=\"%Y-%m-%d\")` - Format timestamp \"2023-12-30\"\n- `format_timestamp(value=timestamp, format=\"compact_date\")` - \"20231230\"\n\n\u003c!-- Corresponding test: tests/integration_tests/flow/docs/io.rs:test_template_documentation_examples --\u003e\n\n### zerv check: Validate version formats\n\nValidate version strings against specific format requirements.\n\n```bash\nzerv check \"1.2.3-rc.2\"\n# Version: 1.2.3-rc.2\n# ✓ Valid PEP440 format (normalized: 1.2.3rc2)\n# ✓ Valid SemVer format\n```\n\n### zerv render: Format conversion\n\nParse and render version strings with format conversion, templates, and custom prefixes.\n\n```bash\n# Convert SemVer to PEP440\nzerv render \"1.2.3-alpha.1\" --output-format pep440\n# 1.2.3a1\n\n# Convert PEP440 to SemVer\nzerv render \"1.2.3b2\" --input-format pep440 --output-format semver\n# 1.2.3-beta.2\n\n# Auto-detect input format\nzerv render \"1.2.3a1\" --output-format semver\n# 1.2.3-alpha.1\n```\n\n**Templates:**\n\n```bash\n# Custom format\nzerv render \"1.2.3\" --template \"v{{major}}.{{minor}}\"\n# v1.2\n\n# With pre-release\nzerv render \"2.0.0-beta.2\" --template \"{{major}}.{{minor}}.{{patch}}-{{pre_release.label}}\"\n# 2.0.0-beta\n```\n\n**Prefixes:**\n\n```bash\nzerv render \"1.2.3\" --output-prefix \"v\"\n# v1.2.3\n```\n\n### Python API\n\nZerv can be used as a Python library for version generation in Python scripts.\n\n```python\nimport zerv\n\nzerv.version()\n# \"1.2.3-alpha.1\"\n```\n\n## Installation\n\n```bash\n# Python (uv - global CLI tool) - Recommended\nuv tool install zerv-version\n\n# Python (pip)\npip install zerv-version\n\n# Python (uv - add to project)\nuv add zerv-version\n\n# Rust (cargo)\ncargo install zerv\n\n# Installation script (latest version)\ncurl -sSL https://raw.githubusercontent.com/wislertt/zerv/main/scripts/install.sh | bash\n\n# Installation script (specific version)\ncurl -sSL https://raw.githubusercontent.com/wislertt/zerv/main/scripts/install.sh | bash -s vX.X.X\n\n# Pre-built binaries\n# Download from: https://github.com/wislertt/zerv/releases\n```\n\n### Uninstall\n\n```bash\n# Rust/cargo\ncargo uninstall zerv\n\n# Python (pip)\npip uninstall zerv-version\n\n# Python (uv tool)\nuv tool uninstall zerv-version\n\n# Manual binary\nrm ~/.local/bin/zerv\n```\n\n## Links\n\n- **Comprehensive Documentation**: [docs/llms.md](docs/llms.md) - Complete reference for all Zerv capabilities\n- **CLI Help**: `zerv --help`, `zerv flow --help`, `zerv version --help` - Detailed command-line reference\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwislertt%2Fzerv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwislertt%2Fzerv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwislertt%2Fzerv/lists"}