docker-diff

Inspect the changes to a container since it was created

$ docker diff [container]

$ docker diff --help

docker diff [OPTIONS] CONTAINER

-f, --format string
    Pretty-print diff using a Go template. This allows for custom output formatting based on the Go template syntax.

--no-trunc
    Do not truncate output. By default, output might be truncated for readability, but this option ensures full paths and other details are displayed.

docker diff is a powerful command-line utility within the Docker ecosystem that allows users to examine changes made to the filesystem of a running or stopped container. It provides a concise summary of files and directories that have been added, modified, or deleted within the container's writable layer since it was created or started.

This command is invaluable for debugging containerized applications, understanding the runtime state of a container, and verifying immutability. For instance, if an application unexpectedly creates files or modifies configurations, docker diff can quickly highlight these changes. It operates by comparing the current state of the container's filesystem with its original base image layers. The output is typically presented as a list of paths prefixed with 'A' (Added), 'C' (Changed), or 'D' (Deleted), indicating the type of modification. Understanding these differences is crucial for maintaining clean container images and troubleshooting unexpected behavior.

docker diff focuses solely on the container's writable layer. This implies several limitations:


• Volumes Ignored: It will not show any changes made within mounted volumes (e.g., bind mounts, named volumes). Changes in volumes reside outside the container's filesystem layering and are not tracked by this command.


• Snapshot in Time: The output reflects differences relative to the container's initial state (when it was created from an image) or its last commit. It does not provide a historical log of every single change made over time, only the net differences.


• Abstraction of Contents: While it lists changed files, it does not show the actual content differences (like a traditional diff utility). For content comparison, you would typically need to copy the files out of the container.

The output of docker diff uses single-character prefixes to denote the type of change:


• A: Added - A file or directory has been newly created within the container's writable layer.


• C: Changed - An existing file or directory within the container's writable layer has been modified (e.g., content altered, permissions changed).


• D: Deleted - A file or directory that existed in a lower layer (or was previously created in the writable layer) has been removed.

docker diff is intrinsically linked to Docker's copy-on-write (CoW) layered filesystem. When a container is started, it gets a thin, writable layer on top of its read-only image layers. All modifications (additions, changes, deletions) made by the container at runtime are recorded in this writable layer. docker diff essentially reports on the contents of this top-most writable layer relative to the layers below it, providing visibility into the state changes specific to that container instance.

The docker diff command has been an integral part of the Docker Command Line Interface (CLI) since the early versions of the Docker engine. Its inclusion reflects the fundamental need for developers and operators to understand the runtime state and modifications occurring within containerized environments. It is not a standalone utility but rather a core function bundled with the main docker client, evolving alongside the Docker platform itself to provide insights into its layered filesystem architecture. Its stability and consistent functionality highlight its foundational role in Docker diagnostics and management.

docker inspect(1), docker history(1), docker commit(1), diff(1)