Repository files navigation

Zide is a combination ofZellij layouts and conveniencebash scripts that creates an IDE-like layout environment. It mainly consists of a file picker (such asyazi) in one pane, and your editor of choice in the main pane. You can browse the file tree in your picker pane, and then any files that are selected or opened do so in the editor's pane.

The project was inspired by theyazelix project, but simplifies it down to work in most shells (instead of requiringnushell), more editors (vs just Helix), and essentailly any file picker, with less required configuration.

1. Start azellij layout with a filepicker on the left and your editor on the right
2. Browse for files in any visual file picker of your choosing, and open any selected files or directories in your editor pane
3. Open multiple files at once in your editor if your picker supports a multiselect UI
4. When opening a directory, set that directory as the working directory in your editor automatically
5. Automatic resizing foryazi andlf to change the number of columns based on the width of the picker pane

This project has been tested and works well with the following modal editors:

• Helix (hx)
• Kakoune (kak)
• NeoVim (nvim)
• Vim (vim)

And the following file pickers:

• yazi
• nnn
• broot
• lf
• fff
• felix

But will probably work with just about any TUI file manager.

I recently started usingHelix as my editor of choice. I loved most everything about it, except that there was no tree-style file browser to open files. While the fuzzy finder is fantastic for quickly getting to files I know about, I often work in large monorepos where I don't know the directory or file naming structure in advance, and a visual filepicker is extremely useful. On top of that,yazi is an incredibly powerful and useful tool for file management, and integrating it seemlessly with Helix was high on my list of priorities.

Download or clone the project files and place them somewhere convenient on your system (such as$HOME/.config/zide).

$ git clone git@github.com:josephschmitt/zide.git$HOME/.config/zide

Then add thebin/ directory to yourPATH.

# Add this to your shell profileexport PATH="$PATH:$HOME/.config/zide/bin"

This project integrateszellij with a file picker of your choosing and an editor, and so you'll need these installed for any of this to work (if no specific file picker is set, it defaults toyazi).

There are some additional (optional) layouts included that use alazygit floating pane for easy git integration, so you'll needlazygit installed if you plan on using that. Otherwise, the rest is written in plainbash so it should work on a wide variety of systems without further dependencies.

  $ zide [OPTIONS]<working_dir><layout>

Run thezide command to start using Zellij with the zide-style IDE-like layout. It accepts two positional arguments, both of which are optional:

1. <working_dir> Defaults to., aka your current working directory. Whatever directory you pass as this argument will be the directory that the file picker, your editor, and any future panes will start out in. If you want to open the IDE to a specific project, I suggest passing in that project's directory as this argument (as opposed to navigating after startup) so the working directory is correctly set.
2. <layout> Defaults to theZIDE_DEFAULT_LAYOUT env var if set, otherwise todefault. You can see the list of available layouts in thelayouts/ directory.

When executed, thezide command will do one of two things:

1. If you're not currently in azellij session, it'll start one
2. If you're in an existingzellij session, it'll create a new tab

1. -p, --picker: File picker to use. Available file pickers are listed inbin/lib. This is equivalent to settingZIDE_FILE_PICKER env var.
2. -n, --name: Optional name to give the newly opened session (when starting a new session) or tab (when launching from an existing session). If a session with this name already exists, it'll use a default random session name.
3. -N: Name the newly opened session or tab after the directory being opened (ignored if--name is set). If a session with this name already exists, it'll use a default random session name.

The following layouts can all be found in thelayouts/ directory as separate .kdl files. You can choose which layout to start with by either passing it to thezide command, or setting theZIDE_DEFAULT_LAYOUT env var.

By default startingzide will use a layout consisting of 2 vertical split of panes with a filepicker on the left occupying a small slice of it, and your editor on the right occupying the rest, with your current working directory set as the directory in both your editor and the filepicker.

If you add one more pane, you'll have the choice between two swap layouts: "compact" and "wide". The "compact" layout will set the new pane below the editor, while the "wide" layout will set it to the right. Adding a 4th pane will split these panes in half, vertically for "compact", and horizontally for "wide".

Thetall layout takes advantage of tall screens or windows and lays the panes out horizontally, with the picker occupying the top of the layout in a narrow view, and the editor below. Due to zide's new-found config switching, if you useyazi orlf as your file picker, this layout will automatically switch to a 3-pane view.

Thestacked layout uses Zellij's pane stacking feature to create 3 horizontal panes stacked on top of each other, but only 1 pane is visible at any one time. Switching panes will then make that pane visible, and collapse the rest.

Each default layout also includes a_lazygit variant that includes a floating pane runninglazygit for easier git access.

Any additional layouts you add or configure in the zidelayouts/ directory will be available to use from thezide command, and will be git ignored.

$ zide --help

For basic help, you can use the-h or--help flags on any of the available commands to get details on how to configure them.

If you want to make your own layouts, duplicate any of the built-in layouts in thelayouts/ directory and give them custom names. You'll be able to refer to those names when providing a custom layout to thezide command.

You can make any type of layout you like and use any and all of Zellij's awesome layout features. The one absolute requirement is thatyour editor pane must be next to the picker pane. There's no way to uniquely identify the different panes inzellij (outside of a plugin, anyway), therefore these scripts depend on callingzellij action focus-next-pane to focus your editor from your picker.

This project provides customization via the use of environment variables:

