Merge pull request #778 from infosiftr/bashbrew-readme

Adjust the bashbrew README to be closer to the truth

bashbrew/README.md

@@ -1,35 +1,62 @@
 # Bashbrew
 
-## Main Scripts
-
-### `build.sh`
+The recommended way to use `bashbrew.sh` is to install a symlink in your `PATH` somewhere as `bashbrew`, for example `~/bin/bashbrew -> /path/to/official-images/bashbrew/bashbrew.sh` (assuming `~/bin` is in `PATH`).
 
 ```console
-$ ./bashbrew/build.sh --help
-
-usage: ./bashbrew/build.sh [options] [repo[:tag] ...]
-   ie: ./bashbrew/build.sh --all
-       ./bashbrew/build.sh debian ubuntu:12.04
-
-   This script builds the Docker images specified using the Git repositories
-   specified in the library files.
-
-options:
+$ bashbrew --help
+
+usage: bashbrew [build|push|list] [options] [repo[:tag] ...]
+   ie: bashbrew build --all
+       bashbrew push debian ubuntu:12.04
+       bashbrew list --namespaces='_' debian:7 hello-world
+
+This script processes the specified Docker images using the corresponding
+repository manifest files.
+
+common options:
+  --all              Build all repositories specified in library
+  --docker="docker"
+                     Use a custom Docker binary
+  --retries="4"
+                     How many times to try again if the build/push fails before
+                     considering it a lost cause (always attempts a minimum of
+                     one time, but maximum of one plus this number)
   --help, -h, -?     Print this help message
-  --all              Builds all Docker repos specified in library
-  --no-clone         Don't pull the Git repos
-  --no-build         Don't build, just echo what would have built
-  --library="./stackbrew/library"
+  --library="/home/tianon/docker/stackbrew/library"
                      Where to find repository manifest files
-  --src="./stackbrew/bashbrew/src"
-                     Where to store the cloned Git repositories
-  --logs="./stackbrew/bashbrew/logs"
+  --logs="/home/tianon/docker/stackbrew/bashbrew/logs"
                      Where to store the build logs
-  --namespaces="library stackbrew"
-                     Space separated list of namespaces to tag images in after
-                     building
+  --namespaces="_"
+                     Space separated list of image namespaces to act upon
+                     
+                     Note that "_" is a special case here for the unprefixed
+                     namespace (ie, "debian" vs "library/debian"), and as such
+                     will be implicitly ignored by the "push" subcommand
+                     
+                     Also note that "build" will always tag to the unprefixed
+                     namespace because it is necessary to do so for dependent
+                     images to use FROM correctly (think "onbuild" variants that
+                     are "FROM base-image:some-version")
+  --uniq
+                     Only process the first tag of identical images
+                     This is not recommended for build or push
+                     i.e. process python:2.7, but not python:2
+
+build options:
+  --no-build         Don't build, print what would build
+  --no-clone         Don't pull/clone Git repositories
+  --src="/home/tianon/docker/stackbrew/bashbrew/src"
+                     Where to store cloned Git repositories (GOPATH style)
+
+push options:
+  --no-push          Don't push, print what would push
+
 ```
 
+## Subcommands
+
+### `bashbrew build`
+
 This script reads the library files for the images specified and then clones the required Git repositories into the specified `--src` directory. If the Git repository already exists, the script verifies that the Git ref specified in the library file exists and does `git fetch` as necessary.
 
 The next step in the script is to build each image specified. All the `image:tag` combinations are placed into a queue. The processing order is determined by the order of items passed in on the command line (or alphabetical if `--all` is used). When a whole image, like `debian`, is specified the `image:tag` combinations are added to the queue in the order that they appear in the library file. For each `image:tag` to be processed, the system checks out the specified commit and sets mtimes (see [`git-set-mtimes`](#git-set-mtimes)) of all files in the Git repository to take advantage of Docker caching. If the `image:tag` is `FROM` another image that is later in the queue, it is deferred to the end of the queue.
@@ -42,32 +69,49 @@ The `--no-build` option skips all the building, including setting the mtimes.
 
 **WARNING:** setting `--src` so that it uses a local working copy of your Git directory for a specified build will delete untracked and uncommitted changes, and will disable `gc.auto`. It is not recommended to symlink in your working directories for use during build.
 
-### `push.sh`
+### `bashbrew push`
 
-```console
-$ ./bashbrew/push.sh --help
+This script takes advantage of `docker login` and does a `docker push` on each `image:tag` specified for the given `--namespaces`. The script will warn if a given `namespace/image:tag` does not exist.
 
-usage: ./bashbrew/push.sh [options] [repo[:tag] ...]
-   ie: ./bashbrew/push.sh --all
-       ./bashbrew/push.sh debian ubuntu:12.04
+The `--no-push` option prints out the `docker push` instructions that would have been executed.
 
-   This script pushes the specified Docker images from library that are built
-   and tagged in the specified namespaces.
+### `bashbrew list`
 
-options:
-  --help, -h, -?     Print this help message
-  --all              Pushes all Docker images built for the given namespaces
-  --no-push          Don't actually push the images to the Docker Hub
-  --library="./stackbrew/library"
-                     Where to find repository manifest files
-  --namespaces="library stackbrew"
-                     Space separated list of namespaces to tag images in after
-                     building
-```
+Takes the same arguments as `bashbrew build` and `bashbrew push`, but prints a list of image names and quits.
 
-This script takes advantage of `docker login` and does a `docker push` on each `image:tag` specified for the given `--namespaces`. The script will warn if a given `namespace/image:tag` does not exist.
+For example:
 
-The `--no-push` option prints out the `docker push` instructions that would have been executed.
+```console
+$ # count the number of tags in the official library
+$ bashbrew list --all | wc -l
+802
+$ # count the number of _unique_ tags in the official library
+$ bashbrew list --all --uniq | wc -l
+296
+
+$ # pull all officially supported tags of "debian"
+$ bashbrew list debian | xargs -n1 --verbose docker pull
+...
+
+$ # list all unique supported tags of "python"
+$ bashbrew list --uniq python
+python:2.7.10
+python:2.7.10-onbuild
+python:2.7.10-slim
+python:2.7.10-wheezy
+python:3.2.6
+python:3.2.6-onbuild
+python:3.2.6-slim
+python:3.2.6-wheezy
+python:3.3.6
+python:3.3.6-onbuild
+python:3.3.6-slim
+python:3.3.6-wheezy
+python:3.4.3
+python:3.4.3-onbuild
+python:3.4.3-slim
+python:3.4.3-wheezy
+```
 
 ## Helper Scripts