cmd: Document the cas, refs, and init commands

Most of this is new boilerplate, but oci-image-tools.7.md is based on the old oci-image-tool.1.md removed by fe363aa (*: move to opencontainers/image-tools, 2016-09-15). There's a lot going on in this repo, and it's nice to have a page that outlines everything provided by the project even though we're no longer providing a single command. Signed-off-by: W. Trevor King <wking@tremily.us>
opencontainers · Oct 11, 2016 · c8c9708 · c8c9708
1 parent c78878f
commit c8c9708
Show file tree

Hide file tree

Showing 13 changed files with 340 additions and 3 deletions.
diff --git a/cmd/oci-cas/oci-cas-get.1.md b/cmd/oci-cas/oci-cas-get.1.md
@@ -0,0 +1,27 @@
+% OCI(1) OCI-IMAGE-TOOL User Manuals
+% OCI Community
+% AUGUST 2016
+# NAME
+
+oci-cas-get \- Retrieve a blob from the store
+
+# SYNOPSIS
+
+**oci-cas get** [OPTIONS] PATH DIGEST
+
+# DESCRIPTION
+
+`oci-cas get` retrieves a blob referenced by `DIGEST` from the store at `PATH` and writes it to standard output.
+
+# OPTIONS
+
+**--help**
+  Print usage statement
+
+# SEE ALSO
+
+**oci-cas**(1), **oci-cas-put**(1)
+
+# HISTORY
+
+August 2016, Originally compiled by W. Trevor King (wking at tremily dot us)
diff --git a/cmd/oci-cas/oci-cas-put.1.md b/cmd/oci-cas/oci-cas-put.1.md
@@ -0,0 +1,27 @@
+% OCI(1) OCI-IMAGE-TOOL User Manuals
+% OCI Community
+% AUGUST 2016
+# NAME
+
+oci-cas-put \- Write a blob to the store
+
+# SYNOPSIS
+
+**oci-cas put** [OPTIONS] PATH
+
+# DESCRIPTION
+
+`oci-cas put` reads a blob from stdin, writes it to the store at `PATH`, and prints the digest to standard output.
+
+# OPTIONS
+
+**--help**
+  Print usage statement
+
+# SEE ALSO
+
+**oci-cas**(1), **oci-cas-get**(1)
+
+# HISTORY
+
+August 2016, Originally compiled by W. Trevor King (wking at tremily dot us)
diff --git a/cmd/oci-cas/oci-cas.1.md b/cmd/oci-cas/oci-cas.1.md
@@ -0,0 +1,47 @@
+% OCI(1) OCI-User Manuals
+% OCI Community
+% AUGUST 2016
+# NAME
+
+oci-cas \- Content-addressable storage manipulation
+
+# SYNOPSIS
+
+**oci-cas** [command]
+
+# DESCRIPTION
+
+`oci-cas` manipulates content-addressable storage.
+
+# OPTIONS
+
+**--help**
+  Print usage statement
+
+# COMMANDS
+
+**get**
+  Retrieve a blob from the store.
+  See **oci-cas-get**(1) for full documentation on the **get** command.
+
+**put**
+  Write a blob to the store.
+  See **oci-cas-put**(1) for full documentation on the **put** command.
+
+# EXAMPLES
+
+```
+$ oci-image-init image-layout image.tar
+$ echo hello | oci-cas put image.tar
+sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
+$ oci-cas get image.tar sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
+hello
+```
+
+# SEE ALSO
+
+**oci-image-tools**(7), **oci-cas-get**(1), **oci-cas-put**(1), **oci-image-init**(1)
+
+# HISTORY
+
+August 2016, Originally compiled by W. Trevor King (wking at tremily dot us)
diff --git a/cmd/oci-create-runtime-bundle/oci-create-runtime-bundle.1.md b/cmd/oci-create-runtime-bundle/oci-create-runtime-bundle.1.md
@@ -36,7 +36,7 @@ $ cd busybox-bundle && sudo runc run busybox
 ```
 
 # SEE ALSO
-**runc**(1), **skopeo**(1)
+**oci-image-tools**(7), **runc**(1), **skopeo**(1)
 
 # HISTORY
 Sept 2016, Originally compiled by Antonio Murdaca (runcom at redhat dot com)
diff --git a/cmd/oci-image-init/oci-image-init-image-layout.1.md b/cmd/oci-image-init/oci-image-init-image-layout.1.md
@@ -0,0 +1,27 @@
+% OCI(1) OCI-IMAGE-TOOL User Manuals
+% OCI Community
+% AUGUST 2016
+# NAME
+
+oci-image-init-image-layout \- Initialize an OCI image-layout repository
+
+# SYNOPSIS
+
+**oci-image-init image-layout** [OPTIONS] PATH
+
+# DESCRIPTION
+
+`oci-image-init image-layout` initializes an image-layout repository at `PATH`.
+
+# OPTIONS
+
+**--help**
+  Print usage statement
+
+# SEE ALSO
+
+**oci-image-init**(1), **oci-cas**(1), ***oci-refs**(1)
+
+# HISTORY
+
+August 2016, Originally compiled by W. Trevor King (wking at tremily dot us)
diff --git a/cmd/oci-image-init/oci-image-init.1.md b/cmd/oci-image-init/oci-image-init.1.md
@@ -0,0 +1,33 @@
+% OCI(1) OCI-IMAGE-TOOL User Manuals
+% OCI Community
+% AUGUST 2016
+# NAME
+
+oci-image-init \- Initialize an OCI image
+
+# SYNOPSIS
+
+**oci-image-init** [command]
+
+# DESCRIPTION
+
+`oci-image-init` Initializes an OCI image.
+
+# OPTIONS
+
+**--help**
+  Print usage statement
+
+# COMMANDS
+
+**image-layout**
+  Initialize an OCI image-layout repository.
+  See **oci-image-init-image-layout**(1) for full documentation on the **image-layout** command.
+
+# SEE ALSO
+
+**oci-image-tool**(1), **oci-image-init-image-layout**(1)
+
+# HISTORY
+
+August 2016, Originally compiled by W. Trevor King (wking at tremily dot us)
diff --git a/cmd/oci-image-tools.7.md b/cmd/oci-image-tools.7.md
@@ -0,0 +1,40 @@
+% OCI(1) OCI-IMAGE-TOOL User Manuals
+% OCI Community
+% JULY 2016
+# NAME
+
+oci-image-tools \- OCI (Open Container Initiative) image tools
+
+# DESCRIPTION
+
+The OCI image tools are a collection of tools for working with the OCI image specification.
+
+# COMMANDS
+
+**oci-cas**(1)
+  Content-addressable storage manipulation.
+
+**oci-create-runtime-bundle**(1)
+  Create an OCI image runtime bundle
+
+**oci-image-init**(1)
+  Initialize an OCI image.
+
+**oci-refs**(1)
+  Name-based reference manipulation.
+
+**oci-unpack**(1)
+  Unpack an image or image source layout
+
+**oci-validate**(1)
+  Validate one or more image files
+
+# SEE ALSO
+
+**skopeo**(1),
+https://github.com/opencontainers/image-spec,
+https://github.com/opencontainers/image-tools
+
+# HISTORY
+
+July 2016, Originally compiled by Antonio Murdaca (runcom at redhat dot com)
diff --git a/cmd/oci-image-validate/oci-image-validate.1.md b/cmd/oci-image-validate/oci-image-validate.1.md
@@ -33,7 +33,7 @@ busybox-oci: OK
 ```
 
 # SEE ALSO
