tmux-hints.sh Screenshot

tmux-hints.sh: The auto cheatsheet for vim, zsh, tmux etc.

Although I’m comfortable using terminal – getting used to new shortcuts, key-combos and custom mappings can be a memory-game. I’ve ended up with many note files containing hints for all the things I should have remembered by now. There’s a better way...

The background and why this started… I’m in the process of switching to full-time cloud-terminal based development from years of developing using a visual IDE and hopping in-and-out of a bash shell for nearly everything else.

Jumping in-and-out of note files with vim notes.md, vim notes-vim.md, vim-tmux.md and then double-checking with the latest config etc can end-up being time consuming and distracting.

So, I’ve knocked together a bash script to automatically load note files for the programme currently focused in tmux.

https://github.com/hozza/tmux-hints

In a tmux pane on the side, I run:

Now when you focus on getting some vim work fun done in another tmux pane, your vim notes are displayed automatically – when you switch back to another pane running something else, that programmes notes are automagically shown instead.

You can create a ‘hint file’ for any command, and tmux-hints.sh will load it automatically while you’re focusing on the work-at-hand, showing your notes without any input from yourself, leaving you to get on with whatever it is you were doing.

Usage

Grab the bash file from GitHub, make sure the file is marked as executable and run the script in a pane. Detailed terminal commands can be found on the GitHub repo.

tmux-hints.sh looks for a file with the name of the currently focused command, in a folder called ‘hints’ in your home directory.

e.g. ~/hints/COMMAND_NAME.txt

Once tmux-hints.sh is running in a tmux pain, you can focus on another pane running something else, like vim for example and tmux-hints.sh will show the vim hint file you’ve saved in ~/hints/vim.txt.

Exit tmux-hints.sh with a standard Ctrl+c while focused on its tmux pane.

I haven’t included any hint files in by default as everyone will have their own notes – usually based on your configuration files and plugins.

Which leads us nicely to .dotfiles

Dotfiles.

Quick side-note: If you’re not already blessed with the underworld of dotfile configurations – I’d like to take this moment to send you down a rabbit-hole. Developers and terminal users in general are quite fond of bottling up all their customisations and configurations into a folder called ~/.dotfiles/ and sharing these configs, instructions, hacks, setups and easy-installation-scripts online with other like minded peeps. Partly for the somewhat-niche fame and partly for the easy backup-and-restore of their favourite shell environment.

Since hints can consist of custom key maps/bindings and other usage notes they could quite nicely be bundled along with your .dotfiles configs.

You can tell .tmux-hints.sh to look for hint files inside your dotfiles folder, just start it with:

If you’re super fancy… and have a markdown viewer installed – you could write your hint files in markdown, using the .md extension, and start tmux-hints.sh with:

Where markdown-viewer is the command, or chain of piped commands, you’d like to show the markdown files with. This essentially tells tmux-hints.sh to run the following when a new command is in focus:

Where vim is whatever command is currently focused in tmux.

How does it work?

It uses tmux’s built in feature called hooks, and tells tmux to output the name of the currently focused command to a tmp file.

tmux-hints.sh checks the modification time of the tmp file every second, and if changed – it will read the command name, clear the current file from the terminal pane, look in the hint file path and if it finds one, outputs it to the terminal.

Apparently, even though tmux-hints.sh is checking the modification time of a tmp file (presumably on disk) in a never ending one second loop, and then reading out another file… Linux is quite good at managing and caching this time of file stat request and has little overhead while doing so.

Contributing

I’m sure tmux-hints.sh could be much better – with more features or written in a better way.

I’m planning to update it as I learn new things, as this is my first attempt at bash scripting, but would like to keep it as simple and versatile as possible, with few dependencies or hurdles – as after all, it’s aimed at easing the learning-curve with new tech, configs and environments.

I would like to add some sort of hint-making config-scraping option to automatically generate and append the current custom-mappings for common config files such as vim, tmux and zsh…

Teach me a thing or two by getting involved on the GitHub repo, submit an issue, fork and pull-request etc.

Happy terminal-ing, and remember those combos you keep forgetting!exit,q,Ctrl+c,kj:x

Published by

~/bh

Ben Hoskins, a SaaS developer from London who loves anything code, business or sailing!

Leave a Reply

Your email address will not be published. Required fields are marked *