### Use Semantic Versioning CLI

Source: https://context7.com/paulhatch/semantic-version/llms.txt

Commands for installing and using the CLI tool to retrieve version information and configure custom versioning patterns.

```bash
# Install globally
npm install -g @semanticversion/cli

# Basic usage - outputs version to stdout
sv
# Output: 1.2.4

# JSON output with all version details
sv --format json
# Output:
# {
#   "version": "1.2.4",
#   "versionTag": "v1.2.4",
#   "major": 1,
#   "minor": 2,
#   "patch": 4,
#   "increment": 3,
#   "versionType": "patch",
#   "changed": true,
#   "isTagged": false,
#   "authors": "John Doe <john@example.com>",
#   "currentCommit": "abc123...",
#   "previousCommit": "def456...",
#   "previousVersion": "1.2.3"
# }

# Custom options
sv --tag-prefix "v" \
   --major-pattern "/BREAKING CHANGE:/" \
   --minor-pattern "/feat:/" \
   --version-format '${major}.${minor}.${patch}-rc.${increment}' \
   --format json

# Monorepo usage
sv --namespace api --path src/api

# Bump each commit mode
sv --bump-each-commit

# Pre-release mode (prevents 0.x -> 1.0 jumps)
sv --enable-prerelease-mode

# Branch-based versioning
sv --version-from-branch

# Debug output
sv --debug
# Outputs version to stdout, debug info to stderr

# Use in shell scripts
VERSION=$(sv)
echo "Building version $VERSION"
docker build -t myapp:$VERSION .
```

--------------------------------

### Implement CI/CD Pipeline Workflow

Source: https://context7.com/paulhatch/semantic-version/llms.txt

A complete GitHub Actions workflow that integrates versioning, building, testing, and release steps.

```yaml
name: CI/CD Pipeline
on:
  push:
    branches: [main, 'release/*']
  pull_request:
    branches: [main]

jobs:
  version:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.version.outputs.version }}
      version_tag: ${{ steps.version.outputs.version_tag }}
      changed: ${{ steps.version.outputs.changed }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Determine Version
        id: version
        uses: paulhatch/semantic-version@v5.4.0
        with:
          tag_prefix: "v"
          version_format: "${major}.${minor}.${patch}"
          enable_prerelease_mode: ${{ github.ref != 'refs/heads/main' }}

  build:
    needs: version
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: |
          echo "Building v${{ needs.version.outputs.version }}"
          npm ci
          npm run build

      - name: Test
        run: npm test

      - name: Build Docker Image
        run: |
          docker build -t myapp:${{ needs.version.outputs.version }} .
          docker tag myapp:${{ needs.version.outputs.version }} myapp:latest

  release:
    needs: [version, build]
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Create Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ needs.version.outputs.version_tag }}
          release_name: Release ${{ needs.version.outputs.version }}
          draft: false
          prerelease: false
```

--------------------------------

### Configure Checkout for Versioning

Source: https://github.com/paulhatch/semantic-version/blob/master/readme.md

Ensure full git history and tags are available by setting fetch-depth to 0, which is required for accurate version determination.

```yaml
  - name: Checkout
    uses: actions/checkout@v2
    with:
      fetch-depth: 0    # fetch all history
      filter: blob:none # exclude file contents for faster checkout
```

--------------------------------

### Enable Branch-Based Versioning

Source: https://github.com/paulhatch/semantic-version/blob/master/guide.md

Enables versioning based on the current branch name using default regex patterns.

```yaml
- uses: paulhatch/semantic-version@latest
  with:
    version_from_branch: true
```

--------------------------------

### Custom Version Format Configuration

Source: https://context7.com/paulhatch/semantic-version/llms.txt

Configure custom version output formats using template variables for pre-release versions, build metadata, and custom labeling schemes. The `version_format` input allows for flexible output.

```yaml
name: Build with Custom Version Format
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get Version with Pre-release Label
        id: version
        uses: paulhatch/semantic-version@v5.4.0
        with:
          version_format: "${major}.${minor}.${patch}-prerelease.${increment}"

      - name: Build Docker Image
        run: |
          docker build -t myapp:${{ steps.version.outputs.version }} .
          # Tags: myapp:1.2.4-prerelease.5
```

