diff --git a/contrib/completion/bash/docker b/contrib/completion/bash/docker
index f67ebebd66..f26ff80244 100644
--- a/contrib/completion/bash/docker
+++ b/contrib/completion/bash/docker
@@ -1832,6 +1832,21 @@ _docker_run() {
 			esac
 			return
 			;;
+		--pid)
+			case "$cur" in
+				*:*)
+					cur="${cur#*:}"
+					__docker_complete_containers_running
+					;;
+				*)
+					COMPREPLY=( $( compgen -W 'host container:' -- "$cur" ) )
+					if [ "$COMPREPLY" = "container:" ]; then
+						__docker_nospace
+					fi
+					;;
+			esac
+			return
+			;;
 		--security-opt)
 			COMPREPLY=( $( compgen -W "apparmor= label= no-new-privileges seccomp=" -- "$cur") )
 			if [ "${COMPREPLY[*]}" != "no-new-privileges" ] ; then
diff --git a/contrib/completion/zsh/_docker b/contrib/completion/zsh/_docker
index fa8befe975..5862768ff3 100644
--- a/contrib/completion/zsh/_docker
+++ b/contrib/completion/zsh/_docker
@@ -699,7 +699,7 @@ __docker_subcommand() {
         "($help)--pids-limit[Tune container pids limit (set -1 for unlimited)]"
         "($help -P --publish-all)"{-P,--publish-all}"[Publish all exposed ports]"
         "($help)*"{-p=,--publish=}"[Expose a container's port to the host]:port:_ports"
-        "($help)--pid=[PID namespace to use]:PID: "
+        "($help)--pid=[PID namespace to use]:PID namespace: "
         "($help)--privileged[Give extended privileges to this container]"
         "($help)--read-only[Mount the container's root filesystem as read only]"
         "($help)*--security-opt=[Security options]:security option: "
diff --git a/docs/reference/run.md b/docs/reference/run.md
index 942bba948f..190b9b7601 100644
--- a/docs/reference/run.md
+++ b/docs/reference/run.md
@@ -193,7 +193,8 @@ the digest value is predictable and referenceable.
 ## PID settings (--pid)
 
     --pid=""  : Set the PID (Process) Namespace mode for the container,
-           'host': use the host's PID namespace inside the container
+                 'container:<name|id>': joins another container's PID namespace
+                 'host': use the host's PID namespace inside the container
 
 By default, all containers have the PID namespace enabled.
 
@@ -229,6 +230,23 @@ Use the following command to run `htop` inside a container:
 $ docker run -it --rm --pid=host myhtop
 ```
 
+Joining another container's pid namespace can be used for debugging that container.
+
+### Example
+
+Start a container running a redis server:
+
+```bash
+$ docker run --name my-redis -d redis
+```
+
+Debug the redis container by running another container that has strace in it:
+
+```bash
+$ docker run --it --pid=container:my-redis bash
+$ strace -p 1
+```
+
 ## UTS settings (--uts)
 
     --uts=""  : Set the UTS namespace mode for the container,
diff --git a/man/docker-create.1.md b/man/docker-create.1.md
index f8a80cd347..d48e1ac3c4 100644
--- a/man/docker-create.1.md
+++ b/man/docker-create.1.md
@@ -57,7 +57,7 @@ docker-create - Create a new container
 [**--oom-score-adj**[=*0*]]
 [**-P**|**--publish-all**]
 [**-p**|**--publish**[=*[]*]]
-[**--pid**[=*[]*]]
+[**--pid**[=*[PID]*]]
 [**--userns**[=*[]*]]
 [**--pids-limit**[=*PIDS_LIMIT*]]
 [**--privileged**]
@@ -289,10 +289,11 @@ unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap.
                                When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. (e.g., `-p 1234-1236:1234-1236/tcp`)
                                (use 'docker port' to see the actual mapping)
 
-**--pid**=*host*
+**--pid**=""
    Set the PID mode for the container
-     **host**: use the host's PID namespace inside the container.
-     Note: the host mode gives the container full access to local PID and is therefore considered insecure.
+   Default is to create a private PID namespace for the container
+                               'container:<name|id>': join another container's PID namespace
+                               'host': use the host's PID namespace for the container. Note: the host mode gives the container full access to local PID and is therefore considered insecure.
 
 **--userns**=""
    Set the usernamespace mode for the container when `userns-remap` option is enabled.
diff --git a/man/docker-run.1.md b/man/docker-run.1.md
index 101acfa606..6de2f2d70e 100644
--- a/man/docker-run.1.md
+++ b/man/docker-run.1.md
@@ -59,7 +59,7 @@ docker-run - Run a command in a new container
 [**--oom-score-adj**[=*0*]]
 [**-P**|**--publish-all**]
 [**-p**|**--publish**[=*[]*]]
-[**--pid**[=*[]*]]
+[**--pid**[=*[PID]*]]
 [**--userns**[=*[]*]]
 [**--pids-limit**[=*PIDS_LIMIT*]]
 [**--privileged**]
@@ -420,10 +420,11 @@ but not `docker run -p 1230-1236:1230-1240 --name RangeContainerPortsBiggerThanR
 With ip: `docker run -p 127.0.0.1:$HOSTPORT:$CONTAINERPORT --name CONTAINER -t someimage`
 Use `docker port` to see the actual mapping: `docker port CONTAINER $CONTAINERPORT`
 
-**--pid**=*host*
+**--pid**=""
    Set the PID mode for the container
-     **host**: use the host's PID namespace inside the container.
-     Note: the host mode gives the container full access to local PID and is therefore considered insecure.
+   Default is to create a private PID namespace for the container
+                               'container:<name|id>': join another container's PID namespace
+                               'host': use the host's PID namespace for the container. Note: the host mode gives the container full access to local PID and is therefore considered insecure.
 
 **--userns**=""
    Set the usernamespace mode for the container when `userns-remap` option is enabled.