zsh-trampoline

Zsh plugin leveraging fzf to jump to the places that matter to you.

What is this?

This is a Zsh plugin to efficiently cd to commonly visited dirs. The plugin displays all your configured dirs in fzf always in the same order. Think of it like a simple zoxide just for Zsh. The plugin can also open files in $EDITOR.

Usage

While on the shell, press ctrl+t to start fzf with dirs and files to "jump" to: cd or open with $EDITOR. This list is taken from $ZT_CONFIG that you need to define. Press enter to select.

Installation

Without a plugin manager

1. Install fzf version >=0.45. Homebrew command: brew install fzf.

2. Clone the zsh-trampoline Git repository by executing the below command:

   git clone 'https://github.com/hernancerm/zsh-trampoline.git' \
     "${HOME}/.zsh-trampoline/zsh-trampoline"
   

3. Place the below snippet at the end of your file ~/.zshrc:

   # ZSH-TRAMPOLINE - Start - <https://github.com/hernancerm/zsh-trampoline>.
   source "${HOME}/.zsh-trampoline/zsh-trampoline/trampoline.plugin.zsh"
   ZT_CONFIG=(
     # Place each dir and file you want to jump to in a new line.
     ~ # Example, you likely want to remove this line.
   )
   zt_setup_widget
   # ZSH-TRAMPOLINE - End.
   

4. Start a new shell.

With a plugin manager

If you feel comfortable with shell scripting and plan to install other Zsh plugins, like zsh-vi-mode, I recommend you use a shell plugin manager like Sheldon for the installation. Comparing this approach to the plugin-manager-less approach, the plugin manager would be in charge of doing the git clone (step 2) and sourcing the plugin on startup (line beginning with source from the snippet of step 3, you still need to define ZT_CONFIG and call zt_setup_widget).

Parameter ZT_CONFIG

Example definition:

ZT_CONFIG=(
  ~/dev/gc
  ~/dev/gr
  ~/.dotfiles:0
  ~/dev/temp:0
  ${HISTFILE}
)

Some things to note:

• If your dir or file has whitespace chars, surround it with single quotes.
• Environment variables, defined as export MY_VAR=~/file/path, are supported quoted. Do not forget the export keyword. That is, this could be a valid entry in ZT_CONFIG: '${MY_VAR}'. The plugin does the expansion.
• On ctrl+t what gets listed is:
  • Files. Quoted env vars which point to a file are listed as the env var.
  • Level 1 sub-dirs of the dirs in ZT_CONFIG. Quoted env vars which point to a dir are treated as dirs.
  • Anything ending in :0. In this case the :0 is stripped. The purpose of this is to be able to list the dirs themselves instead of doing the level-1 sub-dirs expansion.

Integration with other Zsh plugins

• jeffreytse/zsh-vi-mode (ZVM). Binding ctrl+t is done inside a specific ZVM function, as below. Do not call zt_setup_widget when integrating with ZVM.

  function zvm_after_init {
    zt_zvm_setup_widget
  }
  

Optional configuration

(param) ZT_CONFIG_FILE:

Allowed values	Default value	Description
Any filepath	~/.config/zsh-trampoline/config.txt	Alternate configuration source to the ZT_CONFIG parameter. The contents of the file are the contents of the ZT_CONFIG param, with one item per line. For example, if ZT_CONFIG=(~/dev/gr ~/dev/temp:0), then config.txt should have two lines: ~/dev/gr as the first line, and ~/dev/temp:0 as the second line. This config file is only used when ZT_CONFIG is unset.

(param) ZT_CONFIG_FILE_SECRET:

Allowed values	Default value	Description
Any filepath	~/.config/zsh-trampoline/config_secret.txt	Used when ZT_CONFIG_FILE is used and expects the same file content structure. The configuration here is appended to the main config file.

(param) ZT_KEY_MAP_START:

Allowed values	Default value	Description
bindkey key map	^t	Key map to list dirs & files in fzf. Default: ctrl+t.

API

(fn) zt_get_items:

## Get the list of the configured items, optionally filtering by type.
## @param $1:string (optional) Item type filter, either 'd' for directory or 'f' for file.
## @stdout:string

Similar projects

• https://github.com/ajeetdsouza/zoxide
• https://github.com/wting/autojump
• https://github.com/agkozak/zsh-z