z.lua

A command line tool which helps you navigate faster by learning your habits :zap:

An alternative to z.sh with windows and posix shells support and various improvements.

【README in Chinese | 中文文档】

Description

z.lua is a faster way to navigate your filesystem. It tracks your most used directories, based on 'frecency'. After a short learning phase, z will take you to the most 'frecent' directory that matches ALL of the regexes given on the command line, in order.

For example, z foo bar would match /foo/bar but not /bar/foo.

Reputation

From people using z.lua:

• I like this in principal. I’m pretty damn predictable at the command line and far too lazy to make shortcuts
• It feels far more intuitive and it's so incredibly convenient to be able to jump between folders I'm working in without having to traverse an entire tree. The shell used to feel so constraining for me, but tools like this are making me enjoy it so much more.
• I can finally have autojump-like functionality on my Raspberry Pi 1 without waiting 30 seconds every time I open a new shell. Thanks z.lua devs.
• Anyway, z.lua is a promising project. If you only need directory jumping, it may be the best choice.

Features

• 10x times faster than fasd and autojump, 3x times faster than z.sh.
• Gain the ultimate speed with an optional native module written in C.
• Available for posix shells: bash, zsh, dash, sh, ash, ksh, busybox and etc.
• Available for Fish Shell, Nushell, Power Shell and Windows cmd.
• Enhanced matching algorithm takes you to where ever you want precisely.
• Allow updating database only if $PWD changed with "$_ZL_ADD_ONCE" set to 1.
• Interactive selection enables you to choose where to go before cd.
• Integrated with FZF (optional) for interactive selection and completion.
• Quickly go back to a parent directory instead of typing "cd ../../..".
• Corresponding experience in different shells and operating systems.
• Compatible with Lua (5.1, 5.2, 5.3+) and luajit.
• Self contained, distributed as a single z.lua script, no other dependence.

Examples

z foo        # cd to most frecent dir matching foo
z foo bar    # cd to most frecent dir matching foo and bar
z -r foo     # cd to the highest ranked dir matching foo
z -t foo     # cd to most recently accessed dir matching foo
z -l foo     # list matches instead of cd
z -c foo     # restrict matches to subdirs of $PWD
z -e foo     # echo the best match, don't cd
z -i foo     # cd with interactive selection
z -I foo     # cd with interactive selection using fzf
z -b foo     # cd to the parent directory starting with foo
z -b foo bar # replace foo with bar in cwd and cd there

Install

• Bash:

  put something like this in your .bashrc:

  eval "$(lua /path/to/z.lua --init bash)"
  

  the default matching algorithm is similar to z.sh to keep compatible, you may like the enhanced matching algorithm for productivity:

  eval "$(lua /path/to/z.lua --init bash enhanced once)"
  

  and perhaps this:

  eval "$(lua /path/to/z.lua --init bash enhanced once echo)"
  

  if you want z.lua print the new directory after cd.

  For fzf tab completion use:

  eval "$(lua /path/to/z.lua --init bash enhanced once fzf)"
  

  NixOS users using home-manager can add this to their user profile:

  programs.z-lua.enable = true;
  programs.z-lua.enableBashIntegration = true;
  programs.z-lua.options = [ "enhanced" "once" "fzf" ];  # modify as needed
  

  NOTE: For wsl-1 users, lua-filesystem must be installed:

  sudo apt-get install lua-filesystem
  

  To avoid a wsl-1 defect.

• Zsh:

  put something like this in your .zshrc:

  eval "$(lua /path/to/z.lua --init zsh)"
  

  Options like "enhanced", "once" and "fzf" can be used after --init too. It can also be initialized from "skywind3000/z.lua" with your zsh plugin managers (antigen / oh-my-zsh).

  NixOS users using home-manager can add this to their user profile:

  programs.z-lua.enable = true;
  programs.z-lua.enableZshIntegration = true;
  programs.z-lua.options = [ "enhanced" "once" "fzf" ];  # modify as needed
  

  NOTE: for wsl-1 users, lua-filesystem must be installed.

• Posix Shells:

  put something like this in your .profile:

  eval "$(lua /path/to/z.lua --init posix)"
  

  For old shells like ksh (Korn Shell), some features are missing, you can try:

  eval "$(lua /path/to/z.lua --init posix legacy)"
  

  To generate old posix compatible script.

