◉ANTIGRAVITY LABJP
Articles/Tips & Best Practices
✦ Tips & Best Practices/2026-08-24Intermediate

Four Reasons Your .antigravityignore Rules Are Not Taking Effect

Rules that quietly do nothing, and rules that swallow the whole repository. Four causes behind both, each checked against a gitignore-style matcher, plus a symptom-first triage table and why secrets belong in a deny rule instead.

Antigravity419antigravityignoreworkspace11troubleshooting133configuration8

I was trimming what the agent could read in the repository behind one of my wallpaper apps, which is mostly distribution images. I wrote assets/ into .antigravityignore, then added !assets/keep.png right underneath, because that one file still had to be visible.

Half of that worked. The assets/ tree went quiet, and keep.png disappeared along with it. I spent a while blaming caching before it occurred to me that the file was doing exactly what I had written, just not what I meant.

.antigravityignore uses the same syntax as .gitignore, and that syntax has a handful of rules you will not notice by reading them. I took the patterns apart one at a time against a matcher, and the failures — both the silent no-ops and the over-eager matches — clustered into four places.

Before any of that, though, one thing is worth checking first: what you are actually relying on this file to do. A tool for cutting noise and a tool for protecting secrets are not the same tool.

What does .antigravityignore actually stop? (as of November 2026)

I went through the official documentation as it stood in November 2026. The only place I could find .antigravityignore mentioned by name was the CLI v1.1.16 changelog, in a fix for "@ file path completion showing files that were in your .antigravityignore." I could not find a syntax reference, or anything describing how far the agent's file-reading tools honor it. I may be missing a page, but I would not build a security boundary on that.

What is documented is a set of mechanisms that block reads outright.

MechanismWhat the official docs sayGood for
.antigravityignoreHonored by CLI @ completion (the v1.1.16 fix). I found no description of it as a read barrierNoise you do not want in context: build output, images, lockfiles
.gitignore + Strict modeStrict mode lists "Respect .gitignore", preventing access to ignored filesThings that belong neither in the repo nor in the agent's view
A permissions deny rule (e.g. read_file(secrets/))The unified permission engine evaluates Deny > Ask > Allow, and Deny blocks the action immediatelyAPI keys, .env, customer data — anything that must not be read

So the line I draw is a simple one: noise goes in .antigravityignore; secrets go in deny. That way a typo in the ignore file can never be the thing that leaks a key.

The deny syntax lives on the official Permissions page. For the CLI, you add it to ~/.gemini/antigravity-cli/settings.json; paths can be relative to the workspace root.

{
  "permissions": {
    "deny": [
      "read_file(.env)",
      "read_file(secrets/)"
    ]
  }
}

Everything below is about making .antigravityignore behave the way you intend in its role as a noise filter.

Stop reading the file, start querying it

Start with the checking method, because eyeballing patterns stops working the moment the file grows past a dozen lines.

Since the syntax is the gitignore family, the fastest way to test a rule is to borrow git as a matcher. Recreate the path structure in a scratch directory, drop the rules in, and look at what survives.

mkdir -p /tmp/ignore-lab && cd /tmp/ignore-lab && git init -q .
mkdir -p assets/thumbs/ja
touch assets/a.png assets/keep.png assets/thumbs/b.png assets/thumbs/ja/c.png
 
printf 'assets/\n!assets/keep.png\n' > .gitignore
 
# List the files that are still on the readable side
git ls-files -o --exclude-standard

git ls-files -o --exclude-standard prints only what was not excluded. I prefer looking at what remains rather than what disappeared, because over-exclusion is far easier to spot that way.

One caveat cost me a detour. git check-ignore -v also prints negation lines — the ones starting with ! — and still exits 0 when it hits one. I read that as "excluded" and had to redo the first round of triage. When you want a mechanical yes or no, use -q and read exit code 1 as "not excluded."

git check-ignore -v assets/keep.png   # → .gitignore:2:!assets/keep.png  (exit 0)
git check-ignore -q assets/keep.png; echo $?   # → 1 (not excluded)

Everything measured below came from git 2.34.1. The syntax is shared, but I have no guarantee the two implementations are byte-for-byte identical, so it is worth confirming the final result against Antigravity's own behavior once.

