Recently in Shell scripting Category

As I wrote about previously, using bash_varstash and bash_smartcd you can set up your bash shell to set important environment variables without intervention when changing to particular directories, and have it automatically restore them to their previous state when leaving.  The library is on github.

While this library has served me very well, I've now released a new version with several significant and interesting changes.


First is the addition of a new command, called autostash. It will perform the unstash for you, if run from smartcd, when the directory is left, without explicit configuration.  This significantly lowers the already fairly low bar for using this feature, and adds a bit more DTRT.

An example might now look like this:

autostash PATH
export PATH=/foo:$PATH

and that's all you need!  Maybe in a later release, these can be combined into a single command, but not today.

New script layout

Second is a complete change in structure in how the scripts themselves are located and executed.  Previously, files would be co-located with the directory they correspond to.  For example, the directory /foo/bar would contain the file /foo/bar/.bash_enter which would be run upon 'cd'ing into it.  Now, however, the files are located in a hierarchy under your home directory, primarily for security reasons.

To make the transition easier, if a legacy script is found, smartcd will notify you about it and tell you how to migrate it to the proper location.  In addition, if you manually run stash, unstash, or autostash, they too will tell you how to create a proper script to automate the action you just ran.

Here are some examples of this in action:

$ cd my-project/
# NOTICE!  Deprecated .bash_enter found, please migrate this file to the new
# format using the following (or similar) commands:
mkdir -p "/home/username/.smartcd/home/username/my-project"
cat "/home/username/my-project/.bash_enter" >> "/home/username/.smartcd/home/username/my-project/bash_enter"
rm "/home/username/my-project/.bash_enter"

$ autostash PATH
# You are manually autostashing a variable.  To automatically perform this
# whenever you enter this directory, paste the following command(s):
mkdir -p "/home/username/.smartcd/home/username/my-project"
echo autostash PATH >> "/home/username/.smartcd/home/username/my-project/bash_enter"

To turn off these help messages, you can set the variable VARSTASH_QUIET

Interactive and automatic configuration

To additionally simplify configuring things, some additional methods for editing the bash_enter and bash_leave scripts are provided.

If you just want the recommended actions listed in the previous section to be performed for you with no questions asked, you can set the variable VARSTASH_AUTOCONFIG

$ autostash foo
Automatically running echo autostash foo >> "/home/username/.smartcd/home/username/bash_enter"

If you simply want to open the file in your preferred editor, you can run varstash_edit

$ varstash_edit
Usage: varstash_edit ( bash_enter | bash_leave )
$ varstash_edit bash_enter
[ $EDITOR invoked on the correct bash_enter file ]

This can also happen automatically when you type stash, unstash, or autostash if you set the variable VARSTASH_AUTOEDIT.  This will first add the commands, as with VARSTASH_AUTOCONFIG, then launch your editor

Automatically running echo autostash foo >> "/home/username/.smartcd/home/username/bash_enter"
[ $EDITOR invoked on the correct bash_enter file ]
To scratch a few itches that I had, I wrote a number of bash functions.  These are published on Github at

This repository is made of 3 components, each of which are separately useful:

  • bash_arrays
  • bash_varstash
  • bash_smartcd
And with their powers combined, you can.. well let's not get ahead of ourselves.


Bash is a very featureful shell.  It has things that many people aren't even aware of.  One such feature, added in 2.0, is the ability for shell variables to be real arrays, instead of just strings.  Using string variables and IFS (Internal Field Separator, if you don't know, don't ask) to manage multiple values can be very frustrating.

You can initialize array variables with the syntax "name=(value1 ... valuen)", and assign individual elements like "name[subscript]=value".  You access them by index like "${name[subscript]}"

$ foo=(bar baz biff)
$ echo ${foo[2]}
$ foo[3]=blah
$ echo ${foo[3]}

$ foo[3]=blah
$ echo ${foo[3]}

However, this syntax is pretty awkward, and almost no convenience functions are supplied.  If you've worked with any high level dynamic languages, you'll be familiar with things such as push, pop, shift, unshift, and reverse.

These missing functions are provided by the included file bash_arrays, and are named
  • apush - add an element to the end of the array
  • apop - remove an element from the end of the array
  • ashift - remove an element from the beginning of the array
  • aunshift - add an element to the beginning of the array
  • areverse - reorder the array backwards
along with a few others
  • afirst - print the first element but leave it in place
  • alast - print the last element but leave it in place
  • alen - print the number of elements in the array
The "a*" naming convention is to indicate that they work on arrays, and to avoid possible naming conflicts with other functions that might use such common words.

Example usage:

$ apush foo bar baz biff
$ alen foo
$ apop foo
$ apop foo
$ apop foo

Unfortunately, there isn't a simple way to both modify a shell variable and "return" a value. The only way to capture a non-numeric return value is by executing a sub-shell, which will modify the value only in the sub-shell.  The modification is of course lost when that shell exits.

bar=$(apop foo) # $bar has a value, but $foo is unmodified!

To work around this shortcoming, the mutators (functions which modify the array) that also need to return a value (apop and ashift) set a variable which contains the returned value, $_apop_return and $_ashift_return respectively.

apop foo >/dev/null # run in current shell, and quiet output


This file provides 2 functions, stash and unstashstash stores the value of a variable to a temporary location.  unstash restores its value from the temporary variable and deletes it.  The name of the temporary variable is derived from the current working directory of the shell, which means you'll need to be in the directory you stashed from to unstash properly.

$ export FOO=bar
$ echo $FOO
$ stash FOO
$ export FOO=baz
$ echo $FOO
$ unstash FOO
$ echo $FOO

While this might sound a bit arcane, it is specifically useful with...


This file provides a replacement for cd.  It runs the specially named ".bash_enter" shell script when it enters a directory, and runs ".bash_leave" when it moves away, using the bash_arrays functions to keep track of things.

Once loaded, it's enabled by simply adding

alias cd=smartcd

to your shell initialization file.  All path differences are incrementally inspected when changing directories, so it will "leave" the necessary path elements before "entering" the new ones.

For example:

/foo/bar/baz$ cd /foo/biff

This would "leave" baz, then bar, and then enter biff. /foo is ignored because it is common to both paths.

And now for the motivating reason for all of these libraries...


When smartcd is combined with stash and unstash, you can achieve something pretty amazing: per-directory environment variables.  These can be useful for many things, including automagically modifying PATH, PERL5LIB, ORACLE_HOME, or any number of other settings you might want to tweak when you cd into a development directory or some other special environment.  If set up properly, they will be restored to their original values when leaving.

Let's inspect the scripts:

$ cat foo/.bash_enter
echo entering `pwd`
stash FOO
export FOO=baz

$ cat foo/.bash_leave
unstash FOO
echo leaving `pwd`

$ cat foo/bar/.bash_enter
echo entering `pwd`
stash FOO
export FOO=biff

$ cat foo/bar/.bash_leave
unstash FOO
echo leaving `pwd`

Notice that you can stash the same variable multiple times, at different levels.  Now, let's set the variable and try it out.

$ export FOO=bar

$ cd foo
entering /home/count/foo

$ echo $FOO

$ cd bar
entering /home/count/foo/bar

$ echo $FOO

$ cd
leaving /home/count/foo/bar
leaving /home/count/foo

$ echo $FOO

Enhanced by Zemanta

About this Archive

This page is an archive of recent entries in the Shell scripting category.

Linux is the previous category.

Find recent content on the main index or look in the archives to find all content.