```text
# Available template variables:
# ${major}     - Major version number
# ${minor}     - Minor version number
# ${patch}     - Patch version number
# ${increment} - Number of commits since last version tag

# Example formats:
# "${major}.${minor}.${patch}"                    -> 1.2.4
# "${major}.${minor}.${patch}-alpha.${increment}" -> 1.2.4-alpha.5
# "${major}.${minor}.${patch}+build.${increment}" -> 1.2.4+build.5
# "v${major}.${minor}"                            -> v1.2
```

--------------------------------

### Configure Multiple Versions in a Workflow

Source: https://github.com/paulhatch/semantic-version/blob/master/readme.md

Use multiple steps with distinct change paths, patterns, and namespaces to track independent versions for different project components.

```yaml
- name: Application Version
  id: version
  uses: paulhatch/semantic-version@v5.4.0
  with:
    change_path: "src/service"
- name: Database Version
  id: db-version
  uses: paulhatch/semantic-version@v5.4.0
  with:
    major_pattern: "(MAJOR-DB)"
    minor_pattern: "(MINOR-DB)"
    change_path: "src/migrations"
    namespace: db
```

--------------------------------

### Configure Pre-release Mode for 0.x Versions

Source: https://context7.com/paulhatch/semantic-version/llms.txt

Enables pre-release mode to prevent accidental 1.0.0 releases by treating major changes as minor when the version is 0.x.x.

```yaml
name: Early Development Versioning
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get Version (Pre-release Mode)
        id: version
        uses: paulhatch/semantic-version@v5.4.0
        with:
          enable_prerelease_mode: true
          version_format: "${major}.${minor}.${patch}-beta.${increment}"

      - name: Output
        run: |
          echo "Version: ${{ steps.version.outputs.version }}"
          echo "Type: ${{ steps.version.outputs.version_type }}"
```

--------------------------------

### Enable Debug Mode for Troubleshooting

Source: https://context7.com/paulhatch/semantic-version/llms.txt

Enables diagnostic output to help troubleshoot version calculation logic and pattern matching.

```yaml
name: Debug Versioning
on: [push]

jobs:
  debug:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get Version with Debug
        id: version
        uses: paulhatch/semantic-version@v5.4.0
        with:
          debug: true

      - name: Show Debug Output
        run: |
          echo "Version: ${{ steps.version.outputs.version }}"
          echo "Debug Output:"
          echo "${{ steps.version.outputs.debug_output }}"
```

--------------------------------

### Create Integration Test Case

Source: https://github.com/paulhatch/semantic-version/blob/master/contributing.md

Use the test helper to create a temporary repository, perform git operations, and validate the action output using Jest.

```typescript
test('Name of test goes here', async () => {
    // This method creates a test repository in your temp directory, the repo
    // object returned provides methods to interact with the repository
    const repo = createTestRepo({
        // Specify any config options you want to set, the options available can be found
        // in the src/ActionConfig.ts file
        tagPrefix: ''
    });

    // the make commit method creates a commit with the specified message, an empty file will be
    // automatically created for the commit
    repo.makeCommit('Initial Commit');

    // an optional second parameter can be used to specify the path of the file to commit,
    // which will be created if it does not exist already
    repo.makeCommit('Initial Commit', 'subdir');
    
    // the exec method runs an arbitrary command in the repository
    repo.exec('git tag 0.0.1')

    // the runAction method runs the action and returns the result
    const result = await repo.runAction();

    // finally, the use whatever assertion you want to validate the result
    expect(result.formattedVersion).toBe('0.0.1+0');
}, 15000);
```

--------------------------------

### Basic GitHub Action Usage

Source: https://context7.com/paulhatch/semantic-version/llms.txt

Integrate this action into your GitHub workflow to automatically determine the semantic version based on git tags and commit history. Ensure `fetch-depth: 0` is set for accurate versioning.

