stash-rs 0.2.1

Stack-based file management for the terminal.
stash-rs-0.2.1 is not a library.

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
  3. Usage
    1. Basic Operations
    2. How Operations Are Inferred
    3. Push (Stash Files)
    4. Pop (Restore Files)
    5. List Entries
    6. Search Entries
    7. View Information
    8. Clean Old Entries
    9. Rename Entry
    10. Export to Archive
    11. Dump All Entries

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

Usage

All commands support --help:

stash --help

Basic Operations

# 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

How Operations Are Inferred

When you run:

stash [items...]

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

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

  2. All arguments exist locally → Push (stash) those files or directories

  3. Argument does not exist locally → Treated as a stash entry identifier and restored

  4. Ambiguous input → Requires explicit flags or clarification

Push (Stash Files)

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

Options:

  • --name, -n <NAME> Assign a custom name to the stash entry

  • --copy, -c Copy files instead of moving them

Examples:

stash file.txt dir/
stash src/ -n project-source
stash document.pdf --copy

Pop (Restore Files)

stash [identifier] [options]

Options:

  • --copy, -c Copy files instead of moving them

  • --force, -f Overwrite existing files when restoring

  • --restore, -r Restore files to their original paths

Examples:

stash
stash backup-2024
stash --restore
stash --force

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 --rn <old:new>

stash --rename temp:production-backup

Export to Archive

stash --tar <output-file>

stash --tar backup.tar

Dump All Entries

Restore all entries in stash order:

stash --dump

This restores every entry to the current directory using safe defaults.

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

stash config/ --copy --name config-backup
stash config-backup

Contributing

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