homeboy 0.31.1

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

# `homeboy changes`

## Synopsis

```sh
homeboy changes [<component_id>] [--since <tag>] [--git-diffs]
homeboy changes --json <spec> [--git-diffs]

# Project mode
homeboy changes --project <project_id> [<component_ids...>] [--git-diffs]
homeboy changes <project_id> <component_id> [<component_id>...] [--git-diffs]
```

## Component Auto-Detection

When run from a directory containing exactly one Homeboy-managed component, the component ID is optional:

```sh
# In a managed directory with one component
homeboy changes              # Auto-detects component
homeboy changes my-component # Explicit (always works)
```

When multiple components exist or directory is unmanaged, explicit ID is required.

## Description

Show changes since the latest git tag for one component, multiple components (bulk JSON), or all components attached to a project.

This command reports:

- commits since the last tag (or a user-provided tag via `--since`)
- uncommitted changes in the working tree (including `uncommittedDiff`)
- optionally, a commit-range diff for commits since the baseline (via `--git-diffs`)

Release workflow note:

- `commits[]` is intended as input to help you author complete release notes.
- `uncommitted`/`uncommitted_diff` is a reminder that you have local edits; if they are intended for the release, commit them as scoped changes before version bumping. If they are not intended for the release, resolve them before version bumping.
- Use `homeboy changelog add` to capture release notes before running `homeboy version bump` or `homeboy release`.

## Options

- `--json <spec>`: bulk mode input
  - Priority: `--json > --project > positional`
  - `<spec>` supports `-` (stdin), `@file.json`, or an inline JSON string
  - Spec format: `{ "component_ids": ["id1", "id2"] }`
- `--project <project_id>`: show changes for all components attached to a project
  - If you also pass positional `<component_ids...>`, Homeboy only returns changes for those components
- `--since <tag>`: tag name to compare against (single-component mode only)
- `--git-diffs`: include commit-range diff content in output

## JSON output

> Note: all command output is wrapped in the global JSON envelope described in the [JSON output contract](../architecture/output-system.md). `homeboy changes` returns either a single `ChangesOutput` or a bulk `BulkChangesOutput` as `data`.

### Single-component output

```json
{
  "component_id": "<component_id>",
  "path": "<local path>",
  "success": true,
  "latest_tag": "<tag>|null",
  "baseline_source": "tag|version_commit|last_n_commits",
  "baseline_ref": "<ref>|null",
  "commits": [
    {
      "hash": "<sha>",
      "subject": "<subject>",
      "category": "Feature|Fix|Breaking|Docs|Chore|Other"
    }
  ],
  "uncommitted": {
    "has_changes": true,
    "staged": ["..."],
    "unstaged": ["..."],
    "untracked": ["..."],
    "hint": "Large untracked list detected..."
  },
  "uncommitted_diff": "<diff>",
  "diff": "<diff>"
}
```

Notes:

- `uncommitted_diff` is present when the working tree has changes.
- `diff` is included only when `--git-diffs` is used.
- `uncommitted.hint` appears when untracked output is unusually large.
- Optional fields like `warning` / `error` may be omitted when unset.

### Bulk output (`--json` or `--project`)

```json
{
  "action": "changes",
  "results": [
    {
      "id": "<component_id>",
      "component_id": "<component_id>",
      "path": "<local path>",
      "success": true,
      "commits": [...],
      "uncommitted": {...},
      "error": null
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  }
}
```

Notes:

- Each item in `results` contains `id` plus all `ChangesOutput` fields flattened in.
- `error` is set when that component failed; `success` and other fields are omitted on failure.

## Exit code

- `0` when the command succeeds and `summary.failed == 0`.
- `1` in bulk/project modes when `summary.failed > 0`.

## jq examples

Extract diffs for scripting:

```sh
# Single mode: extract uncommitted diff
homeboy changes my-component --git-diffs | jq -r '.data.uncommitted_diff // empty'

# Single mode: extract commit-range diff
homeboy changes my-component --git-diffs | jq -r '.data.diff // empty'

# Bulk mode: extract all diffs (one per component)
homeboy changes --project myproject --git-diffs | jq -r '.data.results[].diff // empty'

# Bulk mode: list components with uncommitted changes
homeboy changes --project myproject | jq -r '.data.results[] | select(.uncommitted.has_changes) | .id'
```

## Related

- [git](git.md)
- [version](version.md)