An easy way to remember what your scripts do

I have a lot of shell utilities in my home bin directory. Some of them I use all of the time and know what they are. Others, no matter how cleverly I name them, I'll not use for long periods of time and will forget what they are for. I can use -h, -H, or --help on each one individually but that takes a lot of time to find the one I'm looking for.

In addition to just you looking for utilities you may create utilities that go into a shared directory resource and others will want to know what the scripts do without having to run help or man on each.

In order to deal with this I created a very simple shell utility called "synopsis". It's little more than a grep line with some sed filtering to get a formatted comment out of my files that tells me what they do. That makes it easier and faster to find what I'm looking for and then I can go into detail by looking at m help and usage using the script's tools, or go in and look at the code and internal comments.

Here is an example of synopsis' output:

[gail@gail]$ synopsis

buildterm:       Launch a stylized xterm that identifies it as my build terminal
evar:    Print formatted output of the environment variables passed as args
foo.php:         Get the target webpage and redirect the output to a blog entry
path:    Prints a one per line list of the $PATH elements.

You can do more to columnize the output, however, I find the quick reminder is good enough in the form that it is.

This script could actually be an alias however, I like having the ability to do more with the formatting if I choose.

This is the script listing:

#!/bin/bash

echo 
grep 'Synopsis:' * | grep -v 'grep Synopsis' |  awk 'BEGIN { FS = ":" } ; { printf "%-30s%-40s\n",$1,$3 }'  -
echo 

As you can see it's very simple. We use grep the find the hatch comment indicator followed by the string 'Synopsis:'. Then we use grep -v to strip out our synopsis script line by looking for 'grep Synopsis'. Grep will give us the script name and colon automatically and awk's file separator will let us ignore the '#Synopsis:' string. We use printf to do a little pretty printing of the strings.

You do have to take some care to keep your synopsis text on one line, however, it will be the most common case for you to want to keep it short anyway.

Most scripting languages recognize the '#' character as a comment so this should work all through your interpreter source trees. If you want it to recognize C++ and javascript comments you can use egrep versus grep to find the '//' comment specifier and then follow the same filtering rules.

If you wanted to extend this idea further you can use perl to look for the string Synopsis: in all of your files. That will give you better control over the look of the output and it will allow you to use synopsis for any type of source file using any type of comment specifier native to that language.

All the best.