.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "bup-meta" "1" "2021-02-06" "Bup 0.32" ""
.hy
.SH NAME
.PP
bup-meta - create or extract a metadata archive
.SH SYNOPSIS
.TP
bup meta --create
[-R] [-v] [-q] [--no-symlinks] [--no-paths] [-f \f[I]file\f[R]]
<\f[I]paths\f[R]\&...>
.TP
bup meta --list
[-v] [-q] [-f \f[I]file\f[R]]
.TP
bup meta --extract
[-v] [-q] [--numeric-ids] [--no-symlinks] [-f \f[I]file\f[R]]
.TP
bup meta --start-extract
[-v] [-q] [--numeric-ids] [--no-symlinks] [-f \f[I]file\f[R]]
.TP
bup meta --finish-extract
[-v] [-q] [--numeric-ids] [-f \f[I]file\f[R]]
.TP
bup meta --edit
[--set-uid \f[I]uid\f[R] | --set-gid \f[I]gid\f[R] | --set-user
\f[I]user\f[R] | --set-group \f[I]group\f[R] | \&...]
<\f[I]paths\f[R]\&...>
.SH DESCRIPTION
.PP
\f[C]bup meta\f[R] 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.
.PP
See \f[C]bup-restore\f[R](1) for a description of the way ownership
metadata is restored.
.SH OPTIONS
.TP
-c, --create
Create a metadata archive for the specified \f[I]path\f[R]s.
Write the archive to standard output unless \f[C]--file\f[R] is
specified.
.TP
-t, --list
Display information about the metadata in an archive.
Read the archive from standard input unless \f[C]--file\f[R] is
specified.
.TP
-x, --extract
Extract a metadata archive.
Conceptually, perform \f[C]--start-extract\f[R] followed by
\f[C]--finish-extract\f[R].
Read the archive from standard input unless \f[C]--file\f[R] is
specified.
.TP
--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
\f[C]--finish-extract\f[R].
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
\f[C]--finish-extract\f[R] should restore the original tree.
The archive will be read from standard input unless \f[C]--file\f[R] is
specified.
.TP
--finish-extract
Finish applying the metadata stored in an archive to the filesystem.
Normally, this command should follow a call to
\f[C]--start-extract\f[R].
The archive will be read from standard input unless \f[C]--file\f[R] is
specified.
.TP
--edit
Edit metadata archives.
The result will be written to standard output unless \f[C]--file\f[R] is
specified.
.TP
-f, --file=\f[I]filename\f[R]
Read the metadata archive from \f[I]filename\f[R] or write it to
\f[I]filename\f[R] as appropriate.
If \f[I]filename\f[R] is \[lq]-\[rq], then read from standard input or
write to standard output.
.TP
-R, --recurse
Recursively descend into subdirectories during \f[C]--create\f[R].
.TP
--xdev, --one-file-system
don\[cq]t cross filesystem boundaries \[en] though as with tar and
rsync, the mount points themselves will still be handled.
.TP
--numeric-ids
Apply numeric IDs (user, group, etc.) rather than names during
\f[C]--extract\f[R] or \f[C]--finish-extract\f[R].
.TP
--symlinks
Record symbolic link targets when creating an archive, or restore
symbolic links when extracting an archive (during \f[C]--extract\f[R] or
\f[C]--start-extract\f[R]).
This option is enabled by default.
Specify \f[C]--no-symlinks\f[R] to disable it.
.TP
--paths
Record pathnames when creating an archive.
This option is enabled by default.
Specify \f[C]--no-paths\f[R] to disable it.
.TP
--set-uid=\f[I]uid\f[R]
Set the metadata uid to the integer \f[I]uid\f[R] during
\f[C]--edit\f[R].
.TP
--set-gid=\f[I]gid\f[R]
Set the metadata gid to the integer \f[I]gid\f[R] during
\f[C]--edit\f[R].
.TP
--set-user=\f[I]user\f[R]
Set the metadata user to \f[I]user\f[R] during \f[C]--edit\f[R].
.TP
--unset-user
Remove the metadata user during \f[C]--edit\f[R].
.TP
--set-group=\f[I]group\f[R]
Set the metadata user to \f[I]group\f[R] during \f[C]--edit\f[R].
.TP
--unset-group
Remove the metadata group during \f[C]--edit\f[R].
.TP
-v, --verbose
Be more verbose (can be used more than once).
.TP
-q, --quiet
Be quiet.
.SH EXAMPLES
.IP
.nf
\f[C]
# Create a metadata archive for /etc.
$ bup meta -cRf etc.meta /etc
bup: removing leading \[dq]/\[dq] from \[dq]/etc\[dq]

# 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 \[rs]
    src.meta > dest.meta
\f[R]
.fi
.SH BUGS
.PP
Hard links are not handled yet.
.SH BUP
.PP
Part of the \f[C]bup\f[R](1) suite.
.SH AUTHORS
Rob Browning <rlb@defaultvalue.org>.