.dockerignore Generator

When you run docker build, the client reads .dockerignore from the root of the build context and drops every matching file before anything is sent to the builder. Each line is cleaned first: surrounding spaces are trimmed, . and .. are resolved, and leading and trailing slashes are removed. So /foo/bar/, foo/bar/ and foo/bar are the same rule.

A pattern is matched against the whole path from the context root, using Go's filepath.Match wildcards plus ** for any number of folders, including none. If the pattern matches a parent folder, everything inside that folder matches too. When several lines match one path, the last one wins. A # starts a comment only in column 1.

The last two rows show a common surprise. Go reads [^…] as "not these characters", so [!a] is just a set containing ! and a. The tester above uses the same rules, so you can paste a path and see which line decided it.

The two files look alike and are often copied from one to the other, but they don't read patterns the same way. Lines that work in Git can quietly do less in Docker.

The first row causes most of the trouble. Prefix anything that can appear in a subfolder with **/ and the rule behaves the way it did in Git.

A workspace repo has a web app and an API under packages/. Someone copied four lines from .gitignore into .dockerignore. The Dockerfile installs dependencies and then runs COPY . . to add the source:

Running the repo's paths through Docker's rules (press Load example above to see this in the tester):

Two things go wrong. The API's .env is copied into the image, where anyone who can pull it can read it. And the web package's node_modules, built on a Mac, is copied over the Linux install. Packages with native binaries, such as esbuild or sharp, then fail with errors saying they were installed for a different platform.

The fix is to make the rules match at any depth: **/node_modules, **/*.log, **/.env, plus **/dist if each package keeps its own build output. The generator writes those **/ forms for you.

A denylist only catches what you thought of. The other approach starts with *, which excludes every top-level entry, and adds back only what the Dockerfile copies. New files then stay out of the build until you list them.

Order matters. The secret rules come after !src, so src/.env is still excluded. If they came first, the !src line would win and send it. The price of an allowlist is maintenance: when the Dockerfile starts copying a new file, the build fails with failed to compute cache key and a "not found" message until you add that file back. Choose "Exclude everything, add back" above to start from your stack's usual files.

Docker reads .dockerignore from the root of the build context, which is the path at the end of the command. That is not necessarily the Dockerfile's folder. With several Dockerfiles, you can also put an ignore file next to each one, named after it. That file takes precedence over the root .dockerignore.

Patterns in a per-Dockerfile ignore file are still written relative to the context root, not to the Dockerfile's folder.

Most stack rules are safe in any project. The build output rules are the exception. They assume the image compiles the code itself, and many Dockerfiles copy a build made earlier instead.

The Ruby rules use log/* followed by !log/.keep rather than plain log. The folder still reaches the image with its placeholder file and without the logs, which is the same approach Rails' own generated .dockerignore takes.

Every build reports the size of the context it sent, in a line like transferring context: 13.16MB. If that number is in the hundreds of megabytes for a small app, something large is getting through. To list the files themselves, build a throwaway image from the same context:

The file list appears in the build log. Paste it into the tester above, which strips the #8 0.312 prefixes, and each path shows which line, if any, would have excluded it. Because the Dockerfile comes from stdin, this check uses the root .dockerignore, not a per-Dockerfile one.

COPY . . copies whatever the context contains, so a missing ignore rule ends up as a file in the image. Deleting it in a later RUN rm doesn't help, because the earlier layer still holds it and anyone with the image can extract it. The fix has to be in .dockerignore, before the file is ever sent.

If the build needs a credential, such as an .npmrc token for a private registry, don't copy it. Mount it for a single step instead:

The secret is available while that RUN step runs and is never written to a layer. Keep **/.npmrc in .dockerignore so the copy on disk can't slip in through COPY . ..