Improve examples and help in several commands (#2277)

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 {

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 {

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)

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) {
 

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 {

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 {

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]'")

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()

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 {

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".

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

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 {

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 {

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()
 	},

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()
 	},

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)

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 {

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 {

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()
 	},

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.