X-Git-Url: https://arthur.barton.de/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=Documentation%2Fbup-meta.md;h=c8d1d3769ed6e0ce4c33d49f1fc3eee6020a0e03;hb=e4ada8c5f7ba1b8273fa8edcda226fe526647e7b;hp=2c2ea67f1c30ccb76f60839cad25a1a356a15fcd;hpb=6f6a1111ea20316499ad748a1cb118ec5d5c117f;p=bup.git

diff --git a/Documentation/bup-meta.md b/Documentation/bup-meta.md
index 2c2ea67..c8d1d37 100644
--- a/Documentation/bup-meta.md
+++ b/Documentation/bup-meta.md
@@ -8,85 +8,118 @@ bup-meta - create or extract a metadata archive
 
 # SYNOPSIS
 
-bup meta \-\-create
-  ~ [-R] [-v] [-q] [\-\-no-symlinks] [\-\-no-paths] [-f *file*] \<*paths*...\>
+bup meta \--create
+  ~ [-R] [-v] [-q] [\--no-symlinks] [\--no-paths] [-f *file*] \<*paths*...\>
   
-bup meta \-\-list
+bup meta \--list
   ~ [-v] [-q] [-f *file*]
   
-bup meta \-\-extract
-  ~ [-v] [-q] [\-\-numeric-ids] [\-\-no-symlinks] [-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 \--start-extract
+  ~ [-v] [-q] [\--numeric-ids] [\--no-symlinks] [-f *file*]
   
-bup meta \-\-finish-extract
-  ~ [-v] [-q] [\-\-numeric-ids] [-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` either creates or extracts a metadata archive.  A metadata
-archive contains the metadata information (timestamps, ownership,
-access permissions, etc.) for a set of filesystem paths.
+`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
+-c, \--create
 :   Create a metadata archive for the specified *path*s.  Write the
-    archive to standard output unless **\-\-file** is specified.
+    archive to standard output unless `--file` is specified.
 
--t, \-\-list
+-t, \--list
 :   Display information about the metadata in an archive.  Read the
-    archive from standard output unless **\-\-file** is specified.
+    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.
+-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
+\--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
+    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
+    files, and then calling `--finish-extract` should restore the
     original tree.  The archive will be read from standard input
-    unless **\-\-file** is specified.
+    unless `--file` is specified.
 
-\-\-finish-extract
+\--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.
+    `--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*
+-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**.
+-R, \--recurse
+:   Recursively descend into subdirectories during `--create`.
 
-\-\-numeric-ids
-:   Apply numeric user and group IDs (rather than text IDs) during
-    **\-\-extract** or **\-\-finish-extract**.
+\--xdev, \--one-file-system
+:   don't cross filesystem boundaries -- though as with tar and rsync,
+    the mount points themselves will still be handled.
 
-\-\-symlinks
+\--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.
+    symbolic links when extracting an archive (during `--extract`
+    or `--start-extract`).  This option is enabled by default.
+    Specify `--no-symlinks` to disable it.
 
-\-\-paths
+\--paths
 :   Record pathnames when creating an archive.  This option is enabled
-    by default.  Specify **\-\-no-paths** to disable it.
+    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`.
 
--v, --verbose
+\--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
+-q, \--quiet
 :   Be quiet.
 
 # EXAMPLES
@@ -103,9 +136,13 @@ access permissions, etc.) for a set of filesystem paths.
 
     # Restore /etc completely.
     $ mkdir tmp && cd tmp
-    $ bup meta \-\-start-extract -f ../etc.meta
+    $ bup meta --start-extract -f ../etc.meta
     ...fill in all regular file contents using some other tool...
-    $ bup meta \-\-finish-extract -f ../etc.meta
+    $ 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