Dockerfile Utilities

This is a collection of utilities for working with Dockerfiles powered by Node.js written in TypeScript. To install and run these utilities, you will need to have Node.js or Docker installed on your computer.

Supported features:

• formatting
• linting

Development Instructions

If you wish to build and compile this project, you must first install Node.js if you have not already done so. After you have installed Node.js and cloned the repository with Git, you may now proceed to build and compile the project with the following commands:

npm install
npm run build
npm test

If you are planning to change the code, use npm run watch to get the TypeScript files transpiled on-the-fly as they are modified.

Installation Instructions

To add this library as a dependency to your project, please add dockerfile-utils as a dependency in your project's package.json file.

Running the CLI with Node.js

To install and use the dockerfile-utils command line interface, please install the dockerfile-utils npm module. The -g flag will install the NPM module globally onto your computer.

npm install -g dockerfile-utils

After the installation has completed, you can run the CLI using the dockerfile-utils binary.

> dockerfile-utils --help
Usage: dockerfile-utils <command> [<args>]

Options:

  -h, --help                Output usage information
  -v, --version             Output version information

Commands:

  format                    Format a Dockerfile
  lint                      Validate a Dockerfile

Running the CLI with Docker

You can use docker run to launch the command line interface with Docker. This removes the requirement of needing to have Node.js installed locally on your computer. The dockerfile-utils binary is available as a Docker image under the name rcjsuen/dockerfile-utils.

> docker run rcjsuen/dockerfile-utils --help
Usage: dockerfile-utils <command> [<args>]

Options:

  -h, --help                Output usage information
  -v, --version             Output version information

Commands:

  format                    Format a Dockerfile
  lint                      Validate a Dockerfile

To format or lint a Dockerfile in the current working directory, please use the following commands.

> docker run -v `pwd`/Dockerfile:/Dockerfile rcjsuen/dockerfile-utils format /Dockerfile

> docker run -v `pwd`/Dockerfile:/Dockerfile rcjsuen/dockerfile-utils lint /Dockerfile

Changelog

All notable changes to this project will be documented in this file.

0.16.2 - 2025-04-10

Fixed

