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 [OPTION...] \<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, and `-l` is not specified,
  25 it formats the output in columns so it can list as much as possible in
  26 as few lines as possible. However, when `-l` is specified or bup is
  27 asked to output to something other than a tty (say you pipe the output
  28 to another command, or you redirect it to a file), it will print one
  29 file name per line. This makes the listing easier to parse with
  30 external tools.
  31
  32 Note that `bup ls` doesn't show hidden files by default and one needs to use
  33 the `-a` option to show them. Files are hidden when their name begins with a
  34 dot. For example, on the topmost level, the special directories named `.commit`
  35 and `.tag` are hidden directories.
  36
  37 Once you have identified the file you want using `bup ls`,
  38 you can view its contents using `bup join` or `git show`.
  39
  40 # OPTIONS
  41
  42 -s, \--hash
  43 :   show hash for each file/directory.
  44
  45 -a, \--all
  46 :   show hidden files.
  47
  48 -A, \--almost-all
  49 :   show hidden files, except "." and "..".
  50
  51 -d, \--directory
  52 :   show information about directories themselves, rather than their
  53     contents, and don't follow symlinks.
  54
  55 -l
  56 :   provide a detailed, long listing for each item.
  57
  58 -F, \--classify
  59 :   append type indicator: dir/, symlink@, fifo|, socket=, and executable*.
  60
  61 \--file-type
  62 :   append type indicator: dir/, symlink@, fifo|, socket=.
  63
  64 \--human-readable
  65 :   print human readable file sizes (i.e. 3.9K, 4.7M).
  66
  67 \--numeric-ids
  68 :   display numeric IDs (user, group, etc.) rather than names.
  69
  70 # EXAMPLES
  71     bup ls /myserver/latest/etc/profile
  72
  73     bup ls -a /
  74
  75 # SEE ALSO
  76
  77 `bup-join`(1), `bup-fuse`(1), `bup-ftp`(1), `bup-save`(1), `git-show`(1)
  78
  79 # BUP
  80
  81 Part of the `bup`(1) suite.