ctrlg ⌨️

Press ctrl + g to jump between projects using a fuzzy finder

^{Demo is using the tmux integration for floating window and lighthaus terminal theme.}

Ctrlg is a tool to quickly switch contexts to another directory, using a fuzzy finder. If enabled (by setting $CTRLG_TMUX to true), ctrlg can cd all split panes in the current window of a tmux session to the selected directory. Press ctrl + g to fuzzy find directories, configured by globbing patterns.

By default, only ~/git/* is searched. To change this or add additional directories to search, see configuration.

Install

With Cargo

cargo install ctrlg

cargo can be installed via rustup.rs.

With Installer Script

Do not run as root or with sudo, the script will ask for sudo if needed.

bash -c 'bash <(curl --proto "=https" --tlsv1.2 -sSf https://raw.githubusercontent.com/mrjones2014/ctrlg/master/install.bash)'

Manual

• Download the appropriate binary for your system from the latest GitHub Release
• Rename the binary ctrlg
• Make the binary executable via chmod +x ctrlg
• Put the binary anywhere on your $PATH, such as /usr/local/bin/ctrlg

Build and Install from Source

Requires cargo:

git clone git@github.com:mrjones2014/ctrlg.git
cd ctrlg
cargo install --path .

Shell Plugin

Once the CLI is installed, you will need to set up the key binding depending on your shell. Alternatively, you can disable the default keybind by setting $CTRLG_NOBIND to true before running the init script, then set up your own keybind to call ctrlgsearchandgo.

Fish

echo 'ctrlg init fish | source' >> ~/.config/fish/config.fish

Zsh

echo 'eval "$(ctrlg init zsh)"' >> ~/.zshrc

Bash

echo 'eval "$(ctrlg init bash)"' >> ~/.bashrc

Tmux Integration

To make ctrlg send the cd command to all split panes in the current tmux window, set the environment variable CTRLG_TMUX to true. You can also make the fuzzy finder appear in a tmux floating window, and specify the window size, with $CTRLGTMUXPOPUP and $CTRLGTMUXPOPUPARGS, respectively. $CTRLGTMUXPOPUPARGS can be any window positioning or sizing arguments accepted by tmux popup. $CTRLGTMUXPOPUP_ARGS defaults to -w 75% -h 75%.

You can also define a hook function to send the cd command to additional tmux panes not in the current window. The function must return a list of tmux pane IDs. The hook function is ctrlggetrelatedpanes.

Fish

set CTRLG_TMUX true
set CTRLGTMUXPOPUP true
IMPORTANT: quote each argument separately so that the variable is an array
set CTRLGTMUXPOPUP_ARGS "-w" "75%" "-h" "75%"

Bash or Zsh

export CTRLG_TMUX=true
export CTRLGTMUXPOPUP=true
for bash and zsh, quote all arguments together
export CTRLGTMUXPOPUP_ARGS="-w 75% -h 75%"

Key Bindings

| Key Binding | Function | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Enter | cd to the selected directory. If $CTRLG_TMUX is true, the cd command is sent to all split panes in the current window. | | Alt/Option + Enter | cd to the selected directory, then open $EDITOR if defined. The $EDITOR command is only run in the currently active tmux pane, if using the tmux integration. | | Alt/Option + o | Open $EDITOR to selected directory without cding the shell. | | Ctrl + o | cd to selected directory only in current tmux pane, do not send cd command to other tmux panes. | | Tab | Insert the selected directory path to the command line, but do not execute anything. Works in Fish and zsh only, in bash, acts the same as Ctrl + o. | | Ctrl + d | Scroll preview up. | | Ctrl + f | Scroll preview down. |

Configuration

ctrlg will look for a configuration file at ~/.config/ctrlg/config.yml. The default configuration is shown below:

# include other configuration files into this configuration file,
does not search recursively (e.g. you cannot include file from
an already included file). The include key is a yaml list
of file paths to include
include: []
configure what directories to list in the fuzzy finder
can be any list of globbing patterns, will only show directories
not files
search_dirs:
  - "~/git/*"
globbing patterns of files to find for use as preview
see below for more details on previews
preview_files:
  - "README.*"
enable or disable the preview window
previews: true
force using or not using glow for previews
this setting takes precedence over previewwithbat
this represents the default but in an actual
config file, this should just be true or false
previewwithglow: (true if glow is installed, false otherwise)
set the line-wrap width passed to glow via glow -w
glowwrapwidth: 80
force using or not using bat for previews
this represents the default but in an actual
config file, this should just be true or false
previewwithbat: (true if bat is installed and glow is NOT installed, false otherwise)
force using or not using exa for preview fallback when no
matching preview_files are found
this represents the default but in an actual
config file, this should just be true or false
previewfallbackexa: (true if exa is installed, false otherwise)
enable or disable showing git branch for directories
which are git repositories
showgitbranch: true
character to render between the directory name and git branch name
you can change this to a Nerd Font symbol if you like
such as git branch symbol: 
gitbranchseparator: "■"
customize color scheme
see section "Color Schemes" below for more details
colors:
  # directory name color
  dir_name: "cyan"
  # git branch color
  git_branch: "247,78,39" # this is git's brand orange color
  # name of theme to use for bat
  # see: https://github.com/sharkdp/bat#highlighting-theme
  bat_theme: "ansi"

Previews

Previews, if enabled, are generated by rendering the first file in each directory matching any of the specified preview_files globbing patterns. If a matching file is found, it will be rendered with bat by default if bat is installed, otherwise it will be rendered with cat. You can force using or not using bat with the previewwithbat option. You can default to always using the fallback instead of rendering a file by setting an empty list of globbing patterns, like: preview_files: [].

If no matching preview files are found, the directory listing is used as the preview. By default, directory contents are listed using exa by default if exa is installed, otherwise contents are listed using ls. You can force using or not using exa as the fallback preview using the previewfallbackexa option.

Color Schemes

Colors in the config file may be specified as a named color, a single integer corresponding to xterm-256 color codes, or an RGB triple of integers (e.g. 255,255,255). If an invalid color is specified (e.g. if you use decimals instead of integers, or an invalid named color), it will default to white. For xterm-256 or RGB colors to work, it must be supported by your terminal emulator. I recommend Kitty.

Named colors are the following:

• "black"
• "red"
• "green"
• "yellow"
• "blue"
• "purple"
• "cyan"
• "white"