---
name: "bup-ls"
section: "1"
platform: "linux"
package: "bup"
version: "0.34-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/bup-ls"
---

# bup-ls(1)

list the contents of a bup repository

## NAME

bup-ls - list the contents of a bup repository

## SYNOPSIS

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

## DESCRIPTION

`bup ls` lists files and directories in your bup repository using the same directory hierarchy as they would have with [`bup-fuse`(1)](/bup-fuse/1.md).

The top level directory contains the branch (corresponding to the `-n` option in `bup save`), the next level is the date of the backup, and subsequent levels correspond to files in the backup.

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. However, when `-l` is specified or bup is asked to output to something other than 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.

Note that `bup ls` doesn’t show hidden files by default and one needs to use 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.

Once you have identified the file you want using `bup ls`, you can view its contents using `bup join` or `git show`.

## OPTIONS

- \-r, --remote=\[*user*@\]*host*:\[*path*\], --remote=URL

  draw the information from the specified remote repository, by default via SSH. See [bup(1)](/bup/1.md) 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-join/1.md), [`bup-fuse`(1)](/bup-fuse/1.md), [`bup-ftp`(1)](/bup-ftp/1.md), [`bup-save`(1)](/bup-save/1.md), [`git-show`(1)](/git-show/1.md), [`ssh_config`(5)](/ssh_config/5.md)

## BUP

Part of the [`bup`(1)](/bup/1.md) suite.

## AUTHORS

Avery Pennarun ⟨apenwarr@gmail.com⟩\\c.