Merge pull request #11697 from pdxdan/7447-GID-Doc

Updated Dockerfile and docker-run documentation for USER commands

docs/man/Dockerfile.5.md

@@ -273,8 +273,15 @@ A Dockerfile is similar to a Makefile.
 
 **USER**
   -- `USER daemon`
-  The **USER** instruction sets the username or UID that is used when running the
-  image.
+  Sets the username or UID used for running subsequent commands.
+
+  The **USER** instruction can optionally be used to set the group or GID. The
+  followings examples are all valid:
+  USER [user | user:group | uid | uid:gid | user:gid | uid:group ]
+
+  Until the **USER** instruction is set, instructions will be run as root. The USER
+  instruction can be used any number of times in a Dockerfile, and will only affect
+  subsequent commands.
 
 **WRKDIR**
   -- `WORKDIR /path/to/workdir`

docs/man/docker-run.1.md

@@ -341,7 +341,12 @@ The **-t** option is incompatible with a redirection of the docker client
 standard input.
 
 **-u**, **--user**=""
-   Username or UID
+   Sets the username or UID used and optionally the groupname or GID for the specified command.
+
+   The followings examples are all valid:
+   --user [user | user:group | uid | uid:gid | user:gid | uid:group ]
+
+   Without this argument the command will be run as root in the container.
 
 **-v**, **--volume**=[]
    Bind mount a volume (e.g., from the host: -v /host:/container, from Docker: -v /container)