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 bup meta \--edit
  27   ~ [\--set-uid *uid* | \--set-gid *gid* | \--set-user *user* | \--set-group *group* | ...] \<*paths*...\>
  28
  29 # DESCRIPTION
  30
  31 `bup meta` creates, extracts, or otherwise manipulates metadata
  32 archives.  A metadata archive contains the metadata information
  33 (timestamps, ownership, access permissions, etc.) for a set of
  34 filesystem paths.
  35
  36 See `bup-restore`(1) for a description of the way ownership metadata
  37 is restored.
  38
  39 # OPTIONS
  40
  41 -c, \--create
  42 :   Create a metadata archive for the specified *path*s.  Write the
  43     archive to standard output unless `--file` is specified.
  44
  45 -t, \--list
  46 :   Display information about the metadata in an archive.  Read the
  47     archive from standard input unless `--file` is specified.
  48
  49 -x, \--extract
  50 :   Extract a metadata archive.  Conceptually, perform `--start-extract`
  51     followed by `--finish-extract`.  Read the archive from standard input
  52     unless `--file` is specified.
  53
  54 \--start-extract
  55 :   Build a filesystem tree matching the paths stored in a metadata
  56     archive.  By itself, this command does not produce a full
  57     restoration of the metadata.  For a full restoration, this command
  58     must be followed by a call to `--finish-extract`.  Once this
  59     command has finished, all of the normal files described by the
  60     metadata will exist and be empty.  Restoring the data in those
  61     files, and then calling `--finish-extract` should restore the
  62     original tree.  The archive will be read from standard input
  63     unless `--file` is specified.
  64
  65 \--finish-extract
  66 :   Finish applying the metadata stored in an archive to the
  67     filesystem.  Normally, this command should follow a call to
  68     `--start-extract`.  The archive will be read from standard input
  69     unless `--file` is specified.
  70
  71 \--edit
  72 :   Edit metadata archives.  The result will be written to standard
  73     output unless `--file` is specified.
  74
  75 -f, \--file=*filename*
  76 :   Read the metadata archive from *filename* or write it to
  77     *filename* as appropriate.  If *filename* is "-", then read from
  78     standard input or write to standard output.
  79
  80 -R, \--recurse
  81 :   Recursively descend into subdirectories during `--create`.
  82
  83 \--xdev, \--one-file-system
  84 :   don't cross filesystem boundaries -- though as with tar and rsync,
  85     the mount points themselves will still be handled.
  86
  87 \--numeric-ids
  88 :   Apply numeric IDs (user, group, etc.) rather than names during
  89     `--extract` or `--finish-extract`.
  90
  91 \--symlinks
  92 :   Record symbolic link targets when creating an archive, or restore
  93     symbolic links when extracting an archive (during `--extract`
  94     or `--start-extract`).  This option is enabled by default.
  95     Specify `--no-symlinks` to disable it.
  96
  97 \--paths
  98 :   Record pathnames when creating an archive.  This option is enabled
  99     by default.  Specify `--no-paths` to disable it.
 100
 101 \--set-uid=*uid*
 102 :   Set the metadata uid to the integer *uid* during `--edit`.
 103
 104 \--set-gid=*gid*
 105 :   Set the metadata gid to the integer *gid* during `--edit`.
 106
 107 \--set-user=*user*
 108 :   Set the metadata user to *user* during `--edit`.
 109
 110 \--unset-user
 111 :   Remove the metadata user during `--edit`.
 112
 113 \--set-group=*group*
 114 :   Set the metadata user to *group* during `--edit`.
 115
 116 \--unset-group
 117 :   Remove the metadata group during `--edit`.
 118
 119 -v, \--verbose
 120 :   Be more verbose (can be used more than once).
 121
 122 -q, \--quiet
 123 :   Be quiet.
 124
 125 # EXAMPLES
 126
 127     # Create a metadata archive for /etc.
 128     $ bup meta -cRf etc.meta /etc
 129     bup: removing leading "/" from "/etc"
 130
 131     # Extract the etc.meta archive (files will be empty).
 132     $ mkdir tmp && cd tmp
 133     $ bup meta -xf ../etc.meta
 134     $ ls
 135     etc
 136
 137     # Restore /etc completely.
 138     $ mkdir tmp && cd tmp
 139     $ bup meta --start-extract -f ../etc.meta
 140     ...fill in all regular file contents using some other tool...
 141     $ bup meta --finish-extract -f ../etc.meta
 142
 143     # Change user/uid to root.
 144     $ bup meta --edit --set-uid 0 --set-user root \
 145         src.meta > dest.meta
 146
 147 # BUGS
 148
 149 Hard links are not handled yet.
 150
 151 # BUP
 152
 153 Part of the `bup`(1) suite.