DOCSEARCHbyAlgolia
Submit Docs

httm

repository·master·Indexed 23 days ago

https://github.com/kimono-koans/httm

A high-performance CLI tool for searching, browsing, and restoring unique file versions from snapshots. It supports ZFS, BTRFS, NILFS2, Restic, and Time Machine backups, as well as rsync-ed local datasets. Key features include multi-dataset search, deleted file recovery, interactive browse/select/restore modes, and deduplication based on metadata or contents.

Tokens
7.9K
Snippets
10
Records
47
Agent score
81%

What's inside httm

  1. Overview of httm

    master

    httm is a CLI Time Machine tool that allows you to find, browse, and restore unique versions of files from snapshots. It works by identifying unique versions based on size and modification time (or checksums) to provide a fast, deduplicated view of file history.

    Key capabilities include:

    • Multi-dataset search: Search for versions of multiple files across different datasets simultaneously.
    • Deleted file recovery: Recursively list and browse files hidden behind deleted directories.
    • Broad snapshot support: Works with ZFS, BTRFS, NILFS2, Restic, and Time Machine backups, as well as rsync-ed local datasets (ext4, XFS, NTFS).
    • Remote & Local pools: List snapshots from all local pools and remote backup pools.
    • Interactive modes: Includes 4 native modes: browse, select, prune, and restore.
    • Advanced features: Preview versions with custom commands (default is diff), roll forward to previous snapshots, and guard restore actions with precautionary snapshots.

  2. Optional dependencies for httm features

    master

    Certain httm features require additional tools to function correctly:

    • --preview behavior: For the default/best preview experience, bowie is required.
    • Time Machine support (macOS): equine is required for Time Machine support on macOS.

  3. Basic usage of httm

    master

    Like standard UNIX utilities, httm can take paths as arguments or read from stdin. If no paths are provided, it waits for input on stdin.

    Note: Viewing versions on BTRFS, NILFS2, or Restic repositories may require sudo due to permission requirements for snapshots or repositories.

  4. Use alternative stores (Time Machine and Restic)

    master

    You can use httm to view versions in non-standard backup locations using the --alt-store flag.

    • Time Machine: Requires equine to mount snapshots. Once mounted, use --alt-store=timemachine.
    • Restic: Mount the repository first using restic -r <repo> mount <mountpoint>, then use --alt-store=restic.

  5. Install httm via Source

    master

    You can install httm using cargo install. By default, this places the release binary in $HOME/.cargo/bin.

    If you prefer to have the binary available in a standard system path, you can move it to /usr/local/bin/httm and then uninstall the cargo version:

    cp $HOME/.cargo/bin/httm /usr/local/bin/httm
cargo uninstall httm

  6. Install httm via Native Packages

    master

    You can install httm using native package managers depending on your distribution:

    • Debian/Ubuntu: Use the personal package archive (PPA) or download tagged releases.
    • Redhat-based (Fedora, etc.): Use tagged releases. Note: When installing via rpm -i, you may need the --replacefiles option.
    • Arch Linux: You can create a package using the provided example PKGBUILD.
    • MacOS: Available via Homebrew.

  7. Browse and recover files with httm

    master

    Use httm to browse file versions across local snapshots and perform restorations.

    Browsing

    • Recursive browsing: Use -R to browse a directory recursively and view unique versions on local snapshots.
    • Deleted files: Use -d to find files on snapshots that have been deleted from the live filesystem.
    • Alternative stores: Use -a to view versions on both local and alternative replicated dataset snapshots.

    Restoring

    • Overwrite mode: Use -r=overwrite to restore a selected version to its original location, overwriting the current file.
    • Guard mode: Use -r (or set HTTM_RESTORE_MODE="guard") to restore a file while protecting the action with a pre-recovery ZFS snapshot.
    • Shortcut recovery: Use -l -r <path> to immediately recover the last-in-time unique version of a file without browsing.

  8. Install httm optional components and scripts

    master

    To get the full experience, you may want to install the manual pages and the helper scripts.

    Manual Pages: Copy the man page to a directory in your manpath (e.g., /usr/local/share/man/man1/).

    Helper Scripts: Copy the following scripts to a directory in your PATH and make them executable:

    • ounce.bash: Packaged script.
    • bowie.bash: Required for the default/best --preview behavior.
    • equine.bash: Required for Time Machine support on MacOS.
    • nicotine.bash: Packaged script.

    Example installation command:

    #!/bin/bash
