---
name: azldev-update-component
description: "Read this before finalizing a component change, changing source resolution, or touching a lock file; lock edits are easy to get wrong. Explains how to refresh azldev component lock files with 'azldev comp update', covering when to run update versus render, the update/render/commit/re-render/amend workflow, and per-component versus -a refresh. Triggers include comp update, refresh lock, bump pin, change snapshot, upstream distro, lock drift, version bump, finalize component."
---

# Update component lock files

`azldev comp update` (`comp` is an alias for `component`) refreshes one or more
component lock files under `locks/`. A lock pins the resolved upstream commit plus
an input fingerprint computed from the component's render inputs — its TOML config,
overlays, the pinned upstream commit, and the distro release version. If any of
those change, the lock is stale.

## When to run `update`

| Situation | Run `update`? |
| --- | --- |
| Adding a new upstream component (no lock yet) | **Yes** — first, to create the lock before `render`/`build` can resolve it |
| Finalizing a component change for a PR | **Yes** — once at the end |
| Changing source resolution (commit pin, upstream distro/version, or snapshot) | **Yes** — also mid-workflow (see below) |
| Iterating on overlays / build config / metadata | No — once the lock exists, `render` alone is enough while iterating |
| Just reading or building existing components | No |

Refresh a single component with `-p <name>`. Use `-a` (all components) only for
coordinated mass refreshes (e.g. a new distro snapshot) or when investigating
lock drift across many components — it is slow. For day-to-day work use `-p`. Add
`-O json` for machine-readable lock output when debugging.

## End-of-work refresh (the common case)

For most edits — overlays, build flags, metadata — run `update` once at the end,
then re-render *after committing* so the generated changelog and release reflect
your new commit:

```sh
azldev comp update -p <name>
azldev comp render -p <name>
git add <changed-component-config-and-source-paths> \
	locks/<name>.lock \
	specs/<first-char>/<name>/
git commit -m "fix(<name>): ..."

# Re-render and amend so the changelog / Release: track the new commit.
azldev comp render -p <name>
git add specs/<first-char>/<name>/
git commit --amend --no-edit
```

### Why the second render-and-amend?

Changelog generation and release calculation are separate. When a spec uses
`%autochangelog`, rpmautospec derives it from the component's **git history** for
every release mode. For non-manual release modes, azldev also derives or bumps
`Release:` from that history. The first render happens before your commit exists,
so a fresh render *after* committing incorporates the new changelog entry and any
automatic release bump. Amending folds that output into a single clean commit and
keeps rendered-spec / lock CI gates (which run against committed state) green.

For a component with `release.calculation = "manual"`, increment the release
counter yourself in the same change. Manual mode is not an exemption from the
post-commit render-stage-amend cycle: when the spec uses `%autochangelog`, that
render incorporates the new commit.

## Changing source resolution

A source-resolution change follows the same rule, using one commit followed by a
post-render amend:

1. Change the commit pin, upstream distro/version, or snapshot, then `azldev comp update -p <name>`; sanity-check `locks/<name>.lock`.
2. `azldev comp render -p <name>` — the spec body now tracks the newly resolved source. `%changelog` / `Release:` still reflect the previous source; that is expected until you commit.
3. Iterate on overlays / patches / build config as the new source requires, re-rendering after each change. Re-run `update` only if you change a source-resolution input again.
4. `azldev comp update -p <name>`, then stage and commit all component inputs changed above with the refreshed lock and rendered output:

   ```sh
   git add <changed-component-config-and-source-paths> \
	   locks/<name>.lock \
	   specs/<first-char>/<name>/
   git commit -m "update(<name>): ..."
   ```
5. `azldev comp render -p <name>` — `%changelog` / `Release:` now reflect the new lock.
6. `git add specs/<first-char>/<name>/`, then `git commit --amend --no-edit` so the source change and rendered output land together.

Generated by `azldev docs agent`; do not hand-edit.