Update docs and move them to docs/

docs/COMMAND.md

@@ -0,0 +1,65 @@
+# Makisu Usage Information
+--------------------------
+
+```
+$ makisu build --help
+Build docker image, optionally push to registries and/or load into docker daemon
+
+Usage:
+  makisu build -t=<image_tag> [flags] <context_path>
+
+Flags:
+  -f, --file string                     The absolute path to the dockerfile (default "Dockerfile")
+  -t, --tag string                      Image tag (required)
+      --push stringArray                Registry to push image to
+      --replica stringArray             Push targets with alternative full image names "<registry>/<repo>:<tag>"
+      --registry-config string          Set build-time variables
+      --dest string                     Destination of the image tar
+      --target string                   Set the target build stage to build.
+      --build-arg stringArray           Argument to the dockerfile as per the spec of ARG. Format is "--build-arg <arg>=<value>"
+      --modifyfs                        Allow makisu to modify files outside of its internal storage dir
+      --commit string                   Set to explicit to only commit at steps with '#!COMMIT' annotations; Set to implicit to commit at every ADD/COPY/RUN step (default "implicit")
+      --blacklist stringArray           Makisu will ignore all changes to these locations in the resulting docker images
+      --local-cache-ttl duration        Time-To-Live for local cache (default 168h0m0s)
+      --redis-cache-addr string         The address of a redis server for cacheID to layer sha mapping
+      --redis-cache-password string     The password of the Redis server, should match 'requirepass' in redis.conf
+      --redis-cache-ttl duration        Time-To-Live for redis cache (default 168h0m0s)
+      --http-cache-addr string          The address of the http server for cacheID to layer sha mapping
+      --http-cache-header stringArray   Request header for http cache server. Format is "--http-cache-header <header>:<value>"
+      --docker-host string              Docker host to load images to (default "unix:///var/run/docker.sock")
+      --docker-version string           Version string for loading images to docker (default "1.21")
+      --docker-scheme string            Scheme for api calls to docker daemon (default "http")
+      --load                            Load image into docker daemon after build. Requires access to docker socket at location defined by ${DOCKER_HOST}
+      --storage string                  Directory that makisu uses for temp files and cached layers. Mount this path for better caching performance. If modifyfs is set, default to /makisu-storage; Otherwise default to /tmp/makisu-storage
+      --compression string              Image compression level, could be 'no', 'speed', 'size', 'default' (default "default")
+      --preserve-root                   Copy / in the storage dir and copy it back after build.
+  -h, --help                            help for build
+
+Global Flags:
+      --cpu-profile         Profile the application
+      --log-fmt string      The format of the logs. Valid values are "json" and "console" (default "json")
+      --log-level string    Verbose level of logs. Valid values are "debug", "info", "warn", "error" (default "info")
+      --log-output string   The output file path for the logs. Set to "stdout" to output to stdout (default "stdout")
+
+$ makisu push --help
+Push docker image to registries
+
+Usage:
+  makisu push -t=<image_tag> [flags] <image_tar_path>
+
+Flags:
+  -t, --tag string               Image tag (required)
+      --push stringArray         Registry to push image to
+      --replica stringArray      Push targets with alternative full image names "<registry>/<repo>:<tag>"
+      --registry-config string   Set build-time variables
+  -h, --help                     help for push
+
+Global Flags:
+      --cpu-profile         Profile the application
+      --log-fmt string      The format of the logs. Valid values are "json" and "console" (default "json")
+      --log-level string    Verbose level of logs. Valid values are "debug", "info", "warn", "error" (default "info")
+      --log-output string   The output file path for the logs. Set to "stdout" to output to stdout (default "stdout")
+
+$ makisu version
+v0.1.14
+```

docs/PARSER.md

