GC-301a · Module 1

Override Precedence & Conflict Resolution

3 min read

Override precedence in Gemini CLI follows a strict hierarchy: CLI flags beat settings.json, settings.json beats GEMINI.md inline directives, subdirectory files beat project files, and project files beat global files. This six-layer stack means runtime overrides always win, configuration files beat instruction files, and specificity beats generality. The practical implication: you can set conservative defaults globally and progressively relax or tighten them at each scope level without worrying about lower layers being ignored.

Conflict resolution becomes complex in monorepos where multiple GEMINI.md files address the same concern. Consider a monorepo with a root GEMINI.md that says "use TypeScript strict mode" and a packages/legacy/ GEMINI.md that says "TypeScript strict mode is disabled — this package has 2000 any-typed legacy files." Both are valid in their scope. The key is that Gemini CLI does not try to reconcile them. It applies whichever rule is active in the current working directory. If you navigate between packages in a single session, the active ruleset changes silently. This is powerful but demands discipline in how you structure sessions.

The /memory add command introduces a fourth dimension to precedence: runtime context. Memory notes injected during a session operate at the highest precedence — above even subdirectory GEMINI.md files. This makes /memory add a powerful override mechanism for temporary rules, but it also means a careless memory note can silently suppress a carefully designed GEMINI.md instruction. Use /memory list periodically to audit what runtime overrides are active.

Do This

  • Keep your hierarchy to two or three layers — global, project, and one subdirectory level at most
  • Use /memory add for temporary overrides and promote lasting ones to GEMINI.md
  • Document why each override exists — not just what it does

Avoid This

  • Create deeply nested GEMINI.md files in every directory — each layer adds unpredictability
  • Rely on /memory add for permanent rules that should live in GEMINI.md
  • Assume Gemini CLI warns you about conflicts — it silently applies the highest-precedence rule