Update docs and move them to docs/ (#332)

* Update docs and move them to docs

* Update docs and move them to docs/

* typo

* typo

README.md

@@ -12,7 +12,7 @@ Some highlights of Makisu:
 * Requires no elevated privileges or containerd/Docker daemon, making the build process portable.
 * Uses a distributed layer cache to improve performance across a build cluster.
 * Provides control over generated layers with a new optional keyword [`#!COMMIT`](#explicit-commit-and-cache), reducing the number of layers in images.
-* Is Docker compatible. Note, the Dockerfile parser in Makisu is opinionated in some scenarios. More details can be found [here](lib/parser/dockerfile/README.md).
+* Is Docker compatible. Note, the Dockerfile parser in Makisu is opinionated in some scenarios. More details can be found [here](docs/PARSER.md).
 
 Makisu has been in use at Uber since early 2018, building thousands of images every day across 4
 different languages. The motivation and mechanism behind it are explained in https://eng.uber.com/makisu/.
@@ -53,7 +53,7 @@ makisu build -t ${TAG} --dest ${TAR_PATH} ${CONTEXT}
 
 # Running Makisu
 
-For a full list of flags, run `makisu build --help` or refer to the README [here](bin/makisu/README.md).
+For a full list of flags, run `makisu build --help` or refer to the README [here](docs/COMMAND.md).
 
 ## Makisu anywhere
 

bin/makisu/README.md → docs/COMMAND.md

@@ -12,15 +12,17 @@ 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-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>"
@@ -30,6 +32,7 @@ Flags:
       --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:

lib/parser/dockerfile/README.md → docs/PARSER.md

@@ -29,7 +29,7 @@ The following directives are not supported: ONBUILD and SHELL.
 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. 
+    - 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.
 
@@ -59,12 +59,13 @@ Variables are substituted using values from ARGs and ENVs within the stage.
 ## COPY
 
 Syntax:
-- COPY \[--chown=\<user\>:\<group\>\] \[--from=\<name|index\>\] \<src\> ... \<dest\>
+- COPY \[--chown=\<user\>:\<group\>\] \[--from=\<name|index\>\] \[--archive\] \<src\> ... \<dest\>
     - Arguments must be separated by whitespace.
-- COPY \[--chown=\<user\>:\<group\>\] \[--from=\<name|index\>\] \["\<src\>",... "\<dest\>"\] (this form is required for paths containing 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 makisu-specific option. By default, makisu will follow docker's behavior, where `dst` itself might be owned by root if not created beforehand. Adding `--archive` will make COPY preserve the original owner and permissions of `src` and its underlying files and directories.
 
 ## ENTRYPOINT
 

docs/index.md

@@ -12,7 +12,7 @@ Some highlights of Makisu:
 * Requires no elevated privileges or containerd/Docker daemon, making the build process portable.
 * Uses a distributed layer cache to improve performance across a build cluster.
 * Provides control over generated layers with a new optional keyword [`#!COMMIT`](#explicit-commit-and-cache), reducing the number of layers in images.
-* Is Docker compatible. Note, the Dockerfile parser in Makisu is opinionated in some scenarios. More details can be found [here](lib/parser/dockerfile/README.md).
+* Is Docker compatible. Note, the Dockerfile parser in Makisu is opinionated in some scenarios. More details can be found [here](docs/PARSER.md).
 
 Makisu has been in use at Uber since early 2018, building thousands of images every day across 4
 different languages. The motivation and mechanism behind it are explained in https://eng.uber.com/makisu/.
@@ -53,7 +53,7 @@ makisu build -t ${TAG} --dest ${TAR_PATH} ${CONTEXT}
 
 # Running Makisu
 
-For a full list of flags, run `makisu build --help` or refer to the README [here](bin/makisu/README.md).
+For a full list of flags, run `makisu build --help` or refer to the README [here](docs/COMMAND.md).
 
 ## Makisu anywhere
 

site/index.html

@@ -178,7 +178,7 @@
                 * Provides control over generated layers with a new optional keyword <a
                   href="#explicit-commit-and-cache"><code>#!COMMIT</code></a>, reducing the number of layers in images.
                 * Is Docker compatible. Note, the Dockerfile parser in Makisu is opinionated in some scenarios. More
-                details can be found <a href="lib/parser/dockerfile/README.md">here</a>.</p>
+                details can be found <a href="docs/PARSER.md">here</a>.</p>
               <p>Makisu has been in use at Uber since early 2018, building thousands of images every day across 4
                 different languages. The motivation and mechanism behind it are explained in
                 https://eng.uber.com/makisu/.</p>
@@ -214,7 +214,7 @@ <h2 id="building-makisu-binary-and-build-simple-images">Building Makisu binary a
 
               <h1 id="running-makisu">Running Makisu</h1>
               <p>For a full list of flags, run <code>makisu build --help</code> or refer to the README <a
-                  href="bin/makisu/README.md">here</a>.</p>
+                  href="docs/COMMAND.md">here</a>.</p>
               <h2 id="makisu-anywhere">Makisu anywhere</h2>
               <p>To build Dockerfiles that contain RUN, Makisu needs to run in a container.
                 To try it locally, the following snippet can be placed inside your <code>~/.bashrc</code> or