From 0731de788d6334f5b206084f63b907e7e19dab8d Mon Sep 17 00:00:00 2001
From: Piotr Migdal <pmigdal@gmail.com>
Date: Sun, 27 Mar 2022 21:09:02 +0200
Subject: [PATCH] instructions for YAML options

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

diff --git a/README.md b/README.md
index 28c0b8a..82d8812 100644
--- a/README.md
+++ b/README.md
@@ -68,6 +68,31 @@ python3 -m bdfr download ./path/to/output --subreddit 'Python, all, mindustry' -
 python3 -m bdfr archive ./path/to/output --subreddit all --format yaml -L 500 --folder-scheme ''
 ```
 
+Alternatively, you can pass options through a YAML file.
+
+```bash
+python3 -m bdfr download ./path/to/output --opts my_opts.yaml
+```
+
+For example, running it with the following file
+
+```yaml
+skip: [mp4, avi]
+file_scheme: "{UPVOTES}_{REDDITOR}_{POSTID}_{DATE}"
+limit: 10
+sort: top
+subreddit:
+  - EarthPorn
+  - CityPorn
+```
+
+would be equilavent to (take note that in YAML there is `file_scheme` instead of `file-scheme`):
+```bash
+python3 -m bdfr download ./path/to/output --skip mp4 --skip avi --file-scheme "{UPVOTES}_{REDDITOR}_{POSTID}_{DATE}" -L 10 -S top --subreddit EarthPorn --subreddit CityPorn
+```
+
+In case when the same option is specified both in the YAML file and in as a command line argument, the command line argument takes prs
+
 ## Options
 
 The following options are common between both the `archive` and `download` commands of the BDFR.
@@ -80,6 +105,10 @@ The following options are common between both the `archive` and `download` comma
 - `--config`
   - If the path to a configuration file is supplied with this option, the BDFR will use the specified config
   - See [Configuration Files](#configuration) for more details
+- `--opts`
+  - Load options from a YAML file.
+  - Has higher prority than the global config file but lower than command-line arguments.
+  - See [opts_example.yaml](./opts_example.yaml) for an example file.
 - `--disable-module`
   - Can be specified multiple times
   - Disables certain modules from being used
@@ -221,7 +250,10 @@ The `clone` command can take all the options listed above for both the `archive`
 
 ## Common Command Tricks
 
-A common use case is for subreddits/users to be loaded from a file. The BDFR doesn't support this directly but it is simple enough to do through the command-line. Consider a list of usernames to download; they can be passed through to the BDFR with the following command, assuming that the usernames are in a text file:
+A common use case is for subreddits/users to be loaded from a file. The BDFR supports this via YAML file options (`--opts my_opts.yaml`).
+
+Alternatively, you can use the command-line [xargs](https://en.wikipedia.org/wiki/Xargs) function.
+For a list of users `users.txt` (one user per line), type:
 
 ```bash
 cat users.txt | xargs -L 1 echo --user | xargs -L 50 python3 -m bdfr download <ARGS>