Zellij

https://github.com/zellij-org/zellij
Admin
A terminal workspace with batteries included
Tokens:15,768
Snippets:140
Trust Score:6.7
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Execute the installed zellij binary

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Run the installed binary to verify the release works.

```bash
$ /tmp/bin/zellij
```

--------------------------------

### Install Zellij on Void Linux (xbps)

Source: https://github.com/zellij-org/zellij/blob/main/docs/THIRD_PARTY_INSTALL.md

Install zellij using the xbps package manager on Void Linux.

```bash
sudo xbps-install zellij
```

--------------------------------

### Install Zellij on Fedora Linux (COPR)

Source: https://github.com/zellij-org/zellij/blob/main/docs/THIRD_PARTY_INSTALL.md

Enable the COPR repository and install zellij using dnf.

```bash
sudo dnf copr enable varlad/zellij 
sudo dnf install zellij
```

--------------------------------

### Install Zellij on macOS (Homebrew)

Source: https://github.com/zellij-org/zellij/blob/main/docs/THIRD_PARTY_INSTALL.md

Install zellij using Homebrew on macOS.

```bash
brew install zellij
```

--------------------------------

### Try Zellij without installing (fish/xonsh)

Source: https://github.com/zellij-org/zellij/blob/main/README.md

Downloads and runs the Zellij launch script for fish or xonsh shells. This allows trying Zellij without installing it.

```bash
bash -c 'bash <(curl -L https://zellij.dev/launch)'
```

--------------------------------

### Install Zellij on Arch Linux (pacman)

Source: https://github.com/zellij-org/zellij/blob/main/docs/THIRD_PARTY_INSTALL.md

Install the zellij package from the official extra repository using pacman.

```bash
pacman -S zellij
```

--------------------------------

### Try Zellij without installing (bash/zsh)

Source: https://github.com/zellij-org/zellij/blob/main/README.md

Downloads and runs the Zellij launch script for bash or zsh shells. This allows trying Zellij without installing it.

```bash
bash <(curl -L https://zellij.dev/launch)
```

--------------------------------

### cargo xtask commands for formatting, building, testing, running, installing, and publishing

Source: https://github.com/zellij-org/zellij/blob/main/CONTRIBUTING.md

Commands supported by the build system. Run `cargo xtask` to format, build, and test. Individual actions are available via `cargo xtask format`, `build`, `test`, `run`, `install`, and `publish`. Use `cargo xtask --help` for all commands; `xtask` can be shortened to `x`.

```sh
cargo xtask
# You can also perform these actions individually
cargo xtask format
cargo xtask build
cargo xtask test
# Run Zellij (optionally with additional arguments)
cargo xtask run
cargo xtask run -- -l strider
# Install Zellij to some directory
cargo xtask install /path/of/zellij/binary
# Publish the zellij and zellij-tile crates
cargo xtask publish
```

--------------------------------

### Install Zellij on macOS (MacPorts)

Source: https://github.com/zellij-org/zellij/blob/main/docs/THIRD_PARTY_INSTALL.md

Install zellij using MacPorts on macOS.

```bash
sudo port install zellij
```

--------------------------------

### Install Zellij with cargo install --locked zellij

Source: https://github.com/zellij-org/zellij/blob/main/README.md

Installs Zellij from crates.io using Cargo. The --locked flag ensures the dependency versions from the lockfile are used.

```bash
cargo install --locked zellij
```

--------------------------------

### Install zellij from private registry

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Install zellij from the ktra registry to a local directory. This tests the release binary.

```bash
$ cargo install --registry ktra --root /tmp zellij
```

--------------------------------

### Install Zellij on Arch Linux (AUR via paru)

Source: https://github.com/zellij-org/zellij/blob/main/docs/THIRD_PARTY_INSTALL.md

Install the zellij-git package from the AUR using the paru helper.

```bash
paru -S zellij-git
```

--------------------------------

### Launch ktra with logging

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Run ktra with debug logging to see what happens. This command starts the registry server.

```bash
RUST_LOG=debug ktra
```

--------------------------------

### Build plugins and Zellij from source for distribution

Source: https://github.com/zellij-org/zellij/blob/main/CONTRIBUTING.md

Builds all builtin plugins from source, then builds Zellij without bundled plugins. Requires protoc for regenerating protobuf definitions. The disable_automatic_asset_installation feature disables plugin embedding and the zellij setup --dump-plugins command.

