A Project Directory Management Facility

Leor Zolman

Typical UNIX users spend most of their time either in their home directories or in subdirectories thereof, but system administrators are more likely to "be all over the place" in the UNIX filesystem. In the course of a typical day of my most recent SA position, I'd usually have several major projects going at a time in a number of different system or application directories. Whenever a user came along with a software problem of some kind, I'd have to change my mental gear, switch directories over to wherever the problem was, and take care of it. Afterwards, I'd ask myself, "Now which of the six different things I'm currently juggling was I working on before that interruption?" Even if I was lucky enough to actually recall the task I was tackling, I still had to get myself back to the proper directory -- and occasionally that took some time.

The First Iteration

Since my memory isn't cut out for this sort of heavy-duty recall, several years ago I began to tinker with a shell script that performs quick directory switching among projects scattered all across the filesystem. The idea was to program some shell functions (for the Bourne shell originally, and later for the Korn shell as well) that would squirrel away pathnames for me in the environment, by request, and then later perform automatic cd commands to return me to those saved locations.

To make this facility as easy to use as possible, I created a set of tersely named shell functions using a "register" metaphor to address the pathnames to be saved. Under this metaphor, I define three scratchpad registers named x, y, and z. For each project register there were two shell function definitions in the startup .profile: setR, to assign the pathname of the current directory to register R, and goR, to change directory to the pathname stored in register R (the code for these definitions is shown in Listing 1). Now, when I was interrupted in the middle of a project, I could just type, say,

$ setx

to save my current directory in scratchpad register x. I'd then go deal with the fire, and when I was ready to go back to my original task, the command

$ gox

would return me there quickly. To examine the values of any scratchpad registers, I could simply use the echo command to display the values, e.g.,

$ echo $x

These shell functions must be explicitly defined in the startup .profile for each desired scratchpad register. Trying to implement them as external shell scripts won't work -- external shell scripts are interpreted by subordinate shells, and subordinate shells cannot directly alter the environment (current working directory or environment variables) of their parent (login) shell. Thus, any shell functions that alter the working directory must be defined within the active shell's environment.

Note that some implementations of the Bourne shell support shell functions, and some do not. If your sh accepts the commands in Listing 1 without complaint, then it supports shell functions. If not, you'll need either a newer sh or a ksh (Korn Shell).

Now Let's Get Fancy

Under the early implementation shown in Listing 1, all stored project registers were cleared at the end of a login session because the paths were saved in nothing but volatile environment variables. Storing the pathnames in environment variables only was quick, efficient, and simple, but after using setx/gox, etc. for a while, I found that what I really wanted was "persistent" pathname memory: a way to define paths and have those definitions persist across login sessions. The only way to save the path definitions is to write them out to a file for safekeeping. Thus, my new versions of the functions "mirror" all scratchpad register assignments by writing them into associated status files as well as to the original environment variables. Every time a new login session initiates, the startup code can simply define all the environmental scratchpad registers from those status files, and then any subsequent change modifies both the status file and the associated environment variable.

Next, I wanted a new category of pathname registers that I could use exclusively for long-term projects. I use the scratchpad registers primarily to move back and forth between either two, or at most three, directories in the course of working on a single project; a new set of project registers for holding pointers to my long-term projects would allow me to conceptually separate the scratchpad registers from the project registers.

I built the user interface for the project register set on two levels: at the bottom level, a single shell function named p performs all the tasks relating to definition and access of the register set. The effect of the p function depends on the number of arguments it is passed. If you give p a single argument, that argument is interpreted as the numeric ID of a project register, and p switches you to the pathname saved in that register. If you pass it two arguments, then the first argument is still a numeric register ID, and the second argument is the path you want assigned to that particular register. For example,

$ p 5 /u/leor/proj/foo

sets project register #5 to the given path. I can then quick-change to that path at any time by saying:

$ p 5

The special path code . may be used to specify the current directory. In most cases this is the way I actually use p to define a path register value.

The p function is shown in Listing 2, lines 29-57. Being one who really hates superfluous keystrokes, I added a layer on top of the p function so that I could access each project register without needing to type the space between the letter p and the register number (a bit self-indulgent, I admit, but it was a great set-up for an interesting shell programming exercise). I began by writing a driver function definition for each project register, i.e.,

p1() { p 1 $*; }
p2() { p 2 $*; }

and so on. While this did the trick, it struck me as inelegant to duplicate the same code for each desired register. Granted, even ten or fifteen of these definitions would not exactly overload the environment space, but what if I could somehow generate the definitions automatically? If I know how many project registers I want to support, there ought to be a way to iterate through each register ID value and create the required function definition on-the-fly. For a long time, however, I was stuck trying to generate an interpolation on a "variable" variable name. I wanted to glue text such as "proj" in front of the interpolated value of an environment variable named, say, value to construct the name of a new environment variable that I could then manipulate. To illustrate, if id had the value 3, then I wanted the statement

proj$id=5

to set an environment variable named proj3 to the value 5. This would be the key to a loop that would iterate through all my desired values for id and generate the required shell functions.

The line of code shown above, however, just choked the shell interpreter. And it continued to do so no matter how many pairs of curly braces, single-, double-, or back-quotes I tried inserting. If you are a true UNIX Wizard, you might very well be laughing right now at my ignorance, or at least shaking your head with pity . . . but, with the experience born of many years of UNIX exploits, I did what always seems to work more quickly and easily than attempting to decipher the man pages: I sought help. Sydney Weinstein finally provided the missing link: the shell's eval command.

eval to the Rescue

Any arbitrary piece of shell script can be constructed first, then submitted for same-level interpretation by use of the shell intrinsic eval. Thus, if id has been set to 3, then the statement

eval "proj$id=5"

submits the text

proj3=5

for evaluation, and the shell ends up successfully setting variable proj3 to the value 5. Armed with this technique, I could now automate the dynamic construction of my shell functions at the start of a login session.

The Project Directory

The final version of the project directory system (Listing 2) uses a directory named .Proj in the home directory to hold one status file for each of the currently defined scratchpad and project registers. Each status file contains a single directory path as defined by either a setR function call (for scratchpad registers) or a pR function call (for project registers).

Scratchpad Registers

The scratchpad register status files are named Rdir, where R is the name of the register and the corresponding environment variables are simply named R (to shorten the amount of typing necessary when using the environment variable name in commands). Although I use only x, y, and z as scratchpad register names, the mechanism supports as many register names as you care to list in the SCRATCHDIRS variable (line 16). Each register name may be up to 10 characters in length on systems with a 14-character filename limit. The predefined functions for each scratchpad register R are: