From e466689c65e52893fbdf57498e88bf6eea70f7b3 Mon Sep 17 00:00:00 2001
From: Blended Bram <bram.kamies@iodigital.com>
Date: Wed, 20 Nov 2024 11:09:56 +0100
Subject: [PATCH] Document handling of `--` argument

---
 README.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/README.md b/README.md
index 6501df5..7f56f4e 100644
--- a/README.md
+++ b/README.md
@@ -164,6 +164,33 @@ console.log(args);
 */
 ```
 
+### Special `--` argument
+
+There is a special case for the `--` argument, if encountered all subsequent arguments are appended to `arg._` and parsing for the remaining arguments is skipped.
+This special behaviour for `--` overrides the argument spec, you cannot trick it into getting parsed.
+
+For example:
+
+```javascript
+const args = arg(
+	{
+		'--foo': [String],
+	},
+	{
+		argv: ['--foo', '1', '--', '2', '--foo', '3']
+	}
+);
+```
+
+results in:
+
+```javascript
+const args = {
+	_: [ '2', '--foo', '3' ],
+	'--foo': [ '1' ],
+};
+```
+
 ### Options
 
 If a second parameter is specified and is an object, it specifies parsing options to modify the behavior of `arg()`.