HIP: Bring .helmignore to parity with .gitignore for Charts v3

[scottrigby]

Summary

This HIP proposes bringing .helmignore file targeting semantics to full parity with .gitignore syntax and matching rules for Charts v3. The current implementation diverges from .gitignore in critical ways—most notably in rule evaluation order (first-match vs. last-match), negation pattern behavior, and lack of ** recursive glob support.

By scoping this change to Charts v3 (per HIP-0020), existing charts continue to work unchanged while v3 charts opt into consistent, predictable ignore behavior.

Motivation

Users familiar with .gitignore expect the same behavior from .helmignore. A comprehensive search of helm/helm issues reveals 27 directly related issues and 5 pull requests showing recurring user pain around pattern matching, negation, and documentation gaps.

References

helm/helm Issues Directly Addressed

• Negations in .helmignore cannot be used effectively helm#8688
• Allow Listing in .helmignore with '/*' returns "chart metadata (Chart.yaml) missing" helm#3622
• .helmignore ".*" entry incorectly ignores current directory helm#1776
• helm package using helm 3.8.1 appears to partially ignore contents of .helmignore  helm#12592
• More gitignore-like implementation of negative ignore rules helm#12265

helm/helm Issues (Context/Out of Scope)

• helm template won't generate output if that yaml is ignored by .helmignore helm#6075
• .helmignore and .Files.Get helm#3050
• .helmignore file not ignored by helm package helm#9436
• Helm release version contains README.md helm#10764
• read helmignore from user's home directory helm#1674
• feat: Global helmignore file helm#5675
• add some more documentation around .helmignore file helm#4638
• fix(helm): fix helmignore evaluation of dirs helm#1028
• fix: .helmignore ignores broken symlinks helm#13293
• feat(create): add --chart-api-version flag helm#31592

helm-www Documentation Issues

• Misleading documentation of .helmignore helm-www#1171
• Docs do not specify location for .helmignore helm-www#1312
• Helm ignore file temp example helm-www#1460

Key Changes in This HIP

• Last-match-wins semantics: All rules evaluated; final matching rule determines outcome
• Negation behavior: !pattern re-includes files (matching .gitignore)
• Recursive globs: Full ** support (**/foo, foo/**, a/**/b)
• Escape sequences: \#, \!, \ supported
• Charts v3 only: Gated behind apiVersion: v3; Charts v2 unchanged

[gjenkins8]

There is one more problem iirc -- today Helm only respects .helmignore for helm package. It will ignore .helmignore if the chart is unpacked/untarred

[scottrigby]

.helmignore definitely ignores files during helm runtime operations too - on both a packed ann unpacked chart - including helm template, install, etc. Here is an unpacked example:

d=$(mktemp -d)
mkdir -p $d/templates $d/files

cat > $d/Chart.yaml <<'EOF'
apiVersion: v2
name: test
version: 0.1.0
EOF

cat > $d/templates/cm.yaml <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Chart.Name }}-cm
data:
{{- (.Files.Glob "files/*").AsConfig | nindent 2 }}
EOF

cat > $d/templates/pod.yaml <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: {{ .Chart.Name }}-pod
spec:
  containers:
  - name: nginx
    image: nginx:alpine
EOF

cat > $d/files/test.conf <<'EOF'
test including .conf file
EOF

cat > $d/files/test.txt <<'EOF'
test including .txt file
EOF

tree $d

echo '\n=== template WITHOUT .helmignore ==='
helm template $d

cat > $d/.helmignore <<'EOF'
*.txt
pod.yaml
EOF

echo '\n=== template WITH .helmignore ==='
helm template $d

echo '\n=== install WITH .helmignore ==='
helm install --dry-run test $d

should return

/var/folders/7j/bxcg16h177zfgfkzdlv8rb240000gn/T/tmp.5QdzSnmxHz
├── Chart.yaml
├── files
│   ├── test.conf
│   └── test.txt
└── templates
    ├── cm.yaml
    └── pod.yaml

3 directories, 5 files

=== template WITHOUT .helmignore ===
---
# Source: test/templates/cm.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: test-cm
data:
  test.conf: |
    test including .conf file
  test.txt: |
    test including .txt file
