homeboy 0.26.4

CLI for multi-component deployment and development workflow automation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163

# `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)