--- title: changelog bundle-amend cli command description: Amend a bundle with additional or excluded changelog entries without modifying the parent bundle file. Amend bundles follow a specific naming convention:... url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3907/cli/changelog/bundle-amend products: - Elastic Docs Builder --- # changelog bundle-amend cli command ```bash docs-builder changelog bundle-amend [options] ``` Amend a bundle with additional or excluded changelog entries without modifying the parent bundle file. Amend bundles follow a specific naming convention: `{parent-bundle-name}.amend-{N}.yaml` where `{N}` is a sequence number. Specify at least one of `--add` or `--remove`. To create a bundle, use [changelog bundle cli command](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3907/cli/changelog/bundle). For details and examples, go to [Bundle changelogs](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3907/data/release-notes/bundle). ## Arguments Required: Path to the original bundle file to amend **Constraints:** symbolic links not allowed, must exist, extensions: yml, yaml ## Options Optional: Changelog YAML paths to add. Repeat --add or pass a comma-separated list in one value (for example, --add "file1.yaml,file2.yaml"). Supports tilde (~) expansion and relative paths. When entries are sourced from the CDN (the default when bundle.repo or the parent bundle's repo resolves), paths are matched by file name and do not need to exist locally; with local sourcing (--force-local or bundle.use_local_changelogs) the paths must exist on disk. **Repeatable:** pass `--add` multiple times to supply more than one value Optional: Changelog YAML paths to exclude from the effective bundle. Repeat --remove or pass a comma-separated list in one value. Supports tilde (~) expansion and relative paths. When entries are sourced from the CDN, paths are matched by file name and do not need to exist locally; with local sourcing the paths must exist on disk unless --force is used to exclude by file name. **Repeatable:** pass `--remove` multiple times to supply more than one value Optional: When removing, match by file name even if the bundle checksum differs from the sourced changelog, or when no YAML can be sourced (inferred git-ref entries). **Default:** `false` Optional: Force local entry sourcing for this run (equivalent to bundle.use_local_changelogs: true without editing config). **Default:** `false` Optional: Preview changes without writing an amend file. **Default:** `false` Minimum log level. **Values:** trace, debug, information, warning, error, critical, none **Default:** `information` Override the configuration source: local, remote **Values:** local, remote, embedded Skip cloning private repositories ## Global Options Minimum log level. **Values:** trace, debug, information, warning, error, critical, none **Default:** `information` Override the configuration source: local, remote **Values:** local, remote, embedded Skip cloning private repositories ## Output Amend bundles contain the parent bundle's `products` plus only the changes for that amend file, not a full repetition of the original bundle's entries. The parent's complete `products` (including `target`, `repo`, and `owner`) are copied into every amend file so the amend is self-contained: upload destination discovery, the registry's per-product `target`, and `:version:`-filtered CDN consumption all derive from a bundle file's own products. Like bundles, amend files embed the full changelog content of each entry: entries added with `--add` carry inline `title`, `type`, `products`, and so on, alongside a `file` block recording the source file name and checksum for provenance. Additions: ```yaml # 9.3.0.amend-1.yaml products: - product: elasticsearch target: 9.3.0 repo: elasticsearch owner: elastic entries: - file: name: late-addition.yaml checksum: abc123def456 type: bug-fix title: A late addition products: - product: elasticsearch target: 9.3.0 ``` Removals: ```yaml # 9.3.0.amend-2.yaml products: - product: elasticsearch target: 9.3.0 repo: elasticsearch owner: elastic exclude-entries: - file: name: 138723.yaml checksum: def456abc123 ``` An amend file can contain both `exclude-entries` and `entries`. Within each amend file, exclusions are applied before additions. When bundles are loaded (either via the `changelog render` command or the `{changelog}` directive), amend files are **automatically merged** with their parent bundles in sequence (`amend-1`, `amend-2`, …). The result is rendered as a single release. Amend bundles created by older docs-builder versions may omit `products`; they are still accepted when loading and merge into their parent as before. `hide-features` is always inherited from the parent bundle. If an amend bundle is found without a matching parent bundle, it remains standalone.`rules.bundle` filtering does not apply to `changelog bundle-amend`. The command is a direct-injection escape hatch: the files you specify with `--add` are always included regardless of any product, type, or area filter configuration.`--add` and `--remove` follow the same entry-sourcing gate as [changelog bundle cli command](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3907/cli/changelog/bundle): CDN by default when `bundle.repo` or the parent bundle's `repo` resolves; local disk when `--force-local` or `bundle.use_local_changelogs` is set, or when no authoring repo can be resolved. In CDN mode, paths are matched by file name (including CDN paths such as `/changelog/elastic/kibana/main/247279.yaml`) and do not need to exist locally. Use `--force-local` to read local changelogs from disk.The parent bundle argument is always a local file. The command writes `{parent}.amend-N.yaml` next to it and does not fetch the parent from the CDN. ## Examples ### Add a changelog from the CDN The first argument is the local parent bundle. `--add` can be a CDN path (matched by file name) when entry sourcing uses the CDN: ```sh docs-builder changelog bundle-amend \ ./docs/changelog/bundles/9.3.0.yaml \ --add /changelog/elastic/kibana/main/138723.yaml ``` ### Add a single local changelog to a bundle ```sh docs-builder changelog bundle-amend \ ./docs/changelog/bundles/9.3.0.yaml \ --add ./docs/changelog/138723.yaml \ --force-local ``` ### Remove a changelog from a bundle ```sh docs-builder changelog bundle-amend \ ./docs/changelog/bundles/9.3.0.yaml \ --remove /changelog/elastic/kibana/main/138723.yaml ``` The CLI computes the checksum of the sourced YAML and matches it against the effective bundle (parent plus any existing amend files). If the bundle contains the file with a different checksum, the command fails unless you pass `--force` to remove by file name only. ### Remove an inferred git-ref entry Git-ref bundles created with `--infer` (or `infer_missing_changelogs: true`) can include entries that were synthesized from GitHub PR metadata. Those entries live only in the bundle. Their `file.name` is `{pull-request-number}.yaml`, and there is no changelog YAML on disk or on the CDN whose checksum you can match. Pass `--force` so matching is by filename only. The path does not need to exist: ```sh docs-builder changelog bundle-amend ./docs/releases/cloud-hosted-2026-08-13.yaml \ --remove 300.yaml --force ``` Refer to [changelog bundle cli command > Inferred entries and bundle-amend](/elastic/docs-builder/pull/3907/cli/changelog/bundle#inferred-entries) for the full workflow, including how to replace inferred copy with a real changelog. ### Add multiple changelogs to a bundle Comma-separated list: ```sh docs-builder changelog bundle-amend \ ./docs/changelog/bundles/9.3.0.yaml \ --add "./docs/changelog/138723.yaml,./docs/changelog/1770424335.yaml" \ --force-local ``` Or repeat `--add`: ```sh docs-builder changelog bundle-amend \ ./docs/changelog/bundles/9.3.0.yaml \ --add ./docs/changelog/138723.yaml \ --add ./docs/changelog/1770424335.yaml \ --force-local ``` ### Remove multiple changelogs from a bundle ```sh docs-builder changelog bundle-amend \ ./docs/changelog/bundles/9.3.0.yaml \ --remove "./docs/changelog/old-a.yaml,./docs/changelog/old-b.yaml" \ --force-local ``` ### Replace an entry in one amend file ```sh docs-builder changelog bundle-amend \ ./docs/changelog/bundles/9.3.0.yaml \ --remove ./docs/changelog/old-entry.yaml \ --add ./docs/changelog/new-entry.yaml \ --force-local ``` ### Preview without writing an amend file ```sh docs-builder changelog bundle-amend \ ./docs/changelog/bundles/9.3.0.yaml \ --remove /changelog/elastic/kibana/main/138723.yaml \ --dry-run ```