Updated April 3, 2023
Introduction to Docker format
Docker format is used to manipulate the output format of commands and log drivers that have the ‘–format’ option, which means if a command has the ‘–format’ option, then we can use that option to change the output format of the command as per our requirement because default command does not shows all the fields related to that object. For example, if we run the ‘docker image ls’ command, it shows only repository, tag, image ID, created, and size; however, a few fields are associated with images like containers, digest, createdate, virtual size, etc.
Syntax
<docker command> --format <Define Output format>
docker command : Any docker command which supports the ‘--format’ option
Define Output format : Specifies how our output should looklike using Go templates and basic functions
Example:
docker system info --format 'Default logging driver: {{.LoggingDriver}}'
Explanation: In the above example, the {{.LoggingDriver}} is replaced by the value, and that is ‘json-file’ the default logging driver.
How does format command work in docker?
It uses the Go template to manipulate the output of the specific commands. It uses a key that we send using the ‘–format’ option to control execution and derive values as output. When execution of the template starts, it checks in the data structure and sets the cursor (represented by a period ‘.’) to the value of the specified key in the structures. Docker also has some basic functions to manipulate template elements.
The above-mentioned command gives us information about the docker system; however, we have formatted the output to show only the default logging driver by sending the key ‘LoggingDriver’ and docker daemon checks for that key in the output of the ‘docker system info’, and it sets the cursor to the value of ‘LoggingDriver’ and shows the value of that key on the STDOUT.
Examples of Docker format
Let’s understand more about it with the below examples: –
1. Let’s assume we have to format the output of any commands, but we don’t know all available fields and values, so we can use the ‘–format’ option with that command as below to know or list all available fields and their values: –
docker ps --format ‘{{json .}}’
Explanation: In the above example, we have an nginx container in a running state. We can see all available fields related to that nginx container.
Note: – We can pipe the output of this command to ‘jq’ to make the output prettier and more readable as below: –
docker ps --format ‘{{json .}}’ | jq
2. Now, we have all fields and values of the related object, and we want to: –
- List only specific fields; for example; we want to know about the networks and ports of all running containers; we can achieve this by using the below command: –
docker ps --format ‘{{ .ID}} {{ .Names}} {{ .Networks}} {{ .Ports}}’
- List the output with more spaces between columns using the ‘\t’ as below: –
docker ps --format ‘{{ .ID}}\t{{ .Names}}\t{{ .Networks}}\t{{ .Ports}}’
We can see more space between the columns now; however, we can also use the specific symbol to separate the columns as below: –
docker ps --format ‘{{ .ID}}\t | \t{{ .Names}}\t | \t{{ .Networks}}\t | \t{{ .Ports}}’
We have added a pipe between the columns in the above example.
- List the output with column header because we can see that there are no headers in the above examples, and user might find it difficult to understand the output, so we can use the ‘table’ keyword to add the header to the column as below: –
docker ps --format ‘table {{ .ID}}\t | \t{{ .Names}}\t | \t{{ .Networks}}\t | \t{{ .Ports}}’
3. We have some basic functions to make the output more readable and useful, and those are: –
- join – It is used to join or concatenate a list of strings to make a single string. We can put any separator between each element in the list as below: –
$docker inspect --format '{{join .Config.Cmd " , "}}' <container name or ID>
Explanation: In the above example, we can see that we have converted the arguments in a single string using the join function with a comma (,); however, we can use any separator as we can see it in the snapshot. Here, the ‘dc’ is the short container ID; we can use the container name as well.
- table – It provides the column or field name so that we can easily understand which column represents what data. We have already seen how it works, for example, 2.c.
- json – It shows output in json format as shown below: –
docker inspect --format ‘{{json .config}}’ <container name or ID>
Explanation: In the above snapshot, we can see that if we don’t use the ‘json’ keyword, command output only values like a long string and not the keys so that we can use the ‘json’ to output the data in JSON format; however, it is difficult to read the output so we can pipe it to ‘jq’ to make it more readable as shown below: –
docker inspect --format ‘{{json .Config}}’ <container name or ID> | jq
- lower – It shows output in lowercase as shown below: –
docker inspect --format ‘{{lower .Name}}’ <container name or ID>
- upper – It shows output in uppercase as shown below: –
docker inspect --format ‘{{upper .Name}}’ <container name or ID>
- println – It prints each value on a new line as shown below: –
docker inspect --format='{{range .NetworkSettings.Networks}}{{println .IPAddress }}{{println .IPPrefixLen}}{{ .MacAddress}}{{end}}' <container name or ID>
Explanation: In the above snapshot, we can see that the ‘IPAddress’, ‘IPPrefixLen’ and ‘MacAddress’ are showing in a single line, and we can not figure out which is what, so we have to use the ‘println’ in each field which we want to output except the last one.
Advantages
- It helps to output the data that we need.
- It also makes the output more human-readable and prettier.
- We can create reports using it by saving the output to a file.
Rules and regulations for using a format?
1. We should observe the shell environment first as: –
- We can run the following command with a single quote in a Posix shell: –
docker inspect --format '{{join .Config.Cmd " , "}}'
- However, we need to escape the double quotes inside params as below: –
docker inspect --format '{{join .Config.Cmd \" , \"}}' <container name or ID>
2. Fields are case sensitive so cross-check the available fields using the ‘{{json .}}’ function with the ‘–format’ option.
3. The field must be a string to transform it in a lower or uppercase representation.
4. We can use ‘range’ to iterate over an array, as shown in example 3.f.
5. The ‘range’ must end with {{end}}.
Conclusion
We have discussed almost all basic functions, and when we add these all together to get the required output, it becomes complex, as we can see in the example 3.f. You can use the ‘–help’ command with any command to know that command supports the ‘format’ option or not.
Recommended Articles
This is a guide to the Docker format. Here we discuss all basic functions and Examples along with the Rules and regulations for using a format. You may also have a look at the following articles to learn more –
