[LIB+CLI] Add flag to explicitly preserve null values in merge

[mozesl-nokia]

Depends on #4745

Added a new flag that allows you to explicitly preserve null values during merge3/update/upgrade.

The use-case for this is packages that are already meant to be patches themselves. Calling the current merge3 flow on such packages can cause the null to get cleared or overridden unintentionally, leading to "combination packages" to inconsistently remove/not remove values.

Default behaviour is unchanged.

The flag is supported by the kpt update command as well, which is persisted into the Kptfile.

AI disclosure: Cursor's Grok 4.6 and Claude Sonnet 5 were used for analysis and most of the implementation

[netlify]

✅ Deploy Preview for kptdocs ready!

Name	Link
🔨 Latest commit	6f34b23
🔍 Latest deploy log	https://app.netlify.com/projects/kptdocs/deploys/6ab4f11b0706010007a8d80a
😎 Deploy Preview	https://deploy-preview-4746--kptdocs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

🟡 Changes recommended

Associative lists and the kptops.PkgUpdate path do not honor the new persisted setting.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds opt-in preservation of explicit YAML null values during resource-merge updates.

Changes:

• Propagates and persists preserveExplicitNull.
• Updates merge3 behavior and CLI support.
• Adds fixtures, tests, documentation, and API dependency updates.

File summaries

File	Description
pkg/lib/update/updatetypes/updatetypes.go	Adds merge option.
pkg/lib/update/update.go	Persists and propagates the option.
pkg/lib/update/update_test.go	Tests Kptfile persistence.
pkg/lib/update/testdata/keep-tagged-null-preserve/updated/Kptfile	Updated fixture metadata.
pkg/lib/update/testdata/keep-tagged-null-preserve/updated/configmap.yaml	Updated resource fixture.
pkg/lib/update/testdata/keep-tagged-null-preserve/origin/Kptfile	Origin fixture metadata.
pkg/lib/update/testdata/keep-tagged-null-preserve/origin/configmap.yaml	Origin resource fixture.
pkg/lib/update/testdata/keep-tagged-null-preserve/expected/Kptfile	Expected fixture metadata.
pkg/lib/update/testdata/keep-tagged-null-preserve/expected/configmap.yaml	Expected preserved-null output.
pkg/lib/update/testdata/keep-tagged-null-preserve/dest/Kptfile	Destination fixture metadata.
pkg/lib/update/testdata/keep-tagged-null-preserve/dest/configmap.yaml	Destination null-value fixture.
pkg/lib/update/resource-merge.go	Passes the option into merge3.
pkg/lib/update/resource-merge_test.go	Tests preserved scalar nulls.
pkg/lib/update/merge3/visitor.go	Implements persistent null handling.
pkg/lib/update/merge3/tuple.go	Carries the option into visitors.
pkg/lib/update/merge3/merge3.go	Extends the merge API.
pkg/lib/update/merge3/merge3_util_test.go	Updates existing merge calls.
internal/docs/generated/pkgdocs/docs.go	Regenerates CLI documentation.
go.mod	Updates the kpt API dependency.
go.sum	Updates dependency checksums.
documentation/content/en/reference/cli/pkg/update/_index.md	Documents the flag and behavior.
documentation/content/en/guides/3-way-merge.md	Documents null preservation.
commands/pkg/update/cmdupdate.go	Adds CLI flag handling.
commands/pkg/update/cmdupdate_test.go	Tests flag parsing.

Review details

• Files reviewed: 22/24 changed files
• Comments generated: 3
• Review effort level: Balanced (auto)

Note

Copilot is running an experiment and ran this review at Balanced.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mozesl-nokia]

Before merging this, it is probably a good idea to create a new tag for the api module and use that in go.mod, not the commit version.

[liamfallon]

Before merging this, it is probably a good idea to create a new tag for the api module and use that in go.mod, not the commit version.

There's already a redirect in the go.mod following the merge of the regexp PR yesterday so I think we should do an API release soon. We can go ahead and merge this one anyway because we'll have to raise a PR on kpt anyway to remove redirect.

[sonarqubecloud]

Quality Gate failed

Failed conditions
77.8% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud