try

Lightweight, time‑sensitive directory navigation for experiments — a fast way to jump between temporary project folders.

Inspired by and adapted from Tobias Lütke's original Ruby tool: https://github.com/tobi/try

Quick Start

One-line install (Linux/macOS):

curl -sSf https://raw.githubusercontent.com/dariuszparys/try-rs/main/install.sh | sh

Then restart your shell and run try to get started!

Why try?

When experimenting you often create throwaway directories (e.g., 2025-08-21-test-feature-x, tmp-viz-poc). Finding and jumping back to them slows you down. try gives you an interactive, fuzzy selector that favors what you touched most recently, and creates a new directory when your query doesn’t exist — all wired to actually cd your shell.

Features

• Interactive fuzzy finder: fast, incremental filtering of your tries.
• Time‑sensitive scoring: boosts recently created or visited dirs.
• Instant creation: press Enter to create when no exact match.
• Git clone integration: try clone <url> or pass a git URL to try to clone into a date‑prefixed dir.
• One‑key deletion: Ctrl‑D, with an explicit “YES” confirmation.
• Shell integration: prints cd commands your shell evaluates.
• Native speed: single‑binary CLI written in Rust.

Installation

Recommended: Quick Install Script (Linux/macOS)

curl -sSf https://raw.githubusercontent.com/dariuszparys/try-rs/main/install.sh | sh

This script will:

• Detect your OS (Linux/macOS) and architecture (x86_64/aarch64/armv7)
• Download the latest pre-built binary from GitHub releases
• Extract and install it to ~/.local/bin
• Check if ~/.local/bin is in your PATH (warns if not)
• Automatically add shell integration to your rc file (bash/zsh/fish)

After installation, restart your shell or source your rc file to start using try.

To skip automatic shell integration:

curl -sSf https://raw.githubusercontent.com/dariuszparys/try-rs/main/install.sh | sh -s -- --no-shell-integration

For help:

curl -sSf https://raw.githubusercontent.com/dariuszparys/try-rs/main/install.sh | sh -s -- --help

From Pre-built Binaries

Download the latest release for your platform from the releases page, extract it, and place the binary in your PATH.

From crates.io

If you have Rust installed:

cargo install try-cli

Then enable shell integration and reload your shell:

eval "$(try init)"
source ~/.zshrc  # or: source ~/.bashrc

From Source

Prerequisites: a working Rust toolchain from https://rustup.rs

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

Or build a release binary: cargo build --release → target/release/try

If you installed from source instead of using install.sh, add shell integration manually:

eval "$(try init)"
source ~/.zshrc  # or: source ~/.bashrc

Shell Integration

If you used the install script, shell integration is already configured! Just restart your shell.

If you installed via another method, add the following to your shell configuration:

bash/zsh:

# add to ~/.bashrc or ~/.zshrc
eval "$(try init)"

fish:

# add to ~/.config/fish/config.fish
eval "$(try init | string collect)"

Then reload your shell:

source ~/.bashrc  # or: source ~/.zshrc

Customize the storage location (default: ~/src/tries) either by passing an absolute path to init or by setting TRY_PATH. You can also override per‑invocation with the global --path option:

eval "$(try init /absolute/path/to/tries)"
# or
export TRY_PATH=/absolute/path/to/tries
eval "$(try init)"
# or override at call time
try --path /absolute/path/to/tries

Usage

Basic:

# With the shell function installed
try                # Open the selector
try my-experiment  # Seed the query (shell function calls `try cd ...`)
try https://github.com/user/repo  # Shorthand for clone when integrated

# Direct binary usage without shell integration
try cd my-experiment
try clone https://github.com/user/repo.git

# Clone a git repo into a date-prefixed directory and cd into it
try clone https://github.com/user/repo.git
try clone git@github.com:user/repo my-fork   # custom name

# Shorthand: passing a git URL to `try` behaves like `try clone`
# when the shell function is installed
try https://github.com/user/repo

Inside the selector:

