.\" Automatically generated by Pandoc 3.5
.\"
.TH "bup\-meta" "1" "2026\-01\-28" "Bup 0.33.10+"
.SH NAME
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
\f[CR]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[CR]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[CR]\-\-file\f[R] is
specified.
.TP
\-t, \-\-list
Display information about the metadata in an archive.
Read the archive from standard input unless \f[CR]\-\-file\f[R] is
specified.
.TP
\-x, \-\-extract
Extract a metadata archive.
Conceptually, perform \f[CR]\-\-start\-extract\f[R] followed by
\f[CR]\-\-finish\-extract\f[R].
Read the archive from standard input unless \f[CR]\-\-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[CR]\-\-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[CR]\-\-finish\-extract\f[R] should restore the original tree.
The archive will be read from standard input unless \f[CR]\-\-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[CR]\-\-start\-extract\f[R].
The archive will be read from standard input unless \f[CR]\-\-file\f[R]
is specified.
.TP
\-\-edit
Edit metadata archives.
The result will be written to standard output unless \f[CR]\-\-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[CR]\-\-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[CR]\-\-extract\f[R] or
\f[CR]\-\-finish\-extract\f[R].
.TP
\-\-symlinks
Record symbolic link targets when creating an archive, or restore
symbolic links when extracting an archive (during \f[CR]\-\-extract\f[R]
or \f[CR]\-\-start\-extract\f[R]).
This option is enabled by default.
Specify \f[CR]\-\-no\-symlinks\f[R] to disable it.
.TP
\-\-paths
Record pathnames when creating an archive.
This option is enabled by default.
Specify \f[CR]\-\-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[CR]\-\-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[CR]\-\-edit\f[R].
.TP
\-\-set\-user=\f[I]user\f[R]
Set the metadata user to \f[I]user\f[R] during \f[CR]\-\-edit\f[R].
.TP
\-\-unset\-user
Remove the metadata user during \f[CR]\-\-edit\f[R].
.TP
\-\-set\-group=\f[I]group\f[R]
Set the metadata user to \f[I]group\f[R] during \f[CR]\-\-edit\f[R].
.TP
\-\-unset\-group
Remove the metadata group during \f[CR]\-\-edit\f[R].
.TP
\-v, \-\-verbose
Be more verbose (can be used more than once).
.TP
\-q, \-\-quiet
Be quiet.
.SH EXAMPLES
.IP
.EX
# 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
.EE
.SH BUGS
Hard links are not handled yet.
.SH BUP
Part of the \f[CR]bup\f[R](1) suite.
.SH AUTHORS
Rob Browning \c
.MT rlb@defaultvalue.org
.ME \c.