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 .Dd September 27, 2015
  34 .Dt UNDO 1
  35 .Os
  36 .Sh NAME
  37 .Nm undo
  38 .Nd Undo changes made to files on HAMMER filesystems
  39 .Sh SYNOPSIS
  40 .Nm
  41 .Op Fl adDiuv
  42 .Op Fl o Ar outfile
  43 .Op Fl t Ar transaction-id
  44 .Op Fl t Ar transaction-id
  45 .Ar
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 utility acquires an older version of the specified files and can output
  50 them to stdout, generate a file with the previous contents, or generate
  51 a diff to stdout.  A history can also be generated.
  52 .Pp
  53 The options are as follows:
  54 .Bl -tag -width indent
  55 .It Fl d
  56 Generate a unified diff from the older version to the current version.
  57 .It Fl D
  58 Generate a unified diff from the current version to the older version.
  59 .It Fl i
  60 Generate a single line giving the transaction id and converted timestamp
  61 of the version of the file requested, rather than dumping the contents
  62 of the file.
  63 .It Fl a
  64 Iterate through the file's entire history generating undo files, diffs,
  65 output, etc.  Note that due to the way file creation is laid down a
  66 file may appear to be zero-filled just after creation before the data
  67 is actually synced.  There will be a later version with the synced
  68 data.  This is a known bug.
  69 .It Fl u
  70 Output to a file with name synthesized from the input filename postfixed with ".undo".
  71 If not specified output is either to stdout or, if a single file argument
  72 is given, the file specified by the
  73 .Fl o
  74 option.
  75 .It Fl v
  76 Increase verboseness.
  77 .It Fl o Ar outfile
  78 Output to the specified file instead of to stdout.  If iterating through
  79 a file's entire history
  80 .Ar outfile
  81 will be postfixed with an iteration number in the form "outfile.%04d".
  82 If multiple files are specified
  83 .Ar outfile
  84 is used as a template where '%s' is replaced with the last component of
  85 each file path.  When used with multiple files '%%' must be used in the
  86 .Ar outfile
  87 specification to indicate a '%'.  When used with a single file the
  88 .Ar outfile
  89 string is used verbatim.
  90 .It Fl t Ar transaction-id
  91 Specify how far to go back in time, by giving a hexadecimal HAMMER
  92 transaction id which must start with "0x".  If not specified
  93 the program will attempt to locate the most recent version of the
  94 file(s) prior to the current version.
  95 This option does not apply if
  96 .Fl a
  97 is specified.
  98 .Pp
  99 A second
 100 .Fl t
 101 specification may be given to provide two end-points for a diff, and
 102 will imply
 103 .Fl d
 104 unless overridden.
 105 .Pp
 106 Transaction ids always start with "0x".
 107 A simple index may be
 108 specified instead of a transaction id where 0 indicates the latest version
 109 and increasing values indicate older versions.
 110 .El
 111 .Sh EXIT STATUS
 112 .Ex -std
 113 .Sh EXAMPLES
 114 .Li "undo -d mytextfile"
 115 .Pp
 116 .Li "undo -o mytextfile.old mytextfile"
 117 .Sh DIAGNOSTICS
 118 .Bl -diag
 119 .It "Warning: fake transaction id path@@0x..."
 120 While locating past versions of the file,
 121 .Nm
 122 came across a fake transaction id, which are automatically generated by
 123 .Xr hammer 5
 124 in case the file's directory entry and inode got bisected in the past.
 125 .El
 126 .Sh SEE ALSO
 127 .Xr hammer 8
 128 .Sh HISTORY
 129 The
 130 .Nm
 131 utility first appeared in
 132 .Dx 1.13 .
 133 .Sh AUTHORS
 134 .An Matthew Dillon Aq Mt dillon@backplane.com
 135 .Sh BUGS
 136 HAMMER only synchronizes information to disk every 30 seconds or so and
 137 a quick file create / delete is done entirely in system memory and cannot
 138 be undone.  This can be worked around by running
 139 .Dq Nm hammer Cm synctid Ar filesystem .