1. Excluding a directory puts its contents out of reach of !

This was the one that tripped me up. Once a directory itself is excluded, nothing inside it gets walked — and what is never walked cannot be pulled back with a negation.

Here is the same "keep one file" goal written several ways.

RulesFiles still readable
assets/ + !assets/keep.pngnone (keep.png was excluded too)
assets/** + !assets/keep.pngassets/keep.png
assets/** + !assets/thumbs/**none
assets/** + !assets/thumbs/ + !assets/thumbs/**assets/thumbs/b.png, assets/thumbs/ja/c.png

The third row is the interesting one. !assets/thumbs/** on its own brings back nothing, because assets/** also matches the assets/thumbs directory node, and the walk stops before it descends. You need two lines: re-include the directory (!assets/thumbs/), then re-include its contents (!assets/thumbs/**).

Put differently, the most intuitive way to write "exclude this folder, except that one file" is precisely the way that does not work.

Order matters too. Placing !assets/keep.png above assets/** left the file excluded. The last matching line wins, so exceptions always go after the rule they carve out of.

2. A slash changes where matching starts

This is where the over-exclusion came from. Whether the pattern contains a slash anywhere but the end changes its meaning entirely.

Patternsrc/tmp/t.txtdocs/src/tmp/z.txt
tmp/ (no internal slash)excludedexcluded
src/tmp/ (internal slash)excludednot excluded

A pattern with no internal slash matches a directory of that name at any depth. A pattern that contains one is anchored to the directory holding the ignore file.

I also wanted to see how that plays out at scale, so I ran it against a 2,250-file Next.js project with a single line in the ignore file.

The rulesPaths matched
content2,133 of 2,250 (about 95%)
content/articles/en/, public/content/, *.lock (three lines)1,032 of 2,250

One unanchored word took almost the entire repository with it — src/content, docs/content, and every similarly named directory further down. When an agent suddenly starts answering as if it has never seen your code, the model is not always the thing to suspect first.

Worth noting: the public/content/ line matched zero paths. In that repository it is a build-time output that does not exist in a fresh clone. A rule that appears not to be working is sometimes a rule with nothing to match.

3. * does not cross directory boundaries

The classic version of this is writing assets/*.png and wondering why the nested images are still being read.

Patternassets/a.pngassets/thumbs/b.pngassets/thumbs/ja/c.png
assets/*.pngexcludednot excludednot excluded
assets/**/*.pngexcludedexcludedexcluded

A single * covers exactly one path segment. For arbitrary depth you need ** in the middle. Assets and build output, which tend to nest, are where this gap shows up most.

4. Invisible characters and leading punctuation

The last group is the kind you cannot see by opening the file. Four cases, each measured.

CaseResult
Trailing space (assets/a.png␣)The space is stripped; the rule still matched
Trailing space protected with a backslash (assets/a.png\␣)No match — it now demands a filename that ends in a space
CRLF line endingsThe rule still matched
Filename starting with # (#temp.txt)Treated as a comment. \#temp.txt works

Trailing whitespace and CRLF look suspicious and turned out to be harmless, so they belong near the bottom of your triage list. Real filenames that begin with # or !, on the other hand, do need the backslash.

Triage by symptom

Here are the same four causes, rearranged so you can start from what you are seeing. The rows near the top are the ones I ran into most often.

SymptomLikely causeHow to checkFix
The one file you carved out is gone tooThe parent was excluded as dir/git check-ignore -v shows dir/ as the matching lineSwitch to dir/** and put the exception after it
The agent suddenly answers as if it cannot see your codeA bare word with no slash is matching at every depthCompare excluded vs. total counts (procedure below)Anchor it with a leading or internal slash
Shallow files are excluded, deep ones are not* only covers one segmentPick one deep file and test it with -qUse dir/**/*.ext
A rule has no effect at allA typo, or the path does not exist yetThe excluded count stays at zeroConfirm the real path with find before writing it
Only one particular filename is unaffectedA leading # or !, or an escaped trailing spaceTurn on whitespace rendering in your editorEscape as \# / \!; drop stray backslashes

Three common misconceptions

"If a file is in .antigravityignore, the agent cannot read it." — The only behavior I could confirm in the official docs is @ completion honoring it. Anything that must not be read belongs in a deny rule.

