usr.bin/undo/undo.1

   1 .\" Copyright (c) 2008 The DragonFly Project.  All rights reserved.
   2 .\"
   3 .\" This code is derived from software contributed to The DragonFly Project
   4 .\" by Matthew Dillon <dillon@backplane.com>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\"
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in
  14 .\"    the documentation and/or other materials provided with the
  15 .\"    distribution.
  16 .\" 3. Neither the name of The DragonFly Project nor the names of its
  17 .\"    contributors may be used to endorse or promote products derived
  18 .\"    from this software without specific, prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  23 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  24 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  26 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  27 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  28 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  29 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  30 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\" $DragonFly: src/usr.bin/undo/undo.1,v 1.5 2008/07/16 21:38:10 dillon Exp $
  34 .Dd November 16, 2009
  35 .Dt UNDO 1
  36 .Os
  37 .Sh NAME
  38 .Nm undo
  39 .Nd Undo changes made to files on HAMMER filesystems
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Op Fl adDiuv
  43 .Op Fl o Ar outfile
  44 .Op Fl t Ar transaction-id
  45 .Op Fl t Ar transaction-id
  46 .Ar
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility acquires an older version of the specified files and can output
  51 them to stdout, generate a file with the previous contents, or generate
  52 a diff to stdout.  A history can also be generated.
  53 .Pp
  54 The options are as follows:
  55 .Bl -tag -width indent
  56 .It Fl d
  57 Generate a unified diff from the older version to the current version.
  58 .It Fl D
  59 Generate a unified diff from the current version to the older version.
  60 .It Fl i
  61 Generate a single line giving the transaction id and converted timestamp
  62 of the version of the file requested, rather than dumping the contents
  63 of the file.
  64 .It Fl a
  65 Iterate through the file's entire history generating undo files, diffs,
  66 output, etc.  Note that due to the way file creation is laid down a
  67 file may appear to be zero-filled just after creation before the data
  68 is actually synced.  There will be a later version with the synced
  69 data.  This is a known bug.
  70 .It Fl u
  71 Output to a file with name synthesized from the input filename postfixed with ".undo".
  72 If not specified output is either to stdout or, if a single file argument
  73 is given, the file specified by the
  74 .Fl o
  75 option.
  76 .It Fl v
  77 Increase verboseness.
  78 .It Fl o Ar outfile
  79 Output to the specified file instead of to stdout.  If iterating through
  80 a file's entire history
  81 .Ar outfile
  82 will be postfixed with an iteration number in the form "outfile.%04d".
  83 If multiple files are specified
  84 .Ar outfile
  85 is used as a template where '%s' is replaced with the last component of
  86 each file path.  When used with multiple files '%%' must be used in the
  87 .Ar outfile
  88 specification to indicate a '%'.  When used with a single file the
  89 .Ar outfile
  90 string is used verbatim.
  91 .It Fl t Ar transaction-id
  92 Specify how far to go back in time, by giving a HAMMER
  93 transaction id (0x16chars).  If not specified
  94 the program will attempt to locate the most recent version of the
  95 file(s) prior to the current version.
  96 This option does not apply if
  97 .Fl a
  98 is specified.
  99 .Pp
 100 A second
 101 .Fl t
 102 specification may be given to provide two end-points for a diff, and
 103 will imply
 104 .Fl d
 105 unless overridden.
 106 .Pp
 107 Transaction ids always start with "0x".
 108 A simple index may be
 109 specified instead of a transaction id where 0 indicates the latest version
 110 and increasing values indicate older versions.
 111 .El
 112 .Sh EXIT STATUS
 113 .Ex -std
 114 .Sh EXAMPLES
 115 .Li "undo -d mytextfile"
 116 .Pp
 117 .Li "undo -o mytextfile.old mytextfile"
 118 .Sh DIAGNOSTICS
 119 .Bl -diag
 120 .It "Warning: fake transaction id 0x..."
 121 While locating past versions of the file,
 122 .Nm
 123 came across a fake transaction id, which are automatically generated by
 124 .Xr hammer 5
 125 in case the file's directory entry and inode got bisected in the past.
 126 .El
 127 .Sh SEE ALSO
 128 .Xr hammer 8
 129 .Sh HISTORY
 130 The
 131 .Nm
 132 utility first appeared in
 133 .Dx 1.13 .
 134 .Sh AUTHORS
 135 .An Matthew Dillon Aq dillon@backplane.com
 136 .Sh BUGS
 137 HAMMER only synchronizes information to disk every 30 seconds or so and
 138 a quick file create / delete is done entirely in system memory and cannot
 139 be undone.  This can be worked around by running
 140 .Dq Nm hammer Cm synctid Ar filesystem .