# NAME

bup-meta - create or extract a metadata archive

# SYNOPSIS

bup meta --create
  [-R] [-v] [-q] [--no-symlinks] [--no-paths] [-f file] <paths…>
bup meta --list
  [-v] [-q] [-f file]
bup meta --extract
  [-v] [-q] [--numeric-ids] [--no-symlinks] [-f file]
bup meta --start-extract
  [-v] [-q] [--numeric-ids] [--no-symlinks] [-f file]
bup meta --finish-extract
  [-v] [-q] [--numeric-ids] [-f file]
bup meta --edit
  [--set-uid uid | --set-gid gid | --set-user user | --set-group group | …] <paths…>

# DESCRIPTION

`bup meta` creates, extracts, or otherwise manipulates metadata archives. A metadata archive contains the metadata information (timestamps, ownership, access permissions, etc.) for a set of filesystem paths.

See `bup-restore`(1) for a description of the way ownership metadata is restored.

# OPTIONS

-c, --create
  Create a metadata archive for the specified paths. Write the archive to standard output unless `--file` is specified.
-t, --list
  Display information about the metadata in an archive. Read the archive from standard input unless `--file` is specified.
-x, --extract
  Extract a metadata archive. Conceptually, perform `--start-extract` followed by `--finish-extract`. Read the archive from standard input unless `--file` is specified.
--start-extract
  Build a filesystem tree matching the paths stored in a metadata archive. By itself, this command does not produce a full restoration of the metadata. For a full restoration, this command must be followed by a call to `--finish-extract`. Once this command has finished, all of the normal files described by the metadata will exist and be empty. Restoring the data in those files, and then calling `--finish-extract` should restore the original tree. The archive will be read from standard input unless `--file` is specified.
--finish-extract
  Finish applying the metadata stored in an archive to the filesystem. Normally, this command should follow a call to `--start-extract`. The archive will be read from standard input unless `--file` is specified.
--edit
  Edit metadata archives. The result will be written to standard output unless `--file` is specified.
-f, --file=filename
  Read the metadata archive from filename or write it to filename as appropriate. If filename is “-”, then read from standard input or write to standard output.
-R, --recurse
  Recursively descend into subdirectories during `--create`.
--xdev, --one-file-system
  don’t cross filesystem boundaries – though as with tar and rsync, the mount points themselves will still be handled.
--numeric-ids
  Apply numeric IDs (user, group, etc.) rather than names during `--extract` or `--finish-extract`.
--symlinks
  Record symbolic link targets when creating an archive, or restore symbolic links when extracting an archive (during `--extract` or `--start-extract`). This option is enabled by default. Specify `--no-symlinks` to disable it.
--paths
  Record pathnames when creating an archive. This option is enabled by default. Specify `--no-paths` to disable it.
--set-uid=uid
  Set the metadata uid to the integer uid during `--edit`.
--set-gid=gid
  Set the metadata gid to the integer gid during `--edit`.
--set-user=user
  Set the metadata user to user during `--edit`.
--unset-user
  Remove the metadata user during `--edit`.
--set-group=group
  Set the metadata user to group during `--edit`.
--unset-group
  Remove the metadata group during `--edit`.
-v, --verbose
  Be more verbose (can be used more than once).
-q, --quiet
  Be quiet.

# EXAMPLES

    # Create a metadata archive for /etc.
    $ bup meta -cRf etc.meta /etc
    bup: removing leading "/" from "/etc"

    # Extract the etc.meta archive (files will be empty).
    $ mkdir tmp && cd tmp
    $ bup meta -xf ../etc.meta
    $ ls
    etc

    # Restore /etc completely.
    $ mkdir tmp && cd tmp
    $ bup meta --start-extract -f ../etc.meta
    ...fill in all regular file contents using some other tool...
    $ bup meta --finish-extract -f ../etc.meta

    # Change user/uid to root.
    $ bup meta --edit --set-uid 0 --set-user root \
        src.meta > dest.meta

# BUGS

Hard links are not handled yet.

# BUP

Part of the `bup`(1) suite.