What does helm repo index --merge do that regenerating the index alone does not?

This flag exists because `helm repo index` has no memory. It is a pure function of one directory: open every chart package in it, copy each chart's metadata into an entry, write `index.yaml`. Nothing about the resulting file is incremental. If a version's `.tgz` is not in the directory when you run the command, that version is not in the file you just produced. ## The failure this causes The classic incident looks like this. A chart called `digest-builder` - a single-service chart with an Ingress and a HorizontalPodAutoscaler for an email-digest builder - has 63 published versions living in an object-store bucket, listed in a 412 KiB `index.yaml`. The publish job runs `helm package`, producing one tarball in the job's empty workspace, then runs `helm repo index .` there and uploads both files. The upload succeeds. The bucket still holds all 63 tarballs. But the catalogue now lists exactly one version, so `helm search repo` shows one version, `--version 2.6.1` fails to resolve for every consumer that refreshes, and any pipeline that installs a pinned older version breaks the moment its cached index expires. Nothing was deleted; the map to the data was replaced with a map of one house. ## What --merge actually does `helm repo index <dir> --merge <path-to-index.yaml>` generates the index from the directory as usual, then folds in the entries of the index file you point at, so chart versions that exist only in that older index are carried into the output. The result is a catalogue that is the union of what you just built and what was already published. The flag takes a *file path*, so the normal shape in a pipeline is to download the live index first: ```bash curl -fsSL https://charts.internal.example/charts/index.yaml -o previous-index.yaml helm repo index . --merge previous-index.yaml \ --url https://charts.internal.example/charts ``` ## The two publishing patterns **Re-index the whole catalogue.** Keep every published tarball in one place - typically syncing the bucket down, or generating the site from a directory that holds all of them - and run a plain `helm repo index` over it. No merge needed, and the index is always a faithful description of what is actually there. This is the more robust option and it is what static-site style chart repositories usually do; the cost is transferring the whole catalogue on every publish. **Merge into the live index.** Fetch `index.yaml`, generate from a directory containing only the new package, merge, upload the new tarball and the new index. Cheap and fast, and the option most CI jobs reach for. The cost is that the index becomes state you edit blind: it can now describe versions whose files are gone, and it is exposed to a lost-update race. ## The race worth naming Merging is read-modify-write against a shared file with no locking. Two publish jobs that both download `index.yaml` at the same moment each merge their own package into their own copy; whichever uploads second overwrites the first, and that version vanishes from the catalogue while its tarball sits perfectly healthy in the bucket. It is a lost update, and it is invisible until someone tries to install the missing version. Serialise publishes for a given repository - a single-concurrency job or a lock - or use the full re-index pattern, where the source of truth is the set of files rather than a snapshot of a file. ## What --merge does not do It does not upload anything - publishing remains a file copy you arrange yourself. It does not repair entries in the old index: an entry that points at a wrong or dead URL keeps pointing there, because merged entries are carried across as they are rather than recomputed. And it is not a substitute for keeping the packages: a merged index entry whose tarball has been deleted is a 404 waiting to happen, and it will surface as a download failure at install time rather than as a search-time absence, which is a considerably more confusing report to receive. ## The neighbouring flag `--url` is often confused with `--merge` because they are usually typed together. `--url` sets the base URL prefixed onto the package filenames in the generated entries' `urls` field. You need it whenever the index is generated somewhere other than where the files are served from - which, in a pipeline, is always. Entries carried in by `--merge` keep the URLs they already had, so a change of hosting requires regenerating the whole catalogue rather than merging on top of it.