// TEMPRS — TEMPORARY FILE STACK MANAGER

Quickstart

Install from crates.io or build from source. tp is the short alias; temprs is the long name. Both binaries are identical.

# install
cargo install temprs

# from source
git clone https://github.com/MenkeTechnologies/temprs
cd temprs && cargo build --release

# push stdin to a new tempfile on top of stack
echo "hello" | tp

# list the stack
tp -l

# read top of stack to stdout
tp | wc -l

# read tempfile at index 1
tp -o 1 | head -5

# tag a tempfile so you can recall it by name
ps aux | tp -w procs
tp -o procs | grep firefox

Full install + usage live in the README; two man pages are shipped under man/man1/ — a short reference (temprs.1, man temprs) and a full manual (temprsall.1, man temprsall).

Stack architecture

Tempfiles are ordered in a persistent stack. Top of stack is the newest entry. Indices are 1-based ascending from the bottom; negative indices count from the top (-1 = top, -stack_size = bottom). Index 0 is always invalid.

Files live in $TMPDIR/temprs/ (override with TEMPRS_DIR). The master record (temprs-stack) maps each stack position to its filename and optional tag; the individual payloads are tempfile<timestamp> files alongside it. Writes go through temprs-stack.tmp and are atomically renamed, with a temprs-stack.lock guarding concurrent access. Stack position is reconstructed from the master on every invocation, so multiple shells share one canonical view.

Dual indexing — by position or by @name

Every operation that takes an INDEX also accepts a tag name. Resolution order: numeric parse first, then tag lookup. Names are unique across the stack and travel with their files through every stack mutation (move, swap, duplicate). Names render with a @ prefix in listings.

# tag on creation
ps aux | tp -w procs

# tag on existing file (rename)
tp -R 1 newname
tp -R procs procs2

# use the tag anywhere INDEX is accepted
tp -o procs
tp -r procs
tp -A procs < more.txt
tp -M procs 1
tp -S procs other
tp -x procs
tp --head procs 10
tp --replace procs old new

Operations — full surface

Flag reference

The same flag set is bound under both binaries. Long forms shown where they exist; tp -h prints the cyberpunk banner + grouped help.

Data integrity

The master record is the single source of truth for the stack. Three layered protections prevent corruption under concurrent access:

• Null-byte delimited format — fields separated by \0, records by \0\0. Filenames containing newlines, tabs, spaces, or any other shell-metacharacters parse correctly. No quoting, no escaping.
• Atomic writes — the master is written to a sibling temp file and renamed into place. A crash mid-write leaves the previous master intact; readers never see a partial record.
• Exclusive file locking — fs2::FileExt::lock_exclusive wraps every read-modify-write. Two shells racing on the same stack serialize cleanly; neither sees a half-mutated state.
• Auto-recovery — corrupt or empty records (e.g. from an aborted external edit) are silently skipped on read and cleaned up on the next write.

Environment

Shell integration

A zsh completion lives at completions/_temprs and dynamically resolves stack indices, file names, and @name tags — tab-completion sees the current stack, not a static word list.

# install into your fpath
cp completions/_temprs /usr/local/share/zsh/site-functions/_tp

# or extend fpath in .zshrc
fpath=(/path/to/temprs/completions $fpath)
autoload -Uz compinit && compinit

Two groff man pages are shipped under man/man1/ — temprs.1 (short reference) and temprsall.1 (full manual). Install to a directory on $MANPATH for man temprs and man temprsall.

Pipeline examples

# capture, transform, recall
ps aux | tp -w procs
tp -o procs | awk '$3 > 5'

# diff two captures
curl -s api/v1/state | tp -w before
make deploy
curl -s api/v1/state | tp -w after
tp -D before after

# build a working set, then dump it
grep -r TODO src | tp -w todos
grep -r FIXME src | tp -w fixmes
tp -C todos fixmes | sort -u

# edit a captured payload, then re-emit
curl -s config.json | tp -w cfg
tp -e cfg
tp -o cfg | curl -X PUT --data-binary @- api/v1/config

# expiry & housekeeping
tp --expire 24    # drop anything older than a day
tp --expire 0.5   # drop anything older than 30 minutes
tp -c             # drop everything

Exit codes & scripting

A few operations are designed to be used in shell conditionals — they set the exit status, not just print output:

• tp -g PATTERN — exits 0 if any tempfile matches, 1 if none. Use it as a guard: tp -g needle && echo found.
• tp -D a b — unified diff; exits 0 when the two tempfiles are identical, 1 when they differ.
• tp --replace N PAT REPL — performs the in-place edit and prints the number of replacements made, so a script can branch on whether anything changed.
• tp --path N — prints the raw filesystem path with no decoration, intended for command substitution: cat "$(tp --path 1)".

Troubleshooting

Errors are written to stderr in a terse form. The messages map directly to the constants in src/util/consts.rs:

Custom directory safety. tp -c (purge all) refuses to operate unless the basename of the temprs directory contains the string temprs. This guards against an accidental TEMPRS_DIR=$HOME wiping unrelated files. Keep temprs in any custom directory name.

If the stack ever looks inconsistent, inspect the raw store: tp -d prints the temprs directory and tp -m prints the master record path. Empty or malformed records are skipped on read and cleaned up on the next write, so a single bad record self-heals.

Development & CI

The repository ships with a GitHub Actions workflow at .github/workflows/ci.yml that runs cargo check, the full cargo test suite (5,644 tests — 5,059 unit + 585 integration), cargo fmt --check, cargo clippy, cargo doc, and a release build on every push to main and on every pull request. Criterion benchmarks live under benches/benchmarks.rs (cargo bench).

For more detail on architecture, test breakdown, and module-level statistics, see the engineering report.