From 451724d514b511ad2ddd6f5b053420b98d37e153 Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Sat, 22 Nov 2025 09:44:20 +1100
Subject: [PATCH] Version bump

---
 README.md                               |  2 +-
 SUMMARY.md                              |  1 +
 operators/anchor-and-alias-operators.md |  2 +-
 usage/base64.md                         | 88 +++++++++++++++++++++++++
 usage/shellvariables.md                 | 20 ++++++
 5 files changed, 111 insertions(+), 2 deletions(-)
 create mode 100644 usage/base64.md

diff --git a/README.md b/README.md
index 93b4a43f..6d46cbad 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # yq
 
-aa lightweight and portable command-line YAML, JSON, INI and XML processor. `yq` uses [jq](https://github.com/stedolan/jq) like syntax but works with yaml files as well as json, xml, ini, properties, csv and tsv. It doesn't yet support everything `jq` does - but it does support the most common operations and functions, and more is being added continuously.
+a lightweight and portable command-line YAML, JSON, INI and XML processor. `yq` uses [jq](https://github.com/stedolan/jq) like syntax but works with yaml files as well as json, xml, ini, properties, csv and tsv. It doesn't yet support everything `jq` does - but it does support the most common operations and functions, and more is being added continuously.
 
 yq is written in go - so you can download a dependency free binary for your platform and you are good to go! If you prefer there are a variety of package managers that can be used as well as Docker and Podman, all listed below.
 
diff --git a/SUMMARY.md b/SUMMARY.md
index 5d814fca..7fbdf962 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -80,6 +80,7 @@
 ## Usage
 
 * [Output format](usage/output-format.md)
+* [Working with Base64](usage/base64.md)
 * [Working with CSV, TSV](usage/csv-tsv.md)
 * [Working with JSON](usage/convert.md)
 * [Working with Properties](usage/properties.md)
diff --git a/operators/anchor-and-alias-operators.md b/operators/anchor-and-alias-operators.md
index cfdc8579..b5dc62eb 100644
--- a/operators/anchor-and-alias-operators.md
+++ b/operators/anchor-and-alias-operators.md
@@ -191,7 +191,7 @@ Given a sample.yml file of:
 ```yaml
 f:
   a: &a cat
-  *a: b
+  *a : b
 ```
 then
 ```bash
diff --git a/usage/base64.md b/usage/base64.md
new file mode 100644
index 00000000..3ab4dd03
--- /dev/null
+++ b/usage/base64.md
@@ -0,0 +1,88 @@
+# Base64
+
+Encode and decode to and from Base64.
+
+Base64 assumes [RFC4648](https://rfc-editor.org/rfc/rfc4648.html) encoding. Encoding and decoding both assume that the content is a UTF-8 string and not binary content.
+
+
+See below for examples
+
+
+## Decode base64: simple
+Decoded data is assumed to be a string.
+
+Given a sample.txt file of:
+```
+YSBzcGVjaWFsIHN0cmluZw==
+```
+then
+```bash
+yq -p=base64 -oy '.' sample.txt
+```
+will output
+```yaml
+a special string
+```
+
+## Decode base64: UTF-8
+Base64 decoding supports UTF-8 encoded strings.
+
+Given a sample.txt file of:
+```
+V29ya3Mgd2l0aCBVVEYtMTYg8J+Yig==
+```
+then
+```bash
+yq -p=base64 -oy '.' sample.txt
+```
+will output
+```yaml
+Works with UTF-16 😊
+```
+
+## Decode with extra spaces
+Extra leading/trailing whitespace is stripped
+
+Given a sample.txt file of:
+```
+
+ YSBzcGVjaWFsIHN0cmluZw==  
+
+```
+then
+```bash
+yq -p=base64 -oy '.' sample.txt
+```
+will output
+```yaml
+a special string
+```
+
+## Encode base64: string
+Given a sample.yml file of:
+```yaml
+"a special string"
+```
+then
+```bash
+yq -o=base64 '.' sample.yml
+```
+will output
+```
+YSBzcGVjaWFsIHN0cmluZw==```
+
+## Encode base64: string from document
+Extract a string field and encode it to base64.
+
+Given a sample.yml file of:
+```yaml
+coolData: "a special string"
+```
+then
+```bash
+yq -o=base64 '.coolData' sample.yml
+```
+will output
+```
+YSBzcGVjaWFsIHN0cmluZw==```
+
diff --git a/usage/shellvariables.md b/usage/shellvariables.md
index ba50315a..455e669b 100644
--- a/usage/shellvariables.md
+++ b/usage/shellvariables.md
@@ -84,3 +84,23 @@ will output
 name='Miles O'"'"'Brien'
 ```
 
+## Encode shell variables: custom separator
+Use --shell-key-separator to specify a custom separator between keys. This is useful when the original keys contain underscores.
+
+Given a sample.yml file of:
+```yaml
+my_app:
+  db_config:
+    host: localhost
+    port: 5432
+```
+then
+```bash
+yq -o=shell --shell-key-separator="__" sample.yml
+```
+will output
+```sh
+my_app__db_config__host=localhost
+my_app__db_config__port=5432
+```
+