Stash File Stack

Stash is a stack-based file management tool for the terminal. It lets you temporarily move files and directories out of your working tree, then restore them later.

Stash is designed to feel obvious: in many cases, you don’t need to specify whether you’re pushing or popping — Stash infers your intent based on context.

---

Table of Contents

1. Features

2. Installation

   1. Install via Cargo
   2. Build from Source

3. Usage

   1. Basic Operations
   2. How Operations Are Inferred
   3. Push (Stash Files)
   4. Pop (Restore Files)
   5. Peek (Copy Without Removing)
   6. Delete Entry
   7. List Entries
   8. Search Entries
   9. View Information
   10. Clean Old Entries
   11. Rename Entry
   12. Export to Archive
   13. Dump All Entries

4. Examples

5. License

6. Contributing

---

Features

• Stack-based workflow — Push files into a stash, pop them back later
• Operation inference — Automatically decides whether to stash or restore
• History & metadata — Track creation time, size, and contents
• Automatic cleanup — Remove old entries after a configurable time

---

Installation

Install via Cargo

cargo install stash-rs

Ensure Cargo’s bin directory is in your PATH:

export PATH="$HOME/.cargo/bin:$PATH"

---

Build from Source

Requires Rust and Cargo:

git clone https://github.com/what386/stash-rs.git
cd stash-rs
cargo build --release

Executable:

./target/release/stash-rs

---

Usage

All commands support --help:

stash --help

---

Basic Operations

Stash tries to “do the right thing” based on context.

# Stash a file (it exists locally)
stash file.txt

# Restore it later (file no longer exists locally)
stash file.txt

# Restore the most recent entry
stash

You can always force a specific operation using flags such as --push or --pop.

---

How Operations Are Inferred

When you run:

stash [items...]

Stash determines what you mean using a small set of predictable rules.

Inference Rules (Priority Order)

1. No arguments → Pop (restore) the most recent entry

2. All arguments exist as paths in the current directory → Push (stash) those files or directories

3. Argument matches a stashed entry name → Pop that entry

4. Argument matches files inside a stashed entry → Pop the entry containing those files

5. Ambiguous or no match → Prompt for clarification or require explicit flags

---

Examples

# No args → restore most recent
stash

# File exists in the current directory → stash it
stash notes.txt

# File is not in the current directory, but entry name matches → restore
stash notes.txt

# Multiple paths in current directory → stash together in one entry

# Multiple path entries are the first item's filename..
stash readme.md license

# Or passed explicitly via the "--name <NAME>" flag
stash data/ schema.sql -n project-data

---

Ambiguity Handling

If a name refers to both a local file and a stashed entry:

stash work.txt

Stash will prompt you to resolve the issue:

Multiple matches found:
1. File "work.txt" in current directory (push)
2. Stashed entry "work.txt" (pop)

Select an option (1–2), or use --push / --pop to specify.

You can control this behavior via configuration or bypass it entirely using explicit flags.

---

Forcing an Operation

Explicit flags always override inference:

stash --push work.txt     # Always stash
stash --pop work.txt      # Always restore
stash --peek work.txt     # Copy out without removing

---

General idea

• If it exists here → stash it
• If it exists in stash → restore it
• If it’s unclear → be explicit

---

Push (Stash Files)

stash <file1> [file2 ...] [options]

Options:

• --name / -n <NAME> – Name the entry
• --copy / -c – Copy instead of move
• --link / -l – Leave symlinks behind

Examples:

stash file.txt dir/
stash src/ -n "project-source-old"
stash document.pdf --copy
stash config/ --link

---

Pop (Restore Files)

stash --pop [identifier] [options]

Options:

• --copy / -c – Copy instead of move
• --force / -f – Overwrite existing files
• --restore – Restore to original paths

Examples:

stash
stash "project-backup"
stash --restore
stash --copy

---

Peek (Copy Without Removing)

stash --peek [identifier]

Examples:

stash --peek
stash --peek work-files

---

List Entries

stash --list

Displays:

• Name
• UUID
• Creation date
• Size
• Item count

---

Search Entries

stash --search <pattern>

stash --search project

---

View Information

stash --info [identifier]

stash --info
stash --info backup-2024

---

Clean Old Entries

stash --clean [days]

stash --clean
stash --clean 7

---

Rename Entry

stash --rename <old:new>

stash --rename "temp:production-backup"

---

Export to Archive

stash --tar <output-file>

stash --tar backup.tar

---

Dump All Entries

stash --dump [--delete]

stash --dump
stash --dump --delete

---

Examples

Temporary Cleanup

stash old-code/ notes.txt
# work on something else
stash

Context Switching

stash src/ --name feature-x
stash src/ --name bugfix-y
stash feature-x --restore

Quick Backups

# create config-backup, move to stash
stash config/ --copy --name config-backup

# restore config-backup from stash
stash config-backup

---

Contributing

Contributions are welcome! Issues and pull requests can be submitted on GitHub.