About
History
Features
Performance
Team
Images

Community
Download
Mirrors
Documentation
Mailing Lists
Source
Commercial
Donations
Bugs

Security
PGP Keys

Exports
Hammer

howtoslide

Introduction

The purpose of this document is to demonstrate how to use the Slider utility to browse through file history and recover/undelete files and directories.

Installing Slider

The HAMMER file system time slider utility is available via dports, thus it can be installed by either binary package or by building from source.

packages

# pkg ins slider

It is recommended that binary packages be used because Slider is written in Ada which requires an Ada compiler -- this compiler can take quite some time to build from source.

ports

If building from source is desired, you may wish to consider installing the Ada compiler from binary packages:

# pkg ins gcc-aux

However, this step is optional. It will be built automatically when the next command is invoked:

# cd /usr/dports/sysutils/slider ; make install

Verify that slider is installed

# rehash ; slider

===============================================
  HAMMER file system time slider utility 2.02
===============================================
       Copyright (C) 2014 John R. Marino


Usage: slider file [save-target]
-or-   slider existing-directory [save-target]

This tool enables the user to browse through all available versions of the
given file stored in HAMMER history, view differences between two versions,
replace the current version with any previous version, restore a deleted file,
and save any previous or deleted version to a new file.

If slider is passed the path of an existing directory, the history of that
directory will be searched for all deleted files and subdirectories that can
be restored, along with the option to restore them.

Typical non-successful messages

Specifying a file that does not and never did exist

# slider /root/nonexistant-file
Error: There is no current file with that name, nor is has any trace of a
deleted version of '/root/nonexistant-file' being found.

You might also see this error if the file was on a non-HAMMER filesystem, or if the HAMMER filesystem has had it's history wiped either forcibly or through normal schedule maintenance.

Specifying an existing file that has no historical versions available

# slider /var/log/slip.log
Sorry, this file has no previous version available.

Specifying an existing directory that doesn't contain deleted entries

# slider /home/marino
Sorry, no deleted entries were detected in this directory.

Slider will scan the directory for records of deleted files or subdirectories. Failure to find even a single record results in the message above.

Browse historical versions of an existing file

The default for the HAMMER filesystem is to create a daily snapshot of the pseudo-filesystem and then remove all versions that aren't captured by an existing snapshot. That means the versions available to restore are all those that existed before the nightly maintenance and those that exist on a snapshot. It is common to see dozens of versions of a highly-edited file and on the next day see that list reduced to only a couple of versions.

Get list of valid transactions

If all you want to do is browse through historical versions, just provide the path to the existing file as a single argument:

# slider ~/.joe_state

If historical versions are found, slider will display them in columns, and even pages if necessary (it adjusts to the console size).

Note that this list could be shorter than what is produced by "hammer history". That is because each version is checked to see if it is a valid inode that can be read. It's not uncommon to run into bad transaction IDs, so they are filtered out for you.

View the file if it is considered a text file

Slider will pre-scan the existing version of the file to determine if the file is a text file or a binary file using logic similar to "diff" and "svn". If it detects that it is a text file, it will allow the file to be viewed minus unprintable characters. To do this, simply use the arrow keys to select the timestamp desired and press the "F1" key. This menu item will be brightly colored for text files and disabled in dark gray when it is a binary file.

The text file will be displayed. The up and down arrow keys can be used to switch between pages. If the file is longer than the equivalent of one hundred 80x22 pages, it will be truncated. Note that files with a huge number of columns such as /usr/ports/INDEX-4 will only have a few pages due to this. Press "F4" key when done viewing.

Viewing the difference between historical versions

It is possible to view the difference between any two versions (current or historical) with either considered "original" or "changed". The current version is considered the "original" file by default, and it is indicated by a bright white color. The version that is back-lighted blue is considered the "changed" version, and this can be manipulated by selecting a different file with the arrow keys. Pressing the ">" key will show the diff between them, and pressing the "<" will show the reverse diff between them.

The "diff" can be browsed via paged just as the contents can, and "F4" returns to the version list.

In the event you don't want to include the current version of the file in the diff view, you can designate a different version as the "original" one. All you do is use the arrow keys to select the desired "origin" version and press the "0" (zero) key. That version will now display bright white and the arrow keys should be used to designate a new "changed" file for the diff view.

Restoring a historical version to a new filename

