Documentation/bup-meta.md

   1 % bup-meta(1) Bup %BUP_VERSION%
   2 % Rob Browning <rlb@defaultvalue.org>
   3 % %BUP_DATE%
   4
   5 # NAME
   6
   7 bup-meta - create or extract a metadata archive
   8
   9 # SYNOPSIS
  10
  11 bup meta \-\-create
  12   ~ [-R] [-v] [-q] [\-\-no-symlinks] [\-\-no-paths] [-f *file*] \<*paths*...\>
  13
  14 bup meta \-\-list
  15   ~ [-v] [-q] [-f *file*]
  16
  17 bup meta \-\-extract
  18   ~ [-v] [-q] [\-\-numeric-ids] [\-\-no-symlinks] [-f *file*]
  19
  20 bup meta \-\-start-extract
  21   ~ [-v] [-q] [\-\-numeric-ids] [\-\-no-symlinks] [-f *file*]
  22
  23 bup meta \-\-finish-extract
  24   ~ [-v] [-q] [\-\-numeric-ids] [-f *file*]
  25
  26 # DESCRIPTION
  27
  28 `bup meta` either creates or extracts a metadata archive.  A metadata
  29 archive contains the metadata information (timestamps, ownership,
  30 access permissions, etc.) for a set of filesystem paths.
  31
  32 # OPTIONS
  33
  34 -c, \-\-create
  35 :   Create a metadata archive for the specified *path*s.  Write the
  36     archive to standard output unless **\-\-file** is specified.
  37
  38 -t, \-\-list
  39 :   Display information about the metadata in an archive.  Read the
  40     archive from standard output unless **\-\-file** is specified.
  41
  42 -x, \-\-extract
  43 :   Extract a metadata archive.  Conceptually, perform **\-\-start-extract**
  44     followed by **\-\-finish-extract**.  Read the archive from standard input
  45     unless **\-\-file** is specified.
  46
  47 \-\-start-extract
  48 :   Build a filesystem tree matching the paths stored in a metadata
  49     archive.  By itself, this command does not produce a full
  50     restoration of the metadata.  For a full restoration, this command
  51     must be followed by a call to **\-\-finish-extract**.  Once this
  52     command has finished, all of the normal files described by the
  53     metadata will exist and be empty.  Restoring the data in those
  54     files, and then calling **\-\-finish-extract** should restore the
  55     original tree.  The archive will be read from standard input
  56     unless **\-\-file** is specified.
  57
  58 \-\-finish-extract
  59 :   Finish applying the metadata stored in an archive to the
  60     filesystem.  Normally, this command should follow a call to
  61     **\-\-start-extract**.  The archive will be read from standard input
  62     unless **\-\-file** is specified.
  63
  64 -f, \-\-file=*filename*
  65 :   Read the metadata archive from *filename* or write it to
  66     *filename* as appropriate.  If *filename* is "-", then read from
  67     standard input or write to standard output.
  68
  69 -R, \-\-recurse
  70 :   Recursively descend into subdirectories during **\-\-create**.
  71
  72 \-\-numeric-ids
  73 :   Apply numeric user and group IDs (rather than text IDs) during
  74     **\-\-extract** or **\-\-finish-extract**.
  75
  76 \-\-symlinks
  77 :   Record symbolic link targets when creating an archive, or restore
  78     symbolic links when extracting an archive (during **\-\-extract**
  79     or **\-\-start-extract**).  This option is enabled by default.
  80     Specify **\-\-no-symlinks** to disable it.
  81
  82 \-\-paths
  83 :   Record pathnames when creating an archive.  This option is enabled
  84     by default.  Specify **\-\-no-paths** to disable it.
  85
  86 -v, --verbose
  87 :   Be more verbose (can be used more than once).
  88
  89 -q, --quiet
  90 :   Be quiet.
  91
  92 # EXAMPLES
  93
  94     # Create a metadata archive for /etc.
  95     $ bup meta -cRf etc.meta /etc
  96     bup: removing leading "/" from "/etc"
  97
  98     # Extract the etc.meta archive (files will be empty).
  99     $ mkdir tmp && cd tmp
 100     $ bup meta -xf ../etc.meta
 101     $ ls
 102     etc
 103
 104     # Restore /etc completely.
 105     $ mkdir tmp && cd tmp
 106     $ bup meta \-\-start-extract -f ../etc.meta
 107     ...fill in all regular file contents using some other tool...
 108     $ bup meta \-\-finish-extract -f ../etc.meta
 109
 110 # BUGS
 111
 112 Hard links are not handled yet.
 113
 114 # BUP
 115
 116 Part of the `bup`(1) suite.