NAME

snapshot

Simple utility which uses diff/patch to snapshot a single text file without touching the original file.

SYNOPSIS

snapshot <OPERATION> [OPTIONS] <FILE>

DESCRIPTION

When a revision history of a single file in a home directory is desired, all of the other version control systems are difficult to use in such a simple use case. RCS, CVS, and git are suited for multi-user collaborations on entire directory trees. Tracking one file is a pain. Most of these use a "black box" data storage. Common operations like check-ins can also delete and then recreate the source file, which freaks out most text editors.

I wanted something that used common GNU diff and patch tools and stored patches in a hidden directory for a single file. You can even view or edit the individual patch revisions if you want. And it supports a simple comment in each patch if you desire. All without ever modifying the original source file.

This is meant to be run from a cron job to keep track of text files like a .bashrc, .bash_history or a scratchpad of notes or to-do lists.

REQUIREMENTS

This script requires perl packages:

• Getopt::Long (perl-Getopt-Long)

• Pod::Usage (perl-Pod-Usage)

• Switch (libswitch-perl or perl-Switch)

• File::Spec

Requires GNU utilities diff, patch, mktemp and date

OPERATION

save

Save a diff of the file

--message or -m <string>

Optionally add a message to the diff file. Keep it only one line.

restore

Roll through the diffs and create a temp file at a snapshotted point in time. Does NOT modify the original file.

--time or -t <string>

By default, restore will patch up to the most recent patch file stored in the snapshot directory. Specify a time string to be parsed by your local GNU date --date utility. Examples like "last Thursday", "2021-12-08 13:27:00" or "2 weeks ago + 5 hours"

view

Restore a snapshot to a temp file and view it with whatever your $EDITOR is set to.

Also accepts the --time parameter like the restore operation. After your editor exits, the temp file will be deleted.

list

List the snapshots for this file

grep [OPTIONS]

Grep through the contents of all snapshots. OPTIONS are passed directly to your system's grep utility.

GLOBAL OPTIONS

--help

Show usage information

--man

Show the full manual page. Includes more content than the --help display.

--snapshot_dir </path/to/directory>

By default, snapshot creates a new subdirectory within the absolute path of the given FILE. The directory name is .FILE-snapshot

Override this if you want something special.

--verbose --debug

By default, this script runs fairly quiet for use with scripts and crontabs. Add verbose or debug for extra noise

EXAMPLES

Start or save a new snapshot

$ snapshot save myfile.txt

$ snapshot save --verbose --message "Updates to TODO list" myfile.txt

View a list of snapshots

$ snapshot list myfile.txt
Patch Time                      Comment

Wed Dec  8 13:10:13 CST 2021    Original Snapshot
Wed Dec  8 13:25:07 CST 2021    Updates to TODO list 

Restore a temp snapshot

$ snapshot restore --time "15 minutes ago" myfile.txt
File /tmp/tmp.gN8bAHpsRE is restored to time Wed Dec  8 13:10:13 CST 2021

$ snapshot restore --time "Wed Dec  8 13:25:07" myfile.txt
File /tmp/tmp.qrAayDnLQI is restored to time Wed Dec  8 13:25:07 CST 2021

View a temp snapshot

$ snapshot view --time "last Thursday" myfile.txt

Files are plain text patches

$ ls -l .myfile.txt-snapshot/
-rw-rw-r-- 13  Dec  8 13:10 original
-rw-rw-r-- 174 Dec  8 13:25 1638991507.patch

Grep your .bash_history snapshots for a command

$ snapshot grep 'aws ecs create-service' .bash_history
$ snapshot grep -i apigateway .bash_history