docker / cli

Output Formatting and Filtering

This section outlines how the Docker CLI formats and filters output for user readability. The formatter package is used to handle this functionality. This package supports several output formats, including JSON, table, and plain text.

Output Formats

The formatter package provides various output formats for Docker commands. The choice of format depends on the specific command and user preferences. Here’s a breakdown of available formats and their functionalities:

  • JSON: This format is particularly useful for programmatic access to command output. It provides a structured and machine-readable representation of data.

    • Example:
    docker ps -f "status=running" -f "name=my-container" --format "json"

  • Table: The table format is designed for human-readable output. It presents data in a clear and organized way, with columns and rows for easy comprehension.

    • Example:
    docker ps -f "status=running" -f "name=my-container" --format "table"

  • Plain Text: The plain text format provides a basic, non-structured output for simple display.

    • Example:
    docker ps -f "status=running" -f "name=my-container" --format "plain"

Filtering Output

Docker CLI supports filtering output using various criteria to narrow down the information displayed. This filtering is often combined with output formatting for a more focused and tailored experience.

  • Filtering Options:

    • Status: Filter by container status: --filter "status=running"
    • Name: Filter by container name: --filter "name=my-container"
    • Image: Filter by image name: --filter "image=my-image"
    • Label: Filter by container label: --filter "label=key=value"
    • ID: Filter by container ID: --filter "id=123456"
    • Created: Filter by container creation time: --filter "created=1234567890"
    • Since: Filter by container creation time relative to a specific date/time: --filter "since=2023-03-15"
    • Before: Filter by container creation time relative to a specific date/time: --filter "before=2023-03-15"

  • Examples:

    • Show only running containers:
      docker ps -f "status=running" --format "table"
    • List containers with a specific image:
      docker ps -f "image=my-image" --format "json"
    • Show containers created before a specific date:
      docker ps -f "before=2023-03-15" --format "plain"

  • Source: cli/command/container/ps.go

Customizing Output Formatting

The --format flag allows for greater control over the output. It can be used with predefined templates for common output formats like JSON, table, and plain text. Additionally, custom formatting options can be defined by specifying a specific template.

  • Predefined Templates:

    • json: Outputs data in JSON format.
    • table: Presents data in a table format.
    • plain: Outputs data in plain text format.

  • Custom Templates:

    • --format "{{.ID}} {{.Image}}" outputs container ID and image name.
    • --format "{{.Name}} - {{.Status}}" outputs container name and status.

  • Source: cli/formatter/formatter.go

The formatter package offers a robust mechanism for formatting and filtering Docker CLI output. It allows developers and users to tailor the output for different use cases and needs, promoting flexibility and usability.