smartcd - make your shell come alive

WHAT IS SMARTCD?

smartcd is a library for bash and zsh which brings transformative power to your fingertips.

The basic premise is that as you move around your computer using the shell, actions can be automatically taken to provide you with the environment you really want, not the one you're accustomed to putting up with.

Have you ever...

Created a file for a project to alter your environment by setting variables or creating aliases so that things work correctly, one which you need to remember to load by hand
Struggled to set up your shell's configuation to support conflicting needs for different uses
Wished that your prompt could be made to say something or be a different color when you are in a sensitive directory
Wanted a daemon process to run automatically when you go to work on a project, and shut down when you finish
Wanted to automatically update your project from source control when you enter
Needed to attach to a particular screen(1) session when working in a particular directory

These are just a few examples of problems people are solving with smartcd.

OK, HOW DO I USE IT?

It's stupid easy. If you have already downloaded the archive or checked out the source, you can:

make install
source load_smartcd
smartcd config

However, if you would rather skip all that and simply have it install itself, try this:

curl -L http://smartcd.org/install | bash

wget --no-check-certificate -O - http://smartcd.org/install | bash

Either method will prompt you to configure a small number of settings, and then help you set up your shell to load it on login.

Once it is installed, you're ready to go. All actions are available through the smartcd command.

Usage: smartcd (edit|append|show|delete|filename|helper|template|setup|config) [args]

If you run smartcd edit enter, it will launch your editor to allow you to begin creating a script for the current directory which will run when you enter. Its counterpart, smartcd edit leave, will create a script that runs when you cd away from the current directory.

An auxiliary library is provided with smartcd called varstash. This provides you with a powerful mechanism which saves the definitions of variables, aliases, and shell functions to allow you to change or unset them temporarily. Once you are finished, it will allow you to (or automatically) restore their prior values.

For example,

autostash PATH=/path/to/my/project/bin:$PATH
autostash alias restart="apachectl restart"
restart

will save the value of your $PATH, and prepend a project-specific directory to it. smartcd will automagically restore its old value when you leave the directory.

The second line creates a temporary alias which is probably something only meaningful to the directory you are in, allowing you to keep concise aliases that won't get in your way, and allow you to re-use them between projects.

And these commands are immediately available, as shown by the third line, which makes use of the newly defined alias to restart your server.

You could instead create the files non-interactively

echo 'autostash PATH=__PATH__/temporary/path:$PATH' | smartcd edit enter

which also highlights a convenient feature that replaces __PATH__ with the directory name before the script is run.

If you like doing things by hand, you may prefer

mkdir -p ~/.smartcd/scripts/some/directory
echo 'autostash PATH=__PATH__/temporary/path:$PATH' >> ~/.smartcd/scripts/some/directory/bash_enter

HOW DOES IT WORK?

Scripts for smartcd are contained in a directory structure under your home, in the .smartcd directory. As you change directory, it will look for files which correspond to where you are leaving from and going to, and run them for you.

The primary way of doing this is to create a "cd" function which calls smartcd cd. This also works with push and popd. The simplest way to create these wrappers is to call smartcd setup cd, smartcd setup pushd, and smartcd setup popd. When you smartcd config, this will be set up for you.

If you prefer (or in addition), you can hook the prompt command. This sets PROMPT_COMMAND in bash, or precmd in zsh. This is enabled using smartcd setup prompt-hook. After calling smartcd, it will call any prior command for those hooks. This feature allows users with the "autocd" option set in their shell to also benefit from smartcd.

The structure of .smartcd will mirror the filesystem hierarchy you wish to configure. For example:

  Path         Action      Script
------------------------------------------------------------
 /foo/bar       enter     ~/.smartcd/scripts/foo/bar/bash_enter
 /foo/bar/baz   leave     ~/.smartcd/scripts/foo/bar/baz/bash_leave

You can edit and read these files with the smartcd command using the "edit", "append", "show", and "filename" actions.

user@host:/usr/local/bin$ smartcd filename enter
/home/user/.smartcd/scripts/usr/local/bin/bash_enter

