docker/cli

mirror of https://github.com/docker/cli.git synced 2025-08-27 13:42:00 +03:00

Files

Sebastiaan van Stijn 80b1285fec cli: use custom annotation for aliases

Cobra allows for aliases to be defined for a command, but only allows these
to be defined at the same level (for example, `docker image ls` as alias for
`docker image list`). Our CLI has some commands that are available both as a
top-level shorthand as well as `docker <object> <verb>` subcommands. For example,
`docker ps` is a shorthand for `docker container ps` / `docker container ls`.

This patch introduces a custom "aliases" annotation that can be used to print
all available aliases for a command. While this requires these aliases to be
defined manually, in practice the list of aliases rarely changes, so maintenance
should be minimal.

As a convention, we could consider the first command in this list to be the
canonical command, so that we can use this information to add redirects in
our documentation in future.

Before this patch:

    docker images --help

    Usage:  docker images [OPTIONS] [REPOSITORY[:TAG]]

    List images

    Options:
      -a, --all             Show all images (default hides intermediate images)
      ...

With this patch:

    docker images --help

    Usage:  docker images [OPTIONS] [REPOSITORY[:TAG]]

    List images

    Aliases:
      docker image ls, docker image list, docker images

    Options:
      -a, --all             Show all images (default hides intermediate images)
      ...

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

2022-06-28 17:32:09 +02:00

2.7 KiB

Raw Blame History

title, description, keywords

title	description	keywords
import	The import command description and usage	import, file, system, container

import

Usage:  docker import [OPTIONS] file|URL|- [REPOSITORY[:TAG]]

Import the contents from a tarball to create a filesystem image

Aliases:
  docker image import, docker import

Options:
  -c, --change value     Apply Dockerfile instruction to the created image (default [])
      --help             Print usage
  -m, --message string   Set commit message for imported image
      --platform string  Set platform if server is multi-platform capable

Description

You can specify a URL or - (dash) to take data directly from STDIN. The URL can point to an archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz) containing a filesystem or to an individual file on the Docker host. If you specify an archive, Docker untars it in the container relative to the / (root). If you specify an individual file, you must specify the full path within the host. To import from a remote location, specify a URI that begins with the http:// or https:// protocol.

Examples

Import from a remote location

This creates a new untagged image.

$ docker import https://example.com/exampleimage.tgz

Import from a local file

Import to docker via pipe and STDIN.

$ cat exampleimage.tgz | docker import - exampleimagelocal:new

Import with a commit message.

$ cat exampleimage.tgz | docker import --message "New image imported from tarball" - exampleimagelocal:new

Import to docker from a local archive.

$ docker import /path/to/exampleimage.tgz

Import from a local directory

$ sudo tar -c . | docker import - exampleimagedir

Import from a local directory with new configurations

$ sudo tar -c . | docker import --change "ENV DEBUG=true" - exampleimagedir

Note the sudo in this example – you must preserve the ownership of the files (especially root ownership) during the archiving with tar. If you are not root (or the sudo command) when you tar, then the ownerships might not get preserved.

When the daemon supports multiple operating systems

If the daemon supports multiple operating systems, and the image being imported does not match the default operating system, it may be necessary to add --platform. This would be necessary when importing a Linux image into a Windows daemon.

$ docker import --platform=linux .\linuximage.tar

2.7 KiB Raw Blame History Unescape Escape