---
# Source: test/templates/pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: test-pod
spec:
  containers:
  - name: nginx
    image: nginx:alpine

=== template WITH .helmignore ===
---
# Source: test/templates/cm.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: test-cm
data:
  test.conf: |
    test including .conf file

=== install WITH .helmignore ===
level=WARN msg="--dry-run is deprecated and should be replaced with '--dry-run=client'"
NAME: test
LAST DEPLOYED: Wed Dec 17 22:14:13 2025
NAMESPACE: default
STATUS: pending-install
REVISION: 1
DESCRIPTION: Dry run complete
TEST SUITE: None
HOOKS:
MANIFEST:
---
# Source: test/templates/cm.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: test-cm
data:
  test.conf: |
    test including .conf file

• Without .helmignore, both files are globbed into the configmap, and the pod template is rendered.
• With .helmignore containing *.txt and pod.yaml only the non .txt file is globbed into the configmap, and the pod is not rendered.

[gjenkins8]

Interesting, digging up my reference where I think we deemed .helmignore was not being used.

[gjenkins8]

ah, I was mistaken: helm/helm#12592 (comment)

User was reporting .helmignore was not being respected during helm package. But this just seems like an outright bug.

[banjoh]

LGTM

[gjenkins8]

I think users would expect .helmignore to affect all operations, no?

Easy example is helm install ./foo works locally, then helm package ./foo; helm install foo.tar.gz will fail, because a required file is not present in the chart (it was excluded by helm package)

[scottrigby]

Yes, it should and already does affect all operations. I can see how this bullet as-is could imply otherwise.

I just reopened that linked issue and commented helm/helm-www#1312 (comment). I should probably move this scope confusion bullet to the list of Documentation issues, since this HIP isn't proposing changing any of the behavior discussed in this scope confusion issues - and I think all of those would be addressed with better documentation.

[scottrigby]

OK, I see what you mean - the wording here implied otherwise. I removed the example from this motivation point entirely; the documentation gaps (about syntax, not scope) are sufficient motivation. Thanks for catching this!

[gjenkins8]

IMHO, .helmignore should be used for all operations. Why would we expect/want unpacked charts to work differently to packed charts?

[gjenkins8]

Below, in the "Integration points" section, there is the opposite language:

Apply .gitignore-parity matching in all chart file operations:

[scottrigby]

Yes, it does and should continue to be used for all operations. Thanks for catching the wording inconsistency. I clarified the Integration Points language to be clear this describes where the new matching logic applies, not a change in scope. .helmignore already affects all these operations; only the matching semantics change.

[gjenkins8]

Suggested change

	This is the appropriate scope because changing `.helmignore` semantics would break charts that depend on current (albeit buggy) behavior.
	This is the appropriate scope because changing `.helmignore` semantics would break charts that depend on current (albeit surprising) behavior.

nitpick: .helmignore today is working as designed. So I wouldn't say it is "buggy"

[scottrigby]

Agreed

[scottrigby]

you're right, "buggy" implies implementation defects when this is working as originally designed (just differently than users expect). Changed to "surprising" in both places.

[gjenkins8]

\ escapes any character (not just spaces and exclamation marks (below))

A backslash ("") can be used to escape any character. E.g., "*" matches a literal asterisk (and "\a" matches "a", even though there is no need for escaping there). As with fnmatch(3), a backslash at the end of a pattern is an invalid pattern that never matches.

[scottrigby]

Good point - the table was incomplete and would require duplicating gitignore docs to fix. Restructured the HIP to avoid re-documenting gitignore syntax:

1. Removed the Pattern Types table
2. Added a "Design Intent" section clarifying that Charts v3 follows gitignore semantics (with link to docs)
3. Kept focused subsections on key behavioral changes (recursive globs, rule evaluation, negation)
4. The Backwards Compatibility table shows the complete v2→v3 delta

This makes the HIP cleaner and avoids incomplete enumerations.

[gjenkins8]

