From cdcea98290e01a90fa4ebfbd4528b3dfd890d1d6 Mon Sep 17 00:00:00 2001
From: Ben Firshman <ben@firshman.co.uk>
Date: Thu, 16 Jan 2014 13:17:00 +0000
Subject: [PATCH] Copy readme commands docs to CLI docstrings

---
 README.md       |  6 ++++--
 fig/cli/main.py | 35 +++++++++++++++++++++++++++++------
 2 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 2f9599a8b..9499fc86c 100644
--- a/README.md
+++ b/README.md
@@ -212,7 +212,7 @@ View output from services.
 
 #### ps
 
-List running containers.
+List containers.
 
 #### rm
 
@@ -221,7 +221,9 @@ Remove stopped service containers.
 
 #### run
 
-Run a one-off command for a service. E.g.:
+Run a one-off command on a service.
+
+For example:
 
     $ fig run web python manage.py shell
 
diff --git a/fig/cli/main.py b/fig/cli/main.py
index 51c4d27fb..b7a84fa3d 100644
--- a/fig/cli/main.py
+++ b/fig/cli/main.py
@@ -95,13 +95,17 @@ class TopLevelCommand(Command):
         """
         Build or rebuild services.
 
+        Services are built once and then tagged as `project_service`,
+        e.g. `figtest_db`. If you change a service's `Dockerfile` or the
+        contents of its build directory, you can run `fig build` to rebuild it.
+
         Usage: build [SERVICE...]
         """
         self.project.build(service_names=options['SERVICE'])
 
     def kill(self, options):
         """
-        Kill containers.
+        Force stop service containers.
 
         Usage: kill [SERVICE...]
         """
@@ -150,7 +154,7 @@ class TopLevelCommand(Command):
 
     def rm(self, options):
         """
-        Remove stopped containers
+        Remove stopped service containers.
 
         Usage: rm [SERVICE...]
         """
@@ -166,7 +170,15 @@ class TopLevelCommand(Command):
 
     def run(self, options):
         """
-        Run a one-off command.
+        Run a one-off command on a service.
+
+        For example:
+
+            $ fig run web python manage.py shell
+
+        Note that this will not start any services that the command's service
+        links to. So if, for example, your one-off command talks to your
+        database, you will need to run `fig up -d db` first.
 
         Usage: run [options] SERVICE COMMAND [ARGS...]
 
@@ -203,7 +215,9 @@ class TopLevelCommand(Command):
 
     def stop(self, options):
         """
-        Stop running containers.
+        Stop running containers without removing them.
+
+        They can be started again with `fig start`.
 
         Usage: stop [SERVICE...]
         """
@@ -211,12 +225,21 @@ class TopLevelCommand(Command):
 
     def up(self, options):
         """
-        Create and start containers.
+        Build, (re)create, start and attach to containers for a service.
+
+        By default, `fig up` will aggregate the output of each container, and
+        when it exits, all containers will be stopped. If you run `fig up -d`,
+        it'll start the containers in the background and leave them running.
+
+        If there are existing containers for a service, `fig up` will stop
+        and recreate them (preserving mounted volumes with volumes-from),
+        so that changes in `fig.yml` are picked up.
 
         Usage: up [options] [SERVICE...]
 
         Options:
-            -d    Detached mode: Run containers in the background, print new container names
+            -d    Detached mode: Run containers in the background, print new
+                  container names
         """
         detached = options['-d']