From dbedcb694ea006444c45bb9709782f07b6e65d65 Mon Sep 17 00:00:00 2001
From: Francis Lavoie <lavofr@gmail.com>
Date: Wed, 29 May 2024 18:09:42 -0400
Subject: [PATCH] Update the README as per #186 (#187)

---
 README.md | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index f82cff6..1047aa6 100644
--- a/README.md
+++ b/README.md
@@ -73,11 +73,14 @@ $ xcaddy build [<caddy_version>]
   - A commit like `a58f240d3ecbb59285303746406cab50217f8d24`
 
 - `--output` changes the output file.
+
 - `--with` can be used multiple times to add plugins by specifying the Go module name and optionally its version, similar to `go get`. Module name is required, but specific version and/or local replacement are optional.
-- `--replace` can be used multiple times to replace dependencies to specific forks or local replacements. Useful in development environment to fix bugs in dependencies.
-- `--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. 
 
-Examples:
+- `--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 devloping 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.
+
+#### Examples
 
 ```bash
 $ xcaddy build \
@@ -99,18 +102,22 @@ $ xcaddy build \
     --with github.com/caddyserver/ntlm-transport@v0.1.1=../../my-fork
 ```
 
-You can even replace Caddy core using the `--replace` flag:
+You can even replace Caddy core using the `--with` flag:
 
 ```
 $ xcaddy build \
-    --replace github.com/caddyserver/caddy/v2=../../my-caddy-fork
+    --with github.com/caddyserver/caddy/v2=../../my-caddy-fork
     
 $ xcaddy build \
-    --replace github.com/caddyserver/caddy/v2=github.com/my-user/caddy/v2@some-branch
+    --with github.com/caddyserver/caddy/v2=github.com/my-user/caddy/v2@some-branch
 ```
 
 This allows you to hack on Caddy core (and optionally plug in extra modules at the same time!) with relative ease.
 
+---
+
+You may embed directories into the Caddy executable:
+
 ```
 $ xcaddy build --embed foo:./sites/foo --embed bar:./sites/bar
 $ cat Caddyfile
@@ -130,6 +137,15 @@ bar.localhost {
 ```
 This allows you to serve 2 sites from 2 different embedded directories, which are referenced by aliases, from a single Caddy executable.
 
+---
+
+If you need to work on Caddy's dependencies, you can use the `--replace` flag to replace it with a local copy of that dependency (or your fork on github etc if you need):
+
+```
+$ xcaddy build some-branch-on-caddy \
+    --replace golang.org/x/net=../net
+```
+
 ### For plugin development
 
 If you run `xcaddy` from within the folder of the Caddy plugin you're working on _without the `build` subcommand_, it will build Caddy with your current module and run it, as if you manually plugged it in and invoked `go run`.