```sh
# 1. build the plugins from source (repeat for every plugin, or use `cargo x build --release`)
cargo build --release --target wasm32-wasip1 \
  -p status-bar -p tab-bar -p compact-bar -p strider -p session-manager \
  -p configuration -p plugin-manager -p about -p share -p multiple-select \
  -p layout-manager -p link

# 2. install the resulting artifacts from <target-dir>/wasm32-wasip1/release/*.wasm
#    into $PREFIX/share/zellij/plugins/

# 3. build zellij without bundled plugins
PREFIX=/usr cargo build --release --bin zellij \
  --no-default-features --features disable_automatic_asset_installation
```

--------------------------------

### Handling Result with if let and match

Source: https://github.com/zellij-org/zellij/blob/main/docs/ERROR_HANDLING.md

An example showing how to handle a `Result` with an `if let` statement, which hides the error in the `else` branch. The subsequent `match` statement is recommended to access the error and log it with context.

```rust
if let Ok(active_tab) = self.get_active_tab(client_id) {
    let active_tab_pos = active_tab.position;
    let new_tab_pos = (active_tab_pos + 1) % self.tabs.len();
    return self.switch_active_tab(new_tab_pos, client_id);
} else {
    log::error!("Active tab not found for client_id: {:?}", client_id);
}
```

```rust
match self.get_active_tab(client_id) {
    Ok(active_tab) => {
        let active_tab_pos = active_tab.position;
        let new_tab_pos = (active_tab_pos + 1) % self.tabs.len();
        return self.switch_active_tab(new_tab_pos, client_id);
    },
    Err(err) => Err::<(), _>(err).with_context(err_context).non_fatal(),
}
```

--------------------------------

### Log a variable with the log crate

Source: https://github.com/zellij-org/zellij/blob/main/CONTRIBUTING.md

Example of using the log crate to log a variable's value. The output is truncated at 100KB by default, adjustable via the LOG_MAX_BYTES constant.

```rust
let my_variable = some_function();
log::info!("my variable is: {:?}", my_variable);
```

--------------------------------

### Get registry token for ktra

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Use this curl command to create a new user and receive a token. Replace PASSWORD with your chosen password.

```bash
curl -X POST -H 'Content-Type: application/json' -d '{"password":"PASSWORD"}' http://localhost:8000/ktra/api/v1/new_user/ALICE
```

--------------------------------

### Before: Screen::render with unwrap

Source: https://github.com/zellij-org/zellij/blob/main/docs/ERROR_HANDLING.md

Original implementation that calls unwrap() on the send result, causing a crash on failure. Used as a starting point for refactoring.

```rust
    pub fn render(&mut self) {
        // ...
        let serialized_output = output.serialize();
        self.bus
            .senders
            .send_to_server(ServerInstruction::Render(Some(serialized_output)))
            .unwrap();
    }
```

--------------------------------

### Logging an error with log::error!

Source: https://github.com/zellij-org/zellij/blob/main/docs/ERROR_HANDLING.md

An ad-hoc logging example that logs a custom error message. While functional, it loses the context information that might be attached to the `Result` type.

```rust
log::error!("failed to find tab with index {tab_index}");
```

--------------------------------

### Attaching context messages in render method

Source: https://github.com/zellij-org/zellij/blob/main/docs/ERROR_HANDLING.md

Shows how to attach context messages to errors in a render method, using the .context() method. The context message should describe what you were doing when the error occurred, not repeat the error itself. This example is from the render method in Zellij's screen module.

```rust
    pub fn render(&mut self) -> Result<()> {
        // ...

        for tab_index in tabs_to_close {
            // ...
            self.close_tab_at_index(tab_index)
                .context("Failed to close tab at index: {tab_index}")?;
        }
        // ...
        self.bus
            .senders
            .send_to_server(ServerInstruction::Render(Some(serialized_output)))
            .context("Failed to send message to server")
    }
```

--------------------------------

### Test ANSI/VT escape sequences with echo

Source: https://github.com/zellij-org/zellij/blob/main/docs/TERMINOLOGY.md

Use this command to test ANSI/VT escape sequences in your terminal. The `\033` is an escape character, and the example prints "Hi" in red and "there!" in blinking red.

```bash
echo -e "\033[31mHi \033[5mthere!"
```

--------------------------------

### Simulate release with cargo x publish

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Run this command to simulate a release. Replace <YOUR_ZELLIJ_FORK> with your fork's remote URL. A prompt will open for the commit message; save and close to continue.

