From ddfd8d3faff1267863acdac535a3b5fe15474173 Mon Sep 17 00:00:00 2001
From: Randy Fay <randy@randyfay.com>
Date: Wed, 27 May 2020 07:23:58 -0600
Subject: [PATCH] Improve examples and help in several commands (#2277)

---
 cmd/ddev/cmd/auth-pantheon.go           | 7 ++++---
 cmd/ddev/cmd/auth-ssh.go                | 7 ++++---
 cmd/ddev/cmd/auth.go                    | 2 ++
 cmd/ddev/cmd/composer-create.go         | 6 +++---
 cmd/ddev/cmd/composer.go                | 7 ++++---
 cmd/ddev/cmd/delete.go                  | 1 +
 cmd/ddev/cmd/describe.go                | 1 +
 cmd/ddev/cmd/exec.go                    | 1 +
 cmd/ddev/cmd/hostname.go                | 7 ++++---
 cmd/ddev/cmd/import-db.go               | 6 +++---
 cmd/ddev/cmd/import-files.go            | 5 +++--
 cmd/ddev/cmd/list.go                    | 1 +
 cmd/ddev/cmd/logs.go                    | 3 +++
 cmd/ddev/cmd/pull.go                    | 3 ++-
 cmd/ddev/cmd/restart.go                 | 3 +++
 cmd/ddev/cmd/sequelpro.go               | 7 ++++---
 cmd/ddev/cmd/snapshot.go                | 5 ++++-
 cmd/ddev/cmd/ssh.go                     | 9 ++++++---
 cmd/ddev/cmd/start.go                   | 3 +++
 docs/users/extend/customizing-images.md | 2 ++
 20 files changed, 58 insertions(+), 28 deletions(-)

diff --git a/cmd/ddev/cmd/auth-pantheon.go b/cmd/ddev/cmd/auth-pantheon.go
index 4452d65672a..f54152669a8 100644
--- a/cmd/ddev/cmd/auth-pantheon.go
+++ b/cmd/ddev/cmd/auth-pantheon.go
@@ -9,9 +9,10 @@ import (
 
 // PantheonAuthCommand is the `ddev auth pantheon` command
 var PantheonAuthCommand = &cobra.Command{
-	Use:   "pantheon [token]",
-	Short: "Provide a machine token for the global pantheon auth",
-	Long:  "Configure global machine token for pantheon authentication. See https://pantheon.io/docs/machine-tokens/ for instructions on creating a token.",
+	Use:     "pantheon [token]",
+	Short:   "Provide a machine token for the global pantheon auth",
+	Long:    "Configure global machine token for pantheon authentication. See https://pantheon.io/docs/machine-tokens/ for instructions on creating a token.",
+	Example: `ddev auth pantheon`,
 	Run: func(cmd *cobra.Command, args []string) {
 
 		if len(args) == 0 {
diff --git a/cmd/ddev/cmd/auth-ssh.go b/cmd/ddev/cmd/auth-ssh.go
index 24c4689bf6b..8cbb978ea19 100644
--- a/cmd/ddev/cmd/auth-ssh.go
+++ b/cmd/ddev/cmd/auth-ssh.go
@@ -17,9 +17,10 @@ var sshKeyPath string
 
 // AuthSSHCommand implements the "ddev auth ssh" command
 var AuthSSHCommand = &cobra.Command{
-	Use:   "ssh",
-	Short: "Add ssh key authentication to the ddev-ssh-auth container",
-	Long:  `Use this command to provide the password to your ssh key to the ddev-ssh-agent container, where it can be used by other containers. Normal usage is just "ddev auth ssh", or if your key is not in ~/.ssh, ddev auth ssh --keydir=/some/path/.ssh"`,
+	Use:     "ssh",
+	Short:   "Add ssh key authentication to the ddev-ssh-auth container",
+	Long:    `Use this command to provide the password to your ssh key to the ddev-ssh-agent container, where it can be used by other containers. Normal usage is just "ddev auth ssh", or if your key is not in ~/.ssh, ddev auth ssh --keydir=/some/path/.ssh"`,
+	Example: `ddev auth ssh`,
 	Run: func(cmd *cobra.Command, args []string) {
 		var err error
 		if len(args) > 0 {
diff --git a/cmd/ddev/cmd/auth.go b/cmd/ddev/cmd/auth.go
index 5eff096d8ae..2dd415a8538 100644
--- a/cmd/ddev/cmd/auth.go
+++ b/cmd/ddev/cmd/auth.go
@@ -9,6 +9,8 @@ import (
 var AuthCmd = &cobra.Command{
 	Use:   "auth [command]",
 	Short: "A collection of authentication commands",
+	Example: `ddev auth ssh
+ddev auth pantheon`,
 	Run: func(cmd *cobra.Command, args []string) {
 		err := cmd.Usage()
 		util.CheckErr(err)
diff --git a/cmd/ddev/cmd/composer-create.go b/cmd/ddev/cmd/composer-create.go
index ba2f5a4c23e..34ec6cbb607 100644
--- a/cmd/ddev/cmd/composer-create.go
+++ b/cmd/ddev/cmd/composer-create.go
@@ -28,9 +28,9 @@ var ComposerCreateCmd = &cobra.Command{
 web container. Projects will be installed to a temporary directory and moved to
 the project root directory after installation. Any existing files in the
 project root will be deleted when creating a project.`,
-	Example: `ddev composer create drupal-composer/drupal-project:8.x-dev --stability dev --no-interaction
-ddev composer create "typo3/cms-base-distribution:^9"
-ddev composer create drupal-composer/drupal-project:8.x-dev --stability dev --no-interaction --no-install
+	Example: `ddev composer create drupal/recommended-project
+ddev composer create "typo3/cms-base-distribution:^10"
+ddev composer create drupal/recommended-project --no-install
 ddev composer create --repository=https://repo.magento.com/ magento/project-community-edition`,
 	Run: func(cmd *cobra.Command, args []string) {
 
diff --git a/cmd/ddev/cmd/composer.go b/cmd/ddev/cmd/composer.go
index 6e2defe20a6..5f250ccd22c 100644
--- a/cmd/ddev/cmd/composer.go
+++ b/cmd/ddev/cmd/composer.go
@@ -13,10 +13,11 @@ var ComposerCmd = &cobra.Command{
 	Short: "Executes a composer command within the web container",
 	Long: `Executes a composer command at the project root in the web container. Generally,
 any composer command can be forwarded to the container context by prepending
-the command with 'ddev'. For example:
-
+the command with 'ddev'.`,
+	Example: `ddev composer install
 ddev composer require <package>
-ddev composer outdated --minor-only`,
+ddev composer outdated --minor-only
+ddev composer create drupal/recommended-project`,
 	Run: func(cmd *cobra.Command, args []string) {
 		app, err := ddevapp.GetActiveApp("")
 		if err != nil {
diff --git a/cmd/ddev/cmd/delete.go b/cmd/ddev/cmd/delete.go
index 2ac4f348bbe..a8a02225d0f 100644
--- a/cmd/ddev/cmd/delete.go
+++ b/cmd/ddev/cmd/delete.go
@@ -22,6 +22,7 @@ var DeleteCmd = &cobra.Command{
 ddev delete proj1 proj2 proj3
 ddev delete --omit-snapshot proj1
 ddev delete --omit-snapshot --yes proj1 proj2
+ddev delete -Oy
 ddev delete --all`,
 	Run: func(cmd *cobra.Command, args []string) {
 		if noConfirm && deleteAll {
diff --git a/cmd/ddev/cmd/describe.go b/cmd/ddev/cmd/describe.go
index e404de16b57..73c3d20f779 100644
--- a/cmd/ddev/cmd/describe.go
+++ b/cmd/ddev/cmd/describe.go
@@ -20,6 +20,7 @@ It also provides details for MySQL connections, and connection information for
 additional services like MailHog and phpMyAdmin. You can run 'ddev describe' from
 a project directory to describe that project, or you can specify a project to describe by
 running 'ddev describe <projectname>.`,
+	Example: "ddev describe\nddev describe <projectname>",
 	Run: func(cmd *cobra.Command, args []string) {
 		if len(args) > 1 {
 			util.Failed("Too many arguments provided. Please use 'ddev describe' or 'ddev describe [projectname]'")
diff --git a/cmd/ddev/cmd/exec.go b/cmd/ddev/cmd/exec.go
index 613520d77ce..00b746fb4f4 100644
--- a/cmd/ddev/cmd/exec.go
+++ b/cmd/ddev/cmd/exec.go
@@ -20,6 +20,7 @@ var DdevExecCmd = &cobra.Command{
 	Aliases: []string{"."},
 	Short:   "Execute a shell command in the container for a service. Uses the web service by default.",
 	Long:    `Execute a shell command in the container for a service. Uses the web service by default. To run your command in the container for another service, run "ddev exec --service <service> <cmd>"`,
+	Example: "ddev exec ls /var/www/html\nddev exec --service db\nddev exec -s db\nddev exec -s solr (assuming an add-on service named 'solr')",
 	Run: func(cmd *cobra.Command, args []string) {
 		if len(args) == 0 {
 			err := cmd.Usage()
diff --git a/cmd/ddev/cmd/hostname.go b/cmd/ddev/cmd/hostname.go
index e91ca1252e9..c98ab6eb3db 100644
--- a/cmd/ddev/cmd/hostname.go
+++ b/cmd/ddev/cmd/hostname.go
@@ -20,11 +20,12 @@ var removeInactive bool
 
 // HostNameCmd represents the hostname command
 var HostNameCmd = &cobra.Command{
-	Use:   "hostname [hostname] [ip]",
-	Short: "Manage your hostfile entries.",
+	Use:     "hostname [hostname] [ip]",
+	Example: "ddev hostname somesite.ddev.local 127.0.0.1",
+	Short:   "Manage your hostfile entries.",
 	Long: `Manage your hostfile entries. Managing host names has security and usability
 implications and requires elevated privileges. You may be asked for a password
-to allow ddev to modify your hosts file.`,
+to allow ddev to modify your hosts file. If you are connected to the internet and using the domain ddev.site this is generally not necessary, becauses the hosts file never gets manipulated.`,
 	Run: func(cmd *cobra.Command, args []string) {
 		hosts, err := goodhosts.NewHosts()
 		if err != nil {
diff --git a/cmd/ddev/cmd/import-db.go b/cmd/ddev/cmd/import-db.go
index b6b08779433..5e198549952 100644
--- a/cmd/ddev/cmd/import-db.go
+++ b/cmd/ddev/cmd/import-db.go
@@ -17,9 +17,9 @@ var progressOption bool
 var ImportDBCmd = &cobra.Command{
 	Use:   "import-db [project]",
 	Args:  cobra.RangeArgs(0, 1),
-	Short: "Import a sql archive into the project.",
-	Long: `Import a sql archive into the project.
-The database can be provided as a SQL dump in a .sql, .sql.gz, .mysql, .mysql.gz, .zip, .tgz, or .tar.gz
+	Short: "Import a sql file into the project.",
+	Long: `Import a sql file into the project.
+The database dump file can be provided as a SQL dump in a .sql, .sql.gz, .mysql, .mysql.gz, .zip, .tgz, or .tar.gz
 format. For the zip and tar formats, the path to a .sql file within the archive
 can be provided if it is not located at the top level of the archive. An optional target database
 can also be provided; the default is the default database named "db".
diff --git a/cmd/ddev/cmd/import-files.go b/cmd/ddev/cmd/import-files.go
index 65c027db13d..ec2fe33dcf1 100644
--- a/cmd/ddev/cmd/import-files.go
+++ b/cmd/ddev/cmd/import-files.go
@@ -16,8 +16,9 @@ var extPath string
 
 // ImportFileCmd represents the `ddev import-db` command.
 var ImportFileCmd = &cobra.Command{
-	Use:   "import-files",
-	Short: "Pull the uploaded files directory of an existing project to the default public upload directory of your project.",
+	Use:     "import-files",
+	Example: `ddev import-files --src=/path/to/files.tar.gz`,
+	Short:   "Pull the uploaded files directory of an existing project to the default public upload directory of your project.",
 	Long: `Pull the uploaded files directory of an existing project to the default
 public upload directory of your project. The files can be provided as a
 directory path or an archive in .tar, .tar.gz, .tgz, or .zip format. For the
diff --git a/cmd/ddev/cmd/list.go b/cmd/ddev/cmd/list.go
index d92cb9a0472..efa5186b0cf 100644
--- a/cmd/ddev/cmd/list.go
+++ b/cmd/ddev/cmd/list.go
@@ -24,6 +24,7 @@ var ListCmd = &cobra.Command{
 	Short: "List projects",
 	Long:  `List projects. Shows all projects by default, shows active projects only with --active-only`,
 	Example: `ddev list
+ddev list --active-only
 ddev list -A`,
 	Run: func(cmd *cobra.Command, args []string) {
 		for {
diff --git a/cmd/ddev/cmd/logs.go b/cmd/ddev/cmd/logs.go
index e8b510769cf..15342b7cf9a 100644
--- a/cmd/ddev/cmd/logs.go
+++ b/cmd/ddev/cmd/logs.go
@@ -19,6 +19,9 @@ var DdevLogsCmd = &cobra.Command{
 	Use:   "logs",
 	Short: "Get the logs from your running services.",
 	Long:  `Uses 'docker logs' to display stdout from the running services.`,
+	Example: `ddev logs
+ddev logs -f
+ddev logs -s db`,
 	Run: func(cmd *cobra.Command, args []string) {
 		app, err := ddevapp.GetActiveApp("")
 		if err != nil {
diff --git a/cmd/ddev/cmd/pull.go b/cmd/ddev/cmd/pull.go
index 7244a723496..585c13eea79 100644
--- a/cmd/ddev/cmd/pull.go
+++ b/cmd/ddev/cmd/pull.go
@@ -33,7 +33,8 @@ var PullCmd = &cobra.Command{
 	Long: `Pull files and database using a configured provider plugin.
 	Running pull will connect to the configured provider and download + import the
 	latest backups.`,
-	Args: cobra.ExactArgs(0),
+	Example: `ddev pull`,
+	Args:    cobra.ExactArgs(0),
 	PreRun: func(cmd *cobra.Command, args []string) {
 		dockerutil.EnsureDdevNetwork()
 	},
diff --git a/cmd/ddev/cmd/restart.go b/cmd/ddev/cmd/restart.go
index 7881f9dadb7..69a004d80fa 100644
--- a/cmd/ddev/cmd/restart.go
+++ b/cmd/ddev/cmd/restart.go
@@ -17,6 +17,9 @@ var RestartCmd = &cobra.Command{
 	Use:   "restart [projects]",
 	Short: "Restart a project or several projects.",
 	Long:  `Stops named projects and then starts them back up again.`,
+	Example: `ddev restart
+ddev restart <project1> <project2>
+ddev restart --all`,
 	PreRun: func(cmd *cobra.Command, args []string) {
 		dockerutil.EnsureDdevNetwork()
 	},
diff --git a/cmd/ddev/cmd/sequelpro.go b/cmd/ddev/cmd/sequelpro.go
index 0c40f4e2067..193948b7fe7 100644
--- a/cmd/ddev/cmd/sequelpro.go
+++ b/cmd/ddev/cmd/sequelpro.go
@@ -25,9 +25,10 @@ var SequelproLoc = "/Applications/Sequel Pro.app"
 
 // DdevSequelproCmd represents the sequelpro command
 var DdevSequelproCmd = &cobra.Command{
-	Use:   "sequelpro",
-	Short: "Connect sequelpro to a project database",
-	Long:  `A helper command for using sequelpro (macOS database browser) with a running DDEV-Local project's database'.`,
+	Use:     "sequelpro",
+	Short:   "Connect sequelpro to a project database",
+	Long:    `A helper command for using sequelpro (macOS database browser) with a running DDEV-Local project's database'.`,
+	Example: `ddev sequelpro`,
 	Run: func(cmd *cobra.Command, args []string) {
 		if len(args) != 0 {
 			output.UserOut.Fatalf("invalid arguments to sequelpro command: %v", args)
diff --git a/cmd/ddev/cmd/snapshot.go b/cmd/ddev/cmd/snapshot.go
index 9a86db9e8bd..becf86a6878 100644
--- a/cmd/ddev/cmd/snapshot.go
+++ b/cmd/ddev/cmd/snapshot.go
@@ -12,7 +12,10 @@ var snapshotName string
 var DdevSnapshotCommand = &cobra.Command{
 	Use:   "snapshot [projectname projectname...]",
 	Short: "Create a database snapshot for one or more projects.",
-	Long:  `Uses mariabackup command to create a database snapshot in the .ddev/db_snapshots folder.`,
+	Long:  `Uses mariabackup or xtrabackup command to create a database snapshot in the .ddev/db_snapshots folder. These are compatible with server backups using the same tools and can be restored with "ddev restore-snapshot".`,
+	Example: `ddev snapshot
+ddev snapshot --name some_descriptive_name
+ddev snapshot --all`,
 	Run: func(cmd *cobra.Command, args []string) {
 		apps, err := getRequestedProjects(args, snapshotAll)
 		if err != nil {
diff --git a/cmd/ddev/cmd/ssh.go b/cmd/ddev/cmd/ssh.go
index 0761cefdc9c..a2a6f7fe670 100644
--- a/cmd/ddev/cmd/ssh.go
+++ b/cmd/ddev/cmd/ssh.go
@@ -14,11 +14,14 @@ var sshDirArg string
 
 // DdevSSHCmd represents the ssh command.
 var DdevSSHCmd = &cobra.Command{
-	Use: "ssh [projectname]",
-
+	Use:   "ssh [projectname]",
 	Short: "Starts a shell session in the container for a service. Uses web service by default.",
 	Long:  `Starts a shell session in the container for a service. Uses web service by default. To start a shell session for another service, run "ddev ssh --service <service>`,
-	Args:  cobra.MaximumNArgs(1),
+	Example: `ddev ssh
+ddev ssh -s sb
+ddev ssh <projectname>
+ddev ssh -d /var/www/html`,
+	Args: cobra.MaximumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		projects, err := getRequestedProjects(args, false)
 		if err != nil {
diff --git a/cmd/ddev/cmd/start.go b/cmd/ddev/cmd/start.go
index 4d42501016f..0f834e22fc9 100644
--- a/cmd/ddev/cmd/start.go
+++ b/cmd/ddev/cmd/start.go
@@ -22,6 +22,9 @@ var StartCmd = &cobra.Command{
 to provide a local development environment. You can run 'ddev start' from a
 project directory to start that project, or you can start stopped projects in
 any directory by running 'ddev start projectname [projectname ...]'`,
+	Example: `ddev start
+ddev start <project1> <project2>
+ddev start --all`,
 	PreRun: func(cmd *cobra.Command, args []string) {
 		dockerutil.EnsureDdevNetwork()
 	},
diff --git a/docs/users/extend/customizing-images.md b/docs/users/extend/customizing-images.md
index 8a594c1b48b..4564117e5f5 100644
--- a/docs/users/extend/customizing-images.md
+++ b/docs/users/extend/customizing-images.md
@@ -39,3 +39,5 @@ Note that if a Dockerfile is provided, any config.yaml `webimage_extra_packages`
 ```
 RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y -o Dpkg::Options::="--force-confold" --no-install-recommends --no-install-suggests php-yaml php7.3-ldap
 ```
+
+Remember that the Dockerfile is building a docker image that will be used later with ddev. At the time the Dockerfile is executing, your code is not mounted and the container is not running, it's just being built.