Teleport: The Unix/Linux ‘cd’ command, improved

Summary: By keeping a history of the directories you've visited, the Teleport command is an improvement on the Unix/Linux cd command. By having a memory, Teleport lets you jump from one directory to any previously visited directory, easily.

January, 2015 Update: The Teleport command now supports Bash completion. For more details on this, see the Github INSTALL.md file.

A few quick notes:

• If you're just looking for the Download link, it's at the bottom of this article.
• If you'd like to see the Teleport command in action, I created this Teleport command video on YouTube:

The Teleport command

I've named the command "teleport", and it's intended to be a replacement for the Unix/Linux cd command. Really, it's a wrapper around the cd command, first doing all of its own work related to keeping a history, and then issuing the appropriate Linux cd command.

The teleport command (tp, for short) does everything the Linux cd command does, with these improvements:

• It keeps a history, remembering the directories you've visited before.
• It can display your history.
• You can easily jump to any directory in your history.
• And you can create aliases for your directories to make it even easier to jump to them.

Teleport command help

Once installed, you can get help on the teleport command by issuing the -h flag, like this:

tp -h

This displays a usage statement similar to the following:

Usage:      tp [DIR]

Purpose:    Provide the same capabilities as the 'cd' command, but with a memory
            of directories that you have previously visited.

  -h        Show HELP (this output)
  -j PARTIAL-DIR
            JUMP to a directory found in your history (by partial directory name)
  -l        LIST the history of visited directories
  -n [NUM]
            Go to a directory by NUMBER. NUM corresponds to the number printed
            by the -l option. If NUM is not specified then a list of visited
            directories is shown and user can pick a number.
  -s DIR    SEARCH for and display a directory named DIR found in your history

Given that starter information, let's see what the teleport command can do.

For basic use, tp is just like cd

For basic cases, you'll use the tp command just like the cd command. For instance, to move to your home directory, just type tp by itself, just like you would with the cd command:

tp

Or, if you prefer more typing, you can add the ~ character:

tp ~

Either one of those commands will take you to your home directory, just like cd.

To move back to your last directory, just add a -, again, just like cd:

tp -

To move to a local subdirectory named Pictures, again just replace the cd command with tp:

tp Pictures

To move to an absolute directory, like /tmp, again tp works just like cd:

tp /tmp

And to move up two directory levels, again, tp is the same:

tp ../..

Nothing too exciting yet ... so far it it works just like the Unix/Linux cd command. Now let's have some fun.

Basic teleporting

Where the tp command really shines is with its memory. For instance, let's say your current working directory is something like this:

/tmp/foo/bar/baz

Next, let's assume you want to move to another directory somewhere else in the filesystem, like this one:

/home/al/Pictures/2008/AlaskaTrip/Talkeetna

With the cd command, you'd normally have to type something like this:

cd /home/al/Pictures/2008/AlaskaTrip/Talkeetna

But with the tp command, if you've already been to the Talkeetna subdirectory, all you have to type is this:

tp Talkeetna

The teleport command instantly takes you to that directory. In this case, that saves you over 30 characters of typing.

Here's an image showing a few more examples of how easily the Teleport command lets you jump around:

This is one example of what remembering your working directory history can do for you, and is the primary reason for the name "teleport".

Listing your teleport history

The next nice thing teleport does is provide a listing of your teleport history. When you issue the teleport "list" command, like this:

tp -l

teleport will show you all the directories you've visited recently, like this:

43  /Users/al/Projects/DD/Sketch
44  /Users/al/Desktop
45  /Users/al/Projects/DD/Imagen/release
46  /Users/al/Projects/DD/Hyde/build
47  /Applications/MAMP/htdocs/minime/sites/all/modules/minime
48  /Applications/MAMP/logs
49  /Users/al/Projects/DD/Imagen/build
50  /Users/al/Working/Cato-CRUD-Generator
51  /Applications/MAMP/htdocs/cato
52  /Users/al/Projects/DD/Imagen
53  /Applications/MAMP/htdocs/cato/templates
54  /Applications/MAMP/htdocs/sleetmute

I like this feature because (a) I work on a lot of different projects every week, and (b) I have a bad memory. With the teleport command, it's much easier to remember where all my project files are located.

Also, once you've seen this history, you can teleport to any of those directories very easily. For instance, no matter where I am currently in the filesystem, if I want to go to this directory:

/Applications/MAMP/htdocs/minime/sites/all/modules/minime

all I have to type is this command:

tp minime

and I'm instantly teleported to that directory. I think you'll agree that's a really nice time-saver.

Teleport by number

The teleport command also includes an option to let you teleport to a directory by the number that is shown when you list the teleport history. For instance, using the listing shown above, I can teleport to the same 'minime' directory by typing this -n command:

tp -n 47

This is a nice feature for many purposes, especially when you have multiple directories that end with the same name.

New in Version 0.5: Thanks to a nice contribution by John Santos (somewhere in Portugal), the '-n' command has been significantly improved. Now, instead of typing '-l' and then using those results to feed the '-n' command, if you now type the -n command without a number, like this:

tp -n

the Teleport command will automatically give you the -l history list, and prompt you for a selection, like this:

