From 73ae6648226d905b36f91ccd50fdc8ee14775d2e Mon Sep 17 00:00:00 2001
From: Cameron Martin <camzig@gmail.com>
Date: Fri, 20 Sep 2024 14:18:38 -0700
Subject: [PATCH] Expand + clarify `--embed` docs

* Add documentation of unaliased embed behavior
* Add example for unaliased/merged embedded directories
---
 README.md       | 31 +++++++++++++++++++++++++++----
 cmd/commands.go |  2 +-
 2 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index de07a2c..bd99d69 100644
--- a/README.md
+++ b/README.md
@@ -78,7 +78,7 @@ $ xcaddy build [<caddy_version>]
 
 - `--replace` is like `--with`, but does not add a blank import to the code; it only writes a replace directive to `go.mod`, which is useful when developing on Caddy's dependencies (ones that are not Caddy modules). Try this if you got an error when using `--with`, like `cannot find module providing package`.
 
-- `--embed` can be used multiple times to embed directories into the built Caddy executable. The directory can be prefixed with a custom alias and a colon `:` to use it with the `root` directive and sub-directive.
+- `--embed` can be used to embed the contents of a directory into the Caddy executable. `--embed` can be passed multiple times with separate source directories. The source directory can be prefixed with a custom alias and a colon `:` to write the embedded files into an aliased subdirectory, which is useful when combined with the `root` directive and sub-directive.
 
 #### Examples
 
@@ -116,10 +116,10 @@ This allows you to hack on Caddy core (and optionally plug in extra modules at t
 
 ---
 
-You may embed directories into the Caddy executable and serve them from the `embedded` filesystem module:
+If `--embed` is used without an alias prefix, the contents of the source directory are written directly into the root directory of the embedded filesystem within the Caddy executable. The contents of multiple unaliased source directories will be merged together:
 
-```
-$ xcaddy build --embed foo:./sites/foo --embed bar:./sites/bar
+```sh
+$ xcaddy build --embed ./my-files --embed ./my-other-files
 $ cat Caddyfile
 {
     # You must declare a custom filesystem using the `embedded` module.
@@ -128,7 +128,27 @@ $ cat Caddyfile
     filesystem my_embeds embedded
 }
 
+localhost {
+    # This serves the files or directories that were
+    # contained inside of ./my-files and ./my-other-files
+	file_server {
+		fs my_embeds
+	}
+}
+```
+
+You may also prefix the source directory with a custom alias and colon separator to write the source directory's contents to a separate subdirectory within the `embedded` filesystem:
+
+```sh
+$ xcaddy build --embed foo:./sites/foo --embed bar:./sites/bar
+$ cat Caddyfile
+{
+    filesystem my_embeds embedded
+}
+
 foo.localhost {
+    # This serves the files or directories that were
+    # contained inside of ./sites/foo
 	root * /foo
 	file_server {
 		fs my_embeds
@@ -136,12 +156,15 @@ foo.localhost {
 }
 
 bar.localhost {
+    # This serves the files or directories that were
+    # contained inside of ./sites/bar
 	root * /bar
 	file_server {
 		fs my_embeds
 	}
 }
 ```
+
 This allows you to serve 2 sites from 2 different embedded directories, which are referenced by aliases, from a single Caddy executable.
 
 ---
diff --git a/cmd/commands.go b/cmd/commands.go
index daec448..9670375 100644
--- a/cmd/commands.go
+++ b/cmd/commands.go
@@ -51,7 +51,7 @@ Flags:
 
  --replace is like --with, but does not add a blank import to the code; it only writes a replace directive to go.mod, which is useful when developing on Caddy's dependencies (ones that are not Caddy modules). Try this if you got an error when using --with, like cannot find module providing package.
 
- --embed can be used multiple times to embed directories into the built Caddy executable. The directory can be prefixed with a custom alias and a colon : to use it with the root directive and sub-directive. Example: xcaddy build --embed foo:./sites/foo --embed bar:./sites/bar (This allows you to serve 2 sites from 2 different embedded directories, which are referenced by aliases, from a single Caddy executable).
+ --embed can be used to embed the contents of a directory into the Caddy executable. --embed can be passed multiple times with separate source directories. The source directory can be prefixed with a custom alias and a colon : to write the embedded files into an aliased subdirectory, which is useful when combined with the root directive and sub-directive.
 `,
 	Short: "Compile custom caddy binaries",
 	Args:  cobra.MaximumNArgs(1),