5.1.1.1 Context File Set

The context file set is the actual, final list of files that get transferred to the Docker daemon for a given build, determined by the chosen context directory minus whatever is excluded by a .dockerignore file, and is the complete universe of files available to COPY and ADD instructions during that build.

How the File Set Is Determined

Starting from every file within the context directory, any pattern matched by .dockerignore is removed from consideration before the remaining files are packaged and transferred.

node_modules
.git
*.log
tests/

A .dockerignore containing these patterns removes matching files and directories from the context file set entirely, regardless of how the build's COPY instructions might otherwise have referenced them.

Inspecting the Actual File Set Being Used

Confirming exactly which files end up included in a build's context can help diagnose unexpectedly slow builds or unexpected file content ending up in an image.

docker build --progress=plain -t myapp . 2>&1 | head -5

The reported context size near the start of build output gives a quick sanity check on roughly how much was actually included.

Why an Excluded File Can't Be Copied, Even Explicitly

Because .dockerignore exclusions apply before the build even begins, a file excluded this way cannot be referenced by COPY, even if the instruction explicitly names it — the file was simply never made available to the build in the first place.

secrets.env

COPY secrets.env .

If secrets.env is excluded via .dockerignore, this COPY instruction fails, since the file was never part of the transferred context file set to begin with.

Why Understanding the Context File Set Matters

A clear understanding of exactly what is, and is not, included in a given build's file set helps explain both unexpectedly large build context transfers and confusing "file not found" failures, both of which trace back directly to this underlying file set determination.