more on the draft

1 files changed, 164 insertions, 43 deletions

diff --git a/gemfeed/DRAFT-terminal-multiplexing-with-tmux.gmi b/gemfeed/DRAFT-terminal-multiplexing-with-tmux.gmi
index f330f210..b9a6a892 100644
--- a/gemfeed/DRAFT-terminal-multiplexing-with-tmux.gmi
+++ b/gemfeed/DRAFT-terminal-multiplexing-with-tmux.gmi
@@ -17,7 +17,7 @@ Before continuing reading this post, I encourage to get familiar with Tmux first
 
 Over the years, I have build a couple of shell helper functions to optimize my workflows. 
 
-Tmux is integrated into my daily workflows (personal and work) a lot. I had colleagues asking me about my tmux config and halper scripts for temux a couple of times. I thought it would be neat to blog about it, so that everyone who is interested in it, can make a copy of my configuration and scripts.
+Tmux is integrated into my daily workflows (personal and work) a lot. I had colleagues asking me about my tmux config and helper scripts for temux a couple of times. I thought it would be neat to blog about it, so that everyone who is interested in it, can make a copy of my configuration and scripts.
 
 The configuration and the scripts in this blog post are only the non-work specific parts. There are more helper scripts which I only use for work (and aren't really useful outside of work due to the nature how servers and clusters are structured there).
 
@@ -45,7 +45,7 @@ Note all `tmux::...`, those are custom shell functions doing certain things, tho
 
 The first two are pretty straight forward. `tm` is simply a shorthand for `tmux`, so I have to type less and `tl` simply lists all Tmux sessions currently open. Not much magic here.
 
-### The `tn` alias
+## The `tn` alias - Creating a new session
 
 The `tn` alias is referencing this function:
 
@@ -69,10 +69,12 @@ tmux::new () {
 alias tn=tmux::new
 ```
 
-There is a lot of stuff going on here. Let's have a look in detail what it is doing. As a note, the function relies on GNU Date, so for MacOS it is looking for the `gdate` commans to be available. Otherwise, it will fallback to `date`. For Mac, you would need to install GNU Date as it isn't installed by default there.
+There is a lot of stuff going on here. Let's have a look in detail what it is doing. As a note, the function relies on GNU Date, so for MacOS it is looking for the `gdate` commands to be available. Otherwise, it will fallback to `date`. For Mac, you would need to install GNU Date as it isn't installed by default there. As I use Fedora Linux on my personal Laptop and a MacBook for work, I have to make it work for both.
 
 First, as a first argument, a Tmux session name can be passed to the function. That session name is only optional. Without it, Tmux will select a session named `T$($date +%s)` as a default. Which is T followed by the UNIX epoch, e.g. `T1717133796`.
 
+### Cleaning up default sessions automatically
+
 Note also the call to `tmux::cleanup_default`, it would clean up all already opened default sessions if they aren't attached. Those kind of sessions are only of temporal nature and I found myself that I had too many flying around after a while. So I decided to auto delete the sessions if they aren't still attached. If I want to keep sessions around I would rename them with the Tmux command `prefix-key $`. This is the cleanup function:
 
 ```bash
@@ -86,28 +88,172 @@ tmux::cleanup_default () {
 }
 ```
 
+The cleanup function kills all open Tmux session which haven't beren renamed properly yet - but only if they aren't attached (e.g. don't run in the foreground in any terminal). Cleaning them up automatically keeps my Tmux sessions as neat and tidy as it gets. 
+
+## The `ta` alias - Attaching to a session
+
+This alias refers to the following function, which simply tries to attach to an already-running Tmux session.
+
+```bash
+tmux::attach () {
+    readonly session=$1
+
+    if [ -z "$session" ]; then
+        tmux attach-session || tmux::new
+    else
+        tmux attach-session -t $session || tmux::new $session
+    fi
+}
+alias ta=tmux::attach
+```
+
+If there is no session specified (as the argument of the function), it will try to attach to the first open session. If there is no Tmux server running, it will create a new one with `tmux::new`. Otherwise, with a session name given as the argument, it will attach to it. If unsuccessful (e.g. session doesn't exist), it will be created and attached to.
+
+## The `tr` alias - For a nested remote session
+
+This SSHs into the remote server specified and then, remotely on the server itself, starts a nested Tmux session. So we have one Tmux session on the local computer and, inside of it, an SSH connection to a remote server with a Tmux session running again. The benefit of this is that, in case my network connection breaks down, the next time I connect, I can continue my work on the remote server exactly where I left off. The session name is the name of the server being SSHed into. If a session like this already exists, it simply attaches to it.
+
+```bash
+tmux::remote () {
+    readonly server=$1
+    tmux new -s $server "ssh -t $server 'tmux attach-session || tmux'" || \
+        tmux attach-session -d -t $server
+}
+alias tr=tmux::remote
+```
+
+### Change of the Tmux prefix for better nesting
+
+In order to make nested Tmux sessions work smoothly, one must change the Tmux key either locally or remotely. I think there might also be another way around this (without reconfiguring the prefix key), but that is pretty cumbersome to use as far as I remember. To change the prefix key from the standard `b` to, for example, `w`, you must add this to the `tmux.conf`:
+
+```
+set-option -g prefix C-w
+```
+
+In my case, I have that deployed to all remote servers through a configuration management system (out of scope for this blog post).
+
+## The `ts` alias - Searching sessions with fuzzy finder
+
+Despite the fact that with `tmux::cleanup_default` I don't leave a huge mess with trillions of Tmux sessions flying around all the time, at times it can become challenging to find exactly the session I am currently interested in. After a busy workday, I often end up with around twenty sessions on my laptop. This is where fuzzy search for session names comes in handy, as I often don't remember the exact session names.
+
+```bash
+tmux::search () {
+    local -r session=$(tmux list-sessions | fzf | cut -d: -f1)
+    if [ -z "$TMUX" ]; then
+        tmux attach-session -t $session
+    else
+        tmux switch -t $session
+    fi
+}
+alias ts=tmux::search
+```
+
+All it does is list all currently open sessions in `fzf`, where one of them can be searched and selected through fuzzy find, and then either switch (if already inside a session) to the other session or attach to the other session (if not yet in Tmux).
+
+For this to work, you will need to install the `fzf` command on your computer.
+
+## The `tssh` alias - Cluster SSH replacement
+
+Before I used Tmux, I was a heavy user of ClusterSSH, which allowed me to log in to multiple servers at once in a single terminal window and type and run commands on all of them in parallel.
+
+=> https://github.com/duncs/clusterssh
+
+But since I started using Tmux, I retired ClusterSSH, as it came with the benefit that Tmux only needs to be run in the terminal, whereas ClusterSSH actually spawned terminal windows. The `tmux::cluster_ssh` function can have N arguments, where:
+
+* ...the first argument will be the session name (see `tmux::tssh_from_argument` helper function) and all remaining arguments will be server hostnames/FQDNs to connect to simultaneously.
+* ...or, the first argument is a file name and the file contains a list of hostnames/FQDNs  (see `tmux::ssh_from_file` helper function)
+
+This is how it looks:
+ 
+```bash
+tmux::cluster_ssh () {
+    if [ -f "$1" ]; then
+        tmux::tssh_from_file $1
+        return
+    fi
+
+    tmux::tssh_from_argument $@
+}
+alias tssh=tmux::cluster_ssh
+```
+
+This function is really just a wrapper around the more complex `tmux::tssh_from_file` and `tmux::tssh_from_argument` functions, as you have learned already. Most of the magic happens there.
+
+### The `tmux::tssh_from_argument` helper
+
+This is the most magic helper function we will cover in this post. It looks liket his:
+
+```bash
+tmux::tssh_from_argument () {
+    local -r session=$1; shift
+    local first_server=$1; shift
+
+    tmux new-session -d -s $session "ssh -t $first_server"
+    if ! tmux list-session | grep "^$session:"; then
+        echo "Could not create session $session"
+        return 2
+    fi
+
+    for server in "${@[@]}"; do
+        tmux split-window -t $session "tmux select-layout tiled; ssh -t $server"
+    done
+
+    tmux setw -t $session synchronize-panes on
+    tmux -2 attach-session -t $session | tmux -2 switch-client -t $session
+}
+```
+
+It expects at least two arguments. The first argument is the session name to create for the clustered SSH session. All other arguments are server hostnames or FQDNs to connect to. The first one is used to create the initial session. All remaining ones are then added to that session with `tmux split-window -t $session....`. At the end, we enable synchronized panes by default, so whenever you type, the commands will be sent to every SSH connection, thus enabling the neat ClusterSSH feature to run commands on multiple servers at once. Once done, we attach (or switch, if we are already in Tmux) to it.
 
-## Cluster SSH replacement
+Sometimes I don't want the synchronized panes behavior and want to switch it off temporarily. I can do that with `prefix-key p` and `prefix-key P` after adding the following to my local `tmux.conf`:
 
-I am using `tmux` as a Cluster SSH replacement.
 
-# Tmux
+```
+bind-key p setw synchronize-panes off
+bind-key P setw synchronize-panes on
+```
+
+### The `tmux::tssh_from_file` helper
+
+This one simply sets the session name to the file name and then reads a list of servers from that file, passing the list of servers to `tmux::tssh_from_argument` as the arguments. So this is a neat little wrapper enabling me to open clustered SSH sessions from an input file as well.
+
+```bash
+tmux::tssh_from_file () {
+    local -r serverlist=$1; shift
+    local -r session=$(basename $serverlist | cut -d. -f1)
 
+    tmux::tssh_from_argument $session $(awk '{ print $1} ' $serverlist | sed 's/.lan./.lan/g')
+}
+```
+
+## Tmux configurations
+
+There are some features I have configured directly in Tmux that don't require an external shell alias to function properly. Let's walk line by line through my local `~/config/tmux/tmux.conf`:
 
-This is my `~/.tmux.conf`:
 
 ```
-source ~/.tmux.local.conf
+source ~/.config/tmux/tmux.local.conf
 
 set-option -g allow-rename off
-set-option -g default-terminal "screen-256color"
 set-option -g history-limit 100000
 set-option -g status-bg '#444444'
 set-option -g status-fg '#ffa500'
 set-option -s escape-time 0
-
 set-window-option -g mode-keys vi
 
+```
+
+There's not much magic happening here just yet. I source a `tmux.local.conf`, which I sometimes use to override the default configuration that comes from the configuration management system. But it is mostly just an empty file, so it doesn't throw any errors on Tmux startup when I don't use it.
+
+I work with a lot of terminal output, which I also like to search within Tmux, so I add a large enough `history-limit`, enabling me to search backward in Tmux for any output up to a million lines of text.
+
+Besides changing some colors (personal taste), I also set `escape-time` to `0`, which is just a workaround, as otherwise my Helix text editor's `ESC` key would take ages to trigger within Tmux. I don't remember the gory details. You can leave it out, and if everything works fine for you, then just leave it out.
+
+I am navigating within Tmux using Vi key-bindings, so the `mode-keys` is set to `vi`. I am a user of the Helix modal text editor, and it is close enough to vi bindings for simple navigation in order to feel "native" to me. (BTW, I have been a long time Vim and NeoVim user, but I switched eventually to Helix - It's off-topic for here, but maybe worh another blog post one time).
+
+The next set of lines in the configuration file are:
+
+```
 bind-key h select-pane -L
 bind-key j select-pane -D
 bind-key k select-pane -U
@@ -117,7 +263,13 @@ bind-key H resize-pane -L 5
 bind-key J resize-pane -D 5
 bind-key K resize-pane -U 5
 bind-key L resize-pane -R 5
+```
+
+These allow me to use `prefix-key h`, `prefix-key j`, `prefix-key k`, and `prefix-key l` for switching panes and `prefix-key H`, `prefix-key J`, `prefix-key K`, and `prefix-key L` for resizing the panes. If you don't know Vi/Vim/NeoVim, the letters `hjkl` are commonly used there for left, down, up, and right, which is also the same for Helix, by the way.
+
+The next set of lines in the configuration file are:
 
+```
 bind-key c new-window -c '#{pane_current_path}'
 bind-key F new-window -n "session-switcher" "tmux list-sessions | fzf | cut -d: -f1 | xargs tmux switch-client -t"
 bind-key p setw synchronize-panes off
@@ -126,39 +278,6 @@ bind-key r source-file ~/.tmux.conf \; display-message "~/.tmux.conf reloaded"
 bind-key T choose-tree
 ```
 
-* I don't like programs running in tmux to change the window title, so i configured `allow-rename` to `off.`
-* Somtimes, I deal with a lot of terminal output which I also want to search. So I configured the `history-limit` to apretty high value.
-* The `escape-time` had to be configured to 0 to avoid issues with Helix, the text editor of my choice.
-* I am using vi key bindings in tmux, which is configured with `set-window-option -g mode-keys vi`.
-* The `bind-key h`...`bind-key l` make it so, that I can cycle tyhrought the tmux windows with the hjkl keys (vi and Helix editor emulation for arrow keys)
-* Respectively, the capital letters HJKL are used to resize the windows.
-* bind-key c creates a new window.
-* bind-key F opens a fuzzy finder for all open sessions.
-* bind-key p and C-P for controlling whether to syncrhonise the panes or not.
-* bind-key T to show a tree of all sessions and windows.
-
-
-
-This is my `~/.tmux.local.conf` on my local laptops:
-
-```
-bind-key -T copy-mode-vi 'v' send -X begin-selection
-bind-key -T copy-mode-vi 'y' send -X copy-selection-and-cancel
-```
-
-    
-
-Copy n paste, buffer search
-
-Clusterssh + p P
-
-Nested tmuxes are nice, too. E.g. one tmux on your laptop or workstation. In there you SSH into remote servers (use tmux as a ClusterSSH replacement). And then on the remote servers you start tmux again. I have configured a different leader key for the remote tmux instances, so they dont conflict with the local instance of tmux.
-
-Remote config file
-
-Zsh helper functions
-
-foo alias on remote servers
 
 Tmux is part of the OpenBSD Base system.
 
@@ -166,5 +285,7 @@ Tmux book I read.
 
 Rename sessions I use frequently 
 
+ uText search copy and paste  i use frequently
+
 TL and ta aliases