# `homeboy version`

## Synopsis

```sh
homeboy version <COMMAND>
```

## Subcommands

### `show`

```sh
homeboy version show [<component_id>]
```

Shows the current version for the specified component, or the Homeboy binary version if omitted.

### `bump`

```sh
homeboy version bump [<component_id>] <patch|minor|major>
homeboy version bump [<component_id>] <patch|minor|major> --no-commit
```

Flags:

- `--dry-run`: Simulate the bump without making any changes
- `--no-commit`: Skip automatic git commit after bump

### `set`

```sh
homeboy version set [<component_id>] <new_version>
```

`set` writes the version targets directly without incrementing and does not finalize the changelog.

## Description

`homeboy version bump`:

- Bumps all configured `version_targets` using semantic versioning (X.Y.Z).
- Finalizes the component changelog by moving the current "next" section (usually `Unreleased`) into a new `## [<new_version>] - YYYY-MM-DD` section.
- **Auto-commits** version target files and changelog with message `release: v{new_version}`. Use `--no-commit` to skip.
- Runs any `post_version_bump_commands` configured on the component.

`homeboy version set`:

- Writes the new version directly to targets without touching the changelog.

Changelog entries must be added *before* running `version bump` (recommended: `homeboy changelog add --json ...`). Make sure the changelog includes ALL changes since the last update, not just the ones you personally worked on. 

Recommended release workflow (non-enforced):

- Land work as scoped feature/fix commits first.
- Use `homeboy changes <component_id>` to review everything since the last tag.
- Add changelog items as user-facing release notes that capture anything impacting user or developer experience (not a copy of commit subjects).
- Run `homeboy version bump ...` when the only remaining local changes are release metadata (changelog + version).

Note: `--json` for changelog entries is on `homeboy changelog add` (not `homeboy changelog`).

Arguments:

- `[<component_id>]`: component ID (optional, shows Homeboy binary version when omitted)
- `<patch|minor|major>`: version bump type

## JSON output

> Note: all command output is wrapped in the global JSON envelope described in the [JSON output contract](../json-output/json-output-contract.md). `homeboy version` returns a `VersionOutput` object as the `data` payload.

`homeboy version show` data payload:

- `command`: `version.show`
- `component_id`
- `version` (detected current version)
- `targets`: array of `{ file, pattern, full_path, match_count }`

`homeboy version bump` data payload:

- `command`: `version.bump`
- `component_id`
- `old_version` (version before bump)
- `new_version` (version after bump)
- `targets`: array of `{ file, pattern, full_path, match_count }`
- `changelog_path` (resolved changelog path)
- `changelog_finalized` (always `true` on success)
- `changelog_changed` (whether the changelog file was modified)
- `git_commit` (present unless `--no-commit` or `--dry-run`):
  - `success`: boolean
  - `message`: commit message (`release: v{new_version}`)
  - `files_staged`: array of file paths
  - `stdout` (omitted if empty)
  - `stderr` (omitted if empty)

`homeboy version set` data payload:

- `command`: `version.set`
- `component_id`
- `old_version`
- `new_version`
- `targets`: array of `{ file, pattern, full_path, match_count }`

Errors:

- `bump` errors if the changelog cannot be resolved, if the changelog is out of sync with the current version, or if the "next" section is missing/empty.
- `bump` errors if the current version is not semantic versioning format (X.Y.Z).

Notes:

- Homeboy does not auto-fix existing changelogs. If the next section is missing or empty, follow the hints in the error to fix it manually.
- Configure `post_version_bump_commands` on a component to run extra tasks (for example, `cargo generate-lockfile`) after the bump.

## Exit code

- `show`: `0` on success; errors if the version cannot be parsed.
- `bump`: `0` on success.
- `set`: `0` on success.

## Notes

- Components must have `version_targets` configured (non-empty). Homeboy uses the first target as the primary version source.
- Each `version_targets[]` entry has `file` and optional `pattern`. When `pattern` is omitted, Homeboy checks module-provided version patterns for that file type; if none are provided, the command errors.

### Changelog Requirements

`version bump` requires a changelog file. Homeboy auto-detects changelogs at well-known locations:

1. `CHANGELOG.md`
2. `changelog.md`
3. `docs/CHANGELOG.md`
4. `docs/changelog.md`
5. `HISTORY.md`

If your changelog is at a non-standard location, configure `changelog_target`:

```sh
homeboy component set <id> --changelog-target "path/to/CHANGELOG.md"
```

To bypass changelog finalization entirely, use `version set` instead of `version bump`.

## Related Workflows

Before bumping, add changelog entries:

```sh
homeboy changelog add <component_id> "Added: new feature"
homeboy changelog add <component_id> -m "Fixed: bug" -m "Changed: behavior"
```

After bumping, push and optionally tag:

```sh
homeboy git push <component_id>
homeboy git tag <component_id>
```

## Related

- [build](build.md)
- [component](component.md)
- [git](git.md)
