zsh-trampoline

Jump to the places that matter to you.

What is this?

This is a plugin for Zsh that reduces the time it takes to (a) cd to a commonly visited dir and to (b) open in an editor a recurring file. The plugin is very simple, it displays all your configured dirs and files in fzf, always in the same order.

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 the global parameter ZT_CONFIG that you need to define. While in fzf, press ctrl+t to toggle showing only the dirs and files explicitly listed in ZT_CONFIG. 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 can remove this line.
   )
   zt_setup_widget_jump_to_file
   # 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_jump_to_file).

Parameter ZT_CONFIG

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 to use the export keyword. That is, this could be a valid entry in ZT_CONFIG: '${MY_VAR}'. The plugin does the expansion.
• On ctrl+t specifically 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 which are in ZT_CONFIG, avoiding the sub-dirs replacement.
• While in fzf, on ctrl+t specifically what gets listed is:
  • Allows to toggle between initial listing and items as-are from ZT_CONFIG.

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_jump_to_file when integrating with ZVM.

  function zvm_after_init {
    zt_zvm_setup_widget_jump_to_file
  }
  

Optional configuration

Optional configuration is provided through parameters.

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

Similar projects

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