From 9eadac3410e80f4a8520c9caf8f52f1f0c3f728e Mon Sep 17 00:00:00 2001
From: Megan Marsh <megan@hashicorp.com>
Date: Mon, 22 Apr 2019 15:35:00 -0700
Subject: [PATCH] add guide for uisng jq to strip comments from packer template

---
 .../guides/use-packer-with-comment.html.md    | 77 +++++++++++++++++++
 website/source/layouts/guides.erb             |  3 +
 2 files changed, 80 insertions(+)
 create mode 100644 website/source/guides/use-packer-with-comment.html.md

diff --git a/website/source/guides/use-packer-with-comment.html.md b/website/source/guides/use-packer-with-comment.html.md
new file mode 100644
index 000000000..52fbaa7dc
--- /dev/null
+++ b/website/source/guides/use-packer-with-comment.html.md
@@ -0,0 +1,77 @@
+---
+layout: guides
+sidebar_current: use-packer-with-comment
+page_title: Use jq and Packer to comment your templates - Guides
+description: |-
+  You can add detailed comments beyond the root-level underscore-prefixed field
+  supported by Packer, and remove them using jq.
+---
+
+#How to use jq to strip unsupported comments from a Packer template
+
+One of the biggest complaints we get about packer is that json doesn't use comments. We're in the process of moving to HCL2, the same config language used by Terraform, which does allow comments. But in the meantime, you can add detailed comments beyond the root-level underscore-prefixed field supported by Packer, and remove them using jq.
+
+Let's say we have a file named commented_template.json
+
+``` json
+{
+  	"_comment": [
+	    "this is",
+	    "a multi-line",
+	    "comment"
+  	],
+    "builders": [
+        {
+            "_comment": "this is a comment inside a builder",
+            "type": "null",
+            "communicator": "none"
+        }
+    ],
+    "_comment": "this is a root level comment",
+    "provisioners": [
+        {
+          "_comment": "this is a different comment",
+          "type": "shell",
+          "_comment": "this is yet another comment",
+          "inline": ["echo hellooooo"]
+        }
+    ]
+}
+```
+
+```sh
+jq 'walk(if type == "object" then del(._comment) else . end)' commented_template.json > uncommented_template.json
+```
+
+will produce a new file containing:
+
+```json
+{
+  "builders": [
+    {
+      "type": "null",
+      "communicator": "none"
+    }
+  ],
+  "provisioners": [
+    {
+      "type": "shell",
+      "inline": [
+        "echo hellooooo"
+      ]
+    }
+  ]
+}
+```
+
+Once you've got your uncommented file, you can call `packer build` on it like
+you normally would.
+
+## The walk function
+If your install of jq does not have the walk function and you get an error like
+
+```
+jq: error: walk/1 is not defined at <top-level>,
+```
+
+You can create a file `~/.jq` and add the [walk function](https://github.com/stedolan/jq/blob/ad9fc9f559e78a764aac20f669f23cdd020cd943/src/builtin.jq#L255-L262) to it by hand.
diff --git a/website/source/layouts/guides.erb b/website/source/layouts/guides.erb
index 1d5653c04..f6e2de6d0 100644
--- a/website/source/layouts/guides.erb
+++ b/website/source/layouts/guides.erb
@@ -4,6 +4,9 @@
       <li<%= sidebar_current("guides-veewee-to-packer") %>>
         <a href="/guides/veewee-to-packer.html">Veewee to Packer</a>
       </li>
+      <li<%= sidebar_current("use-packer-with-comment") %>>
+        <a href="/guides/use-packer-with-comment.html">Use jq to strip comments from a Packer template</a>
+      </li>
       <li<%= sidebar_current("guides-packer-on-cicd") %>>
         <a href="/guides/packer-on-cicd/index.html">Build Immutable Infrastructure with Packer in CI/CD</a>
         <ul class="nav">