From df5110dfd545462d52e09532116111abe0b934d0 Mon Sep 17 00:00:00 2001
From: Daniel J Walsh <dwalsh@redhat.com>
Date: Fri, 6 Oct 2017 18:06:29 +0000
Subject: [PATCH] Add documentation on kpod attach

Add a man page on how to achieve the same user experience as using
kpod attach by using either the kpod logs or kpod exec commands.
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
---
 README.md             |  1 +
 docs/kpod-attach.1.md | 31 +++++++++++++++++++++++++++++++
 docs/kpod-cp.1.md     |  2 +-
 transfer.md           |  6 ++++--
 4 files changed, 37 insertions(+), 3 deletions(-)
 create mode 100644 docs/kpod-attach.1.md

diff --git a/README.md b/README.md
index 48390728..7460b5fb 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,7 @@ It is currently in active development in the Kubernetes community through the [d
 | ---------------------------------------------------- | --------------------------------------------------------------------------|-----|
 | [crio(8)](/docs/crio.8.md)                           | OCI Kubernetes Container Runtime daemon                                   ||
 | [kpod(1)](/docs/kpod.1.md)                           | Simple management tool for pods and images                                ||
+| [kpod-attach(1)](/docs/kpod-attach.1.md)             | Instead of providing a `kpod attach` command, the man page `kpod-attach` describes how to use the `kpod logs` and `kpod exec` commands to achieve the same goals as `kpod attach`.||
 | [kpod-cp(1)](/docs/kpod-cp.1.md)                     | Instead of providing a `kpod cp` command, the man page `kpod-cp` describes how to use the `kpod mount` command to have even more flexibility and functionality.||
 | [kpod-diff(1)](/docs/kpod-diff.1.md)                 | Inspect changes on a container or image's filesystem                      ||
 | [kpod-export(1)](/docs/kpod-export.1.md)             | Export container's filesystem contents as a tar archive                   ||
diff --git a/docs/kpod-attach.1.md b/docs/kpod-attach.1.md
new file mode 100644
index 00000000..4c2a0218
--- /dev/null
+++ b/docs/kpod-attach.1.md
@@ -0,0 +1,31 @@
+% kpod(1) kpod-attach - See the output of pid 1 of a container or enter the container
+% Dan Walsh
+# kpod-attach "1" "September 2017" "kpod"
+
+## NAME
+kpod-attach - Attach to a running container
+
+## Description
+
+We chose not to implement the `attach` feature in `kpod` even though the upstream Docker
+project has it. The upstream project has had lots of issues with attaching to running
+processes that we did not want to replicate. The `kpod exec` and `kpod log` commands
+offer you the same functionality far more dependably.
+
+**Reasons to attach to the primary PID of a container:**
+
+
+1) Executing commands inside of the container
+
+  We recommend that you use `kpod exec` to execute a command within a container
+
+  `kpod exec CONTAINERID /bin/sh`
+
+2) Viewing the output stream of the primary process in the container
+
+  We recommend that you use `kpod logs` to see the output from the container
+
+  `kpod logs CONTAINERID`
+
+## SEE ALSO
+kpod(1), kpod-exec(1), kpod-logs(1)
diff --git a/docs/kpod-cp.1.md b/docs/kpod-cp.1.md
index 3f3e1ca1..eea48e6c 100644
--- a/docs/kpod-cp.1.md
+++ b/docs/kpod-cp.1.md
@@ -6,7 +6,7 @@
 kpod-cp - Copy files/folders between a container and the local filesystem.
 
 ## Description
-We chose not to implement this feature in kpod even though the upstream docker
+We chose not to implement the `cp` feature in `kpod` even though the upstream Docker
 project has it. We have a much stronger capability.  Using standard kpod-mount
 and kpod-umount, we can take advantage of the entire linux tool chain, rather
 then just cp.
diff --git a/transfer.md b/transfer.md
index b6d23b47..670720b8 100644
--- a/transfer.md
+++ b/transfer.md
@@ -39,8 +39,9 @@ There are other equivalents for these tools
 
 | Existing Step | CRI-O (and friends) |
 | :---: | :---: |
+| `docker attach` | [`kpod exec`](./docs/kpod-attach.1.md) ***|
 | `docker build`  | [`buildah bud`](https://github.com/projectatomic/buildah/blob/master/docs/buildah-bud.md) |
-| `docker cp`     | [`kpod mount`](./docs/kpod-cp.1.md) ***   |
+| `docker cp`     | [`kpod mount`](./docs/kpod-cp.1.md) ****   |
 | `docker diff`   | [`kpod diff`](./docs/kpod-diff.1.md)      |
 | `docker export` | [`kpod export`](./docs/kpod-export.1.md)  |
 | `docker history`| [`kpod history`](./docs/kpod-history.1.md)|
@@ -61,4 +62,5 @@ There are other equivalents for these tools
 | `docker version`| [`kpod version`](./docs/kpod-version.1.md)|
 | `docker wait`   | [`kpod wait`](./docs/kpod-wait.1.md)|
 
-*** Use mount to take advantage of the entire linux tool chain rather then just cp.  Read [`here`](./docs/kpod-cp.1.md) for more information.
+*** Use `kpod exec` to enter a container and `kpod logs` to view the output of pid 1 of a container.
+**** Use mount to take advantage of the entire linux tool chain rather then just cp.  Read [`here`](./docs/kpod-cp.1.md) for more information.