"A ! line can bring a file back from anywhere." — Not if a parent directory is excluded. The official gitignore documentation says as much: it is not possible to re-include a file if a parent directory of that file is excluded.

"If check-ignore prints a line, the file is excluded." — It prints negation matches too, with exit code 0. Use -q and the exit code for a yes-or-no answer.

Count what is left, not what you removed

Audit your rules in a throwaway repository. This is where I stumbled a second time.

My first version ran git -c core.excludesFile=.antigravityignore check-ignore directly inside the working repository, and the count quietly included files that were only excluded by .gitignore. check-ignore reads .gitignore and .git/info/exclude as well. When I tested it, a docs/y.md listed only in .gitignore showed up on the "excluded" side.

When you count, send every other rule out of the room. These days I do it like this:

# 1) In the working repository, write out every file path
find . -path ./.git -prune -o -type f -print | sed 's|^\./||' > /tmp/all-paths.txt
 
# 2) Create a throwaway repository that holds only .antigravityignore
L=$(mktemp -d) && git -C "$L" init -q . && cp .antigravityignore "$L/.gitignore"
 
# 3) Disable the global excludes file too, then compare excluded vs. total
git -C "$L" -c core.excludesFile=/dev/null check-ignore --no-index --stdin < /tmp/all-paths.txt | wc -l
wc -l < /tmp/all-paths.txt

check-ignore works on paths that do not exist, so nothing needs to be copied into the throwaway repository. A trailing-slash pattern like assets/ still matched as a directory, as long as the path continued below it, as in assets/keep.png.

I look at those two numbers, and if the magnitude is off from what I expected, the rules get rewritten. A case like the 2,133 above is obvious the moment you count it. A stubborn zero, on the other hand, points at a typo in the path — or at a path that is not there yet.

Where you will probably get stuck next

Once exclusion starts behaving, the next questions tend to be how to handle secrets and what to let the agent run. I wrote up where to begin a deny list — by counting your own history — in Start Your Antigravity Deny List From Your Own Shell History.

If you hand the agent whole folders as archives, Before Handing an Agent a .zip: Dropping .git Cut 29 MB to 15 MB, and 28 Secret Warnings Turned Out to Be Noise is the closer story. If exclusion is working and things are still slow, When Antigravity's Workspace Indexing Won't Finish may be the better match.

Once you hand the agent write and delete permissions, controlling what it reads is no longer enough. I traced an actual incident and its recovery in The Cleanup Step Removed the Working Directory, Not Its Contents, which is about stopping destructive work after the approval has already gone through.

The one step I would suggest today is running the procedure above against whatever project you have open and writing both numbers down. Having a baseline means that the next time something goes strange, the ignore file makes it onto your list of suspects instead of being assumed innocent.

I used to consider an ignore file finished the moment I saved it. Counting instead is a habit I owe to the afternoon one image went missing.

Share

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.

  • ✦Copy-paste ready implementation code
  • ✦New advanced guides published daily
  • ✦$5/mo or $10 for lifetime access
View Membership →

If you found this article helpful, a small tip ($1.50) would mean a lot to us. Your support helps keep this site ad-free and covers server and hosting costs.

Related Articles

✦ Tips2026-10-29
The Agent Said It Used My Skill, but There Is No Trace — Check Files, Not Replies
When an agent ignores your Rules or says it used a Skill without doing so, its reply can't settle the question. Here is a small file-based check, and a way to decide between rewriting, adding a mechanical check, or handing the task elsewhere.
✦ Tips2026-04-25
When Antigravity's Workspace Indexing Won't Finish: A Field Guide to Fixing Stalled Indexes
Indexing that never moves, or finishes while the agent still can't find your files. A count-first diagnostic: measure the project, verify your ignore rules, and test with .git set aside. No undocumented internal paths.
✦ Tips2026-11-19
Before an Agent Clones Your Template Repo, Hand It a Trap Index: One Line per Fix, the Reasons Kept in One Place
When you copy a running site to start the next one, an agent carries the fixes over but leaves the reasons behind. A symptom-first trap index, a one-page porting plan written before the copy, and three small scripts that catch drift between the index, the source docs and their mirrors.