• Fish Shell (version 2.4.0 or above):

  Create ~/.config/fish/conf.d/z.fish with following code

  lua /path/to/z.lua --init fish | source
  

  If you'd like z.lua to cooperate with fish's own directory history, you can put

  set -gx _ZL_CD cd
  

  into the same file.

  NixOS users using home-manager can add this to their user profile:

  programs.z-lua.enable = true;
  programs.z-lua.enableFishIntegration = true;
  programs.z-lua.options = [ "enhanced" "once" "fzf" ];  # modify as needed
  

• Nushell

  Put something like this in your env.nu:

  lua /path/to/z.lua --init nushell | save -f ~/.cache/zlua.nu
  

  Then put something like this in your config.nu:

  source ~/.cache/zlua.nu
  

  Note: Only Nushell v0.96+ is supported

• Power Shell:

  ⚠️ WARNING: users of Starship Prompt should add the following command after starship init.

  put something like this in your profile.ps1:

  Invoke-Expression (& { (lua /path/to/z.lua --init powershell) -join "`n" })
  

• Windows cmd (with clink):

  • Copy z.lua and z.cmd to clink's home directory
  • Add clink's home to %PATH% (z.cmd can be called anywhere)
  • Ensure that "lua" can be called in %PATH%

• Windows cmder:

  • Copy z.lua and z.cmd to cmder/vendor
  • Add cmder/vendor to %PATH%
  • Ensure that "lua" can be called in %PATH%

• Windows WSL-1:

  Install lua-filesystem module before init z.lua:

    sudo apt-get install lua-filesystem
  

  This module is required due to a wsl-1 defect.

Options

• set $_ZL_CMD in .bashrc/.zshrc to change the command (default z).
• set $_ZL_DATA in .bashrc/.zshrc to change the datafile (default ~/.zlua).
• set $_ZL_NO_PROMPT_COMMAND if you're handling PROMPT_COMMAND yourself.
• set $_ZL_EXCLUDE_DIRS to a comma separated list of dirs to exclude.
• set $_ZL_ADD_ONCE to '1' to update database only if $PWD changed.
• set $_ZL_MAXAGE to define a aging threshold (default is 5000).
• set $_ZL_CD to specify your own cd command (default is builtin cd in Unix shells).
• set $_ZL_ECHO to 1 to display new directory name after cd.
• set $_ZL_MATCH_MODE to 1 to enable enhanced matching.
• set $_ZL_NO_CHECK to 1 to disable path validation, use z --purge to clean
• set $_ZL_HYPHEN to 0 to treat a hyphen (-) as a lua regexp special character, set $_ZL_HYPHEN to 1 to treat a hyphen as a normal character. If $_ZL_HYPHEN is not set or if it is set to auto, z.lua tries to treat - as a lua regexp special character first. If there are no matches, z.lua tries again, this time treating - as a normal character.
• set $_ZL_CLINK_PROMPT_PRIORITY change clink prompt register priority (default 99).

Aging

The rank of directories maintained by z.lua undergoes aging based on a simple formula. The rank of each entry is incremented every time it is accessed. When the sum of ranks is over 5000 ($_ZL_MAXAGE), all ranks are multiplied by 0.9. Entries with a rank lower than 1 are forgotten.

Frecency

Frecency is a portmanteau of 'recent' and 'frequency'. It is a weighted rank that depends on how often and how recently something occurred. As far as I know, Mozilla came up with the term.

To z.lua, a directory that has low ranking but has been accessed recently will quickly have higher rank than a directory accessed frequently a long time ago. Frecency is determined at runtime.

Default Matching

By default, z.lua uses default matching algorithm similar to the original z.sh. Paths must be match all of the regexes in order.

• cd to a directory contains foo:

  z foo
  

• use multiple arguments:

  Assuming the following database:

  10   /home/user/work/inbox
  30   /home/user/mail/inbox
  

  "z in" would cd into /home/user/mail/inbox as the higher weighted entry. However you can pass multiple arguments to z.lua to prefer a different entry. In the above example, "z w in" would then change directory to /home/user/work/inbox.

• use regexes:

  z foo$   # cd to a directory ends with foo
  z %d     # cd to a directory that contains a digit
  

  Unlike z.sh, z.lua uses the Lua regular expression syntax.

Enhanced Matching

Enhanced matching can be enabled by exporting the environment:

export _ZL_MATCH_MODE=1

Or, append a enhanced after --init xxx:

eval "$(lua /path/to/z.lua --init bash enhanced)"

For a given set of queries (the set of command-line arguments passed to z.lua), a path is a match if and only if:

1. Queries match the path in order (same as default method).
2. The last query matches the last segment of the path.

If no match is found, it will fall back to default matching method.

• match the last segment of the path:

  Assuming the following database:

  10   /home/user/worksp