```bash
cargo x publish --git-remote <YOUR_ZELLIJ_FORK> --cargo-registry ktra
```

--------------------------------

### Create ~/.cargo/config.toml for ktra registry

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Create this file in your home directory to configure the ktra registry globally. Replace $INDEX_REPO with your HTTPS clone URL.

```bash
[registries.ktra]
index = "https://$INDEX_REPO"
```

--------------------------------

### Create ktra.toml configuration file

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Create this config file for ktra in the folder where you want to store registry data. Replace placeholders with your actual values.

```toml
[index_config]
remote_url = "https://$INDEX_REPO"
https_username = "your-git-username"
https_password = "$TOKEN" 
branch = "main"  # Or whatever branch name you used
```

--------------------------------

### Add ktra registry to .cargo/config.toml

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Add this registry entry to your local zellij repo's .cargo/config.toml. Replace $INDEX_REPO with your HTTPS clone URL.

```toml

[registries]
ktra = { index = "https://$INDEX_REPO" }
```

--------------------------------

### Before: resize_to_screen without Result

Source: https://github.com/zellij-org/zellij/blob/main/docs/ERROR_HANDLING.md

Original function that calls render() without propagating errors. Shown as a contrast to the refactored version.

```rust
    pub fn resize_to_screen(&mut self, new_screen_size: Size) {
        // ...
        self.render();
    }
```

--------------------------------

### Using context and with_context in a function

Source: https://github.com/zellij-org/zellij/blob/main/docs/ERROR_HANDLING.md

Shows how to use context for static messages and with_context for formatted messages when handling errors in a function that moves clients between tabs.

```rust
    fn move_clients_between_tabs(
        &mut self,
        source_tab_index: usize,
        destination_tab_index: usize,
        clients_to_move: Option<Vec<ClientId>>,
    ) -> Result<()> {
        // ...
        if let Some(client_mode_info_in_source_tab) = drained_clients {
            let destination_tab = self.get_indexed_tab_mut(destination_tab_index)
                .context("failed to get destination tab by index")
                .with_context(|| format!("failed to move clients from tab {source_tab_index} to tab {destination_tab_index}"))?;
            // ...
        }
        Ok(())
    }
```

--------------------------------

### Find zellij-utils dependency in Cargo.toml

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Locate all zellij subcrate dependencies that look like this in Cargo.toml files. These need to be modified to use the private registry.

```toml
zellij-utils = { path = "../zellij-utils/", version = "XXX" }
```

--------------------------------

### Login to ktra registry with cargo

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Use the token received from the previous command to log in to the ktra registry. Replace KTRA_TOKEN with the actual token.

```bash
cargo login --registry ktra "KTRA_TOKEN"
```

--------------------------------

### After: Screen::render returning Result with context

Source: https://github.com/zellij-org/zellij/blob/main/docs/ERROR_HANDLING.md

Refactored version that returns Result<()> and attaches context using anyhow's with_context. Propagates errors to callers instead of crashing.

```rust
    pub fn render(&mut self) -> Result<()> {
        let err_context = || "failed to render screen".to_string();
        // ...

        let serialized_output = output.serialize();
        self.bus
            .senders
            .send_to_server(ServerInstruction::Render(Some(serialized_output)))
            .with_context(err_context)
    }
```

--------------------------------

### Create config.json for cargo index repository

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Add this config.json to the root of your cargo index repository. It configures the download and API URLs for the private registry.

```json
{"dl":"http://localhost:8000/dl","api":"http://localhost:8000"}
```

--------------------------------

### After: resize_to_screen returning Result with context

Source: https://github.com/zellij-org/zellij/blob/main/docs/ERROR_HANDLING.md

Refactored function that returns Result<()> and uses with_context to add a descriptive error message. Allows callers to handle the error.

```rust
    pub fn resize_to_screen(&mut self, new_screen_size: Size) -> Result<()> {
        // ...
        self.render()
            .with_context(|| format!("failed to resize to screen size: {new_screen_size:#?}"))
    }
```

--------------------------------

### Import Zellij error prelude

Source: https://github.com/zellij-org/zellij/blob/main/docs/ERROR_HANDLING.md

Add this import to access the error handling functions and traits mentioned in the document, such as fatal and non_fatal.

```rust
use zellij_utils::errors::prelude::*;
```

--------------------------------

### Terminating execution with .fatal()

Source: https://github.com/zellij-org/zellij/blob/main/docs/ERROR_HANDLING.md