Suggested change

	# Exclude everything
	/*
	# Exclude everything
	/**

We should be precise

[scottrigby]

The /* pattern is intentional here - it's a Helm-specific version of Example 2 from gitignore docs. Using /** would match recursively, which breaks the whitelist pattern because you can't re-include files whose parent directories were excluded (noted in Negation Behavior section).

Instead I updated the comment to "Exclude all top-level entries" to be more precise with language about what /* matches.

[gjenkins8]

Below, in the "Integration points" section, there is the opposite language:

Apply .gitignore-parity matching in all chart file operations:

[gjenkins8]

We need to specify that we (presumably) will only support a single .helmignore file (in the root of the chart). Or, we will match git's recusive .gitignore behavior:

Patterns read from a .gitignore file in the same directory as the path, or in any parent directory (up to the top-level of the working tree), with patterns in the higher level files being overridden by those in lower level files down to the directory containing the file. These patterns match relative to the location of the .gitignore file.

(and iirc, there is text which specifys/assumes .helmignore is in the root of the chart filesystem layout)

[scottrigby]

Good call-out. Added a "File Location" subsection clarifying that .helmignore loads only from the chart root (existing intended behavior).

For subchart .helmignore files specifically, added this as an Open Issue - unclear if the current behavior (ignoring them) is intended, a bug, or an oversight. I'll investigate and raise at the next dev meeting. For now, this HIP preserves existing behavior.

[gjenkins8]

What do we mean here by "MAY"? We should be specific as to if we are excluding or not. And we should also specify that this point means .helmignore won't be included in packaged archives (if we retain this).

---

I'm also on the fence as to whether we should do this. The only direct functional effect of excluding I think is to save a few bytes in a packaged archive. But it is another rule that people need to discover and understand (if they are impacted). #9436 doesn't really give any specific rationale either.

On the other hand, once a chart is packaged, .helmignore is spurious. The only reason it might become useful again, is if a user "mirrors" a chart (back into source) in order to modify a vendors chart (a relatively common pattern). But they could of course re-create the .helmignore file as well.

Overall, given a user could exclude .helmignore from within .helmignore if they really want to save those bytes.

I think we default to the explicit behavior (don't exclude, user can exclude via .helmignore if wanted). Unless we can come up with better reason(s). Thoughts?

[scottrigby]

Agreed - this was accidentally left in from an earlier draft. Removed. The explicit behavior (user excludes .helmignore in their own .helmignore if wanted) is better than magic auto-exclusion. This is already documented as intentional in the Out of Scope section.

[gjenkins8]

Suggested change

	- `.Files.Get` / `.Files.Glob` (file access in templates)
	- `.Files.Get` / `.Files.Glob` (file access in templates)
	- etc

nitpick: This list might not be exhaustive

[scottrigby]

Good catch - added: "This list is representative; the matching logic applies wherever chart files are loaded or accessed."

[gjenkins8]

this seems like AI generated extras? And not relevant to a HIP, unless we wanted to include this in the "How to teach this section".

[scottrigby]

Fair point - removed this section. The backwards compatibility specifics are already in the table above, and "Migration guide" is listed under "How to Teach This". No need to repeat.

[gjenkins8]

I think we don't want to do this. We need to define our own spec, which we could refer to Git's as our inspiration. e.g. if Git changes its spec, we would be on the hook to modify our behavior as a bug.

[scottrigby]

Good call-out. Clarified in the Specification section:

• .helmignore intentionally mirrors Git's .gitignore matching semantics as documented at the time of this HIP
• Divergence from current Git behavior should be treated as a bug
• Future Git changes require explicit Helm evaluation—we don't implicitly inherit them

Also updated the documentation guidance to reference Git docs as "background documentation" rather than "canonical spec."

[gjenkins8]

We are not addressing global ignores as part of this HIP (as far as I can tell). We shouldn't refer to these issues if we are not, and perhaps add a section to "Rejected ideas".

And IMHO, a global ignore can be a follow up HIP / behavior extension.

[scottrigby]

Agreed - removed the global ignore feature request references from Evidence of User Pain. They're properly listed in the Feature Requests (Out of Scope) section already. Thanks for catching this!

[scottrigby]

Just pushed a commit linking to a Go library reference implementation.