Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal: Group available commands in the command line help text into "general", "image centric" and "container centric" #8756

Closed
samuell opened this Issue Oct 24, 2014 · 17 comments

Comments

Projects
None yet
8 participants
@samuell
Copy link

commented Oct 24, 2014

Newbie here, who had a hard time "getting" how to work with docker, until I realized there are 2-3 categories of commands available to the docker command: General commands, image centric ones, and container centric ones (and I had to look up the difference between the last two as well).

Currently, all the commands are mixed together in a long and thus comparably unreadable list:

[18:35:21] ~ $ docker
Usage: docker [OPTIONS] COMMAND [arg...]
 -H=[unix:///var/run/docker.sock]: tcp://host:port to bind/connect to or unix://path/to/socket to use

A self-sufficient runtime for linux containers.

Commands:
    attach    Attach to a running container
    build     Build an image from a Dockerfile
    commit    Create a new image from a container's changes
    cp        Copy files/folders from the containers filesystem to the host path
    diff      Inspect changes on a container's filesystem
    events    Get real time events from the server
    export    Stream the contents of a container as a tar archive
    history   Show the history of an image
    images    List images
    import    Create a new filesystem image from the contents of a tarball
    info      Display system-wide information
    inspect   Return low-level information on a container
    kill      Kill a running container
    load      Load an image from a tar archive
    login     Register or Login to the docker registry server
    logs      Fetch the logs of a container
    port      Lookup the public-facing port which is NAT-ed to PRIVATE_PORT
    pause     Pause all processes within a container
    ps        List containers
    pull      Pull an image or a repository from the docker registry server
    push      Push an image or a repository to the docker registry server
    restart   Restart a running container
    rm        Remove one or more containers
    rmi       Remove one or more images
    run       Run a command in a new container
    save      Save an image to a tar archive
    search    Search for an image in the docker index
    start     Start a stopped container
    stop      Stop a running container
    tag       Tag an image into a repository
    top       Lookup the running processes of a container
    unpause   Unpause a paused container
    version   Show the docker version information
    wait      Block until a container stops, then print its exit code

I think, grouping them into the categories methined above ("general", "image centric" and "container centric") would go a very long way in making this list less confusing, and to highlight the difference between images and containers, from the start, to help new users note the difference.

So, what about grouping them something like this (Not sure I've classified the commands 100% correctly, so correct me on that):

[18:35:21] ~ $ docker
Usage: docker [OPTIONS] COMMAND [arg...]
 -H=[unix:///var/run/docker.sock]: tcp://host:port to bind/connect to or unix://path/to/socket to use

A self-sufficient runtime for linux containers.

General commands:
    events    Get real time events from the server
    info      Display system-wide information
    login     Register or Login to the docker registry server
    version   Show the docker version information

Commands for working with images:
    build     Build an image from a Dockerfile
    history   Show the history of an image
    images    List images
    import    Create a new filesystem image from the contents of a tarball
    load      Load an image from a tar archive
    pull      Pull an image or a repository from the docker registry server
    push      Push an image or a repository to the docker registry server
    rmi       Remove one or more images
    save      Save an image to a tar archive
    search    Search for an image in the docker index
    tag       Tag an image into a repository

Commands for working with containers (running instances of images):
    attach    Attach to a running container
    commit    Create a new image from a container's changes
    diff      Inspect changes on a container's filesystem
    cp        Copy files/folders from the containers filesystem to the host path
    export    Stream the contents of a container as a tar archive
    inspect   Return low-level information on a container
    kill      Kill a running container
    logs      Fetch the logs of a container
    port      Lookup the public-facing port which is NAT-ed to PRIVATE_PORT
    pause     Pause all processes within a container
    ps        List containers
    ps -a     List all containers (including stopped ones)
    restart   Restart a running container
    rm        Remove one or more containers
    run       Run a command in a new container
    start     Start a stopped container
    stop      Stop a running container
    top       Lookup the running processes of a container
    unpause   Unpause a paused container
    wait      Block until a container stops, then print its exit code

(I also added ps -a here, since it was such a crucial revelation for me when I realized that is what I need in order to see containers that I had just ran, but suddently couldn't find)

Wadda'ya think?

@samuell samuell changed the title Group available commands in the command line help text into groups Group available commands in the command line help text into "general", "image centric" and "container centric" Oct 24, 2014

@jamtur01

This comment has been minimized.

Copy link
Contributor

commented Oct 24, 2014

@jamtur01

This comment has been minimized.

Copy link
Contributor

commented Oct 24, 2014

The list doth groweth I guess. Not sure this is the right demarcation but some demarcation might be needed.

@samuell

This comment has been minimized.

Copy link
Author

commented Oct 24, 2014

@jamtur01 Exactly. I'm sure someone more used to working with docker can improve or come up with something much better than this, but already making this categorization in my head, already goes a long way, for me :)

@fredlf

This comment has been minimized.

Copy link
Contributor

commented Oct 24, 2014

I think this is an excellent first step. I'm sure we can come up with a more refined taxonomy over time, but I see no reason not to start with this basic division. Thanks for the suggestion.

Don't forget to capitalize Docker.

@SvenDowideit

This comment has been minimized.

Copy link
Contributor

commented Oct 27, 2014

don't look at me - I find alphabetical order easier to scan than subject style groupings that don't apply to whatever i'm trying to do at the time. :)

@SvenDowideit SvenDowideit changed the title Group available commands in the command line help text into "general", "image centric" and "container centric" Proposal: Group available commands in the command line help text into "general", "image centric" and "container centric" Oct 27, 2014

@fredlf

This comment has been minimized.

Copy link
Contributor

commented Oct 27, 2014

Maybe the difference is that @sven is an experienced user, so he knows what he is looking for. I think the groupings might make things easier for new users. As a noob myself, I have sympathy for this approach!

@SvenDowideit

This comment has been minimized.

Copy link
Contributor

commented Oct 28, 2014

@fredlf no maybe about it - thats what I was indicating - not everyone does it the same way.

I'm a little worried that this kind of grouping hasn't worked well for me in other tools - for eg, tar --help also spews out a non-alpha list of options grouped by one mind-set - and the options I want are almost never in the gorup i'm expecting them to be in (because my need is often different from that set).

Alpha-order is also a terrible match for all task oriented grouping....

(and thus don't look at me - which also means - do it :) , i'm not the target audience you're looking for)

Sorry, what an awesfully round about way of saying +0.98

@fredlf

This comment has been minimized.

Copy link
Contributor

commented Oct 31, 2014

It occurs to me that there's no reason we can't have both alphabetical and grouped. I'd think you'd want the grouped list first, for the less experienced users who will visit the page the most, with the alpha-list below. Back-to-top links would be a nice touch too. Thoughts, @SvenDowideit @jamtur01 @samuell ?

@thaJeztah

This comment has been minimized.

Copy link
Member

commented Oct 31, 2014

I think the basic problem is that the list is just becoming too long and for some commands it is unclear what they apply to. I can relate to both "points of view". @fredlf I think you're talking about the website, not the CLI help?

Couple of additional issues I see;

"Export/Import" and "Save/Load"

I've seen some issues reported on the issue tracker, because it was unclear that, for example, save and import are incompatible. Both the alphabetical presentation and the grouped presentation will not fix this problem. (Same problem applied to the docs on the website)

Perhaps change the wording a bit (happy to provide a separate PR);

import    Create a new filesystem image from the contents of a tarball
          created with the * export * command
load      Load an image from a tar archive created with the * save * command

"Options"

I think that most, if not all, options (except for -v / --version) "Options" only apply to the daemon (-d / --daemon) and basically are "sub flags" for this flag.

Making daemon a command in stead is beyond scope (see #6055), but the daemon flags could be put in a separate group:

Options:
    -d, --daemon=false             Start docker in daemon mode
    -v, --version=false            Print version information and quit

Daemon (-d / --daemon) options:

    These options can only be used when starting
    docker as daemon (-d / --daemon=true)

    --api-enable-cors=false        Enable CORS headers in the remote API
    -b, --bridge=""                Attach containers to a pre-existing network bridge
                                   use 'none' to disable container networking
# etc
@fredlf

This comment has been minimized.

Copy link
Contributor

commented Oct 31, 2014

@thaJeztah I'm talking about both help and web docs. I think the downsides of two versions of the list are few, as long as it is presented very clearly.

@thaJeztah

This comment has been minimized.

Copy link
Member

commented Oct 31, 2014

@fredlf sorry, was confused because of the "back to top" links; anyway; I do like the idea as long as it's easy to use :)

@SvenDowideit

This comment has been minimized.

Copy link
Contributor

commented Nov 3, 2014

I think we should separate the discussion of the cli help output (which this PR and #8594) are about from rearranging the online help.

I presonally prefer cli help to be only one screen long - so wouldn't find duplicated lists helpful - but I do think @samuell and @errordeveloper are right - for those that most need it, alphabetical order is least useful.

If I were you, I'd make a PR :)

@SvenDowideit

This comment has been minimized.

Copy link
Contributor

commented Nov 3, 2014

I do like #8829.

@errordeveloper

This comment has been minimized.

Copy link
Contributor

commented Nov 3, 2014

Great to hear I'm not the only one thinking this! Would be amazing if some of the additional sections I had in #8594 could be incorporated here, I think those make a big difference.

@errordeveloper

This comment has been minimized.

Copy link
Contributor

commented Nov 3, 2014

I think there at least 5 distinct concerns:

  • Container state management: wait/unpause/start/stop/save/kill/run
  • Basic local container image data management: save/load/rm
  • Container inspection tools: top/diff/logs/inspect/port/ps
  • Management of locally stored images: export/import/images/history/rmi
  • Interaction with the registry: commit/push/pull/login/logout
@icecrime

This comment has been minimized.

Copy link
Contributor

commented Sep 10, 2016

You're going to love #26025 (cc @dnephin)!

@errordeveloper

This comment has been minimized.

Copy link
Contributor

commented Sep 10, 2016

Excellent!

On Sat, 10 Sep 2016, 02:05 Arnaud Porterie, notifications@github.com
wrote:

You're going to love #26025 #26025
(cc @dnephin https://github.com/dnephin)!


You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#8756 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAPWS2FTFOjvf_QxmAiws4XM6ZgXIYUXks5qogJfgaJpZM4CyvGH
.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.