50  /Users/al/Working/Cato-CRUD-Generator
51  /Applications/MAMP/htdocs/cato
52  /Users/al/Projects/DD/Imagen
53  /Applications/MAMP/htdocs/cato/templates
54  /Applications/MAMP/htdocs/sleetmute

Pick a number or press [Enter] 
  
  
   
    to cancel: _ 
  
  

If you've used the Teleport command before, you know this is a sweet addition. I suspect most people will now just use the -n option, and -l will mostly hang around for legacy purposes.

Bash completion with Teleport

Thanks to a nice addition by SneakyBobito, Teleport now supports Bash completion. This is described in detail in the Github INSTALL.md file, but in short, if you have a directory named TwitterClient in your history and you begin to type this tp command at the Unix command prompt:

$ tp Twit

and then hit the [Tab] key, the new completion code will scan your Teleport history file, and if it finds any matches, it will automatically complete the directory name on the command line. For instance, I have a directory named TwitterClient in my .tp_history file, so when I type this:

$ tp Twit[Tab]

my command is expanded to this:

$ tp TwitterClient

This is a terrific new addition to the Teleport command.

In addition to all of these features, you can also use teleport aliases.

Teleport aliases

Teleport aliases provide a simple way for you to create aliases to directories. If you want to resolve conflicts between multiple directories with the same name (as I just showed in the previous section), or you simply want to make sure teleport always knows about a certain directory, you can create an alias for that directory.

Currently the teleport alias works as a separate command named tpa. (I've thought about merging the tp and tpa commands into one command, but have not done so yet. After using the commands for a while, I'll be glad to hear your opinion on whether they should be merged together, or not.)

Here's the usage statement for the teleport alias (tpa) command:

Usage:           tpa ALIAS
Purpose:         Transport to a directory that has an alias ALIAS associated with it.

  -a ALIAS DIR   Add ALIAS as an alias/shortcut for the directory DIR
  -h             Show HELP (this output)
  -l             LIST the known directory aliases
  -r ALIAS       Remove ALIAS from your list of known aliases

Adding/creating a teleport alias

To add a new teleport alias, use the -a option, and specify the alias first, followed by the actual directory name, like this:

tpa -a baz /tmp/bar/baz

After issuing that command you'll see output similar to this:

Alias "baz" was added for the directory "/tmp/bar/baz".

Using a teleport alias

Once you've created an alias like that, no matter where you are on the filesystem, you can move to that directory using your alias with the tpa command, like this:

tpa baz

Listing your teleport aliases

To list your teleport aliases, just use the -l option of the tpa command, like this:

tpa -l

This will list all of the aliases you've defined, like this:

perl:/Users/al/AlsLife/DD/Perl
arrays:/Users/al/AlsLife/DD/Perl/ArrayTests
pub:/Users/al/AlsLife/DD/Perl/published

(I need to improve this format, but that's the way it looks currently.)

Removing an alias

To remove a tpa alias, just use the -r option and the name of the alias, like this:

tpa -r pub

The tpa command responds like this:

About to remove alias "pub" -- are you sure (y/[n])?: _
Remove operation cancelled.

At this point 'n' will cancel the remove operation, and 'y' will proceed with the remove.

A tpgrep command

It’s now May, 2020, and I just added a tpgrep command to my personal installation. (It’s not in the download below.) As its name implies, this command makes it easy to grep my ~/.tp_history file. I currently have 192 directories in that file, so it’s nice to have a command like this:

$ tpgrep html

/Users/al/Projects/Books/ScalaBook/html
/Users/al/Projects/Books/HelloScala/AmazonKindleVersion2/HtmlForAmazon
/Users/al/Projects/Scala/AsciiDocToHtml
/Users/al/Projects/Scala/FunctionalProgramming/FPBook/Pandoc/PdfOfBook/HtmlForAmazon
/Users/al/Projects/Scala/FunctionalProgramming/FPBook/Pandoc/FPSimplified/HtmlForAmazon
/Users/al/Projects/Scala/FunctionalProgramming/FPBook/Pandoc/AmazonKindle/BookAsHtml

As that output shows, the tpgrep command does a `grep -i` on the name you supply. If you’re interested in this shell script, here’s its source code:

if [ $# -eq 0 ]; then
    echo "Please provide the file/directory name you want search for."
    echo "USAGE: tpgrep foo"
    echo "       That commands shows all match in the ~/.tp_history file."
    exit 1
fi

grep -i $1 ~/.tp_history

I can make that fancier, but it works for today.

Summary

I hope you like the teleport command. I think it makes some nice improvements to the standard Linux cd command.

The hardest part for me when I first started using it was remembering to type tp instead of cd. Once I made it through that mental hurdle, I now hate to work on systems where I haven't installed the teleport command yet.

Download

You can download the teleport command as a tar'd and gzip'd file from the following link:

• Click here to download the teleport command
  (md5sum: 2159de9e82e9a4ccee6a450fa8cb75c2)

This file will extract to a directory named teleport, and that directory will contain the following files:

teleport/tp_command
teleport/INSTALL
teleport/LICENSE

Once you've extracted the contents of this file, you can proceed with the installation. See the INSTALL file for more information.