snapshot

A very opinionated, bare-metal Bash tool to synchronize snapshots of directories with a remote FTPES server.

Designed for macOS and UNIX distributions, it provides a straightforward way to create, upload, and download snapshots of any working directory with minimal hassle.

Just cd into the directory you want to snapshot, and run snapshot push or snapshot pull to manage your snapshots.

snapshot automates the process of zipping/unzipping archives of directories, and downloading/uploading them to/from a remote FTP server, ultimately saving thousands of mouse clicks and keystrokes.

• Straightforward usage with simple commands.
• Super lightweight, about 7KB in size.
• Minimal dependencies by using only zip, unzip, find and curl.
• Supports weird FTPES servers using TLS v1.2.
• Human-friendly info and error messages.
• Configure it once and use it anywhere.

Bonus: When snapshot detects that the directory is a Flutter, Node.js or Rust project, and if the appropriate commands are available, it automatically runs the stack-specific cleanup before packing the snapshot. This ensures that snapshots of such projects are free of unnecessary build artifacts, to optimize storage space and network transfer.

Why?

The initial motivation for this tool was to avoid committing ugly work-in-progress code to Git, especially when working on multiple machines simultaneously. It allows to quickly snapshot your current working directory and push it to a remote server, ensuring you can always retrieve your latest work without cluttering your Git history — all in a few seconds, and with a two-words command.

However, this tool is useful in many other power-user scenarios, such as:

• Backing up music, photos, etc.
• Avoid relying on cloud services to keep stuff synchronized across devices.
• Archiving projects before making significant changes.
• Archiving old projects to free up space on your local machine.

Usage

snapshot [pack | push | pull | compare | history] [-q | --quiet]

Important: All of these commands must be invoked from the directory you want to snapshot — ie. when in my_project, running these commands will assume it manages snapshot of the my_project directory.

Commands

• pack: Creates a snapshot of the current working directory. A snapshot is a ZIP archive containing the current state of the directory. The snapshot is named with the directory name, and the archive's root is a directory with the same name containing the files.

• push: Packs a snapshot and uploads it to the remote FTP server. Note that this command calls pack first, so you don't have to run it beforehand.

• pull: Downloads the latest snapshot from the remote FTP server to the current working directory, and replaces the current contents with the snapshot's contents.

  Note: If the local directory is not empty, it will be replaced with the snapshot's contents, so make sure to back up any important files before running this command.

• compare: Checks the last modification date for both the local working directory and the remote snapshot, and lists the differences between them. This is useful to see what has changed since the last snapshot was taken.

• history: Displays the server's copy of the history of all operations performed by the snapshot tool, including timestamps and status. When in doubt, it allows to get informations about the operation type (push or pull), the exact size of the snapshot, and the path where it was pushed/pulled. If multiple machines interact with the same remote server, this history will include operations from all of them, which is why the hostname is also included in each entry.

• -q or --quiet: Suppresses or reduces output messages, useful for scripting or when you don't need detailed feedback.

Examples

First, navigate to the directory where you want to snapshot your work:

cd ~/Documents/Work/my_project

To take a snapshot of the current working directory and send it to the remote server, simply run:

snapshot push

This is typically used when you want to save the contents of your current working directory to the remote server, ensuring you can safely retrieve it later from (almost) anywhere in the world.

Later on, to download the latest snapshot from the remote server and replace the current working directory's contents, run:

snapshot pull

Installation

1. Move the snapshot executable to usr/local/bin, and make it executable:

   mv snapshot /usr/local/bin/snapshot
   chmod +x /usr/local/bin/snapshot

2. Create your user configuration file at ~/.snapshot/config:

   mkdir -p ~/.snapshot
   nano ~/.snapshot/config
   chmod 600 ~/.snapshot/config

3. Edit the configuration file with your FTP server credentials:

   REMOTE_HOST="your.ftp.server"
   REMOTE_PORT="21"  # Default FTP port
   REMOTE_USER="your_username"
   REMOTE_PASS="bmljZSB0cnksIGRpZGR5"  # base64 encoded
   REMOTE_PATH="/path/to/remote/directory"

Ideas

• Add an interactive credentials provisioning flow when the tool runs for the first time.

• Add a confirmation when pushing to the remote server, showing the last time the remote snapshot was updated.

• Add a confirmation when pulling from the remote server, showing the last time the local snapshot was updated.

• Add a diff mechanism to compare the local working directory with the remote snapshot's contents:

  • List modified files (Git style).
  • Open interactive diff with FileMerge.

• Add a transactions history file in ~/.snapshot/history

• Add FTP connection parameters such as TLS version and security protocol to the configuration file, to override the default hardcoded values.

• Add more options:

  • --remote-subpath to override or --remote-path to supplement the REMOTE_PATH variable in the config file, allowing to push/pull snapshots to/from a subdirectory of the remote path.

  • --local-subpath to override or --local-path to supplement the local path, allowing to push/pull snapshots to/from a subdirectory of the current working directory.

Side notes

Some tweaking may be needed for the curl request to work with your FTP server, especially if it requires specific TLS versions or security protocol, or if it has unique authentication methods.

The script is designed to work with a single FTPES server, which has very specific requirements. It is easily adaptable to other FTP servers with minor modifications.

Made with ♥ by mrcendre.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.