How does a `.dockerignore` file work — where must it live, what pattern syntax does it use, and in what ways does its matching differ from `.gitignore`?

## Placement The file must be at the **root of the build context** — the directory you pass to `docker build`. If you build from the repository root with `-f services/api/Dockerfile .`, the ignore file belongs at the repository root, not beside the Dockerfile. Putting it next to the Dockerfile in that layout is a common and silent failure: the build works, it is just slow, because nothing is being filtered. BuildKit adds one refinement: if a file named `<path-to-dockerfile>.dockerignore` exists — for example `services/api/Dockerfile.dockerignore` — it is used **instead of** the context-root file. That is what makes per-service ignore rules practical in a monorepo where every service shares one context. ## Pattern syntax One pattern per line. Blank lines and lines beginning with `#` are ignored. Patterns are matched against each file's path **relative to the context root**, using Go's `filepath.Match` semantics plus a Docker extension: - `*` matches any sequence of characters **except** the path separator. - `?` matches a single non-separator character. - `**` matches any number of directories, including zero. - A leading `/` is allowed and means the same as omitting it — everything is anchored at the context root. - `!` at the start of a line re-includes anything that matches it. - **Last match wins**: ordering is significant, and Docker evaluates every pattern against every path rather than short-circuiting on the first hit. Examples: `*.md` excludes markdown at the top level only; `**/*.md` excludes it everywhere; `logs/*` excludes the contents of `logs` but keeps the directory itself; `temp?` excludes `temp1` and `tempa` but not `temp10`. ## The three differences from `.gitignore` worth memorising **1. No implicit recursion.** In git, a pattern without a slash matches at any depth, so `node_modules` covers nested copies. In `.dockerignore`, `node_modules` matches only the top-level directory because `*`-free patterns are compared against the full relative path. In a workspace repository with `packages/*/node_modules`, that single missing `**/` is often the whole reason a context is a gigabyte. **2. Re-inclusion under an excluded parent works.** Git refuses to re-include a file if its parent directory was excluded, because it never descends into it. Docker walks the whole tree and evaluates patterns per path, so the allowlist idiom is valid and widely used: ``` * !src !package.json !package-lock.json ``` This works because `*` does not cross `/`, so it excludes top-level entries only, and `!src` re-includes the directory whose children were never matched by `*` in the first place. Allowlists give the smallest, most predictable context; the cost is that a genuinely new required file is silently omitted until someone updates the list, which surfaces as a confusing COPY failure or a missing file at runtime. **3. No trailing-slash directory semantics.** Git treats `build/` as 'directory only'. Docker's matcher has no such distinction; `build` matches the path whether it is a file or a directory. ## What exclusion actually does Excluded paths are not walked into the transfer, so they are not sent to the builder and are **not available to COPY or ADD**. This makes `.dockerignore` do double duty: - **Performance**: less to walk, hash and transfer, and — importantly — a stable set of inputs for the `COPY . .` layer, so the cache is not invalidated by a rebuilt `dist/` or a fresh `.git` object. - **Safety**: `.env`, private keys, `.git` history and cloud credential files never enter the payload, so a broad `COPY . .` cannot bake them into a layer that ships to a registry. A subtlety: listing `Dockerfile` and `.dockerignore` themselves is allowed and does not break the build, because the client reads them separately; it only prevents them from being COPY-able into the image. A second subtlety: exclusion is client-side filtering, not redaction. If a secret already exists in an earlier image layer, adding it to `.dockerignore` later changes nothing about that published image. ## Verifying it works Do not trust the file by inspection. Compare the builder's reported context size before and after (`docker build --progress=plain` shows `transferring context: …`). For a precise answer, build a throwaway image that copies everything and list it: ``` printf 'FROM busybox\nCOPY . /ctx\nCMD ["true"]\n' > /tmp/ctx.Dockerfile docker build -f /tmp/ctx.Dockerfile -t ctxcheck . docker run --rm ctxcheck find /ctx -maxdepth 2 ``` That shows exactly what survived the filter — far more reliable than reasoning about pattern precedence in your head. ## Practical baseline Most repositories want, at minimum: version-control metadata (`.git`), dependency directories (`**/node_modules`, `**/target`, `**/.venv`), build outputs (`dist`, `build`, `out`), local environment and secret files (`.env*`, `*.pem`), editor and OS noise (`.idea`, `.vscode`, `.DS_Store`), and test/CI artifacts. Then measure, and tighten toward an allowlist if the context is still large.