diff --git a/website/source/docs/command-line/build.html.markdown b/website/source/docs/command-line/build.html.markdown index 09a271af8..198bd85b4 100644 --- a/website/source/docs/command-line/build.html.markdown +++ b/website/source/docs/command-line/build.html.markdown @@ -1,5 +1,6 @@ --- layout: "docs" +page_title: "Build - Command-Line" --- # Command-Line: Build @@ -22,7 +23,7 @@ artifacts that are created will be outputted at the end of the build. In general, a builder supporting the forced build will remove the artifacts from the previous build. This will allow the user to repeat a build without having to manually clean these artifacts beforehand. - + * `-except=foo,bar,baz` - Builds all the builds except those with the given comma-separated names. Build names by default are the names of their builders, unless a specific `name` attribute is specified within the configuration. diff --git a/website/source/docs/command-line/fix.html.markdown b/website/source/docs/command-line/fix.html.markdown index 614777d4c..fa96f394c 100644 --- a/website/source/docs/command-line/fix.html.markdown +++ b/website/source/docs/command-line/fix.html.markdown @@ -1,6 +1,6 @@ --- layout: "docs" -page_title: "Command-line: Fix" +page_title: "Fix - Command-Line" --- # Command-Line: Fix diff --git a/website/source/docs/command-line/machine-readable.html.markdown b/website/source/docs/command-line/machine-readable.html.markdown new file mode 100644 index 000000000..b5f5b5b71 --- /dev/null +++ b/website/source/docs/command-line/machine-readable.html.markdown @@ -0,0 +1,83 @@ +--- +layout: "docs" +page_title: "Machine-Readable Output - Command-Line" +--- + +# Machine-Readable Output + +By default, the output of Packer is very human-readable. It uses nice +formatting, spacing, and colors in order to make Packer a pleasure to use. +However, Packer was built with automation in mind. To that end, Packer +supports a fully machine-readable output setting, allowing you to use +Packer in automated environments. + +The machine-readable output format is easy to use and read and was made +with Unix tools in mind, so it is awk/sed/grep/etc. friendly. + +## Enabling + +The machine-readable output format can be enabled by passing the +`-machine-readable` flag to any Packer command. This immediately enables +all output to become machine-readable on stdout. Logging, if enabled, +continues to appear on stderr. An example of the output is shown +below: + +``` +$ packer -machine-readable version +1376289459,,version,0.2.4 +1376289459,,version-prerelease, +1376289459,,version-commit,eed6ece +1376289459,,ui,say,Packer v0.2.4.dev (eed6ece+CHANGES) +``` + +The format will be covered in more detail later. But as you can see, +the output immediately becomes machine-friendly. Try some other commands +with the `-machine-readable` flag to see! + +## Format + +The machine readable format is a line-oriented, comma-delimeted text +format. This makes it extremely to parse using standard Unix tools such +as awk or grep in addition to full programming languages like Ruby or +Python. + +The format is: + +``` +timestamp,target,type,data... +``` + +Each component is explained below: + +* **timestamp** is a Unix timestamp in UTC of when the message was + printed. + +* **target** is the target of the following output. This is empty if + the message is related to Packer globally. Otherwise, this is generally + a build name so you can relate output to a specific build while parallel + builds are running. + +* **type** is the type of machine-readable message being outputted. There + are a set of standard types which are covered later, but each component + of Packer (builders, provisioners, etc.) may output their own custom types + as well, allowing the machine-readable output to be infinitely flexible. + +* **data** is zero or more comma-seperated values associated with the prior + type. The exact amount and meaning of this data is type-dependent, so you + must read the documentation associated with the type to understand fully. + +Within the format, if data contains a comma, it is replaced with +`%!(PACKER_COMMA)`. This was preferred over an escape character such as +`\'` because it is more friendly to tools like awk. + +Newlines within the format are replaced with their respective standard +escape sequence. Newlines become a literal `\n` within the output. Carriage +returns become a literal `\r`. + +## Message Types + +The set of machine-readable message types can be found in the +[machine-readable format](#) +complete documentation section. This section contains documentation +on all the message types exposed by Packer core as well as all the +components that ship with Packer by default. diff --git a/website/source/docs/command-line/validate.html.markdown b/website/source/docs/command-line/validate.html.markdown index fcf992f1f..e05c9410a 100644 --- a/website/source/docs/command-line/validate.html.markdown +++ b/website/source/docs/command-line/validate.html.markdown @@ -1,5 +1,6 @@ --- layout: "docs" +page_title: "Validate - Command-Line" --- # Command-Line: Validate diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 8b3ef5ddd..2ab4b4a8e 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -13,6 +13,7 @@