-**skopeo**(1)
+**oci-image-tools**(7), **skopeo**(1)
 
 # HISTORY
 Sept 2016, Originally compiled by Antonio Murdaca (runcom at redhat dot com)
diff --git a/cmd/oci-refs/oci-refs-get.1.md b/cmd/oci-refs/oci-refs-get.1.md
@@ -0,0 +1,27 @@
+% OCI(1) OCI-IMAGE-TOOL User Manuals
+% OCI Community
+% AUGUST 2016
+# NAME
+
+oci-refs-get \- Retrieve a reference from the store
+
+# SYNOPSIS
+
+**oci-refs get** [OPTIONS] PATH NAME
+
+# DESCRIPTION
+
+`oci-refs get` retrieves reference `NAME` from the store at `PATH` and writes the JSON descriptor to standard output.
+
+# OPTIONS
+
+**--help**
+  Print usage statement
+
+# SEE ALSO
+
+**oci-refs**(1), **oci-refs-list**(1), **oci-refs-put**(1)
+
+# HISTORY
+
+August 2016, Originally compiled by W. Trevor King (wking at tremily dot us)
diff --git a/cmd/oci-refs/oci-refs-list.1.md b/cmd/oci-refs/oci-refs-list.1.md
@@ -0,0 +1,27 @@
+% OCI(1) OCI-IMAGE-TOOL User Manuals
+% OCI Community
+% AUGUST 2016
+# NAME
+
+oci-refs-list \- Return available names from the store
+
+# SYNOPSIS
+
+**oci-refs list** [OPTIONS] PATH
+
+# DESCRIPTION
+
+`oci-refs list` retrieves all names from the store at `PATH` and writes them to standard output.
+
+# OPTIONS
+
+**--help**
+  Print usage statement
+
+# SEE ALSO
+
+**oci-refs**(1), **oci-refs-get**(1), **oci-refs-put**(1)
+
+# HISTORY
+
+August 2016, Originally compiled by W. Trevor King (wking at tremily dot us)
diff --git a/cmd/oci-refs/oci-refs-put.1.md b/cmd/oci-refs/oci-refs-put.1.md
@@ -0,0 +1,27 @@
+% OCI(1) OCI-IMAGE-TOOL User Manuals
+% OCI Community
+% AUGUST 2016
+# NAME
+
+oci-refs-put \- Write a reference to the store
+
+# SYNOPSIS
+
+**oci-refs put** [OPTIONS] PATH NAME
+
+# DESCRIPTION
+
+`oci-refs put` reads descriptor JSON from standard input and writes it to the store at `PATH` as `NAME`.
+
+# OPTIONS
+
+**--help**
+  Print usage statement
+
+# SEE ALSO
+
+**oci-refs**(1), **oci-refs-get**(1), **oci-refs-list**(1)
+
+# HISTORY
+
+August 2016, Originally compiled by W. Trevor King (wking at tremily dot us)
diff --git a/cmd/oci-refs/oci-refs.1.md b/cmd/oci-refs/oci-refs.1.md
@@ -0,0 +1,55 @@
+% OCI(1) OCI-IMAGE-TOOL User Manuals
+% OCI Community
+% AUGUST 2016
+# NAME
+
+oci-refs \- Name-based reference manipulation
+
+# SYNOPSIS
+
+**oci-refs** [command]
+
+# DESCRIPTION
+
+`oci-refs` manipulates name-based references.
+
+# OPTIONS
+
+**--help**
+  Print usage statement
+
+# COMMANDS
+
+**get**
+  Retrieve a reference from the store.
+  See **oci-refs-get**(1) for full documentation on the **get** command.
+
+**list**
+  Return available names from the store.
+  See **oci-refs-list**(1) for full documentation on the **list** command.
+
+**put**
+  Write a reference to the store.
+  See **oci-refs-put**(1) for full documentation on the **put** command.
+
+# EXAMPLES
+
+```
+$ oci-image-init image-layout image.tar
+$ DIGEST=$(echo hello | oci-cas put image.tar)
+$ SIZE=$(echo hello | wc -c)
+$ printf '{"mediaType": "text/plain", "digest": "%s", "size": %d}' "${DIGEST}" "${SIZE}" |
+>   oci-refs put image.tar greeting
+$ oci-refs list image.tar
+greeting
+$ oci-refs get image.tar greeting
+{"mediaType":"text/plain","digest":"sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03","size":6}
+```
+
+# SEE ALSO
+
+**oci-image-tools**(7), **oci-cas-put**(1), **oci-refs-get**(1), **oci-refs-list**(1), **oci-refs-put**(1)
+
+# HISTORY
+
+August 2016, Originally compiled by W. Trevor King (wking at tremily dot us)
diff --git a/cmd/oci-unpack/oci-unpack.1.md b/cmd/oci-unpack/oci-unpack.1.md
@@ -43,7 +43,7 @@ busybox-bundle
 ```
 
 # SEE ALSO
-**skopeo**(1)
+**oci-image-tools**(7), **skopeo**(1)
 
 # HISTORY
 Sept 2016, Originally compiled by Antonio Murdaca (runcom at redhat dot com)