From 7cc55734a8fc505e288fbd62d04a2f47deff6c28 Mon Sep 17 00:00:00 2001
From: Timothy Stack <timothyshanestack@gmail.com>
Date: Sun, 1 May 2022 15:42:13 -0700
Subject: [PATCH] [docs] add some regex101 integration stuff

---
 .../_posts/2022-05-01-regex101-integration.md | 69 +++++++++++++++++++
 docs/source/cli.rst                           |  3 +
 2 files changed, 72 insertions(+)
 create mode 100644 docs/_posts/2022-05-01-regex101-integration.md

diff --git a/docs/_posts/2022-05-01-regex101-integration.md b/docs/_posts/2022-05-01-regex101-integration.md
new file mode 100644
index 00000000..d519e4b1
--- /dev/null
+++ b/docs/_posts/2022-05-01-regex101-integration.md
@@ -0,0 +1,69 @@
+---
+layout: post
+title: Integration with regex101.com
+excerpt: Create format files from regular expressions on regex101.com and edit
+them too
+---
+
+*(This change will be in the upcoming v0.10.2 release)*
+
+Creating and updating format files for **lnav** can be a bit tedious and
+error-prone. To help streamline the process, an integration with regex101.com
+has been added. Now, you can create regular expressions for plaintext log
+files on https://regex101.com and then create a skeleton format file with a
+simple command. If you already have a format file that needs to be updated,
+you can push the regexes up to regex101, edit them with their interface, and
+then pull the changes back down as a format patch file. In addition, there
+is work underway to improve error messages, both how in what they say and
+how they look.
+
+## Management CLI
+
+The regex101 integration can be accessed through the new "management-mode CLI".
+This mode can be accessed by passing `-m` as the first option to **lnav**. The
+management CLI is organized as a series of nested commands. If you're not sure
+what to do at a given level, run the command as-is and the CLI should print out
+help text to guide you through the hierarchy of commands and required
+parameters.
+
+### Create a format from a regular expression
+
+The `regex101 import` command can be used to import a regular expression from
+regex101.com and create or patch a format file. The command takes the URL of
+the regex, the format name, and the name of the regex in the log format (
+defaults to "std" if not given). For example, the following command can be used
+to import the regex at "https://regex101.com/r/zpEnjV/2" into the format named "
+re101_example_log":
+
+```shell
+$ lnav -m regex101 import https://regex101.com/r/zpEnjV/2 re101_example_log
+```
+
+If the import was successful, the path to the skeleton format file will be
+printed. You will most likely need to edit the file to fill in more details
+about your log format.
+
+### Editing an existing regular expression
+
+If you have a log format with a regex that needs to be updated, you can push
+the regex to regex101.com for editing with a command like (replace
+"myformat_log"/"std" with the name of your format and regex):
+
+```shell
+$ lnav -m format myformat_log regex std regex101 push
+```
+
+Along with the regex, the format's samples will be added to the entry to ensure
+changes won't break existing matches. If the push was successful, the URL for
+the new regex101.com entry will be printed out. You can use that URL to edit the
+regex to your needs. Once you're done editing the regex, you can pull the
+changes down to a "patch" file using the following command:
+
+```shell
+$ lnav -m format myformat_log regex std regex101 pull
+```
+
+The patch file will be evaluated after the original format file and override
+the values from the original. Once you are satisfied with the changes, you
+can move the contents of the patch file to the original file and delete the
+patch.
diff --git a/docs/source/cli.rst b/docs/source/cli.rst
index 8700200c..5dca5423 100644
--- a/docs/source/cli.rst
+++ b/docs/source/cli.rst
@@ -96,6 +96,9 @@ Options
 Management Mode (v0.10.2+)
 --------------------------
 
+The management CLI mode provides functionality for query **lnav**'s log
+format definitions.
+
 Options
 ^^^^^^^