How to use docker buildx history ls command to list build records

Introduction

In this lab, you will learn how to use the docker buildx history ls command to manage and view your Docker build records. We will start by building a simple Docker image using docker buildx build, which automatically creates a build record.

Following the image build, you will explore how to list all build records using docker buildx history ls. You will then learn how to filter these records based on their status using the --filter option and how to customize the output format using the --format option. Finally, you will discover how to list only local build records using the --local option. This lab will provide you with practical skills for tracking and analyzing your Docker build history.

Skills Graph

Build a simple image to create a build record

In this step, we will build a simple Docker image. Building an image with Docker Buildx automatically creates a build record. A build record contains information about the build, such as the build arguments, the build context, and the resulting image.

First, let's create a simple Dockerfile in the ~/project directory. This Dockerfile will create an image based on the ubuntu image and install curl.

cd ~/project
nano Dockerfile

Add the following content to the Dockerfile:

FROM ubuntu:latest
RUN apt-get update && apt-get install -y curl

Save and close the file.

Now, let's build the image using docker buildx build. We will tag the image as my-ubuntu-curl.

docker buildx build -t my-ubuntu-curl .

This command will build the image based on the Dockerfile in the current directory (.) and tag it as my-ubuntu-curl. Docker Buildx will automatically create a build record for this build.

After the build is complete, you should see output indicating the build process and the successful creation of the image.

List all build records using docker buildx history ls

In this step, we will learn how to list all build records using the docker buildx history ls command. As we saw in the previous step, building an image with docker buildx build automatically creates a build record. These records are stored and can be viewed to track your build history.

To list all build records, simply run the following command:

docker buildx history ls

This command will display a table with information about each build record. The output typically includes the build ID, the builder used, the build status, the build duration, and the time the build was created.

You should see at least one entry in the output, corresponding to the image we built in the previous step (my-ubuntu-curl).

The docker buildx history ls command is useful for getting an overview of your build activity and identifying specific builds.

Filter build records by status using --filter option

In this step, we will learn how to filter build records based on their status using the --filter option with the docker buildx history ls command. This is useful when you want to see only builds that have a specific status, such as completed or failed builds.

The --filter option takes a key-value pair in the format key=value. To filter by status, we use the key status. The possible values for status include complete, running, failed, etc.

Since the build we performed in the first step was successful, its status should be complete. Let's filter the build history to show only completed builds:

docker buildx history ls --filter status=complete

This command will display only the build records where the status is complete. You should see the build record for my-ubuntu-curl in the output.

If you had any failed builds, you could filter for them using --filter status=failed.

Format the output of build records using --format option

In this step, we will learn how to format the output of the docker buildx history ls command using the --format option. This allows you to customize the information displayed and the format in which it is presented.

The --format option accepts a Go template string. You can use placeholders like .ID, .Builder, .Status, .Duration, and .CreatedAt to include specific information from the build record.

Let's try formatting the output to show only the build ID and the status, separated by a colon:

docker buildx history ls --format "{{.ID}}: {{.Status}}"

This command will output each build record on a new line, displaying the build ID followed by a colon and its status.

You can create more complex formats by combining different placeholders and text. For example, to show the builder and the duration:

docker buildx history ls --format "Builder: {{.Builder}}, Duration: {{.Duration}}"

Experiment with different format strings to see how you can customize the output to your needs.

List local build records using --local option

In this step, we will explore the --local option with docker buildx history ls. By default, docker buildx history ls lists build records from all builders. The --local option restricts the output to only show build records from the current builder instance.

To list only the local build records, use the following command:

docker buildx history ls --local

In this lab environment, since we have only used the default builder, the output of docker buildx history ls and docker buildx history ls --local will likely be the same. However, in environments with multiple builders, this option is useful for focusing on the history of a specific builder.

This concludes our exploration of listing and filtering Docker Buildx build history. You now know how to view your build records, filter them by status, format the output, and list records from the local builder.

Summary

In this lab, we learned how to use the docker buildx history ls command to manage build records. We started by building a simple Docker image using docker buildx build, which automatically created a build record. We then used docker buildx history ls to list all available build records, observing the information associated with each build.

We further explored the capabilities of docker buildx history ls by learning how to filter build records based on their status using the --filter option and how to customize the output format using the --format option. Finally, we discovered how to list only local build records using the --local option, providing a comprehensive overview of managing and inspecting Docker Buildx build history.