From 27268aae265d181d7e67c958c99d70ddc1cae74c Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Sat, 30 Oct 2021 05:09:29 +0000
Subject: [PATCH] GitBook: [#209] split docs

---
 SUMMARY.md                         |  1 +
 usage/split-into-multiple-files.md | 80 ++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 usage/split-into-multiple-files.md

diff --git a/SUMMARY.md b/SUMMARY.md
index 228993ba..422810f8 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -53,6 +53,7 @@
 
 ## Usage
 
+* [Split into multiple files](usage/split-into-multiple-files.md)
 * [Output format](usage/output-format.md)
 * [Working with Properties](usage/properties.md)
 * [Working with JSON](usage/convert.md)
diff --git a/usage/split-into-multiple-files.md b/usage/split-into-multiple-files.md
new file mode 100644
index 00000000..02e5438b
--- /dev/null
+++ b/usage/split-into-multiple-files.md
@@ -0,0 +1,80 @@
+# Split into multiple files
+
+`yq` can split out the results into multiple files with the `--split-exp/s` flag. You will need to give this flag an expression (that returns a string), this will be used as the filename for each result. In this expression, you can use `$index` to represent the result index in the name, if desired.
+
+## Split documents into files
+
+Given a file like
+
+```yaml
+a: test_doc1
+--- 
+a: test_doc2
+```
+
+Then running:
+
+```bash
+yq e -s '.a' myfile.yml
+```
+
+will result in two files:
+
+test\_doc1.yml:
+
+```yaml
+a: test_doc1
+```
+
+test\_doc2.yml:
+
+```yaml
+---
+a: test_doc2
+```
+
+TIP: if you don't want the leading document separators (`---`), then run with the `--no-doc` flag.
+
+## Split documents into files, using index
+
+This is like the example above, but we'll use `$index` for the filename. Note that this variable is only defined for the `--split-exp/s` flag.
+
+```
+yq e -s '"file_" + $index' myfile.yml
+```
+
+This will create two files, `file_0.yml` and `file_1.yml`.
+
+## Split single document into files
+
+You can also split results into separate files. Notice
+
+```yaml
+- name: bob
+  age: 23
+- name: tim
+  age: 17
+```
+
+Then, by splatting the array into individual results, we can split the content into several files:
+
+```bash
+yq e '.[]' file.yml -s '"user_" + .name'
+```
+
+will result in two files:
+
+user\_bob.yml:
+
+```yaml
+name: bob
+age: 23
+```
+
+user\_tim.yml:
+
+```yaml
+name: tim
+age: 17
+```
+