bup-ls(1)

💖 bup-ls(1) — the "what's even IN here" command 💖

okay bestie, welcome to the General Commands Manual for bup-ls, aka the little icon that lets you peek inside your bup repository 🎀

---

✨ NAME ✨

bup-ls — list the contents of a bup repository 🦋

---

🌸 SYNOPSIS 🌸

bup ls [-r host:[path]] [OPTION...]  <paths...>

---

👑 DESCRIPTION 👑

so like, bup ls lists the files and directories chillin' in your bup repository, and it uses the exact same directory hierarchy you'd get with bup-fuse(1). same vibes, different command 💅

The top level directory contains the branch (this is the one that corresponds to the -n option in bup save), the next level down is the date of the backup, and every level after that corresponds to files in the backup. it's giving tree structure, fr fr 🌳

When bup ls is asked to output on a tty, and -l is not specified, it formats the output in columns so it can list as much as possible in as few lines as possible. cute and efficient ✨ BUT — when -l is specified, or when bup is asked to output to something that isn't a tty (say you pipe the output to another command, or you redirect it to a file), it will print one file name per line. This makes the listing easier to parse with external tools. lowkey genius 🧠

heads up babe: bup ls doesn't show hidden files by default, and you need the -a option to show them. Files are hidden when their name begins with a dot. For example, on the topmost level, the special directories named .commit and .tag are hidden directories. sneaky little things 🙈

Once you've identified the file you want using bup ls, you can view its contents using bup join or git show. easy peasy 🍓

---

💅 OPTIONS 💅

• -r, --remote=[user@]host:[path], --remote=URL — draw the information from the specified remote repository, by default via SSH. See bup(1) REMOTE OPTIONS for further information 🌈
• -s, --hash — show hash for each file/directory 🔥
• -a, --all — show hidden files 👀
• -A, --almost-all — show hidden files, except “.” and “..” 💀
• -d, --directory — show information about directories themselves, rather than their contents, and don’t follow symlinks 🚫🔗
• -l — provide a detailed, long listing for each item 📋
• -F, --classify — append type indicator: dir/, symlink@, fifo|, socket=, and executable* ⭐
• --file-type — append type indicator: dir/, symlink@, fifo|, socket= 🏷️
• --human-readable — print human readable file sizes (i.e. 3.9K, 4.7M) 🫶
• --numeric-ids — display numeric IDs (user, group, etc.) rather than names 🔢

---

🌈 EXAMPLES 🌈

bup ls /myserver/latest/etc/profile

bup ls -a /

---

🦋 SEE ALSO 🦋

bup-join(1), bup-fuse(1), bup-ftp(1), bup-save(1), git-show(1), ssh_config(5)

---

🎀 BUP 🎀

Part of the bup(1) suite. you're in the family now 👑

---

💜 AUTHORS 💜

Avery Pennarun apenwarr@gmail.com

---

and that's the whole page bestie, no cap 💖 this was Bup 0.34, dated 2026-09-01 — main character energy from the bup-ls(1) manual, periodt ✨🫶