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 [-r *host*:[*path*]] [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 -r, \--remote=*host*:[*path*]
  43 :   list information for the repository at *path* on the indicated
  44     *host*.  If *path* is omitted, uses the default path on the remote
  45     server (you still need to include the ':').  The connection to the
  46     remote server will be made by SSH.  If you'd like to specify the
  47     port, user, or private key, we recommend you use the
  48     `~/.ssh/config` file (`ssh_config(5)`).
  49
  50 -s, \--hash
  51 :   show hash for each file/directory.
  52
  53 -a, \--all
  54 :   show hidden files.
  55
  56 -A, \--almost-all
  57 :   show hidden files, except "." and "..".
  58
  59 -d, \--directory
  60 :   show information about directories themselves, rather than their
  61     contents, and don't follow symlinks.
  62
  63 -l
  64 :   provide a detailed, long listing for each item.
  65
  66 -F, \--classify
  67 :   append type indicator: dir/, symlink@, fifo|, socket=, and executable*.
  68
  69 \--file-type
  70 :   append type indicator: dir/, symlink@, fifo|, socket=.
  71
  72 \--human-readable
  73 :   print human readable file sizes (i.e. 3.9K, 4.7M).
  74
  75 \--numeric-ids
  76 :   display numeric IDs (user, group, etc.) rather than names.
  77
  78 # EXAMPLES
  79     bup ls /myserver/latest/etc/profile
  80
  81     bup ls -a /
  82
  83 # SEE ALSO
  84
  85 `bup-join`(1), `bup-fuse`(1), `bup-ftp`(1), `bup-save`(1),
  86 `git-show`(1), `ssh_config`(5)
  87
  88 # BUP
  89
  90 Part of the `bup`(1) suite.