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.
| Mechanism | What the official docs say | Good for |
|---|---|---|
.antigravityignore | Honored by CLI @ completion (the v1.1.16 fix). I found no description of it as a read barrier | Noise you do not want in context: build output, images, lockfiles |
.gitignore + Strict mode | Strict mode lists "Respect .gitignore", preventing access to ignored files | Things 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 immediately | API 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-standardgit 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.
| Rules | Files still readable |
|---|---|
assets/ + !assets/keep.png | none (keep.png was excluded too) |
assets/** + !assets/keep.png | assets/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.
| Pattern | src/tmp/t.txt | docs/src/tmp/z.txt |
|---|---|---|
tmp/ (no internal slash) | excluded | excluded |
src/tmp/ (internal slash) | excluded | not 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 rules | Paths matched |
|---|---|
content | 2,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.
| Pattern | assets/a.png | assets/thumbs/b.png | assets/thumbs/ja/c.png |
|---|---|---|---|
assets/*.png | excluded | not excluded | not excluded |
assets/**/*.png | excluded | excluded | excluded |
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.
| Case | Result |
|---|---|
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 endings | The 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.
| Symptom | Likely cause | How to check | Fix |
|---|---|---|---|
| The one file you carved out is gone too | The parent was excluded as dir/ | git check-ignore -v shows dir/ as the matching line | Switch to dir/** and put the exception after it |
| The agent suddenly answers as if it cannot see your code | A bare word with no slash is matching at every depth | Compare 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 segment | Pick one deep file and test it with -q | Use dir/**/*.ext |
| A rule has no effect at all | A typo, or the path does not exist yet | The excluded count stays at zero | Confirm the real path with find before writing it |
| Only one particular filename is unaffected | A leading # or !, or an escaped trailing space | Turn on whitespace rendering in your editor | Escape 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.txtcheck-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.