Permalink
Browse files

man: add man pages

Signed-off-by: Aleksa Sarai <asarai@suse.com>
  • Loading branch information...
1 parent 508556f commit 44f290407371e4ca134418bc2d3911babb579ab1 @cyphar committed Dec 10, 2016
Showing with 453 additions and 1 deletion.
  1. +3 −0 .travis.yml
  2. +1 −0 Dockerfile
  3. +11 −1 Makefile
  4. +4 −0 man/.gitignore
  5. +100 −0 man/umoci-config.1.md
  6. +24 −0 man/umoci-gc.1.md
  7. +25 −0 man/umoci-init.1.md
  8. +31 −0 man/umoci-new.1.md
  9. +57 −0 man/umoci-repack.1.md
  10. +57 −0 man/umoci-stat.1.md
  11. +20 −0 man/umoci-tag.1.md
  12. +45 −0 man/umoci-unpack.1.md
  13. +75 −0 man/umoci.1.md
View
@@ -12,6 +12,9 @@ go:
#- 1.6
#- master
+before_install:
+ - go get -u github.com/cpuguy83/go-md2man
+
env:
- DOCKER_IMAGE="opensuse/amd64:42.2"
- DOCKER_IMAGE="fedora:latest"
View
@@ -28,6 +28,7 @@ RUN zypper -n in \
git \
'go>=1.6' \
go-mtree \
+ golang-github-cpuguy83-go-md2man \
jq \
make \
oci-image-tools \
View
@@ -14,6 +14,7 @@
# limitations under the License.
GO ?= go
+GO_MD2MAN ?= go-md2man
# Set up the ... lovely ... GOPATH hacks.
PROJECT := github.com/cyphar/umoci
@@ -60,6 +61,15 @@ local-validate:
#@echo "git-validation"
#@git-validation -v -run DCO,short-subject,dangling-whitespace $(EPOCH_COMMIT)..HEAD
+MANPAGES_MD := $(wildcard man/*.md)
+MANPAGES := $(MANPAGES_MD:%.md=%)
+
+man/%.1: man/%.1.md
+ $(GO_MD2MAN) -in $< -out $@
+
+.PHONY: doc
+doc: $(MANPAGES)
+
# Used for tests.
DOCKER_IMAGE :=opensuse/amd64:tumbleweed
@@ -87,4 +97,4 @@ local-test-integration: umoci
bats -t test/*.bats
.PHONY: ci
-ci: umoci validate test-unit test-integration
+ci: umoci validate doc test-unit test-integration
View
@@ -0,0 +1,4 @@
+# Ignore everything except markdown files.
+*
+!.gitignore
+!*.md
View
@@ -0,0 +1,100 @@
+% umoci-config(1) # umoci config - Modifies the configuration of an OCI image
+% Aleksa Sarai
+% DECEMBER 2016
+# NAME
+umoci config - Modifies the configuration of an OCI image
+
+# SYNOPSIS
+**umoci config**
+**--image**=*image*[:*tag*]
+[**--tag**=*new-tag*]
+[**--history.comment**=*comment*]
+[**--history.created_by**=*created_by*]
+[**--history.author**=*author*]
+[**--history-created**=*date*]
+[**--clear**=*value*]
+[**--config.user**=[*value*]]
+[**--config.memory.limit**=[*value*]]
+[**--config.memory.swap**=[*value*]]
+[**--config.cpu.shares**=[*value*]]
+[**--config.exposedports**=[*value*]]
+[**--config.env**=[*value*]]
+[**--config.entrypoint**=[*value*]]
+[**--config.cmd**=[*value*]]
+[**--config.volume**=[*value*]]
+[**--config.label**=[*value*]]
+[**--config.workingdir**=[*value*]]
+[**--created**=[*value*]]
+[**--author**=[*value*]]
+[**--architecture**=[*value*]]
+[**--os**=[*value*]]
+[**--manifest.annotation**=[*value*]]
+
+# OPTIONS
+The global options are defined in **umoci**(1).
+
+**--image**=*image*[:*tag*]
+ The source tagged OCI image whose config will be modified. *image* must be
+ a path to a valid OCI image and *tag* must be a valid tag in the image. If
+ *<tag>* is not provided it defaults to "latest".
+
+**--tag**=*new-tag*
+ Tag name for the repacked image, if unspecified then the original tag
+ provided to **--image** will be clobbered.
+
+**--history.comment**=*comment*
+ Comment for the history entry corresponding to this modification of the image
+ configuration. If unspecified, **umoci**(1) will generate an
+ implementation-dependent value.
+
+**--history.created_by**=*created_by*
+ CreatedBy entry for the history entry corresponding to this modification of
+ the image configuration. If unspecified, **umoci**(1) will generate an
+ implementation-dependent value.
+
+**--history.author**=*author*
+ Author value for the history entry corresponding to this modification of the
+ image configuration. If unspecified, this value will be the image's author
+ value **after** any modifications were made by this call of
+ **umoci-config**(1).
+
+**--history-created**=*date*
+ Creation date for the history entry corresponding to this modifications of
+ the image configuration. This must be an ISO8601 formatted timestamp (see
+ **date**(1)). If unspecified, the current time is used.
+
+**--clear**=*value*
+ Removes all pre-existing entries for a given set or list configuration option
+ (it will not undo any modification made by this call of **umoci-config**(1)).
+ The valid values of *value* are:
+
+ * config.labels
+ * manifest.annotations
+ * config.exposedports
+ * config.env
+ * config.volume
+
+The following commands all set their corresponding values in the configuration
+or image manifest. For more information see [the OCI image specification][1].
+
+* **--config.user**=[*value*]
+* **--config.memory.limit**=[*value*]
+* **--config.memory.swap**=[*value*]
+* **--config.cpu.shares**=[*value*]
+* **--config.exposedports**=[*value*]
+* **--config.env**=[*value*]
+* **--config.entrypoint**=[*value*]
+* **--config.cmd**=[*value*]
+* **--config.volume**=[*value*]
+* **--config.label**=[*value*]
+* **--config.workingdir**=[*value*]
+* **--created**=[*value*]
+* **--author**=[*value*]
+* **--architecture**=[*value*]
+* **--os**=[*value*]
+* **--manifest.annotation**=[*value*]
+
+# SEE ALSO
+**umoci**(1)
+
+[1]: https://github.com/opencontainers/image-spec
View
@@ -0,0 +1,24 @@
+% umoci-gc(1) # umoci gc - Garbage collects all unreferenced OCI image blobs
+% Aleksa Sarai
+% DECEMBER 2016
+# NAME
+umoci gc - Garbage collects all unreferenced OCI image blobs
+
+# SYNOPSIS
+**umoci gc**
+**--layout**=*image*
+
+# DESCRIPTION
+Conduct a mark-and-sweep garbage collection of the provided OCI image, only
+retaining blobs which can be reached by a descriptor path from the root set of
+tags. All other blobs will be removed.
+
+# OPTIONS
+The global options are defined in **umoci**(1).
+
+**--layout**=*image*
+ The OCI image layout to be garbage collected. *image* must be a path to a
+ valid OCI image.
+
+# SEE ALSO
+**umoci**(1)
View
@@ -0,0 +1,25 @@
+% umoci-init(1) # umoci init - Modifies the inituration of an OCI image
+% Aleksa Sarai
+% DECEMBER 2016
+# NAME
+umoci init - Modifies the inituration of an OCI image
+
+# SYNOPSIS
+**umoci init**
+**--layout**=*image*
+
+# DESCRIPTION
+Creates a new OCI image layout. The new OCI image does not contain any new
+references or blobs, but those can be created through the use of
+**umoci-new**(1), **umoci-tag**(1), **umoci-repack**(1) and other similar
+commands.
+
+# OPTIONS
+The global options are defined in **umoci**(1).
+
+**--layout**=*image*
+ The path where the OCI image layout will be created. The path must not exist
+ already or **umoci-init**(1) will return an error.
+
+# SEE ALSO
+**umoci**(1), **umoci-new**(1)
View
@@ -0,0 +1,31 @@
+% umoci-new(1) # umoci new - Create a blank tag in an OCI image
+% Aleksa Sarai
+% DECEMBER 2016
+# NAME
+umoci new - Create a blank tag in an OCI image
+
+# SYNOPSIS
+**umoci new**
+**--image**=*image*[:*tag*]
+
+# DESCRIPTION
+Create a blank tag in an OCI image. The created image's configuration and
+manifest are all set to **umoci**-defined default values, with no filesystem
+layer blobs added to the image.
+
+Once a new image is created with **umoci-new**(1) you can directly use the
+image with **umoci-unpack**(1), **umoci-repack**(1), and **umoci-config**(1) to
+modify the new tagged image as you see fit. This allows you to create entirely
+new images from scratch, without needing a base image to start with.
+
+# OPTIONS
+The global options are defined in **umoci**(1).
+
+**--image**=*image*[:*tag*]
+ The destination of the blank tag in the OCI image. *image* must be a path to
+ a valid OCI image, and *tag* must be a valid tag name. If a tag already
+ exists with the name *tag* it will be overwritten.
+
+# SEE ALSO
+**umoci**(1), **umoci-unpack**(1), **umoci-repack**(1), **umoci-config**(1)
+
View
@@ -0,0 +1,57 @@
+% umoci-repack(1) # umoci repack - Repacks an OCI runtime bundle into an image tag
+% Aleksa Sarai
+% DECEMBER 2016
+# NAME
+umoci repack - Repacks an OCI runtime bundle into an image tag
+
+# SYNOPSIS
+**umoci repack**
+**--image**=*image*[:*tag*]
+[**--history.comment**=*comment*]
+[**--history.created_by**=*created_by*]
+[**--history.author**=*author*]
+[**--history-created**=*date*]
+*<bundle>*
+
+# DESCRIPTION
+Given a modified bundle extracted with **umoci-unpack**(1), **umoci-repack**(1)
+computes the filesystem delta for the OCI bundle's *rootfs*. The delta is used
+to generate a delta layer, which is then appended to the original image
+manifest (that was used as an argument to **umoci-unpack**(1)) and tagged as a
+new image tag. Between a call to **umoci-unpack**(1) and **umoci-repack**(1)
+users SHOULD NOT modify the OCI image in any way.
+
+All **--uid-map** and **--gid-map** settings are implied from the saved values
+specified in **umoci-unpack**(1), so they are not available for
+**umoci-repack**(1).
+
+# OPTIONS
+The global options are defined in **umoci**(1).
+
+**--image**=*image*[:*tag*]
+ The destination tag for the repacked OCI image. *image* must be a path to a
+ valid OCI image (and the same *image* used in **umoci-unpack**(1) to create
+ the *bundle*) and *tag* must be a valid tag name. If another tag already has
+ the same name as *tag* it will be overwritten.
+
+**--history.comment**=*comment*
+ Comment for the history entry corresponding to this modification of the image
+ If unspecified, **umoci**(1) will generate an implementation-dependent value.
+
+**--history.created_by**=*created_by*
+ CreatedBy entry for the history entry corresponding to this modification of
+ the image. If unspecified, **umoci**(1) will generate an
+ implementation-dependent value.
+
+**--history.author**=*author*
+ Author value for the history entry corresponding to this modification of the
+ image. If unspecified, this value will be the image's author value **after**
+ any modifications were made by this call of **umoci-config**(1).
+
+**--history-created**=*date*
+ Creation date for the history entry corresponding to this modifications of
+ the image. This must be an ISO8601 formatted timestamp (see **date**(1)). If
+ unspecified, the current time is used.
+
+# SEE ALSO
+**umoci**(1), **umoci-unpack**(1)
View
@@ -0,0 +1,57 @@
+% umoci-stat(1) # umoci stat - Display status information about an image tag
+% Aleksa Sarai
+% DECEMBER 2016
+# NAME
+umoci stat - Display status information about an image tag
+
+# SYNOPSIS
+**umoci stat**
+**--image**=*image*[:*tag*]
+[**--json**]
+
+# DESCRIPTION
+Generates various pieces of status information about an image tag, including
+the history of the image.
+
+**WARNING**: Do not depend on the output of this tool unless you are using the
+**--json** flag. The intention of the default formatting of this tool is to
+make it human-readable, and might change in future versions. For parseable
+and stable output, use **--json**.
+
+# OPTIONS
+The global options are defined in **umoci**(1).
+
+**--image**=*image*[:*tag*]
+ The OCI image tag to display information about. *image* must be a path to a
+ valid OCI image and *tag* must be a valid tag in the image. If *<tag>* is not
+ provided it defaults to "latest".
+
+**--json**
+ Output the status information as a JSON encoded blob.
+
+# FORMAT
+The format of the **--json** blob is as follows. Many of these fields come from
+the [OCI image specification][1].
+
+ {
+ # This is the set of history entries for the image.
+ "history": [
+ {
+ "layer": <descriptor>, # null if empty_layer is true
+ "diff_id": <diffid>,
+ "created": <created>,
+ "created_by": <created_by>,
+ "author": <author>,
+ "empty_layer": <empty_layer>
+ }...
+ ]
+ }
+
+In future versions of **umoci**(1) there may be extra fields added to the above
+structure. However, the currently defined fields will always be set (until a
+backwards-incompatible release is made).
+
+# SEE ALSO
+**umoci**(1)
+
+[1]: https://github.com/opencontainers/image-spec
View
@@ -0,0 +1,20 @@
+% umoci-tag(1) # umoci tag - Modify tags in an OCI image
+% Aleksa Sarai
+% DECEMBER 2016
+# NAME
+umoci tag - Modify tags in an OCI image
+
+# SYNOPSIS
+**umoci tag**
+[*option*]...
+
+# DESCRIPTION
+
+## TODO
+
+# OPTIONS
+
+## TODO
+
+# SEE ALSO
+**umoci**(1)
Oops, something went wrong.

0 comments on commit 44f2904

Please sign in to comment.