• Up/Down or Ctrl‑P/Ctrl‑N: move selection
• Type: filter entries
• Enter: select existing or create YYYY-MM-DD-<query> and cd
• Ctrl‑D: delete the selected directory (requires typing YES to confirm)
• Esc/Ctrl‑C: cancel and return to the shell

Notes:

• If there’s no matching directory, Enter creates one (prefixed by YYYY-MM-DD-) and jumps into it.
• Ranking combines fuzzy score with recency to surface likely targets.
• Query terms that start with a hyphen must be placed after -- so they aren’t parsed as flags, for example: try cd -- --foo --bar. With the shell function installed, use: try -- --foo.

Deletion semantics

• Ctrl‑D prompts for confirmation; type YES to permanently delete the selected directory.
• File count and size are displayed before confirmation.
• Operations are restricted to the configured tries root; entries outside are never touched.

CLI Reference

• try (with no args): open the selector; with shell integration active, the wrapper evaluates the resulting shell commands for you.
• try --help: show top‑level help (lists subcommands and global options).
• try init [--path PATH] [PATH]: print the shell function; add it to your rc file.
• try cd [QUERY...] [--path PATH]: launch selector and print the cd/mkdir/touch commands (used by the shell function).
• try clone <git-uri> [name] [--path PATH]: print a clone pipeline (mkdir -p, git clone, touch, cd) into the tries directory.
• Shorthand: try <git-uri> behaves like try clone <git-uri> when shell integration is active.
• Subcommand help: try cd --help, try init --help, try clone --help.

Configuration

• Default tries directory: ~/src/tries
• Override via TRY_PATH env var or an absolute path argument to try init

Troubleshooting

• command not found: try: ensure ~/.local/bin (or ~/.cargo/bin if installed via cargo) is on your PATH or reference the binary directly, e.g. eval "$(~/.local/bin/try init)".
• try init prints a shell function: expected. init emits shell code; evaluate it with eval "$(try init)" (or add that line to your rc file) instead of treating the printed function as normal command output.
• try prints something like dir='...' && mkdir -p "$dir" && cd "$dir" or opens the selector but does not change directories: shell integration is not active. Run eval "$(try init)", then restart or reload your shell.
• try my-experiment or try https://github.com/... says unrecognized subcommand: without shell integration, use try cd my-experiment or try clone <git-uri> directly.
• Selector opens but no cd happens: confirm your rc file sources the init function and that you restarted/reloaded the shell. If you have multiple shells configured, ensure the integration is in the correct shell's RC file (e.g., ~/.zshrc for zsh, ~/.bashrc or ~/.bash_profile for bash).
• Wrong tries location: check echo $TRY_PATH or the path passed to init.

Development

• Build: cargo build (or cargo build --release)
• Run: cargo run -- [args] (e.g., cargo run -- cd foo)
• Test: cargo test --all --locked
• Lint: cargo clippy --all-targets -- -D warnings
• Format: cargo fmt --all

Architecture: single‑binary CLI using crossterm for TUI, dirs for home paths, and unicode-width for display width.

Colors

• Help and error output from clap uses its built‑in color logic (color: auto) and respects standard environment conventions.
• try’s own warnings and errors are styled on stderr when appropriate and degrade to plain text when not:
  • Colors enabled only if stderr is a TTY.
  • NO_COLOR disables colors.
  • CLICOLOR=0 disables; CLICOLOR_FORCE!=0 forces enable.
• When output is piped or redirected, styling is disabled to avoid ANSI sequences in logs.

Error Handling

• Internally, the app uses a small, typed error (thiserror) at high‑level boundaries and returns plain io::Error for low‑level file operations.
• The selector and CLI keep a lenient UX: non‑critical issues print a warning and continue; critical issues surface clearly and set a non‑zero exit where appropriate.

Security & Behavior

• try writes only under the configured tries directory (default ~/src/tries).
• No network access or secrets required.

License

MIT — see LICENSE.

Contributing

See CONTRIBUTING.md for workflow and PR expectations, and AGENTS.md for structure, commands, style, and testing guidelines.