```yaml
name: Build and Version
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0    # Required: fetch all history for accurate versioning
          filter: blob:none # Optional: faster checkout without file contents

      - name: Get Semantic Version
        id: version
        uses: paulhatch/semantic-version@v5.4.0

      - name: Use Version
        run: |
          echo "Version: ${{ steps.version.outputs.version }}"
          echo "Major: ${{ steps.version.outputs.major }}"
          echo "Minor: ${{ steps.version.outputs.minor }}"
          echo "Patch: ${{ steps.version.outputs.patch }}"
          echo "Increment: ${{ steps.version.outputs.increment }}"
          echo "Version Type: ${{ steps.version.outputs.version_type }}"
          echo "Version Tag: ${{ steps.version.outputs.version_tag }}"
          echo "Is Tagged: ${{ steps.version.outputs.is_tagged }}"
          echo "Changed: ${{ steps.version.outputs.changed }}"
          echo "Authors: ${{ steps.version.outputs.authors }}"
```

```text
# Expected output for repository with commits after v1.2.3 tag:
# Version: 1.2.4
# Major: 1
# Minor: 2
# Patch: 4
# Increment: 2
# Version Type: patch
# Version Tag: v1.2.4
# Is Tagged: false
# Changed: true
# Authors: John Doe <john@example.com>
```

--------------------------------

### Enable Debug Output in GitHub Actions

Source: https://github.com/paulhatch/semantic-version/blob/master/contributing.md

Configure the action to output diagnostic information and print it to the console for troubleshooting.

```yaml
- name: Version
  uses: paulhatch/semantic-version@v5.4.0
  id: version
  with:
    tag_prefix: ""
    version_format: "${major}.${minor}.${patch}.${increment}"
    debug: true

- name: Print Diagnostic Output
  run: echo "$DEBUG_OUTPUT"
  env:
    DEBUG_OUTPUT: ${{ steps.version.outputs.debug_output }}
```

--------------------------------

### Configure Tag Versioning Strategy

Source: https://github.com/paulhatch/semantic-version/blob/master/guide.md

This is the default behavior where versions are determined by existing tags, requiring no additional configuration parameters.

```yaml
- uses: paulhatch/semantic-version@latest
```

--------------------------------

### Configure Semantic Versioning Action

Source: https://github.com/paulhatch/semantic-version/blob/master/readme.md

Use this configuration in a GitHub Actions workflow to define how semantic versions are generated. Customize tag prefixes, patterns for major/minor changes, version formatting, and more.

```yaml
- uses: paulhatch/semantic-version@v5.4.0
  with:
    # The prefix to use to identify tags
    tag_prefix: "v"
    # A string which, if present in a git commit, indicates that a change represents a
    # major (breaking) change, supports regular expressions wrapped with '/'
    major_pattern: "/!:|BREAKING CHANGE:/"
    # A string which indicates the flags used by the `major_pattern` regular expression. Supported flags: idgs
    major_regexp_flags: ""
    # Same as above except indicating a minor change, supports regular expressions wrapped with '/'
    minor_pattern: "/feat(\(.+\))?:/"
    # A string which indicates the flags used by the `minor_pattern` regular expression. Supported flags: idgs
    minor_regexp_flags: ""
    # A string to determine the format of the version output
    version_format: "${major}.${minor}.${patch}-prerelease${increment}"
    # Optional path to check for changes. If any changes are detected in the path the
    # 'changed' output will true. Enter multiple paths separated by spaces.
    change_path: "src/my-service"
    # Named version, will be used as suffix for name version tag
    namespace: my-service
    # If this is set to true, *every* commit will be treated as a new version.
    bump_each_commit: false
    # If bump_each_commit is also set to true, setting this value will cause the version to increment only if the pattern specified is matched.
    bump_each_commit_patch_pattern: ""
    # If true, the body of commits will also be searched for major/minor patterns to determine the version type.
    search_commit_body: false
    # The output method used to generate list of users, 'csv' or 'json'.
    user_format_type: "csv"
    # Prevents pre-v1.0.0 version from automatically incrementing the major version.
    # If enabled, when the major version is 0, major releases will be treated as minor and minor as patch. Note that the version_type output is unchanged.
    enable_prerelease_mode: true
    # If enabled, diagnostic information will be added to the action output.
    debug: false
    # If true, the branch will be used to select the maximum version.
    version_from_branch: false
```

--------------------------------

### Configure Increment Every Release Strategy

Source: https://github.com/paulhatch/semantic-version/blob/master/guide.md

Use this strategy to automatically increment the version on every push to the default branch.

```yaml
- uses: paulhatch/semantic-version@latest
  with:
    bump_each_commit: true
```

--------------------------------