cp ./httm/scripts/ounce.bash /usr/local/bin/ounce
# bowie is "required" for the default/best "--preview" behavior
cp ./httm/scripts/bowie.bash /usr/local/bin/bowie
# equine is "required" for Time Machine support on MacOS
cp ./httm/scripts/equine.bash /usr/local/bin/equine
cp ./httm/scripts/nicotine.bash /usr/local/bin/nicotine
chmod +x /usr/local/bin/bowie /usr/local/bin/ounce /usr/local/bin/equine /usr/local/bin/nicotine

  9. Configure preview and snapshotting

    master

    Previewing content

    Use --preview to view the content of a snapshot. You can use a custom command by passing it to --preview.

    • Default: Requires bowie for best behavior.
    • Custom: Use --preview="command {snap_file}" to specify how to display the snapshot file.

    Snapshotting

    Use -S <path> to manually trigger a snapshot of the dataset containing the specified path. This requires sudo for system files.

    Roll Forward

    Instead of rolling back (which can destroy intermediate snapshots), use --roll-forward=<dataset@snapshot> to move the filesystem state to a specific snapshot while taking pre- and post-execution snapshots for safety.

  10. Configure Zsh hot-key bindings for httm

    master

    You can enable interactive Zsh hot-keys to speed up your workflow:

    • ESC+s: Select snapshot filenames to be dropped into your current command line (e.g., after cat).
    • ESC+m: Browse all snapshots for a specific file.

    To install, run the following command and then source the resulting script in your .zshrc:

    httm --install-zsh-hot-keys
    ➜ httm --install-zsh-hot-keys

  11. Build and install httm from source

    master

    To build the httm executable directly using cargo, use the following command. This installs the binary to $HOME/.cargo/bin. If you prefer it in a system path, you can manually move it to /usr/local/bin/httm and then run cargo uninstall httm.

    To install via a convenience script:

    bash -c "$(curl -fsSL https://raw.githubusercontent.com/kimono-koans/httm/master/packaging/install-from-source.bash)"

    To build manually with cargo using the latest git tag:

    #!/bin/bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
latest="(wget -nv -O - "https://api.github.com/repos/kimono-koans/httm/releases/latest" 2>/dev/null | grep tag_name | cut -d: -f2 | cut -d'"' -f2)"
cargo install --locked --git https://github.com/kimono-koans/httm.git --tag "$latest"
    #!/bin/bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
latest="(wget -nv -O - "https://api.github.com/repos/kimono-koans/httm/releases/latest" 2>/dev/null | grep tag_name | cut -d: -f2 | cut -d'"' -f2)"
# cargo-install places a release binary in your $HOME/.cargo/bin, however, 
# you may wish to: cp $HOME/.cargo/bin/httm /usr/local/bin/httm; cargo uninstall httm
cargo install --locked --git https://github.com/kimono-koans/httm.git --tag "$latest"

  12. Understand the httm execution modes

    master

    The httm tool operates in several distinct modes determined by the ExecMode configuration. These modes dictate whether the tool runs interactively, performs batch operations, or displays filesystem snapshot information:

    • Interactive Modes:
      • InteractiveMode::Restore: Launches an interactive selection process to restore files/directories.
      • InteractiveMode::Select: Allows interactive selection of snapshots for specific output.
      • InteractiveMode::Browse: Provides an interactive browsing interface to explore versions.
    • Display Modes:
      • BasicDisplay, Preview, and NumVersions: These modes generate a VersionsMap and output a formatted string representation of available snapshots.
    • Batch/Utility Modes:
      • NonInteractiveRecursive: Executes a recursive operation in a non-interactive wrapper.
      • SnapFileMount: Executes snapshot mounting based on a provided suffix.
      • SnapsForFiles: Maps files to their corresponding snapshot names.
      • Prune: Executes snapshot pruning based on provided filters.
      • MountsForFiles: Maps files to their respective mounts.
      • RollForward: Executes a roll-forward operation for a specific snapshot name.