try-rs 1.1.1

Temporary workspace manager for fast experimentation in the terminal
Documentation

try-rs is a CLI tool designed to manage the chaos of temporary projects. Instead of cluttering your Desktop or /tmp with test1, new-test, and final-test, try-rs organizes them into date-prefixed directories, offering a robust TUI (Terminal User Interface) to create, navigate, and clean up your experiments.

try-rs.gif

Features

Feature Description
Blazing Fast Built in Rust, compiled to native binary. No interpreter lag.
Rich TUI Beautiful terminal interface built with Ratatui.
Fuzzy Search Instantly find old experiments with smart matching.
Auto-Dating Creates directories like rust-test automatically.
Git Integration Auto-clones URLs (try-rs <url>) and marks repos with ().
Content Preview Inspect files inside a folder before entering it.
Editor Integration Open experiments directly in your editor (Ctrl+E).
Theming Switch themes at runtime (Ctrl+T) or set a default in config.
Safe Deletion Delete old experiments via UI with confirmation (Ctrl+D).
Configurable Supports XDG Base Directory (view section Configuration).
Multi-Shell Support Supports Fish, Zsh, Bash, Power Shell and Nushell.
Multi-OS Support Supports Linux, macOS and Windows.
Shell Tab Completion Dynamic tab completion for directory names from your tries path.
Icons Identification Supports icons identification projects ( 󰬔     ).

Installation

Prerequisites

  • A shell (Fish, Zsh, Bash, Power Shell or Nushell).
  • A Nerd Font installed (required for icons like  and 🦀).

Building from source

git clone https://github.com/tassiovirginio/try-rs.git
cd try-rs
cargo install --path . --bin try-rs

Cargo install try-rs

cargo install try-rs

Eget

eget tassiovirginio/try-rs

Install in Archlinux

yay -S try-rs-bin

Ubuntu/Debian (APT Repository)

# Add the repository
echo "deb [trusted=yes] https://tassiovirginio.github.io/try-rs stable main" | sudo tee /etc/apt/sources.list.d/try-rs.list

# Update and install
sudo apt update
sudo apt install try-rs

Ubuntu/Debian (.deb manual)

  • Download the latest .deb for your architecture (amd64/arm64) from the Releases page and install it:
# Replace X.Y.Z with the latest version and choose amd64 or arm64
wget https://github.com/tassiovirginio/try-rs/releases/download/vX.Y.Z/try-rs_X.Y.Z-1_amd64.deb
sudo apt install ./try-rs_X.Y.Z-1_amd64.deb

Windows (Releases)

Homebrew

brew install try-rs

Nix Install (flakes)

nix profile install github:tassiovirginio/try-rs

Automatic Setup

On the first run, try-rs will attempt to detect your shell and ask if you want to automatically configure the shell integration.

Configuration

  1. Setup the Shell Integration

Since try-rs needs to change your shell's current directory, it requires a small wrapper function.

  • Fish Shell (Recommended)
try-rs --setup fish

(Optional) Create an alias:

alias try "try-rs"
  • Zsh
try-rs --setup zsh
  • Bash
try-rs --setup bash
  • Power-shell
try-rs --setup power-shell
  • Nushell
try-rs --setup nu-shell

Shell Tab Completion (Optional)

try-rs supports dynamic tab completion for directory names in your tries_path. When you type try-rs <partial-name> and press <Tab>, it will suggest existing directories from your tries folder.

To enable tab completion, run:

# For Bash
try-rs --completions bash >> ~/.bashrc

# For Zsh
try-rs --completions zsh >> ~/.zshrc

# For Fish
try-rs --completions fish > ~/.config/fish/completions/try-rs.fish

# For PowerShell
try-rs --completions power-shell >> $PROFILE

# For Nushell
try-rs --completions nu-shell >> ~/.config/nushell/config.nu

Or generate the completion script to stdout and redirect it manually:

try-rs --completions bash

The completion script automatically detects your tries_path from:

  1. The TRY_PATH environment variable (highest priority)
  2. The tries_path setting in your config file
  3. The default ~/work/tries path

Example usage:

If you have folders like rust-test, go-playground, and python-ml in your tries path:

$ try-rs ru<Tab>
# Completes to: try-rs rust-test

$ try-rs go<Tab>
# Completes to: try-rs go-playground

$ try-rs py<Tab>
# Completes to: try-rs python-ml

