44485c4c72
- Update package description and fix mainProgram typo - Rewrite documentation to describe project switching, not process viewing - Add PROJECT_FOLDERS configuration and usage examples - Update all references across docs (README, guides, module overviews)
205 lines
3.9 KiB
Markdown
205 lines
3.9 KiB
Markdown
# zellij-ps
|
|
|
|
A Zellij project switcher for quickly navigating and opening project workspaces.
|
|
|
|
## Description
|
|
|
|
zellij-ps is a Fish script inspired by ThePrimeagen's tmux-sessionizer. It provides a fast, interactive way to switch between project folders in Zellij. Using `fd` for fast directory discovery and `fzf` for fuzzy selection, it helps you quickly jump into your work.
|
|
|
|
The script searches through your configured project folders (`$PROJECT_FOLDERS`) and either creates a new Zellij session for the selected project or attaches to an existing one.
|
|
|
|
## Installation
|
|
|
|
### Via Overlay
|
|
|
|
```nix
|
|
{pkgs, ...}: {
|
|
environment.systemPackages = with pkgs; [
|
|
zellij-ps
|
|
];
|
|
}
|
|
```
|
|
|
|
### Direct Reference
|
|
|
|
```nix
|
|
{pkgs, ...}: {
|
|
environment.systemPackages = with pkgs; [
|
|
inputs.m3ta-nixpkgs.packages.${pkgs.system}.zellij-ps
|
|
];
|
|
}
|
|
```
|
|
|
|
### Run Directly
|
|
|
|
```bash
|
|
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#zellij-ps
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Usage
|
|
|
|
```bash
|
|
# Run from outside Zellij to start a project session
|
|
zellij-ps
|
|
|
|
# Or pass a project path directly
|
|
zellij-ps ~/projects/my-project
|
|
```
|
|
|
|
This will:
|
|
|
|
1. Search through your `$PROJECT_FOLDERS` for directories
|
|
2. Open fzf for fuzzy project selection (if no argument provided)
|
|
3. Create a new Zellij session or attach to existing one for the selected project
|
|
|
|
### Configuration
|
|
|
|
Set your project folders in your shell configuration:
|
|
|
|
**Fish example:**
|
|
```fish
|
|
set -x PROJECT_FOLDERS ~/projects:~/code:~/work
|
|
```
|
|
|
|
**Bash/Zsh example:**
|
|
```bash
|
|
export PROJECT_FOLDERS="$HOME/projects:$HOME/code:$HOME/work"
|
|
```
|
|
|
|
Folders should be delimited by `:` and can include `~` for home directory.
|
|
|
|
## Home Manager Module
|
|
|
|
### Enable Module
|
|
|
|
```nix
|
|
{config, ...}: {
|
|
imports = [m3ta-nixpkgs.homeManagerModules.default];
|
|
|
|
m3ta.cli.zellij-ps = {
|
|
enable = true;
|
|
};
|
|
}
|
|
```
|
|
|
|
### Module Options
|
|
|
|
#### `m3ta.cli.zellij-ps.enable`
|
|
|
|
Enable the zellij-ps module.
|
|
|
|
- Type: `boolean`
|
|
- Default: `false`
|
|
|
|
#### `m3ta.cli.zellij-ps.package`
|
|
|
|
Custom package to use.
|
|
|
|
- Type: `package`
|
|
- Default: `pkgs.zellij-ps`
|
|
|
|
## Requirements
|
|
|
|
### System Requirements
|
|
|
|
- Linux or Unix-like system
|
|
- Configured `$PROJECT_FOLDERS` environment variable
|
|
|
|
## Platform Support
|
|
|
|
- Linux (primary)
|
|
- macOS (may work)
|
|
- Windows (not supported)
|
|
|
|
## Build Information
|
|
|
|
- **Version**: 0.1.0
|
|
- **Type**: Fish script
|
|
- **License**: MIT
|
|
- **Inspired by**: [ThePrimeagen's tmux-sessionizer](https://github.com/ThePrimeagen/.dotfiles/blob/master/bin/.local/scripts/tmux-sessionizer)
|
|
- **Source**: [Gitea](https://code.m3ta.dev/m3tam3re/helper-scripts)
|
|
|
|
## Source Code
|
|
|
|
The script is available at:
|
|
|
|
```
|
|
https://code.m3ta.dev/m3tam3re/helper-scripts/src/branch/main/zellij-ps.fish
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### No Projects Found
|
|
|
|
If fzf shows no results, check your `$PROJECT_FOLDERS` variable:
|
|
|
|
```bash
|
|
# In fish
|
|
echo $PROJECT_FOLDERS
|
|
|
|
# In bash/zsh
|
|
echo $PROJECT_FOLDERS
|
|
```
|
|
|
|
Ensure the folders exist and contain subdirectories.
|
|
|
|
### Already in Zellij Session
|
|
|
|
If you're already inside a Zellij session, you'll see:
|
|
|
|
```
|
|
You are in a Zellij Session!
|
|
Please use the session manager to switch sessions.
|
|
```
|
|
|
|
Use Zellij's built-in session manager (`Ctrl+p` → `s`) to switch sessions instead.
|
|
|
|
### fd Not Found
|
|
|
|
Error: `fd: command not found`
|
|
|
|
**Solution**: Ensure fd is installed:
|
|
|
|
```nix
|
|
{pkgs, ...}: {
|
|
environment.systemPackages = with pkgs; [
|
|
fd
|
|
];
|
|
}
|
|
```
|
|
|
|
### Fish Not Found
|
|
|
|
Error: `fish: command not found`
|
|
|
|
**Solution**: Ensure Fish is installed:
|
|
|
|
```nix
|
|
{pkgs, ...}: {
|
|
programs.fish = {
|
|
enable = true;
|
|
};
|
|
}
|
|
```
|
|
|
|
### fzf Not Working
|
|
|
|
Ensure fzf is installed and configured:
|
|
|
|
```bash
|
|
# Check fzf
|
|
which fzf
|
|
|
|
# Test fzf
|
|
echo -e "item1\nitem2\nitem3" | fzf
|
|
```
|
|
|
|
## Related
|
|
|
|
- [zellij-ps Module](../modules/home-manager/cli/zellij-ps.md) - Home Manager module documentation
|
|
- [Using Modules](../guides/using-modules.md) - How to use modules
|
|
- [Adding Packages](../guides/adding-packages.md) - How to add new packages
|
|
- [Quick Start](../QUICKSTART.md) - Getting started guide
|