Update base_version to 0.34~ for 0.34 development

[bup.git] / Documentation / bup-meta.md

diff --git a/Documentation/bup-meta.md b/Documentation/bup-meta.md
index 2c2ea67f1c30ccb76f60839cad25a1a356a15fcd..c8d1d3769ed6e0ce4c33d49f1fc3eee6020a0e03 100644 (file)
--- a/Documentation/bup-meta.md
+++ b/Documentation/bup-meta.md
@@ -8,85 +8,118 @@ bup-meta - create or extract a metadata archive
 
 # SYNOPSIS
 
 
 # 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*]
   
   ~ [-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
 
 
 # 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
 
 
 # OPTIONS
 

--c, \-\-create
+-c, \--create

 :   Create a metadata archive for the specified *path*s.  Write the
 :   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
 :   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
 :   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
     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
     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
 :   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.
 
 :   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
 :   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
 :   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).
 
 :   Be more verbose (can be used more than once).
 

--q, --quiet
+-q, \--quiet

 :   Be quiet.
 
 # EXAMPLES
 :   Be quiet.
 
 # EXAMPLES


@@ -103,9 +136,13 @@ access permissions, etc.) for a set of filesystem paths.
 
     # Restore /etc completely.
     $ mkdir tmp && cd tmp
 
     # 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...
     ...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
 
 
 # BUGS