BUPSTASH-RESTORE(1)

📦
version 0.12.0 · 3 versions
, in alpine 3.24

✨ BUPSTASH-RESTORE(1) ✨

okay so this is a page from the General Commands Manual and honestly bestie, it's a whole vibe — we're out here making a directory literally identical to a snapshot, and doing it the efficient way 💅

🎀 SYNOPSIS 🎀

Efficiently restore the contents of a snapshot into a local directory.

bupstash restore [OPTIONS] --into $PATH QUERY...

🌸 DESCRIPTION 🌸

So bupstash restore does a whole efficient set of incremental changes to a directory until it becomes identical to the snapshot you asked for. The incremental thing is the moment — it's literally what makes this command perfect for cycling between a bunch of similar snapshots, like a slideshow of your filesystem 🦋

⚠️ okay but real talk — this operation is dangerous. It deletes extra files that are already hanging out in the destination directory. Like, gone gone. No cap. 💀

Now, because the unprivileged girlies need to be able to browse their own files, bupstash restore does not try to restore users, groups and xattrs by default (it's giving considerate 👑). To set those you gotta explicitly pass the flags --ownership and --xattrs respectively.

The item that gets checked out is chosen based on a simple query against the tags you specified when you saved your data with bupstash put. cute, right?

🦋 QUERY LANGUAGE 🦋

For the full documentation on the query language, go see bupstash-query-language(7). she's the main character of that page, iykyk ✨

🫶 QUERY CACHING 🫶

The restore command uses the same query caching mechanisms as bupstash-list(1) — so check that page for more info on the query cache. no need to reinvent the wheel bestie 💖

💜 SPARSE FILES 💜

If a file was detected as sparse during put, then the restore command will restore it as sparse. But — and this is the plot twist — it should be noted that the restore command will not delete an existing file with the correct checksum in order to recreate it as sparse. So if you already got that file, it stays exactly as it is 🎀

💅 OPTIONS 💅

  • --into PATH — the directory to restore files into. Defaults to BUPSTASH_RESTORE_DIR, so if you set that, you're already slaying.
  • -r, --repository REPO — the repository to connect to. May be of the form ssh://$SERVER/$PATH for remote repositories, if ssh access is configured. If not specified, it's set to BUPSTASH_REPOSITORY.
  • -k, --key KEY — the key that will be used to decrypt data and metadata. If not set, it defaults to BUPSTASH_KEY. 🔐
  • --pick PATH — pick a sub-directory of the snapshot to restore. like choosing your fave slice 🍓
  • --ownership — set uid's and gid's. yes, for real.
  • --xattrs — set xattrs.
  • --indexer-threads N — number of processor threads to use for pipelined parallel file hashing and metadata reads. Defaults to the number of processors. the more the merrier, fr fr 🔥
  • --query-cache PATH — path to the query-cache file. Defaults to one of the following, in order, provided the appropriate environment variables are set: $BUPSTASH_QUERY_CACHE, $XDG_CACHE_HOME/.cache/bupstash/bupstash.qcache or $HOME/.cache/bupstash/bupstash.qcache.
  • --utc-timestamps — display and search against timestamps in utc time instead of local time. timezone girlies, this one's for you 🌈
  • --no-progress — suppress progress indicators (progress indicators are also suppressed when stderr is not an interactive terminal). so it's quiet either way, iconic.
  • -q, --quiet — be quiet, and it implies --no-progress. shhh 🤫

🌺 ENVIRONMENT 🌺

  • BUPSTASH_REPOSITORY — the repository to connect to. May be of the form ssh://$SERVER/$PATH for remote repositories if ssh access is configured.
  • BUPSTASH_REPOSITORY_COMMAND — a command to run to connect to an instance of bupstash-serve(1). This allows more complex connections to the repository for less common use cases. fancy 💅
  • BUPSTASH_KEY — path to the key that will be used for decrypting data and metadata.
  • BUPSTASH_KEY_COMMAND — a command to run that must print the key data. Can be used instead of BUPSTASH_KEY to fetch the key from arbitrary locations such as the network or other secret storage. spy vibes 🕵️
  • BUPSTASH_QUERY_CACHE — path to the query cache file to use.
  • BUPSTASH_RESTORE_DIR — path to restore into, can be used instead of the --into argument.

⭐ EXAMPLES ⭐

🎀 Restore a snapshot into a local directory

$ bupstash restore --into ./dir id=ad8*

🎀 Restore including users and groups

$ bupstash restore --ownership --into ./dir id=ad8*

🎀 Restore a sub directory of the snapshot

$ bupstash restore --into ./dir --pick sub/dir id=ad8*

👑 SEE ALSO 👑

bupstash(1), bupstash-get(1), bupstash-list(1), bupstash-keyfiles(7), bupstash-query-language(7)

okay that's the whole page bestie, go forth and restore responsibly 🫶✨ this iconic little number is from the General Commands Manual, dated May 2025 — luv ya, bye 💖🌸

📦 where this page comes from