Documentation/bup-ls.md

   1 % bup-ls(1) Bup %BUP_VERSION%
   2 % Avery Pennarun <apenwarr@gmail.com>
   3 % %BUP_DATE%
   4
   5 # NAME
   6
   7 bup-ls - list the contents of a bup repository
   8
   9 # SYNOPSIS
  10
  11 bup ls [-s] [-a] \<paths...\>
  12
  13 # DESCRIPTION
  14
  15 `bup ls` lists files and directories in your bup repository
  16 using the same directory hierarchy as they would have with
  17 `bup-fuse`(1).
  18
  19 The top level directory contains the branch (corresponding to
  20 the `-n` option in `bup save`), the next level is the date
  21 of the backup, and subsequent levels correspond to files in
  22 the backup.
  23
  24 When `bup ls` is asked to output on a tty, it formats its output
  25 in columns so that it can list as much as possible in as few lines
  26 as possible. However, when `bup ls` is asked to output to something
  27 other than a tty (say you pipe the output to another command, or you
  28 redirect it to a file), it will output one file name per line. This
  29 makes the listing easier to parse with external tools.
  30
  31 Note that `bup ls` doesn't show hidden files by default and one needs to use
  32 the `-a` option to show them. Files are hidden when their name begins with a
  33 dot. For example, on the topmost level, the special directories named `.commit`
  34 and `.tag` are hidden directories.
  35
  36 Once you have identified the file you want using `bup ls`,
  37 you can view its contents using `bup join` or `git show`.
  38
  39 # OPTIONS
  40
  41 -s, \--hash
  42 :   show hash for each file/directory.
  43
  44 -a, \--all
  45 :   show hidden files.
  46
  47 # EXAMPLE
  48
  49     bup ls /myserver/latest/etc/profile
  50
  51     bup ls -a /
  52
  53 # SEE ALSO
  54
  55 `bup-join`(1), `bup-fuse`(1), `bup-ftp`(1), `bup-save`(1), `git-show`(1)
  56
  57 # BUP
  58
  59 Part of the `bup`(1) suite.