### Implement Branch-Based Versioning

Source: https://context7.com/paulhatch/semantic-version/llms.txt

Derives version numbers from branch names to support concurrent release lines with independent tracking.

```yaml
name: Multi-Release Versioning
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get Version from Branch
        id: version
        uses: paulhatch/semantic-version@v5.4.0
        with:
          version_from_branch: true
          # Or specify custom pattern:
          # version_from_branch: "/v([0-9]+.[0-9]+$|[0-9]+)$/"

      - name: Output
        run: echo "Version: ${{ steps.version.outputs.version }}"
```

--------------------------------

### Configure Monorepo Service Versioning

Source: https://github.com/paulhatch/semantic-version/blob/master/guide.md

Versions a specific service independently based on changes within a defined path, with an optional step to cancel the workflow if no changes are detected.

```yaml
- id: version
  uses: paulhatch/semantic-version@latest
  with:
    change_path: "src/my-service"
    namespace: my-service
- name: Cancel if Unchanged
  if: ${{ ! fromJSON(steps.version.outputs.changed) }}
  run: |
    gh run cancel ${{ github.run_id }}
    gh run watch ${{ github.run_id }}
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Customize Tag Prefix Configuration

Source: https://context7.com/paulhatch/semantic-version/llms.txt

Configures the tag prefix to match repository conventions or removes it entirely.

```yaml
name: Custom Tag Prefix
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # Default: looks for tags like v1.2.3
      - name: Version with v prefix
        uses: paulhatch/semantic-version@v5.4.0
        with:
          tag_prefix: "v"  # default

      # No prefix: looks for tags like 1.2.3
      - name: Version without prefix
        uses: paulhatch/semantic-version@v5.4.0
        with:
          tag_prefix: ""

      # Custom prefix: looks for tags like release/1.2.3 or version/1.2.3
      - name: Version with custom prefix
        uses: paulhatch/semantic-version@v5.4.0
        with:
          tag_prefix: "release/"
```

--------------------------------

### Monorepo Support with Namespaces

Source: https://context7.com/paulhatch/semantic-version/llms.txt

Version multiple projects independently within a monorepo using namespaces and path-based change detection. Each namespace tracks versions independently, and `change_path` filters which commits affect version increments.

```yaml
name: Monorepo Versioning
on: [push]

jobs:
  version-services:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # Main application version
      - name: App Version
        id: app-version
        uses: paulhatch/semantic-version@v5.4.0
        with:
          change_path: "src/app"
          namespace: app

      # API service version (independent)
      - name: API Version
        id: api-version
        uses: paulhatch/semantic-version@v5.4.0
        with:
          change_path: "src/api"
          namespace: api
          major_pattern: "(API-MAJOR)"
          minor_pattern: "(API-MINOR)"

      # Database migrations version
      - name: DB Version
        id: db-version
        uses: paulhatch/semantic-version@v5.4.0
        with:
          change_path: "src/migrations"
          namespace: db

      - name: Build Changed Services
        run: |
          if [ "${{ steps.app-version.outputs.changed }}" == "true" ]; then
            echo "Building app v${{ steps.app-version.outputs.version }}"
          fi
          if [ "${{ steps.api-version.outputs.changed }}" == "true" ]; then
            echo "Building api v${{ steps.api-version.outputs.version }}"
          fi
```

--------------------------------

### Track Contributors in GitHub Actions

Source: https://context7.com/paulhatch/semantic-version/llms.txt

Configure the semantic-version action to output contributor data in JSON or CSV format for use in release notes.

```yaml
name: Release with Contributors
on:
  push:
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get Version Info
        id: version
        uses: paulhatch/semantic-version@v5.4.0
        with:
          user_format_type: "json"  # or "csv" (default)

      - name: Create Release Notes
        run: |
          echo "# Release ${{ steps.version.outputs.version }}" > notes.md
          echo "" >> notes.md
          echo "## Contributors" >> notes.md
          echo '${{ steps.version.outputs.authors }}' | jq -r '.[] | "- \(.name) (\(.commits) commits)"' >> notes.md
          cat notes.md
