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 \--numeric-ids
  84 :   Apply numeric IDs (user, group, etc.) rather than names during
  85     `--extract` or `--finish-extract`.
  86
  87 \--symlinks
  88 :   Record symbolic link targets when creating an archive, or restore
  89     symbolic links when extracting an archive (during `--extract`
  90     or `--start-extract`).  This option is enabled by default.
  91     Specify `--no-symlinks` to disable it.
  92
  93 \--paths
  94 :   Record pathnames when creating an archive.  This option is enabled
  95     by default.  Specify `--no-paths` to disable it.
  96
  97 \--set-uid=*uid*
  98 :   Set the metadata uid to the integer *uid* during `--edit`.
  99
 100 \--set-gid=*gid*
 101 :   Set the metadata gid to the integer *gid* during `--edit`.
 102
 103 \--set-user=*user*
 104 :   Set the metadata user to *user* during `--edit`.
 105
 106 \--unset-user
 107 :   Remove the metadata user during `--edit`.
 108
 109 \--set-group=*group*
 110 :   Set the metadata user to *group* during `--edit`.
 111
 112 \--unset-group
 113 :   Remove the metadata group during `--edit`.
 114
 115 -v, \--verbose
 116 :   Be more verbose (can be used more than once).
 117
 118 -q, \--quiet
 119 :   Be quiet.
 120
 121 # EXAMPLES
 122
 123     # Create a metadata archive for /etc.
 124     $ bup meta -cRf etc.meta /etc
 125     bup: removing leading "/" from "/etc"
 126
 127     # Extract the etc.meta archive (files will be empty).
 128     $ mkdir tmp && cd tmp
 129     $ bup meta -xf ../etc.meta
 130     $ ls
 131     etc
 132
 133     # Restore /etc completely.
 134     $ mkdir tmp && cd tmp
 135     $ bup meta --start-extract -f ../etc.meta
 136     ...fill in all regular file contents using some other tool...
 137     $ bup meta --finish-extract -f ../etc.meta
 138
 139     # Change user/uid to root.
 140     $ bup meta --edit --set-uid 0 --set-user root \
 141         src.meta > dest.meta
 142
 143 # BUGS
 144
 145 Hard links are not handled yet.
 146
 147 # BUP
 148
 149 Part of the `bup`(1) suite.