Skip to content

Add native response file support #909

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bkhouri wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add native response file support #909

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
621472a
Add native response file support
bkhouri Jul 17, 2026
2065f86
Support new line in a quoted string within a response file
bkhouri Jul 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,11 @@ Add new items at the end of the relevant section under **Unreleased**.

## [Unreleased]

### Additions

- Added source-location tracking for arguments expanded from response files. When at least one response-file reference is present in the input, parser error messages now include a multi-line `at <file>:<line>` / `included from <file>:<line>` block that pinpoints the offending argument and its full include chain. For pure command-line invocations, error messages are unchanged.
- Commands can now opt in to response-file expansion by overriding the `ParsableCommand.responseFilePrefix` static property with the character that should introduce a response-file reference (for example, `static var responseFilePrefix: Character? { "@" }`). The property defaults to `nil`, meaning response-file expansion is disabled unless the root command opts in.

---

## [1.8.2] - 2026-06-04
Expand Down
26 changes: 26 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,32 @@ OPTIONS:
-h, --help Show help for this command.
```

## Response Files

Swift Argument Parser can expand response files, letting you store command-line arguments in text files. This is especially useful for commands with many arguments or for reusable configurations. Opt in on your root command by overriding the `responseFilePrefix` static property with the character that should introduce a response-file reference (commonly `@`):

```swift
struct Repeat: ParsableCommand {
static var responseFilePrefix: Character? { "@" }
// ...
}
```

```bash
# Store arguments in a file
$ echo "--count 5 --include-counter hello" > args.txt

# Use the response file with @filename syntax
$ repeat @args.txt
1: hello
2: hello
3: hello
4: hello
5: hello
```

Response files support multiple formats, comments, quoted arguments, and can even reference other response files. See the [Response Files documentation](https://swiftpackageindex.com/apple/swift-argument-parser/documentation/argumentparser/responsefiles) for complete details.

## Documentation

For guides, articles, and API documentation see the
Expand Down
1 change: 1 addition & 0 deletions Sources/ArgumentParser/CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ add_library(ArgumentParser
Parsing/Parsed.swift
Parsing/ParsedValues.swift
Parsing/ParserError.swift
Parsing/ResponseFileExpander.swift
Parsing/SplitArguments.swift

Usage/DumpHelpGenerator.swift
Expand Down
5 changes: 3 additions & 2 deletions Sources/ArgumentParser/Documentation.docc/ArgumentParser.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Begin by declaring a type that defines
the information that you need to collect from the command line.
Decorate each stored property with one of `ArgumentParser`'s property wrappers,
declare conformance to ``ParsableCommand``,
and implement your command's logic in its `run()` method.
and implement your command's logic in its `run()` method.
For `async` renditions of `run`, declare ``AsyncParsableCommand`` conformance instead.

```swift
Expand All @@ -33,7 +33,7 @@ struct Repeat: ParsableCommand {
}
```

When a user executes your command,
When a user executes your command,
the `ArgumentParser` library parses the command-line arguments,
instantiates your command type,
and then either calls your `run()` method or exits with a useful message.
Expand All @@ -58,6 +58,7 @@ and then either calls your `run()` method or exits with a useful message.
### Arguments, Options, and Flags

- <doc:DeclaringArguments>
- <doc:ResponseFiles>
- ``Argument``
- ``Option``
- ``Flag``
Expand Down
Loading