tmux-hints.sh: The auto cheatsheet for vim, zsh, tmux etc.
Being comfortable using terminal means nothing when getting used to new shortcuts, key-combos and custom mappings can be a memory-game.
I've ended up with a bunch of note files containing hints for all the things I should have remembered by now. There's a better way...
2019-12-23 Update! There’s been an update for this tool. See tmux-hints v0.3.
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.
In a tmux pane on the side, I run:
$ ./tmux-hints.sh
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:
$ tmux-hints.sh -p ~/.dotfiles/hints/
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:
$ tmux-hints.sh -p ~/.dotfiles/hints/ -x md -o markdown-viewer
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:
$ markdown-viewer $HOME/.dotfiles/hints/vim.md
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
2019-12-23 Update! v0.3 Thanks for all the support on Reddit - I've implemented some of the changes recommended too. Check out the tmux-hints v0.3 update changelog here.
Comments & Questions
Reply by email to send in your thoughts.
Comments may be featured here unless you say otherwise. You can encrypt emails with PGP too, learn more about my email replies here.
PGP: 9ba2c5570aec2933970053e7967775cb1020ef23Missing Comments. The original post comments have not been imported from Twitter yet.