1. ZIDE_DEFAULT_LAYOUT: Default layout. Available layouts can be found in the zidelayouts/ directory. Feel free to add some layouts of your own here (they're gitignore'd).
2. ZIDE_LAYOUT_DIR: Optionally point to a different directory that contains your layouts. Defaults to thelayouts/ directory in this project.
3. ZIDE_FILE_PICKER: The file picker command to use, defaults toyazi if none is set.
4. ZIDE_ALWAYS_NAME: When set totrue, it'll always use the basename of the current working directory as the name of a new Zellij zide session or tab. Equivalent to always using the-N flag.
5. ZIDE_USE_YAZI_CONFIG (defaults totrue): When usingyazi as a file picker, this will point it to theyazi/yazi.toml included with this project instead of using the default config. This config comes with theauto-layout.yazi plugin that will automatically set the number of columns based on the available width. If you want to continue using your standardyazi config, you have two options:
   1. Use your globalyazi config by setting this env var tofalse
   2. Use a custom config just with zide by pointing this env var to a custom config directory. If you have a custom file atmy/custom-config/yazi/yazi.toml, then you would setZIDE_USE_YAZI_CONFIG=my/custom-config/yazi.
6. ZIDE_USE_LF_CONFIG (defaults totrue): Same idea asZIDE_USE_YAZI_CONFIG, but forlf as the picker. Much like the customyazi config, this config includes logic to automatically change the number of columns based on the available width. If you want to customize this config, you have the same two options asyazi above:
   1. Use your globallf config by setting this env var tofalse.
   2. Use a custom config just with zide by pointing this env var to a custom config directory. Note that the directory here should be the directory thelf config lives inside of, not thelf directory itself. So if you have a file atmy/custom-config/lf/lfrc with your config, then you should setZIDE_USE_LF_CONFIG=my/custom-config.

If you're usingyazi and want to use a custom config other than your default and the one included in this project, you can point to a custom config directory in theZIDE_USE_YAZI_CONFIG var.

# ~/.config/yazi-custom/yazi.toml[manager]ratio = [0,1,0]show-hidden =true# Some more config options here

export ZIDE_USE_YAZI_CONFIG="$HOME/.config/yazi-custom"

This will use that config when running in zide, but not when runningyazi normally. If you want to retain the auto-layout logic, you'll have to add theyazi/plugins/auto-layout.yazi plugin to your config'splugins/ directory, and then addrequire("auto-layout") to yourinit.lua.

-- ~/.config/yazi-custom/init.luarequire("auto-layout")

If you're usinglf and want to use a custom config other than your default and the one included in this project, you can point to a custom config directory in theZIDE_USE_LF_CONFIG var.

# ~/.config/custom-configs/lf/lfrcset hidden true# Some more config options here

export ZIDE_USE_LF_CONFIG="~/.config/custom-configs"

To retain the auto-layout logic, you'll need to integrate with theon-redraw cmd like we do in the custom config by adding this to yourlfrc:

cmd on-redraw %{{    if [ $lf_width -le 40 ]; then        lf -remote "send $id set ratios 1"    elif [ $lf_width -le 80 ]; then        lf -remote "send $id set ratios 1:1"    else        lf -remote "send $id set ratios 1:1:2"    fi}}

This project consists of 4 parts:

1. Pre-configuredzellij layouts
2. Thezide command to launch you into zide mode
3. A wrapper script around launching file pickers calledzide-pick
4. A wrapper script that controls opening files in your editor calledzide-edit

The mainzide command controls opening newzide tabs, either in an existing session if inside one or starting a new one. It sets some environment variables, updates the working directory, and startszellij.

Thezide-pick command is a small wrapper around the file pickers. It handles launching the correct picker based on either the--picker flag or theZIDE_FILE_PICKER environment variable. This lets us avoid having to hard-code what picker to use in our layouts.

It also has one more very important job, which is changing theEDITOR env var to bezide-edit instead of your actual editor, so that the pickers open up our script instead of the real editor when picking files.

Thezide-edit command takes the place of yourEDITOR. Instead of launching yourEDITOR, it automates switching to your open editor pane, and sends it the correctzellij action commands so that it opens those files in the open editor pane.

Thezide-rename command is a convenience script for renaming zellij tabs. You can provide it a parameter of a tab name, and it'll use that to rename the currently focused tab. However, its main use case is in a layout as an auto-closing pane. Usage in this way will automatically name new tabs after whatever directory they're being opened to.

Conceptually, this is the basic flow of the system.

We start upzellij with our layout (say two panes, left isyazi via ourzide-pick wrapper script, and right is our editor,hx). When you choose files inyazi,yazi will attempt to open those files inEDITOR, which now points tozide-edit. Thezide-edit script then switches the focused pane usingzellij action focus-next-pane (which hopefully is the pane with your editor). It then writes the following commands to the pane to execute in the editor:

1. zellij action write 27: This sends the<ESC> key, to force us into Normal mode in your editor.
2. zellij action write-chars :open file1.txt subdir/file2.txt: This essentially just sends the:open file1.txt subdir/file2.txt command to your editor, which will tell it to open those files.
3. zellij action write-chars :cd subdir/:If you chose a directory in your filepicker it'll also send thecd command to set the working directory to that directory in your editor.
4. zellij action write 13: Send the<ENTER> key to submit the commands.