user@host:/usr/local/bin$ smartcd show leave
No leave script for /usr/local/bin

user@host:/usr/local/bin$ smartcd show enter
# ---8<--- begin /home/user/.smartcd/scripts/usr/local/bin/bash_enter
smartcd inform "testing"
# ---8<--- end /home/user/.smartcd/scripts/usr/local/bin/bash_enter

# edit ~/.smartcd/scripts/usr/local/bin/bash_enter
user@host:/usr/local/bin$ smartcd edit enter

# truncate ~/.smartcd/scripts/usr/local/bin/bash_enter and replaces
# its contents with what is piped
user@host:/usr/local/bin$ echo "some-command" | smartcd edit enter

# add a line to ~/.smartcd/scripts/usr/local/bin/bash_enter
user@host:/usr/local/bin$ echo "some-command" | smartcd edit enter

One thing to note is that going from a directory to its child is not considered "leaving", so the bash_leave will not be run until you go to another directory that doesn't contain that same directory as part of its path. The scripts are run as appropriate if they exist for each level going back to the common element between the paths.

If you cd from /foo/bar/baz to /foo/quux/biff, the following actions would take place:

1) bash_leave for /foo/bar/baz
2) bash_leave for /foo/bar
3) bash_enter for /foo/quux
4) bash_enter for /foo/quux/biff

These scripts are run in the interactive shell using eval, so any variables or other environment effects will take place in the user's shell directly.

WHAT ARE SOME COMMON RECIPES?

Here are some examples of useful setups that have been created so far

SILENCE SMARTCD

smartcd is by default verbose about what it does.

This can be silenced either by setting the environment variable SMARTCD_QUIET

export SMARTCD_QUIET=1

Or you can quiet smartcd by setting the silence parameter in smartcd's configuration file: ~/.smartcd_config

SMARTCD_QUIET=1

DISPLAY A MESSAGE

Sometimes you may want a message to be shown when you enter or leave the directory, either to remind to you do something, or simply to let you know what the script has done.

You could use echo for this, but the issue with that is if you are doing something sophisticated with pipes, you may not want this message to interfere with the command being piped. For example, you might use the following command to copy some files

( cd foo; tar -cf - sub-dir ) | ( cd bar; tar -xf - )

but if "foo" has an enter script which echos something, this will corrupt the tar file. By using smartcd inform, this will suppress the output when it is detected that the output is not a terminal

smartcd inform "Reminder, don't forget to commit your code!"

PROMPT COLOR

If you want a visual cue that you need to be careful, it might make sense to change your prompt. Here's one that will temporarily make your prompt red while leaving its actual value alone.

autostash PS1='\[\e[1;31m\]'"$PS1"'\[\e[0m\]'

Note the double-quotes around $PS1. This is not superfluous, if your current value has any space characters in it, it's important to use quoting because otherwise it would be seen as a second argument to autostash

SCREEN

This one can be a bit tricky since screen commands from within screen tend to confuse it. And of course, creating a new screen window will execute your bash_enter scripts.

So what we'll do is set a variable in the attaching shell which is seen from within screen to prevent it from doing so.

if [[ -z $MYSCREEN ]]; then
    autostash MYSCREEN=1
    screen -c __PATH__/.screenrc -RRD my-special-screen-session
fi

PERLBREW

perlbrew is a system for installing multiple builds and versions of the Perl language, allowing you to easily switch between them. This is very valuable for development, but probably not what you want for your whole system.

smartcd now ships with a helper designed to integrate perlbrew and smartcd seamlessly together. Simply put this line in your enter script:

smartcd helper run perlbrew init /path/to/perlbrew/install

When you leave the directory, perlbrew will stop being in effect and you will get your previous perl back.

perlbrew is available at http://search.cpan.org/~gugod/App-perlbrew/

local::lib

Perl currently ships with a module named local::lib, which is handy for installing module dependencies outside of the standard install locations.

A helper is included for interacting with this module as well.

smartcd helper run perl-locallib activate __PA

Smartcd

Install / Use

README