From 10327e09c54696dec36f478c454623f3daeb02d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Harry=20M=C3=ADchal?= Date: Tue, 3 Mar 2020 20:47:26 +0100 Subject: [PATCH] Update documentation The 'reset' command has been dropped (command 'podman system reset' should have the same effect now), so the man page has also been dropped. The whole documentation was slightly updated to match the current behaviour of Toolbox. I'm not entirely satsified with the state our documentation is in, so some more changes will certainly follow. --- doc/toolbox-create.1.md | 31 ++++--------------------------- doc/toolbox-enter.1.md | 15 ++++----------- doc/toolbox-help.1.md | 13 +++++-------- doc/toolbox-list.1.md | 2 +- doc/toolbox-reset.1.md | 26 -------------------------- doc/toolbox-rm.1.md | 6 +++--- doc/toolbox-rmi.1.md | 2 +- doc/toolbox-run.1.md | 19 ++++++++++--------- doc/toolbox.1.md | 11 +++++++---- 9 files changed, 35 insertions(+), 90 deletions(-) delete mode 100644 doc/toolbox-reset.1.md diff --git a/doc/toolbox-create.1.md b/doc/toolbox-create.1.md index ef53802a6..ef81fdaf7 100644 --- a/doc/toolbox-create.1.md +++ b/doc/toolbox-create.1.md @@ -4,10 +4,7 @@ toolbox\-create - Create a new toolbox container ## SYNOPSIS -**toolbox create** [*--candidate-registry*] - [*--container NAME* | *-c NAME*] - [*--image NAME* | *-i NAME*] - [*--release RELEASE* | *-r RELEASE*] +**toolbox create** [*options*] *CONTAINER* ## DESCRIPTION @@ -16,31 +13,16 @@ to interact with the container at any point. A toolbox container is an OCI container created from an OCI image. On Fedora the base image is known as `fedora-toolbox`. If the image is not present -locally, then it is pulled from `registry.fedoraproject.org`. The base image is -locally customized for the current user to create a second image, from which -the container is finally created. +locally, then it is pulled from `registry.fedoraproject.org`. Toolbox containers and images are tagged with the version of the OS that corresponds to the content inside them. The user-specific images and the -toolbox containers are prefixed with the name of the base image and suffixed -with the current user name. +toolbox containers are prefixed with the name of the base image. ## OPTIONS ## The following options are understood: -**--candidate-registry** - -Pull the base image from `candidate-registry.fedoraproject.org`. This is -useful for testing newly built images before they have moved to the stable -registry at `registry.fedoraproject.org`. - -**--container** NAME, **-c** NAME - -Assign a different NAME to the toolbox container. This is useful for creating -multiple toolbox containers from the same base image, or for entirely -customized containers from custom-built base images. - **--image** NAME, **-i** NAME Change the NAME of the base image used to create the toolbox container. This @@ -68,14 +50,9 @@ $ toolbox create --release f30 ### Create a custom toolbox container from a custom image ``` -$ toolbox create --container foo --image bar +$ toolbox create foo --image bar ``` -### Create a toolbox using images from the unstable candidate registry - -``` -$ toolbox create --candidate-registry -``` ## SEE ALSO diff --git a/doc/toolbox-enter.1.md b/doc/toolbox-enter.1.md index e2c63e043..64423113d 100644 --- a/doc/toolbox-enter.1.md +++ b/doc/toolbox-enter.1.md @@ -4,8 +4,7 @@ toolbox\-enter - Enter a toolbox container for interactive use ## SYNOPSIS -**toolbox enter** [*--container NAME* | *-c NAME*] - [*--release RELEASE* | *-r RELEASE*] +**toolbox enter** [*options*] *CONTAINER* ## DESCRIPTION @@ -20,18 +19,12 @@ analogous to a `podman start` followed by a `podman exec`. On Fedora the toolbox containers are tagged with the version of the OS that corresponds to the content inside them. Their names are prefixed with the name -of the base image and suffixed with the current user name. +of the base image. ## OPTIONS ## The following options are understood: -**--container** NAME, **-c** NAME - -Enter a toolbox container with the given NAME. This is useful when there are -multiple toolbox containers created from the same base image, or entirely -customized containers created from custom-built base images. - **--release** RELEASE, **-r** RELEASE Enter a toolbox container for a different operating system RELEASE than the @@ -51,10 +44,10 @@ $ toolbox enter $ toolbox enter --release f30 ``` -### Enter a custom toolbox container using a custom image +### Enter a custom toolbox container using a custom name ``` -$ toolbox enter --container foo +$ toolbox enter foo ``` ## SEE ALSO diff --git a/doc/toolbox-help.1.md b/doc/toolbox-help.1.md index 684221f94..6a5e93ef8 100644 --- a/doc/toolbox-help.1.md +++ b/doc/toolbox-help.1.md @@ -8,23 +8,20 @@ toolbox\-help - Display help information about Toolbox ## DESCRIPTION -When no COMMAND is specified, the `toolbox(1)` manual is shown. If a COMMAND -is specified, a manual page for that command is brought up. +When no COMMAND is specified, the basic usage screen is shown. If a COMMAND +is specified, a usage screen for that command is shown. -Note that `toolbox --help ...` is identical to `toolbox help ...` because the -former is internally converted to the latter. - -This page can be displayed with `toolbox help help` or `toolbox help --help`. +Note that `toolbox --help ...` is identical to `toolbox help ...`. ## EXAMPLES -### Show the toolbox manual +### Show the basic usage screen of Toolbox ``` $ toolbox help ``` -### Show the manual for the create command +### Show the usage screen of the create command ``` $ toolbox help create diff --git a/doc/toolbox-list.1.md b/doc/toolbox-list.1.md index 2c2a35526..358176c0d 100644 --- a/doc/toolbox-list.1.md +++ b/doc/toolbox-list.1.md @@ -4,7 +4,7 @@ toolbox\-list - List existing toolbox containers and images ## SYNOPSIS -**toolbox list** [*--containers* | *-c*] [*--images* | *-i*] +**toolbox list** [*options*] ## DESCRIPTION diff --git a/doc/toolbox-reset.1.md b/doc/toolbox-reset.1.md deleted file mode 100644 index d90a0bfaa..000000000 --- a/doc/toolbox-reset.1.md +++ /dev/null @@ -1,26 +0,0 @@ -% toolbox-reset(1) - -## NAME -toolbox\-reset - Remove all local podman (and toolbox) state - -## SYNOPSIS -**toolbox reset** - -## DESCRIPTION - -Removes all existing podman (and toolbox) containers, images and configuration. -This can be used to factory reset your local Podman and Toolbox installations -when something has gone irrecoverably wrong with the `podman(1)` and -`toolbox(1)` commands. - -This command can only be used on the host, and not from within a toolbox -container, and is only expected to be used right after a fresh boot before any -other `podman(1)` or `toolbox(1)` commands have been invoked. - -## EXAMPLES - -### Reset a broken Podman and Toolbox installation - -``` -$ toolbox reset -``` diff --git a/doc/toolbox-rm.1.md b/doc/toolbox-rm.1.md index df98c403e..690b7f0f7 100644 --- a/doc/toolbox-rm.1.md +++ b/doc/toolbox-rm.1.md @@ -4,7 +4,7 @@ toolbox\-rm - Remove one or more toolbox containers ## SYNOPSIS -**toolbox rm** [*--all*] [*--force*] [*CONTAINER*...] +**toolbox rm** [*options*] [*CONTAINER*...] ## DESCRIPTION @@ -29,10 +29,10 @@ Force the removal of running and paused toolbox containers. ## EXAMPLES -### Remove a toolbox container named `fedora-toolbox-gegl:30` +### Remove a toolbox container named `fedora-toolbox-gegl-30` ``` -$ toolbox rm fedora-toolbox-gegl:30 +$ toolbox rm fedora-toolbox-gegl-30 ``` ### Remove all toolbox containers, but not those that are running or paused diff --git a/doc/toolbox-rmi.1.md b/doc/toolbox-rmi.1.md index 25113e929..25f095f34 100644 --- a/doc/toolbox-rmi.1.md +++ b/doc/toolbox-rmi.1.md @@ -4,7 +4,7 @@ toolbox\-rmi - Remove one or more toolbox images ## SYNOPSIS -**toolbox rmi** [*--all*] [*--force*] [*IMAGE*...] +**toolbox rmi** [*options*] [*IMAGE*...] ## DESCRIPTION diff --git a/doc/toolbox-run.1.md b/doc/toolbox-run.1.md index 4786e8fe8..4c63d0657 100644 --- a/doc/toolbox-run.1.md +++ b/doc/toolbox-run.1.md @@ -4,30 +4,31 @@ toolbox\-run - Run a command in an existing toolbox container ## SYNOPSIS -**toolbox run** [*--container NAME* | *-c NAME*] - [*--release RELEASE* | *-r RELEASE*] [*COMMAND*] +**toolbox run** [*options*] *CONTAINER* [*COMMAND* [*args* ...]] ## DESCRIPTION Runs a command inside an existing toolbox container. The container should have been created using the `toolbox create` command. +If the **--release | -r** option is specified, then the CONTAINER does not have +to be specified. + A toolbox container is an OCI container. Therefore, `toolbox run` is analogous to a `podman start` followed by a `podman exec`. On Fedora the toolbox containers are tagged with the version of the OS that corresponds to the content inside them. Their names are prefixed with the name -of the base image and suffixed with the current user name. +of the base image. ## OPTIONS ## The following options are understood: -**--container** NAME, **-c** NAME +**--default**, **-d** -Run command inside a toolbox container with the given NAME. This is useful -when there are multiple toolbox containers created from the same base image, -or entirely customized containers created from custom-built base images. +Run command inside a toolbox container using the default image matching the +host OS. **--release** RELEASE, **-r** RELEASE @@ -39,7 +40,7 @@ RELEASE than the host. ### Run ls inside a toolbox container using the default image matching the host OS ``` -$ toolbox run ls -la +$ toolbox run -d ls -la ``` ### Run emacs inside a toolbox container using the default image for Fedora 30 @@ -51,7 +52,7 @@ $ toolbox run --release f30 emacs ### Run uptime inside a custom toolbox container using a custom image ``` -$ toolbox run --container foo uptime +$ toolbox run foo uptime ``` ## SEE ALSO diff --git a/doc/toolbox.1.md b/doc/toolbox.1.md index f534f66f8..68f108843 100644 --- a/doc/toolbox.1.md +++ b/doc/toolbox.1.md @@ -4,7 +4,7 @@ toolbox - Unprivileged development environment ## SYNOPSIS -**toolbox** [*--verbose* | *-v*] *COMMAND* [*ARGS*] +**toolbox** [options] *COMMAND* ## DESCRIPTION @@ -40,10 +40,13 @@ Automatically answer yes for all questions. Print a synopsis of this manual and exit. -**--verbose, -v** +**--log-level** -Print debug information including standard error stream of internal commands. -Use `-vv` for more detail. +Log messages above specified level: trace, debug, info, warn, error, fatal or panic (default "warn"). + +**--log-podman** + +Show the log output of Podman. The log level is handled by the log-level option. ## COMMANDS