If slider doesn't receive a second argument which is a target path, it defines the target path as the original path plus ".restored" suffix. Thus it is possible to quickly save a copy of the historical version of the file in a predictable place. Just select the desired version and press the "F3" key to save it there.

You will be shown where the file will be saved. To cancel, just hit "F4" key, otherwise hit the "F1" to save the file and exit Slider. In the console you should see a success screen like the one below, but in a terminal emulator it might disappear before you see it.

Restoring a historical version to the current file

If you want to revert the specified file to an earlier version of itself, just select the "F2" (save) option. You will get a similar confirmation and success screen, followed by Slider's exit.

Scan directory to fully restore a deleted directory

It is possible to completely restore a deleted directory assuming the parent directory exists. To do this, pass the name of the parent directory to slider and it will scan that directory for deleted entries (both files and subdirectories) and display them if found:

# slider /usr

Directories are shown in cyan and prefixed with @@0x and a 16-digit hex number. Files are shown in light gray with no prefix.

To restore the last known directory, use the arrow keys to highlight it and either press "F1" or the "Enter" key.

You will be shown an informational screen showing that you selected a deleted directory and showing its time stamp. That time should match when the directory was deleted. At this point you can choose to view the contents, restore the directory, or exit.

View the contents of a deleted directory (static listing only)

Let's see what the contents look like by pressing "F1" key:

The directory can be browsed in pages. It is not possible to browse the files or subdirectories, it is just a static view. Press "F4" key to return to the informational screen.

Restore the complete directory to the original location

If a restoration to the original location is desired, just select the "F2" option. After passing a confirmation screen, the entire directory will be restored to where it was before.

Restore the complete directory to the default location

If a restoration to the default location of ".restored" is desired, that will be the result of selecting the "F3" option and confirming the restoration.

Restore the complete directory to a specified location.

Let's say we want to restore this directory to my home directory. I'd execute slide something like this:

# slider /usr /home/marino/old-ports.backup

Then I would select the "ports.old" directory and press the "F3" button. Now the confirmation screen looks like this:

At this point, choose "F1" to complete the restoration or "F4" to return to the previous screen.

Scan directory to restore a deleted file

If you already know the name of the file you want to restore, exactly, you can just type it in. However, if you don't know the name of the file, or you aren't sure how it's spelled, or you just plain forgot what's in the directory, just scan the parent directory and see:

# slider /usr/ports/lang

Okay, so this directory has both directories and a file in it.

View the contents of a deleted file from directory scan

It's easy to see the contents if the deleted file was a text file. Just press "F1" or "Enter" to select the file ...

... and you will see that the selection is a file, when it was deleted, and if it is viewable. If it's a binary file, all you can do is exit or restore it. However, if it's a text file, you can view it!

As before, you may view the text file in pages and return from the view by pressing "F4"

Restore the file to the original location

From the information screen, just select "F2" and confirm with "F1" to restore the last version of the deleted file to it's original location.

Restore the file to the default location

Assuming only one argument was passed to Slider, just select "F3" and confirm the default location of ".restored" and confirm by pressing "F1".

Restore the file to a specified location

Invoke slider with two arguments, the first being the path of the parent directory and the second being the path to restore the file to. Then just select the file via the list, press "F3" key, and confirm with "F1" key.

Undelete a file in an existing directory (filename is known)

If the full path to the deleted file is known, you can just pass it directly to Slider:

# ls -al /usr/local/etc/col*
ls: No match.
# slider /usr/local/etc/colord.conf

If Slider thinks it can restore that file, you'd see a screen like this:

As before, there is only one version considered, the last known one. You can either recover it or leave. The easiest thing to do is just press the "F2" to restore the file to its former location:

In the case of selecting "F2" (save), Slider won't even ask you to confirm, it will just do it! In the case of selecting "F3" you will be presented with a confirmation that changes depending on if a target path was specified or not.

It worked!

# ls -al /usr/local/etc/col*
-rw-r--r--  1 root  wheel  1330 Jan 16 17:25 /usr/local/etc/colord.conf

Report issues or provide feedback about Slider

The best place to report issues, bugs or provide feedback about slider is https://github.com/jrmarino/Slider/issues

Other places are possible such as DragonFly mailing list, DPorts issues, or DragonFly bug tracker, but it is less effective to place reports there.

Enjoy Slider!

Site copyright © 2003-2022