```

--------------------------------

### Bump Each Commit Mode for Continuous Deployment

Source: https://context7.com/paulhatch/semantic-version/llms.txt

Increment the version for every commit instead of waiting for explicit version tags. This mode is useful for continuous deployment pipelines where each commit should result in a new version.

```yaml
name: Continuous Deployment
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get Version (Bump Each Commit)
        id: version
        uses: paulhatch/semantic-version@v5.4.0
        with:
          bump_each_commit: true
          version_format: "${major}.${minor}.${patch}"

      - name: Deploy
        run: |
          echo "Deploying v${{ steps.version.outputs.version }}"
```

--------------------------------

### Cancel Unchanged Builds with Path Monitoring

Source: https://context7.com/paulhatch/semantic-version/llms.txt

Skip builds when no relevant files have changed by using the `changed` output in conjunction with `change_path`. The `changed` output is true if commits since the last tag modified files in `change_path`, false otherwise.

```yaml
name: Conditional Build
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get Version
        id: version
        uses: paulhatch/semantic-version@v5.4.0
        with:
          change_path: "src/my-service"
          namespace: my-service

      - name: Cancel if Unchanged
        if: ${{ ! fromJSON(steps.version.outputs.changed) }}
        run: |
          echo "No changes in src/my-service, cancelling workflow"
          gh run cancel ${{ github.run_id }}
          gh run watch ${{ github.run_id }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Build Service
        if: ${{ fromJSON(steps.version.outputs.changed) }}
        run: |
          echo "Building my-service v${{ steps.version.outputs.version }}"
          npm run build
```

--------------------------------

### Configure Increment from Commit Message Strategy

Source: https://github.com/paulhatch/semantic-version/blob/master/guide.md

Use this strategy to increment the version only when commit messages match specific patterns defined by the bump_each_commit_patch_pattern parameter.

```yaml
- uses: paulhatch/semantic-version@latest
  with:
    bump_each_commit: true
    bump_each_commit_patch_pattern: "(PATCH)"
```

--------------------------------

### Custom Major/Minor Commit Patterns

Source: https://context7.com/paulhatch/semantic-version/llms.txt

Override the default Conventional Commits patterns with custom strings or regular expressions to match your team's commit message conventions. This allows for flexible version bumping logic.

```yaml
name: Custom Commit Patterns
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Version with Custom Patterns
        id: version
        uses: paulhatch/semantic-version@v5.4.0
        with:
          # Simple string matching
          major_pattern: "(MAJOR)"
          minor_pattern: "(MINOR)"

          # Or use regular expressions (wrapped in /)
          # major_pattern: "/BREAKING[- ]CHANGE:|^break:/i"
          # minor_pattern: "/^feat(\(.+\))?:|^feature:/i"

          # Regex flags: i (case-insensitive), d, g, s
          # major_regexp_flags: "i"
          # minor_regexp_flags: "i"

      - name: Output Version
        run: echo "Version ${{ steps.version.outputs.version }}"
```

```text
# With these patterns:
# "fix: bug fix"           -> patch bump (1.0.0 -> 1.0.1)
# "(MINOR) add feature"    -> minor bump (1.0.0 -> 1.1.0)
# "(MAJOR) breaking change"-> major bump (1.0.0 -> 2.0.0)

# Default patterns (Conventional Commits):
```

--------------------------------

### Override Branch Versioning Pattern

Source: https://github.com/paulhatch/semantic-version/blob/master/guide.md

Uses a custom regex pattern to extract the version from the branch name.

```yaml
- uses: paulhatch/semantic-version@latest
  with:
    version_from_branch: "/v([0-9]+.[0-9]+$|[0-9]+)$/"
```

--------------------------------

### Ignore Commits Pattern in Semantic Versioning

Source: https://context7.com/paulhatch/semantic-version/llms.txt

Configure the action to ignore specific commit message patterns, preventing them from triggering version bumps. Useful for maintenance commits like chore, docs, style, and ci.

```yaml
name: Version with Ignored Commits
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get Version (Ignoring Maintenance Commits)
        id: version
        uses: paulhatch/semantic-version@v5.4.0
        with:
          # Ignore chore, docs, style, and ci commits
          ignore_commits_pattern: "/^chore:|^docs:|^style:|^ci:/"

      - name: Check Results
        run: |
          echo "Version: ${{ steps.version.outputs.version }}"
          echo "Changed: ${{ steps.version.outputs.changed }}"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.