You can also use it with the TUI - typing a partial name will fuzzy-match existing directories.

2. Config File

The configuration file is stored in a platform-specific directory:

Platform Value Example
Linux $XDG_CONFIG_HOME or $HOME/.config /home/tassio/.config/try-rs
macOS $HOME/Library/Application Support /Users/tassio/Library/Application Support/try-rs
Windows {FOLDERID_RoamingAppData} C:\Users\tassio\AppData\Roaming\try-rs

By default, experiments are stored in ~/work/tries. You can customize the path, choose a theme, and configure the editor. To change this, create config.toml in the directory shown above:

# config.toml
tries_path = "~/Development/playground"
editor = "code" # Optional: code, nvim, hx, etc.
apply_date_prefix = true # optional, default is false
transparent_background = true # optional, default is true (uses terminal background)

# Theme configuration (choose one of the available themes)
theme = "Catppuccin Mocha"

Background Transparency:

By default, try-rs uses a transparent background (inherits from your terminal). Each theme includes its own background color that will be used when transparent_background = false. You can control this with:

# Use theme's background color (solid background)
transparent_background = false

# Use terminal's background (transparent/inherit) - default
transparent_background = true

Available Themes:

You can use any of these theme names in your configuration:

  • "Default"
  • "Catppuccin Mocha"
  • "Catppuccin Macchiato"
  • "Dracula"
  • "JetBrains Darcula"
  • "Gruvbox Dark"
  • "Nord"
  • "Tokyo Night"
  • "One Dark Pro"
  • "Everforest"
  • "SynthWave '84"
  • "OLED True Black"
  • "Silver Gray"
  • "Black & White"
  • "Matrix"
  • "Tron"

3. Environment Variables

You can also configure try-rs using environment variables:

Variable Description
TRY_PATH Overrides the path where experiments are stored.
TRY_CONFIG_DIR Overrides the default configuration directory.
TRY_CONFIG Overrides the config filename (defaults to config.toml).
VISUAL / EDITOR Default editor to use if not specified in config.toml.

Usage

Simply type try-rs (or your alias) in your terminal.

Key Bindings

Key Action
Type Filter the list (Fuzzy Search)
↑ / ↓ / Ctrl+K / Ctrl+J / Ctrl+P / Ctrl+N Navigate the list
Ctrl+U Clear the search box
Enter Select directory (or create new if text doesn't match)
Ctrl+D Delete the selected directory (triggers popup)
Ctrl+E Open in editor (configured in config.toml)
Ctrl+T Open theme selector
Ctrl+A Open about popup
Esc/Ctrl+C Cancel / Close Popup / Exit

Theme Selector Key Bindings

Key Action
↑ / ↓ / j / k / n / p Navigate themes
Enter Select theme
Esc/Ctrl+C Close theme selector

Themes

You can switch between themes at runtime by pressing Ctrl+T. The following themes are available:

  • Default
  • Catppuccin Mocha
  • Catppuccin Macchiato
  • Dracula
  • JetBrains Darcula
  • Gruvbox Dark
  • Nord
  • Tokyo Night
  • One Dark Pro
  • Everforest
  • SynthWave '84
  • OLED True Black
  • Silver Gray
  • Black & White
  • Matrix
  • Tron

CLI Commands

You can also bypass the UI:

Command Description
try-rs Opens the TUI
try-rs <name> Create (or jump to) a named experiment
try-rs <https://github.com/user/repo> Clones a repository into a dated folder
try-rs <https://github.com/user/repo> <name> Clones a repository into a specific folder name (destination)
try-rs -s <url> / try-rs --shallow-clone Shallow clone (--depth 1) when cloning repositories
try-rs -w <name> / try-rs --worktree Create a git worktree from current repository (must be inside repo)
try-rs --setup <shell> Setup shell integration (fish, zsh, bash, nu-shell, power-shell)
try-rs --setup-stdout <shell> Print shell integration script to stdout (for manual setup)
try-rs --completions <shell> Generate shell completion script for tab completion
try-rs --version Show application version
try-rs --help Show help message

Inspiration

This project is a Rust port and re-imagination of the excellent try tool by Tobi Lütke.

While the original is a lightweight Ruby script, try-rs aims to bring the same philosophy, "Your experiments deserve a home", but with the performance, type safety, and modern TUI capabilities (using Ratatui) of the Rust ecosystem.

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

📄 License MIT