From 28d33784ae05c79585ce9d77e3a173424bcbcdc3 Mon Sep 17 00:00:00 2001
From: hygienic-books <hygienic-books@tentic.net>
Date: Fri, 3 Mar 2023 05:37:39 +0100
Subject: [PATCH] docs(script): Add docs (#1)

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

diff --git a/README.md b/README.md
index 0307f29..81da2b8 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,34 @@
 # heidisql-ssh-tunnel
 
-Helper script to spawn SSH tunnels based on HeidiSQL settings
\ No newline at end of file
+Helper script to spawn SSH tunnels based on HeidiSQL settings
+
+# What's this?
+
+The script assumes you have HeidiSQL directory in `~/'.heidisql` where your `portable_settings.txt` file is living.
+
+It peeks into that file and offers auto-completion based on saved sessions. It creates local SSH tunnels for these sessions.
+
+# Setup
+
+1. Git clone this repo
+1. Add a symlink to bash completion script such as:
+    ```
+    sudo ln -s <repo>/hs ~/.local/share/bash-completion/hs
+    ```
+1. Add symlink to script itself and make it executable:
+    ```
+    sudo ln -s <repo>/hs.sh /usr/local/bin/hs
+    chmod +x <repo>/hs.sh
+    ```
+
+# What it looks like
+
+Here with `fzf` as auto-completion helper (optional, is a personal preference):
+
+![Screencast showing hs in action](https://i.imgur.com/FhVFtaR.gif)
+
+> Here `hs` first attempts to set up an SSH tunnel for a HeidiSQL saved session and fails because something's already listening on the local port.
+> 
+> We `kill` the connection in question - an SSH tunnel from a prior test - and try again. This time `hs` correctly creates our tunnel. With `set -xv` we see the actual command that gets executed.
+>
+> Once done we clean up after ourselves and kill SSH tunnels we no longer need.