@@ -0,0 +1,183 @@
+For the most part, this parser is compatible with the official Docker parser. However, there
+are a few unintuitive behaviors present in the Docker parser that have been replaced here.
+
+# Variable substitution
+
+All supported directives allow variable substitution from both ARG and ENV directives.
+
+Valid variable names consist of {letters, digits, '-', '\_', '.'}, and variable values can
+contain any character.
+
+Variable substitutions can be specified in the following formats:
+- $\<var\>
+    - Terminates once an invalid variable name character is encountered (e.g., if var=val1 and var\_=val2, /$var/ -> /val1/ and \_$var\_ -> \_$val2).
+- ${\<var\>}
+    - Supports recursive variable resolution (e.g., if var=val1 and val1=val2, ${$var} -> val2).
+- ${\<var\>:+\<default\_val\>}
+    - If \<var\> not set, resolves to \<default\_val\>, else the value for \<var\>. \<var\> may contain variables to resolve, but \<default\_val\> may not.
+- ${\<var\>:-\<default\_val\>}
+    - If \<var\> set, resolves to \<default\_val\>, else the empty string. \<var\> may contain variables to resolve, but \<default\_val\> may not.
+
+If a variable fails to resolve, it is passed through to the resulting string exactly as it appears in the input.
+
+# Directives
+
+The following directives are not supported: ONBUILD and SHELL.
+
+## COMMIT
+
+Syntax:
+- #!COMMIT
+    - 'COMMIT' can be any case and there can be whitespace preceding '#', after '!', or after 'COMMIT'.
+    - It cannot be at the beginning of a line, since all lines beginning with '#' would be ignored.
+
+This is a special directive that indicates that a layer should be committed (used in the distributed cache). To enable this directive, `--commit=explicit` argument is required.
+
+## ADD
+
+Syntax:
+- ADD \[--chown=\<user\>:\<group\>\] \<src\> ... \<dest\>
+    - Arguments must be separated by whitespace.
+- ADD \[--chown=\<user\>:\<group\>\] \["\<src\>",... "\<dest\>"\] (this form is required for paths containing whitespace)
+    - JSON format.
+
+Variables are substituted using values from ARGs and ENVs within the stage.
+
+## CMD
+
+Syntax:
+- CMD ["\<arg\>", "\<arg\>"...]
+    - JSON format.
+- CMD \<cmd\> [\<arg\> ...]
+    - \<cmd\> and \<arg\>s must be separated by whitespace.
+    - To include whitespace within an argument, the whitespace must be escaped using a backslash character or the argument must be surrounded in quotes.
+    - Quotes to be included in an argument must be escaped with a backslash.
+    - Any backslash characters present in an argument that don't precede whitespace or a quote will be passed through to the resulting string.
+
+Variables are substituted using values from ARGs and ENVs within the stage.
+
+## COPY
+
+Syntax:
+- COPY \[--chown=\<user\>:\<group\>\] \[--from=\<name|index\>\] \[--archive\] \<src\> ... \<dest\>
+    - Arguments must be separated by whitespace.
+- COPY \[--chown=\<user\>:\<group\>\] \[--from=\<name|index\>\] \[--archive\] \["\<src\>",... "\<dest\>"\] (this form is required for paths containing whitespace)
+    - JSON format.
+
+Variables are substituted using values from ARGs and ENVs within the stage.
+'--archive' is a option only Makisu supports. It will make COPY preseve the original owner and permissions of `src` and its underlying files and directories. Otherwise, makisu will follow docker's behavior, where `dst` itself might be owned by root if not created beforehand.
+
+## ENTRYPOINT
+
+Syntax:
+- ENTRYPOINT ["\<arg\>", "\<arg\>"...]
+    - JSON format.
+- ENTRYPOINT \<cmd\> [\<arg\> ...]
+    - \<cmd\> and \<arg\>s must be separated by whitespace. To include whitespace within a single argument, the whitespace must be escaped using a backslash character or the argument must be surrounded in quotes. Quotes within an argument must also be escaped with a backslash. Any backslash characters present in an argument that don't precede whitespace or a quote will be passed through to the resulting string.
+
+Variables are substituted using values from ARGs and ENVs within the stage.
+
+## ENV
+
+Syntax:
+- ENV \<key\> \<value\>
+    - Everything after the first space character after \<key\> is included in \<value\>.
+- ENV \<key\>=\<value\> ...
+    - \<key\>=\<value\> pairs must be separated by whitespace.
+    - Valid \<key\> characters are: letters, digits, '-', '\_', and '.'.
+    - \<value\>s may contain any character, but to include whitespace it must be escaped using a backslash character or the argument must be surrounded in quotes.
+    - Quotes to be included in a \<value\> must be escaped with a backslash.
+
+## EXPOSE
+
+Syntax:
+- EXPOSE \<port\>[/\<protocol\>] ...
+    - Arguments must be separated by whitespace.
+
+Variables are substituted using values from ARGs and ENVs within the stage.
+
+## FROM
+
+Syntax:
+- FROM \<image\> [AS \<name\>]
+
+Variables are substituted using globally defined ARGs (those that appear before the first FROM directive).
+
+## HEALTHCHECK
+
+Syntax:
+- HEALTHCHECK NONE
+- HEALTHCHECK \[--interval=\<time\>\] \[--timeout=\<time\>\] \[--start-period=\<time\>\] \[--retries=\<n\>\] CMD ["\<arg\>", "\<arg\>"...]
+    - CMD section is in JSON format.
+- HEALTHCHECK \[--interval=\<time\>\] \[--timeout=\<time\>\] \[--start-period=\<time\>\] \[--retries=\<n\>\] CMD \<full\_cmd\>
+    - \<full\_cmd\> will be added to healthcheck section of image config as-is (after variable substitution).
+
+Variables after CMD are substituted using values from ARGs and ENVs within the stage.
+
+## LABEL
+
+Syntax:
+- LABEL \<key\>=\<value\> ...
+    - \<key\>=\<value\> pairs must be separated by whitespace.
+    - Valid \<key\> characters are: letters, digits, '-', '\_', and '.'.
+    - \<value\>s may contain any character, but to include whitespace it must be escaped using a backslash character or the argument must be surrounded in quotes.
+    - Quotes to be included in a \<value\> must be escaped with a backslash.
+
+Variables are substituted using values from ARGs and ENVs within the stage.
+
+## MAINTAINER
+
+Syntax:
+- MAINTAINER \<maintainer\>
+
+Variables are not substituted.
+
+## RUN
+
+Syntax:
+- RUN ["\<arg\>", "\<arg\>"...]
+    - JSON format.
+- RUN \<full\_cmd\>
+    - \<full\_cmd\> will be passed to shell via 'sh -c' as-is (after variable substitution).
+
+Variables are substituted using values from ARGs and ENVs within the stage.
+
+## STOPSIGNAL
+
+Syntax:
+- STOPSIGNAL \<signal\>
+
+Variables are not substituted.
+
+## USER
+
+Syntax:
+- USER \<user\>:[\<group\>]
+    - Can be specified by user/group name or user/group ID.
+
+Variables are substituted using values from ARGs and ENVs within the stage.
+
+## VOLUME
+
+Syntax:
+- VOLUME ["\<volume\>", "\<volume\>"...]
+- VOLUME \<volume\> [\<volume\> ...]
+    - Volumes must be separated by whitespace characters.
+
+Variables are substituted using values from ARGs and ENVs within the stage.
+
+## WORKDIR
+
+Syntax:
+- WORKDIR \<path\>
+
+Variables are substituted using values from ARGs and ENVs within the stage.
+
+## ARG
+
+Syntax:
+- ARG \<name\>[=\<default\_val\>]
+
+If after the first FROM directive, variables are substituted into the directive using values from ARGs and ENVs within the stage. Else, variables are only substituted using values from other ARG directives that appeared prior to this one.
+
+Variables defined by ARG directives before the first FROM are used only by all FROM directives. Those defined within a stage are scoped to that stage only.