MANPAGE: -extpass: document dash duplication bug

Closes https://github.com/rfjakob/gocryptfs/issues/621

2 files changed, 31 insertions, 0 deletions

diff --git a/Documentation/MANPAGE.md b/Documentation/MANPAGE.md
index ffed44e..fa2f5b5 100644
--- a/Documentation/MANPAGE.md
+++ b/Documentation/MANPAGE.md
@@ -475,6 +475,10 @@ to your program, use `"--"`, which is accepted by most programs:
 
 Applies to: all actions that ask for a password.
 
+BUG: In `-extpass -X`, the `-X` will be interpreted as `--X`. Please use
+`-extpass=-X` to prevent that. See **Dash duplication** in the **BUGS** section
+for details.
+
 #### -fido2 DEVICE_PATH
 Use a FIDO2 token to initialize and unlock the filesystem.
 Use "fido2-token -L" to obtain the FIDO2 token device path.
@@ -684,6 +688,29 @@ other: please check the error message
 
 See also: https://github.com/rfjakob/gocryptfs/blob/master/internal/exitcodes/exitcodes.go
 
+BUGS
+====
+
+### Dash duplication
+
+gocryptfs v2.1 switched to the `pflag` library for command-line parsing
+to support flags and positional arguments in any order. To stay compatible
+with single-dash long options like `-extpass`, an ugly hack was added:
+The command line is preprocessed, and all single-dash options are converted to
+double-dash.
+
+Unfortunately, this means that in
+
+    gocryptfs -extpass myapp -extpass -X
+
+gocryptfs transforms the `-X` to `--X`, and it will call `myapp --n` as the extpass program.
+
+Please use
+
+    gocryptfs -extpass myapp -extpass=-X
+
+to work around this bug.
+
 SEE ALSO
 ========
 mount(2) fuse(8) fallocate(2) encfs(1) gitignore(5)
diff --git a/cli_args.go b/cli_args.go
index 6b97744..781dc5c 100644
--- a/cli_args.go
+++ b/cli_args.go
@@ -114,6 +114,10 @@ func prefixOArgs(osArgs []string) ([]string, error) {
 // into "--debug" (spf13/pflag style).
 // gocryptfs v2.1 switched from `flag` to `pflag`, but we obviously want to stay
 // cli-compatible, and this is the hack to do it.
+//
+// BUG: In `-extpass -X`, the `-X` gets transformed `--X`.
+// See "Dash duplication" in the man page and
+// https://github.com/rfjakob/gocryptfs/issues/621 .
 func convertToDoubleDash(osArgs []string) (out []string) {
 	out = append(out, osArgs...)
 	for i, v := range out {