Shows how to terminate execution on errors by calling .fatal() on the result of screen_thread_main. This logs the error and panics the application, crashing Zellij. This is used when errors cannot be propagated further because the function runs in a separate thread.

```rust
    // ...
    screen_thread_main(
        screen_bus,
        max_panes,
        client_attributes_clone,
        config_options,
    )
    .fatal();
```

--------------------------------

### Change zellij-utils dependency to use ktra registry

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Modify each zellij subcrate dependency to include the registry = "ktra" attribute. This applies to all zellij subcrates except plugins.

```toml
zellij-utils = { path = "../zellij-utils/", version = "XXX", registry = "ktra" }
```

--------------------------------

### Delete release tag locally

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Delete the release tag locally. Replace vX.Y.Z with the actual tag.

```bash
$ git tag -d "vX.Y.Z"
```

--------------------------------

### Propagating errors in screen_thread_main

Source: https://github.com/zellij-org/zellij/blob/main/docs/ERROR_HANDLING.md

Shows how errors are propagated in the screen_thread_main function using the ? operator, without attaching context messages at each call site. This is because the function is a central location where many errors can occur, and context is added at higher levels.

```rust
    ScreenInstruction::Render => {
        screen.render()?;
    },
    ScreenInstruction::NewPane(pid, client_or_tab_index) => {
        // ...
        screen.update_tabs()?;

        screen.render()?;
    },
    ScreenInstruction::OpenInPlaceEditor(pid, client_id) => {
        // ...
        screen.update_tabs()?;

        screen.render()?;
    },
```

--------------------------------

### Moving context string to a variable

Source: https://github.com/zellij-org/zellij/blob/main/docs/ERROR_HANDLING.md

Demonstrates assigning a static context string to a variable to avoid copy-pasting when using context in multiple places within a render function.

```rust
    pub fn render(&mut self) -> Result<()> {
        let err_context = "failed to render screen";
        // ...

        for tab_index in tabs_to_close {
            // ...
            self.close_tab_at_index(tab_index)
                .context(err_context)?;
        }
        // ...
        self.bus
            .senders
            .send_to_server(ServerInstruction::Render(Some(serialized_output)))
            .context(err_context)
    }
```

--------------------------------

### Moving context closure to a variable

Source: https://github.com/zellij-org/zellij/blob/main/docs/ERROR_HANDLING.md

Shows assigning a closure that formats a context message to a variable, then using it with with_context for multiple error handling points in a close_tab function.

```rust
    // ...
    pub fn close_tab(&mut self, client_id: ClientId) -> Result<()> {
        let err_context = || format!("failed to close tab for client {client_id:?}");

        let active_tab_index = *self
            .active_tab_indices
            .get(&client_id)
            .with_context(err_context)?;
        self.close_tab_at_index(active_tab_index)
            .with_context(err_context)
    }
```

--------------------------------

### Logging a Result with non_fatal()

Source: https://github.com/zellij-org/zellij/blob/main/docs/ERROR_HANDLING.md

A better approach that logs the `Result` type including all context information using the `non_fatal()` method. This preserves valuable context that would otherwise be lost.

```rust
fs::create_dir_all(&plugin_global_data_dir)
    .context("failed to create plugin asset directory")
    .non_fatal();
```

--------------------------------

### Delete release tag on remote

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Force delete the release tag on the remote. Replace <YOUR_ZELLIJ_FORK> and vX.Y.Z with your fork and tag.

```bash
$ git push <YOUR_ZELLIJ_FORK> --force --delete "vX.Y.Z"
```

--------------------------------

### Undo last commit locally

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Reset your local zellij repo to undo the last commit.

```bash
$ git reset --hard HEAD~1
```

--------------------------------

### Symlink shared target directory for cargo

Source: https://github.com/zellij-org/zellij/blob/main/CONTRIBUTING.md

To share compilation artifacts between projects without breaking debug builds, symlink the target folder instead of pointing cargo elsewhere. This avoids issues with the pinned `build.target-dir` in `.cargo/config.toml`.

```sh
ln -s /path/to/shared/target /path/to/zellij/target
```

--------------------------------

### Force push to undo remote commit

Source: https://github.com/zellij-org/zellij/blob/main/docs/RELEASE.md

Force push to your fork to undo the last commit on the remote. Replace <YOUR_ZELLIJ_FORK> with your fork's remote name.

```bash
$ git push --force <YOUR_ZELLIJ_FORK>
```
Tokens:
Raw