• prevent invalid heredocs from crashing the linter or formatter (#127)

0.16.1 - 2024-06-18

Fixed

• consider default value of a variable when determining if FROM is invalid or not (#126)

0.16.0 - 2024-03-25

Added

• support parsing the new --exclude flag for ADD and COPY instructions (#124)
• support parsing the new --parents flag for COPY instructions (#123)

0.15.0 - 2023-09-10

Added

• ignore predefined platform ARG variables if they are used as a base image (#119)

0.14.0 - 2023-09-10

Added

• flag empty tag specified with a digest in FROM instructions as an error (#118)

0.13.0 - 2023-09-09

Added

• support parsing the new --checksum flag for ADD instructions (#116)
• support parsing the new --keep-git-dir flag for ADD instructions (#117)

Changed

• ValidationCode.FLAG_INVALID_LINK_VALUE has been deprecated in favour of ValidationCode.FLAG_EXPECTED_BOOLEAN_VALUE, ValidationCode.FLAG_INVALID_LINK_VALUE may be removed in a future release

0.12.0 - 2023-09-09

Added

• support parsing the new --start-interval flag for HEALTHCHECK instructions (#115)
• allow some diagnostics to be ignored if a # dockerfile-utils: ignore comment precedes the originating line of the error (#106)

0.11.0 - 2022-08-23

Added

• update formatter to ignore heredocs embedded in COPY instructions (#111)
• ignore empty continuation lines in heredocs embedded in COPY instructions (#112)

Fixed

• ignore UTF-8 BOM when validating the Dockerfile (#113)

0.10.0 - 2022-05-04

Added

• support parsing the new --link flag for COPY instructions (#108)
• support parsing the new --link flag for ADD instructions (#109)

0.9.4 - 2022-01-22

Fixed

• empty lines in heredoc content should not trigger the empty continuation line warning (#107)

0.9.3 - 2021-12-11

Fixed

• ignore heredoc content when formatting (#105)

0.9.2 - 2021-09-21

Fixed

• ignore comments embedded in an instruction's keyword (#104)

0.9.1 - 2021-09-20

Fixed

• prevent merging of instructions if it contains an escape character and spans multiple lines (#103)

0.9.0 - 2021-09-18

Added

• support BuildKit by ignoring RUN instructions with no arguments (#102)

0.8.0 - 2021-09-08

Changed

• duplicated escape parser directive errors will now only flag the duplicates (#100)
• duplicated CMD, ENTRYPOINT, and HEALTHCHECK instructions will no longer flag the last one found as it is the valid one (#101)

Fixed

• fix incorrect merging of error ranges if escape character embedded in the keyword (#99)

0.7.0 - 2021-08-29

Added

• flag duplicated escape parser directive declarations as being unnecessary (#82)
• flag duplicated CMD, ENTRYPOINT, and HEALTHCHECK instructions as being unnecessary diagnostics (#82)

0.6.0 - 2021-08-28

Added

• support heredoc syntax in ADD and COPY instructions (#98)

0.5.0 - 2021-08-07

Added

• parse experimental heredoc syntax in RUN instructions (#97)

0.4.2 - 2021-04-11

Fixed

• prevent false positive by improving the parsing of an escape character and newline that immediately follows a label definition (#95)

0.4.1 - 2021-04-10

Added

• ignore *.tgz files when packaging and publishing to npm (#94)

0.4.0 - 2021-04-10

Added

• a new formatRange(string, Range, FormatterSettings) function that returns TextEdit[] for formatting a range in the Dockerfile instead of the whole file (#90)
• allow multiple arguments to be defined for ARG instructions to support Docker Engine 20.10 (#92)
• a new formatOnType(string, Position, string, FormatterSettings) function that returns TextEdit[] for formatting a range in the Dockerfile instead of the whole file (#93)

Fixed

• do not flag ? as an invalid modifier in variable substitutions (#91)

0.3.0 - 2021-02-28

Added

• a new FormatterSettings interface for defining ignoreMultilineInstructions to ignore instructions that span multiple lines (#62)

  export interface FormatterSettings extends FormattingOptions {
  
    /**
     * Flag to indicate that instructions that span multiple lines
     * should be ignored.
     */
    ignoreMultilineInstructions?: boolean;
  }

Changed

• altered the signature of the format(string, FormattingOptions) function to format(string, FormatterSettings), this is a non-breaking change as FormatterSettings extends FormattingOptions (#62)

Fixed

• do not validate variable substitutions if found in CMD and ENTRYPOINT (#89)

0.2.0 - 2021-01-19

Added

• support the --chmod flag for ADD instructions (#85)
• support the --chmod flag for COPY instructions (#86)

0.1.1 - 2020-12-24

Added

• instructions with only an escape character as its argument should be flagged as not having any arguments (#83)

Fixed

• images on Docker Hub are not being updated (#81)

0.1.0 - 2020-07-11

Added

• ARG and ENV instructions that span multiple lines with just a comment are now flagged as an error (#78)
• use DiagnosticTag to indicate if a Diagnostic is informing the user about a deprecation or not(#80)

Fixed

• correct ranges of linting errors if the error is on a multiline argument that is preceded by the escape character (#77)
• fix linting error caused by whitespace followed after the escape character (#79)

0.0.16 - 2020-04-02

Added

• RUN instructions with only flags and no arguments will now be raised as an error (#76)

0.0.15 - 2020-03-08

Fixed

• multiline instructions with empty newlines will no longer throw an error during validation (#71)
• instruction keywords that span multiple lines will no longer be raised as an error (#72)
• embedded comments with an empty continuation line will no longer be raised as an error (#73)
• arguments that follow a non-leading # comment marker will no longer be dropped during validation (#75)
• fix parsing of embedded comments in multiline instructions that have a trailing escape character (#74)

0.0.14 - 2020-02-11

Added

• add validation of FROM's --platform flag introduced in Docker CE 18.04 (#68)
  • ValidationCode.UNKNOWN_FROM_FLAG
• warn if two escape parser directives are defined (#70)

Fixed

• do not append newline when printing out the output of dockerfile-utils format to the console (#63)
• allow paths to be quoted in WORKDIRs (#67)
• do not calculate edits for lines that are already formatted correctly (#66)
• allow an instruction with an argument on the last line to be parsed if it has no leading whitespace and has a length of one (#69)

0.0.13 - 2019-05-22

Added

• allow Bash syntax for variable modifiers in RUNs (#56)
• warn if FROM has a variable for an image and it references nothing (#59)

Fixed

• allow quoted ARG variables in EXPOSE (#58)
• allow ENV variables that reference ARG variables in EXPOSE (#57)
• do not validate variable substitutions if found in RUN (#60)

0.0.12 - 2018-12-20

Fixed

• ignore variables when validating directories for ARGs and COPYs (#54)

0.0.11 - 2018-08-19

Added

• optionally flag WORKDIR instructions that do not point to an absolute path (#47)
  • ValidationCode.WORKDIR_IS_NOT_ABSOLUTE
  • ValidatorSettings.instructionWorkdirRelative
• add support for SCTP in EXPOSE instruction (#52)

Fixed

• fix incorrect validation of ENV and LABEL instructions with many quoted properties on multiple lines (#50)

0.0.10 - 2018-06-27

Added

• flag FROM instructions that refer to an invalid image digest in a private registry with a port as an error (#42)
• flag variables that have an invalid modifier set (#38)
• warn if ARG instruction does not define a name for the variable (#45)
• flag incorrectly quoted arguments for ARG, ENV, and LABEL (#40)

Changed

• upgraded the dependency of Mocha from 3.x to 5.x
  • versions prior to 4.x of Mocha dependended on Growl 1.9.2 which contained a security vulnerability
  • as Mocha is a devDependencies module, there is no reason to believe that the dockerfile-utils module itself was affected by this vulnerability

Fixed

• fix incorrect validation warning in ARG, ENV, and LABEL instructions caused by quotes being used in variable replacements (#36)
• fix incorrect validation of tagged images caused by FROM referencing images in a private registry (#39)
• allow variables to be used in a FROM's base image argument (#43)
• handle ARG instructions with escaped newlines that lead to an EOF comment (#44)

0.0.9 - 2018-04-16

Fixed

• do not flag FROM instructions that use variables with an error (#35)

0.0.8 - 2018-04-08

Added

• warn if hyphens are being parsed as a unit of time in HEALTHCHECK duration flags (#24)
• warn if two or more decimals found in a unit of time in HEALTHCHECK duration flags (#25)
• warn if two hyphens are found in HEALTHCHECK duration flags (#26)
• warn if instruction is written in JSON form incorrectly with single quotes (#28)
  • ValidationCode.JSON_IN_SINGLE_QUOTES
  • ValidatorSettings.instructionJSONInSingleQuotes

Fixed

• fix incorrect validation error if a COPY uses JSON arguments and its last string argument is correctly defined as a folder (#29)
• fix incorrect validation error if an ADD uses JSON arguments and its last string argument is correctly defined as a folder (#30)
• skip validation of content after a JSON's closing bracket (#33)
• fix validation of number of arguments for ADD and COPY instructions written in JSON (#34)

0.0.7 - 2018-03-01

Fixed

• use a non-zero range for the diagnostic if FROM's base image's digest is the empty string (#21)
• ignore multiple CMD, ENTRYPOINT, and HEALTHCHECK instructions in a Dockerfile if there is only ever one in a build stage (#22)
• handle invalid decimal values without a leading zero for duration flags (#23)

0.0.6 - 2018-02-11

Added

• create a Docker image for running the CLI (#10)
• create tags for the Docker image that corresponds to the Git commit's SHA hash (#16)
• warn if COPY has more than two arguments and its last argument is not a directory (#14)
  • ValidationCode.INVALID_DESTINATION
• warn if ADD has more than two arguments and its last argument is not a directory (#17)
  • ValidationCode.INVALID_DESTINATION
• flag durations that include a hyphen as an error (#18)
• warn if FROM's base image's digest is invalid (#15)
  • ValidationCode.INVALID_REFERENCE_FORMAT
• warn if FROM's base image's tag is invalid (#20)
  • ValidationCode.INVALID_REFERENCE_FORMAT

Fixed

• warn if STOPSIGNAL uses invalid variables for its argument (#11)
• allow decimal values for duration flags (#19)

0.0.5 - 2018-01-18

Added

• warn if COPY's --from flag is invalid (#9)
  • ValidationCode.FLAG_INVALID_FROM_VALUE

Fixed

• correct import error in the CLI linter (#8)

0.0.4 - 2018-01-17

Added

• expose ValidationCode enum as an API that may change (#7)

0.0.3 - 2018-01-17

Added

• create TypeScript typings (#5)
• add the main field to package.json (#6)

0.0.2 - 2018-01-17

Fixed

• include final character of the file when printing errors in the linter (#4)
• change linter to ignore EXPOSE instructions that use ARG variables without a default value (#3)

0.0.1 - 2017-12-22

Added

• create formatter for Dockerfiles
• create linter for Dockerfiles