BUPSTASH-DIFF(1)

📦
version 0.12.0 · 3 versions
, in alpine 3.24

💅 BUPSTASH-DIFF(1) — the diff page, but make it cute

okay bestie so this is a page from the General Commands Manual, and it's literally all about bupstash diff. buckle up, it's actually so good 🦋

✨ SYNOPSIS ✨

Diff two snapshots and print the summary to stdout. that's the whole vibe.

bupstash diff [OPTIONS] QUERY1... :: QUERY2...

🌸 DESCRIPTION 🌸

bupstash diff fetches two snapshot listings from the remote server and compares them, then prints the diff line output to stdout. so far so normal, right? 💅

Buuut here's the special case: if either query starts with './' or '/', a temporary listing gets created for that local directory so it can be compared too. local dir girlies stay winning 🎀

and like, why use this instead of just running traditional diff against the output of bupstash list-contents? because bupstash diff is preferred, obviously — it takes the full precision of timestamps into account and the stored file hash when it performs the diff operation. traditional diff could never 💀

bupstash also supports ignoring items in the diff comparison to help with analysis. useful examples are the --ignore values times (to ignore file modification timestamps) and content (to ignore file size and hash changes). obsessed with the flexibility ngl 🫶

⭐ OUTPUT FORMAT ⭐

Output is consistent with that of bupstash list-contents, except each line is prefixed with either + or -, representing removed or added items respectively. cute little markers, very demure 🌸

specifying --format alters the underlying output format as described by bupstash-list-contents(1). and the good news? lines are still prefixed with either + or - regardless of the output format. no cap, the prefix stays 🔥

🦋 QUERY LANGUAGE 🦋

for the full documentation on the query language, see bupstash-query-language(7). go read it, it's giving reference material 👑

💜 QUERY CACHING 💜

the diff command uses the same query caching mechanisms as bupstash-list(1). check that page for more info on the query cache — it's all there i promise 🙈

✨ OPTIONS ✨

  • -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 used to decrypt data and metadata. if not set, defaults to BUPSTASH_KEY 🔑
  • --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. order matters bestie 🌈
  • -i, --ignore — comma separated list of file attributes to ignore in comparisons. valid items are 'content,dev,devnos,inode,type,perms,nlink,uid,gid,times,xattrs' 👀
  • --relaxed — shortcut for --ignore 'dev,inode,nlink,uid,gid,times,xattrs'. this one's useful for comparing content without being so concerned with machine specific metadata. so chill of it 🧚
  • --{left,right}-pick PATH — perform the diff on a sub-directory of the left/right query 🎯
  • --indexer-threads N — number of processor threads to use for pipelined parallel file hashing and metadata reads. defaults to the number of processors. go parallel or go home ⚡
  • --xattrs — fetch xattrs when indexing a local directories 🍓
  • --format FORMAT — set output format to one of the following: 'human', 'jsonl' 💅
  • --utc-timestamps — display and search against timestamps in utc time instead of local time 🕐
  • --no-progress — suppress progress indicators. (progress indicators are also suppressed when stderr is not an interactive terminal, fyi) 🙈
  • -q, --quiet — be quiet, implies --no-progress 🤫

🌸 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. niche but iconic 🎀
  • BUPSTASH_KEY — path to a primary 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 shit, love it 🕵️
  • BUPSTASH_QUERY_CACHE — path to the query cache file to use 🗂️

🦋 EXAMPLES 🦋

compare two snapshots by query

$ bupstash diff id="14eb*" :: id="57de*"
- -rw-r--r-- 1.1kB hello.txt
+ -rw-r--r-- 1.3kB goodbye.txt

look at that, one file gone, one file arrived. character development 😭

compare a snapshot and a local directory

$ bupstash diff --left-pick files --relaxed id="57de*" :: ./files

see how ./files kicks off that local-directory special case? chefs kiss 👑✨

💜 SEE ALSO 💜

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

that's the whole page bestie, go diff something 🫶

sign-off: this adorableness comes to you from May 2025, sourced straight out of the General Commands Manual edition of BUPSTASH-DIFF(1). periodt. 💅🎀
📦 where this page comes from