Unlock Dockerfile v1.7: New BuildKit Features & Advanced COPY Tricks

Introduction

Dockerfile is the fundamental tool for Docker developers, serving as a template for building images. With the new BuildKit toolkit, Docker Buildx CLI, and Dockerfile front‑end version 1.7.0, developers gain access to a range of enhanced Dockerfile features that simplify automation and ensure consistent environments across development stages.

Version Control and Front‑end Selection

Dockerfile versioning is managed by specifying a #syntax directive at the top of the file, which tells BuildKit which front‑end image to use. Two front‑end images are published on Docker Hub: docker/dockerfile:1.7.0 and docker/dockerfile:1.7.0-labs. Example:

#syntax=docker/dockerfile:1.x.x
FROM alpine

Any Dockerfile that includes the correct #syntax line works with any BuildKit version that supports the directive.

Variable Expansion Enhancements

Dockerfile now supports Bash‑style variable expansions for both ARG and ENV. Two basic forms are: ${variable:-word} – use word if the variable is unset. ${variable:+word} – use word if the variable is set.

Additional patterns introduced in v1.7 include: ${variable#pattern} and ${variable##pattern} – remove the shortest or longest matching prefix. ${variable%pattern} and ${variable%%pattern} – remove the shortest or longest matching suffix. ${variable/pattern/replacement} – replace the first occurrence of pattern. ${variable//pattern/replacement} – replace all occurrences of pattern.

Examples:

# example VERSION=1.2.3
ARG VERSION=${VERSION#v}
# VERSION is now 1.2.3

ARG VERSION=v1.7.13
ADD https://github.com/containerd/containerd/releases/download/${VERSION}/containerd-${VERSION#v}-linux-amd64.tar.gz /

Built‑in BuildKit variables such as TARGETOS and TARGETARCH can also be manipulated, e.g.:

ADD https://github.com/oven-sh/bun/releases/download/bun-v1.0.30/bun-linux-${TARGETARCH/arm64/aarch64}.zip /

Advanced Multi‑stage Build Patterns

Using the new variable expansions, you can define a global build argument and select stages dynamically. Traditional multi‑stage example:

ARG BUILD_VERSION=1
FROM alpine AS base
RUN …
FROM base AS branch-version-1
RUN touch version1
FROM base AS branch-version-2
RUN touch version2
FROM branch-version-${BUILD_VERSION} AS after-condition
FROM after-condition
RUN …

The new pattern allows conditional stage selection without enumerating every possible value, though all possible values must still be defined in the Dockerfile.

COPY --parents Flag

The --parents flag preserves the source directory hierarchy when copying files. Example copying app1/src/ while keeping the app1/src path: COPY --parents /app1/src/ /to/dest/dir/ Wildcard usage: COPY --parents */src/ /to/dest/dir/ Copying only Go source files from any depth: COPY --parents **/*.go /to/dest/dir/ The flag also works with COPY --from in multi‑stage builds, allowing selective copying of files while retaining their relative paths.

--exclude Filter

Dockerfile v1.7 introduces --exclude=[pattern] to define exclusion filters directly on COPY and ADD. Patterns follow the same syntax as .dockerignore. Examples:

COPY --exclude=*.md app /dest/

COPY --exclude=*.md --exclude=README app /dest/

COPY --exclude=**/*.md app /dest/

COPY --exclude=**/*.md --exclude=!**/important.md app /dest/

When combined with --parents, the exclusion pattern is evaluated relative to the copied parent directory.

COPY --parents --exclude=testapp assets/.**/icons* /dest/

This creates a destination tree containing only icons directories under app1 and app2, while omitting testapp.

Conclusion

The new Dockerfile capabilities—front‑end selection via #syntax, richer variable expansions, --parents for hierarchical copies, and --exclude filters—give developers finer control over build steps, making Dockerfiles more flexible, powerful, and portable across platforms.