Updated README.md
This commit is contained in:
chawley (chawley02)
90
README.md
90
README.md
@@ -1,74 +1,70 @@
|
||||
---
|
||||
CREATED : 2026-03-03
|
||||
UPDATED :
|
||||
UPDATED : 2026-03-03
|
||||
AUTHOR : chawley
|
||||
---
|
||||
|
||||
# tmux-menu.sh
|
||||
# TMUX Hack Session Launcher
|
||||
|
||||
A hack tmux menu script to manage multiple tmux sessions
|
||||
A Bash script designed to manage and automate pre-defined tmux-sessions. This script allows you to launch complex development or administration environments - complete with multiple windows and SSH connections - using a single command.
|
||||
|
||||
---
|
||||
|
||||
REQ: tmux v3+
|
||||
## Features
|
||||
|
||||
- **Automated Session Creation**: Checks if a session exists; if not, it creates it with your pre-defined windows and layouts.
|
||||
- **Environment Nesting Protection**: Prevents launching a new session if you are already inside an active tmux environment.
|
||||
- **Custom Configuration Support**: Automatically sources your `$HOME/.tmux.conf`.
|
||||
- **Session Attaching**: If a requested session is already running, the script simply attaches you to it.
|
||||
- **Fallback Discovery**: Provides an error message and lists all currently active sessions if an invalid name is provided.
|
||||
|
||||
---
|
||||
|
||||
## Need
|
||||
## Prerequisites
|
||||
|
||||
After I discovered tmux I searched for a way to manage multiple groups of tmux sessions under one unified script. Not finding anything (or maybe just not looking well enough) I decided to write my own. It's not pretty, but I've been using for a couple of years now and it's become an integral part of my workflow.
|
||||
- **tmux**: Ensure `tmux` is installed and available in your `$PATH`.
|
||||
- **SSH Config (Optional)**: For windows that execute SSH commands, ensure your SSH keys or config are set up for seamless connections.
|
||||
|
||||
My setup works this way:
|
||||
---
|
||||
|
||||
Imagine you have multiple SSH connections
|
||||
## Installation
|
||||
|
||||
- web-dev
|
||||
- web-prod
|
||||
- database-dev
|
||||
- database-prod
|
||||
1. Copy the script to a directory in your `$PATH` (e.g., `~/bin` or `/usr/local/bin`).
|
||||
2. Rename it to something short, like `tm`.
|
||||
3. Make the script executable:
|
||||
```bash
|
||||
chmod +x ~/bin/tm
|
||||
```
|
||||
|
||||
and you want to group them together in similar groups.
|
||||
---
|
||||
|
||||
With this script you can name collections of sessions and switch between them easily with just a few keystrokes.
|
||||
## Usage
|
||||
|
||||
Let's see an example using the above connections:
|
||||
Run the script followed by the name of the pre-defined session:
|
||||
|
||||
```bash
|
||||
case $session in
|
||||
web)
|
||||
if [[ $tcheck == 0 ]]; then
|
||||
tmux new-session -d -s web
|
||||
tmux rename-window 'local'
|
||||
tmux new-window -t 1 -n 'root@web-dev' 'exec ssh root@web-dev.example.org'
|
||||
tmux new-window -t:2 -n 'user@web-prod' 'exec ssh user@webprod.example.org'
|
||||
fi
|
||||
tmux attach-session -t web
|
||||
;;
|
||||
tm mine
|
||||
```
|
||||
|
||||
case $session in
|
||||
database)
|
||||
If no session name is provided, or the name doesn't match a case in the script, it will display an error and list all currently active tmux sessions.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
To add a new session, add a new case stanza inside the `case $session in` block.
|
||||
|
||||
### Template
|
||||
```bash
|
||||
session_name)
|
||||
if [[ $tcheck == 0 ]]; then
|
||||
tmux new-session -d -s database
|
||||
tmux rename-window 'local'
|
||||
tmux new-window -t 1 -n 'root@database-dev' 'exec ssh root@databasedev.example.org'
|
||||
tmux new-window -t:2 -n 'user@database-prod' 'exec ssh user@wdatabase.example.org'
|
||||
tmux -f "${TMUX_CONF}" new-session -d -s session_name
|
||||
tmux -f "${TMUX_CONF}" rename-window 'initial_window'
|
||||
tmux -f "${TMUX_CONF}" new-window -t:1 -n 'second_window' 'command_to_run'
|
||||
fi
|
||||
tmux attach-session -t database
|
||||
tmux attach-session -t session_name
|
||||
;;
|
||||
```
|
||||
|
||||
Calling the script with a pre-determined session name (ex: `./tmux-menu.sh web` or `./tmux-menu.sh database`) firstchecks to see if there is already a session group with that name. If not, it creates a new group with the commands youspecify and names each connection in tmux.
|
||||
|
||||
If the session group *does* already exist, it simply switches you to that group.
|
||||
|
||||
If you alias `tmux-menu.sh` to something shorter (like `tm`), switching between active sessions is as easy as `Ctrl-A + d` (to detach) and `tm web` (to attach or create the web group).
|
||||
|
||||
Killing session groups is as easy as `tmux-session kill -t web`.
|
||||
|
||||
---
|
||||
|
||||
## Use
|
||||
|
||||
I've found that I use this script on different servers with different configurations. So I copy the `tmux-menu.template.sh` to `$HOME/tmux-menu.sh` and then alias that to `tm`.
|
||||
|
||||
I also include my `.tmux.conf` file with comments about what does what. If you choose to use it, make sure to copy it to your home directory.
|
||||
### Script Variables
|
||||
- `TMUX_CONF`: Defaults to `$HOME/.tmux.conf`. Modify this variable if your configuration file is located elsewhere.
|
||||
|
||||
Reference in New Issue
Block a user