From b4384af8de9c65742c7a4fadb1ee8e3853368e6c Mon Sep 17 00:00:00 2001
From: Sergey Kamardin <gobwas@gmail.com>
Date: Wed, 30 Sep 2020 21:29:01 +0300
Subject: [PATCH] update readme

---
 README.md | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index c7c6ffc..e125bb8 100644
--- a/README.md
+++ b/README.md
@@ -111,7 +111,9 @@ func main() {
 }
 ```
 
-However, `flagutil` provides ability to define so called flag subsets:
+## Subsets
+
+`flagutil` provides ability to define so called flag subsets:
 
 ```go
 package main
@@ -176,6 +178,35 @@ program as follows:
 $ app --database.endpoint 4055
 ```
 
+## Allowing name collisions
+
+It's rare, but still possible, when you want to receive single flag value from
+multiple places in code. To avoid panics with "flag redefined" reason you can
+(if you _really_ need to) _merge_ two flag values into single by using
+`flagutil.Merge()` function:
+
+```go
+var (
+	s0 string
+	s1 string
+)
+flag.StringVar(&s0,
+	"foo", "default",
+	"foo flag usage",
+)
+flagutil.Merge(flag.CommandLine, func(safe *flag.FlagSet) {
+	safe.StringVar(&s1,
+		"foo", "",
+		"foo flag another usage", // This usage will be joined with previous.
+	)
+})
+
+// After parsing, s0 and s1 will be filled with single `-foo` flag value.
+// If value is not provided, both s0 and s1 will have its default values (which
+// may be _different_).
+```
+
+
 # Conventions and limitations
 
 Any structure from parsed configuration is converted into a pairs of a flat key