Productify

Appearance

pfy version ​

Manage project version using semantic versioning.

Synopsis ​

bash
pfy version <subcommand> [flags]

Description ​

The version command group provides tools for managing your project's semantic version stored in project.yaml. Supports showing, setting, and incrementing versions according to semver 2.0.0.

TIP

pfy version manages the project version. To print the CLI binary's own version, use the global pfy --version flag — it reports the version stamped into the binary at build time, not anything from project.yaml.

Subcommands ​

pfy version show ​

Display the current project version.

bash
pfy version show

Output:

1.2.3

Use Cases:

  • Check current version before release
  • Use in scripts: VERSION=$(pfy version show)
  • Verify version after bump

pfy version set ​

Set the project version to a specific value.

bash
pfy version set --version <version>

Flags:

  • --version (required): Version string in format major.minor.patch

Examples:

bash
# Set to specific version
pfy version set --version 2.0.0

# Output:
# Version updated: 1.2.3 → 2.0.0
# Configuration saved to project.yaml

Use Cases:

  • Align with external version numbers
  • Reset version after major refactor
  • Match version to git tag

pfy version bump ​

Increment the project version using semantic versioning rules.

bash
pfy version bump --part <major|minor|patch>

Flags:

  • --part: Version component to increment (default: patch)
    • major: Breaking changes (1.2.3 → 2.0.0)
    • minor: New features (1.2.3 → 1.3.0)
    • patch: Bug fixes (1.2.3 → 1.2.4)
  • --pre: Pre-release label to attach or advance (e.g., --part minor --pre rc gives 1.2.3 → 1.3.0-rc.1). Omit it to cut a normal release.

Examples:

bash
# Increment patch version (default)
pfy version bump
# or explicitly:
pfy version bump --part patch
# 1.2.3 → 1.2.4

# Increment minor version
pfy version bump --part minor
# 1.2.3 → 1.3.0

# Increment major version
pfy version bump --part major
# 1.2.3 → 2.0.0

# Cut a release candidate
pfy version bump --part minor --pre rc
# 1.2.3 → 1.3.0-rc.1

# Reapplying the same label advances the counter
pfy version bump --part minor --pre rc
# 1.3.0-rc.1 → 1.3.0-rc.2

# Drop --pre to release the candidate
pfy version bump --part patch
# 1.3.0-rc.1 → 1.3.0

Behavior:

  • Patch: Increments third number, keeps major and minor
  • Minor: Increments second number, resets patch to 0
  • Major: Increments first number, resets minor and patch to 0
  • Bumping without --pre strips any pre-release or build metadata. A bump that would merely release an existing pre-release does exactly that rather than skipping ahead — 1.3.0-rc.1 with --part patch becomes 1.3.0, not 1.3.1, since semver orders 1.3.0-rc.1 < 1.3.0.
  • Reapplying the same --pre label advances its counter (rc.1 → rc.2) instead of restarting it or jumping to the next release.

Examples ​

Development Workflow ​

bash
# Check current version
pfy version show
# 1.0.0

# Make bug fix
# ... code changes ...
pfy version bump --part patch
# 1.0.0 → 1.0.1

# Add new feature
# ... code changes ...
pfy version bump --part minor
# 1.0.1 → 1.1.0

# Breaking change
# ... code changes ...
pfy version bump --part major
# 1.1.0 → 2.0.0

Release Script ​

bash
#!/bin/bash
# release.sh

# Bump version
pfy version bump --part minor

# Get new version
VERSION=$(pfy version show)

# Tag and push
git tag "v$VERSION"
git push --tags

echo "Released version $VERSION"

CI/CD Integration ​

Used automatically in CI/CD pipelines (see Auto-Versioning):

yaml
# GitHub Actions
- name: Bump version
  run: |
    pfy version bump --part patch
    echo "NEW_VERSION=$(pfy version show)" >> $GITHUB_ENV

Global Flags ​

All global pfy flags are available:

  • --verbose, -v: Show detailed output
  • --quiet, -q: Suppress non-essential output

Verbose Output ​

bash
pfy --verbose version bump --part minor

Output:

Incrementing minor version from 1.2.3...
Version updated: 1.2.3 → 1.3.0
Configuration saved to project.yaml

Quiet Output ​

bash
pfy --quiet version bump --part patch

No output (check exit code for success).

Version Format ​

Versions must follow Semantic Versioning 2.0.0:

Format: major.minor.patch

Where:

  • major: Breaking changes, incompatible API changes
  • minor: New features, backwards compatible
  • patch: Bug fixes, backwards compatible

Valid Examples:

0.1.0      # Initial development
1.0.0      # First stable release
1.2.3      # Version with all components
1.3.0-rc.1 # Pre-release
10.5.128   # Large version numbers

Invalid Examples:

1.2       # Missing patch
v1.2.3    # No 'v' prefix

Error Handling ​

Invalid Version Format ​

bash
$ pfy version set --version 1.2
Error: invalid version format: 1.2 (expected format: x.y.z)

Solution: Use three-part version: 1.2.0

No project.yaml ​

If project.yaml does not exist, the CLI falls back to a default configuration, so pfy version show prints the default version:

bash
$ pfy version show
0.1.0

To manage a real project version, initialize the project first:

bash
pfy init --name my-project

Invalid Bump Part ​

bash
$ pfy version bump --part release
Error: invalid version part: release (expected: major, minor, or patch)

Solution: Use major, minor, or patch

Integration ​

With CI/CD Templates ​

Project version is automatically embedded in generated CI/CD templates:

bash
# Set version
pfy version set --version 1.5.0

# Generate CI templates
pfy ci update

# CI will build images tagged with:
# - my-app:1.5.0
# - my-app:latest

With Application Promote/Copy ​

Version can be used when promoting applications:

bash
# Promote with current project version
pfy application promote \
  --application-id <id> \
  --target-tenant-id <tenant>
# Uses version from project.yaml

# Or specify explicitly
pfy application promote \
  --application-id <id> \
  --target-tenant-id <tenant> \
  --version $(pfy version show)

In Scripts ​

bash
#!/bin/bash

# Get current version
CURRENT=$(pfy version show)
echo "Current version: $CURRENT"

# Bump version
pfy version bump --part patch
NEW=$(pfy version show)

echo "Updated to: $NEW"

# Use in Docker build
docker build -t my-app:$NEW .

Configuration ​

Version is stored in project.yaml:

yaml
project_name: my-app
version: 1.2.3 # ← Managed by version command
ci:
  type: github
  language: go

Best Practices ​

1. Commit After Version Changes ​

Always commit version changes:

bash
pfy version bump --part minor
git add project.yaml
git commit -m "Bump version to $(pfy version show)"

2. Match Git Tags ​

Keep git tags synchronized:

bash
VERSION=$(pfy version show)
git tag "v$VERSION"
git push --tags

3. Automate in CI ​

Let CI handle patch bumps automatically:

yaml
# .github/workflows/ci.yml
on:
  push:
    branches: [main]

jobs:
  version-and-deploy:
    steps:
      - name: Auto-bump patch version
        run: pfy version bump --part patch

4. Manual Bumps for Features/Breaking Changes ​

Reserve minor/major bumps for developers:

bash
# Before starting new feature
pfy version bump --part minor

# Before breaking change
pfy version bump --part major

See Also ​