A contemporary version of z - jump around.

Key Features • Installation • How To Use

contemporary-z_demo.mp4

Key Features

Contemporary-z (cz) is a modern version of z - jump around. It is implemented in Rust and utilizes temporary files for the inter-process communication with the shell.

For the time being, cz is available for fish shell, Bash and Zsh. Furthermore, it should be relatively easy to adapt it to more shells; it is only necessary to translate into the language of the new shell the z scripts (e.g. z.sh).

Installation

Availability

Linux-only.

• fish shell
• Bash
• Zsh

Install/update using installation script (recommended)

To install cz, you can just run the installation script.

python3 -c "$(curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/j-morano/contemporary-z/main/install)"

Install manually using binary release

To install the program using the binary release, copy and paste the following commands in your terminal.

NOTE: This is only for installing the first time, for updating, see below.

NOTE: In the following snippets, you can replace $HOME/.local/bin/ by any other dir in $PATH.

Fish

wget https://github.com/j-morano/contemporary-z/releases/latest/download/cz
chmod +x cz
mv cz $HOME/.local/bin/
wget https://raw.githubusercontent.com/j-morano/contemporary-z/main/z.fish
mkdir -p $HOME/.config/fish/functions
mv z.fish $HOME/.config/fish/functions

Bash/Zsh

wget https://github.com/j-morano/contemporary-z/releases/latest/download/cz
chmod +x cz
mv cz $HOME/.local/bin/
wget https://raw.githubusercontent.com/j-morano/contemporary-z/main/z.sh
cat z.sh >> $HOME/.bashrc

Update

wget https://github.com/j-morano/contemporary-z/releases/latest/download/cz
chmod +x cz
mv cz $HOME/.local/bin/

Install manually from source

To install cz from source, it is required to have installed Cargo, the Rust package manager. You can install Rust, with rustc and cargo, following the instructions on this page or from the official repositories of your distribution.

If this requirement is met, it is only necessary to clone the repository and run the specific installation script for the desired shell.

Debian-based distros

Clone the repository

git clone https://github.com/j-morano/contemporary-z.git

Install using Cargo

$HOME/.cargo/bin/cargo install --path .

NOTE: ensure that $HOME/.cargo/bin/ is in $PATH.

Then, depending on the shell, do the following.

NOTE: You must be inside the repository folder (contemporary-z) to run the commands as shown below.

Fish

Add the function to fish functions.

mkdir -p $HOME/.config/fish/functions
mv z.fish $HOME/.config/fish/functions

Bash/Zsh

Add the code from z.sh to .bashrc. For example:

cat z.sh >> $HOME/.bashrc

How to use

The default alias of Contemporary-z is z. However, if a different alias is preferred, it can be easily changed in the installation scripts. Hereafter, cz refers to the entire application, and z refers to the command.

Usage

To see the usage of cz, you can just run it with the --help argument.

$ z --help
Usage: z [OPTION]... [DIRECTORY|SUBSTRING]...

FUNCTIONALITY:
  * If no option nor directory or substrings are specified, 'cz' prints a
    numbered list of the most 'frecent' directories to select one of them by
    introducing its number.
  * If a directory alias is introduced, 'cz' does 'cd' to the directory.
  * If a directory name is introduced, 'cz' jumps to the directory (if
    available) and adds it to the directories database (if it is not already
    added).
  * If a substring or substrings are introduced, 'cz' searches in the database
    for coincidences. Then, if 'substring' is 'shortest' or the number of
    matches is equal to 1, it 'cd's to the directory with the shortest pathname.
    If 'substring' is equal to 'score', it goes to the directory with the
    highest score. Otherwise, it prints the interactive selection menu. If there
    is only one result, it always 'cd's to it.

OPTIONS:
Mandatory arguments to long options are mandatory for short options too.
  -                          go to the previous directory.
  =                          go to the current directory.
  -a [ALIAS] DIRECTORY       add directory alias; if only the directory is
                               introduced, its alias is removed; if only an
                               alias is introduced, the programs shows the
                               directory list to select one of them.
      --clear                clear the directories database.
  --database-path            show the path of the directories database.
  -e                         force substring matching by score.
  -f SUBSTRING               force substring match list for SUBSTRING
  -i                         interactive selection (using a numbered list) of
                               the subdirectories of the current directory.
      --ih                   interactive selection, but including hidden
                               directories.
      --id                   interactive selection, for directories only
                               (ignore congifuration option 'show_files').
  -l [NUMBER]                list a certain NUMBER of directories by 'frecency';
                               if no NUMBER is provided, the max_results number
                               from configuration is used.
      --list-all             list all the directories of the database
  -r                         remove a directory from the database, interactively.
      --remove-alias         remove an alias, interactively.
  -t                         force substring matching by shortest path.
      --sync                 sync directories (remove all non-existent
                                directories).
      --help     display this help and exit.
  -v, --version              display version information and exit.

Exit status:
 0  if OK,
 1  if minor problems (e.g., cannot access subdirectory)

Full documentation <https://github.com/j-morano/contemporary-z>

Configuration

cz supports some configuration options. These options must be set in a file with the following path: ~/.config/contemporary-z/cz.conf using the format option = value.

Options:

• theme: string. Color theme.
  • Allowed values: dark, bright
• abs_paths: bool. Record directories using full paths or relative paths. With the latter option, shown directories will vary from one directory to another.
• compact_paths: bool. Replace /home/<username> by ~ and /run/media/<username> by >.
• max_results: int. Maximum results to show in the directory list.
• database_path: string. Directory where the directories database is/will be located.
• substring: string. Which dir to select when substring(s) are introduced.
  • Allowed values:
    • 'shortest': go to the directory with the shortest path name.
    • 'score': go to the directory with the highest score (most 'frecent' dir).
    • 'none': show selection list.
• show_files: string. Whether to show non-dir files, and where, in interactive selection.
  • Allowed values:
    • 'top': show files on top of dirs.
    • 'bottom': show files under the dirs.
    • 'none': do not show files.
• nav_start_number: int. Start number for interactive navigation, that is, the number that the parent directory will have.
  • Recommended values: 1 or 0.

Default config

# ~/.config/contemporary-z/cz.conf

theme = dark
max_results = 9
abs_paths = true
compact_paths = true
database_path = $HOME/.local/share/contemporary-z/directories.dir
substring = shortest
show_files = none
nav_start_number = 1