HTTM(1)

NAME
httm - manual page for httm 0.33.2

DESCRIPTION
httm 0.33.2 httm prints the size, date and corresponding locations of available unique versions of files residing on snapshots. May also be used interactively to select and restore from such versions, and even to snapshot datasets which contain certain files.

  USAGE:

    httm [OPTIONS] [--] [INPUT_FILES]...

  ARGS:

<INPUT_FILES>...
    in any non-interactive mode, put requested paths here. If you include no paths as arguments, then httm will pause waiting for input on stdin. In any interactive mode, this is the directory search path. If no directory is specified, httm will use the current working directory.

  OPTIONS:

-b, --browse

    interactive browse and search a specified directory to display unique file versions. [aliases: interactive]

-s, --select[=<SELECT>...]

    interactive browse and search a specified directory to display unique file versions. Continue to another dialog to select a snapshot version to dump to stdout. This argument optionally takes a value. Default behavior/value is to simply print the path name, but, if the path is a file, the user can print the file's contents by giving the value "contents", or print the PREVIEW output by giving the value "preview". [possible values: path, contents, preview]

-r, --restore[=<RESTORE>...]

    interactive browse and search a specified directory to display unique file versions. Continue to another dialog to select a snapshot version to restore. This argument optionally takes a value. Default behavior/value is a non-destructive "copy" to the current working directory with a new name, so as not to overwrite any "live" file version. However, the user may specify "overwrite" (or "yolo") to restore to the same file location. Note, "overwrite" can be a DESTRUCTIVE operation. Overwrite mode will attempt to preserve attributes, like the permissions/mode, timestamps, xattrs and ownership of the selected snapshot file version (this is and will likely remain a UNIX only feature). In order to preserve such attributes in "copy" mode, specify the "copy-and-preserve" value. User may also specify "guard". Guard mode has the same semantics as "overwrite" but will attempt to take a precautionary snapshot before any overwrite action occurs. Note: Guard mode is a ZFS only option. User may also set via the HTTM_RESTORE_MODE environment variable. [possible values: copy, copy-and-preserve, overwrite, yolo, guard]

-d, --deleted[=<DELETED>...]

show deleted files in interactive modes.
    In non-interactive modes, do a search for all

files deleted from a specified directory. This argument optionally takes a value.
    The

default behavior/value is "all".
    If "only" is specified, then, in the interactive

    modes, non-deleted files will be excluded from the search. If "single" is specified, then, deleted files behind deleted directories, (that is -- files with a depth greater than one) will be ignored. [possible values: all, single, only]

-R, --recursive

    recurse into the selected directory to find more files. Only available in interactive and deleted file modes.

-a, --alt-replicated

    automatically discover locally replicated datasets and list their snapshots as well. NOTE: Be certain such replicated datasets are mounted before use. httm will silently ignore unmounted datasets in the interactive modes.

-p, --preview[=<PREVIEW>...]

    user may specify a command to preview snapshots while in a snapshot selection view. This argument optionally takes a value specifying the command to be executed. The default value/command, if no command value specified, is a 'bowie' formatted 'diff'. User defined commands must specify the snapshot file name "{snap_file}" and the live file name "{live_file}" within their shell command. NOTE: 'bash' is required to bootstrap any preview script, even if user defined preview commands or script is written in a different language.

--uniqueness[=<UNIQUENESS>...]

    comparing file versions solely on the basis of size and modify time (the default "metadata" behavior) may return what appear to be "false positives", in the sense that, modify time is not a precise measure of whether a file has actually changed. A program might overwrite a file with the same contents, or a user can simply update the modify time via 'touch'. If only this flag is specified, the "contents" option compares the actual file contents of file versions, if their sizes match, and overrides the default "metadata" behavior. The "contents" option can be expensive, as the file versions need to be read back and compared, and should probably only be used for smaller files. Given how expensive this operation can be, for larger files or files with many versions, "contents" option is not shown in Interactive browse mode, but after a selection is made, can be utilized in Select or Restore modes. The "all" or "no-filter" option dumps all snapshot versions, and no attempt is made to determine if the file versions are distinct. [aliases: unique] [possible values: all, no-filter, metadata, contents]

-e, --exact

    use exact pattern matching for searches in the interactive modes (in contrast to the default fuzzy searching).

-S, --snap[=<SNAPSHOT>...]

snapshot a file/s most immediate mount.
    This argument optionally takes a value for a

snapshot suffix.
    The default suffix is 'httmSnapFileMount'. Note: This is a ZFS only

    option which requires either superuser or 'zfs allow' privileges. [aliases: snap-file, snapshot, snap-file-mount]

--list-snaps[=<LIST_SNAPS>]

display snapshots names for a file.
    This argument optionally takes a value. By

default, this argument will return all available snapshot names.
    User may limit type of

snapshots returned via the UNIQUENESS flag.
    The user may also omit the last "n"

snapshots from any list.
    By appending a comma, this argument also filters those

snapshots which contain the specified pattern/s.
    A value of "5,prep_Apt" would return

    the snapshot names of only the last 5 (at most) of all snapshot versions which contain "prep_Apt". The value "native" will restrict selection to only 'httm' native snapshot suffix values, like "httmSnapFileMount" and "ounceSnapFileMount". Note: This is a ZFS only option.

--prune

    prune all snapshot/s which contain the input file/s on that file's most immediate mount via "zfs destroy". "zfs destroy" is a DESTRUCTIVE operation which *does not* only apply to the file in question, but the entire snapshot upon which it resides. Careless use may cause you to lose snapshot data you care about. This argument requires and will be filtered according to any values specified at LIST_SNAPS. User may also enable SELECT mode to make a granular selection of specific snapshots to prune. Note: This is a ZFS only option.

--roll-forward=<ROLL_FORWARD>

    traditionally 'zfs rollback' is a destructive operation, whereas httm roll-forward is non-destructive. httm will copy only files and their attributes that have changed since a specified snapshot, from that snapshot, to its live dataset. httm will also take two precautionary snapshots, one before and one after the copy. Should the roll forward fail for any reason, httm will roll back to the pre-execution state. Caveats: This is a ZFS only option which requires super user privileges.

-m, --file-mount[=<FILE_MOUNT>...]

    by default, display the all mount point/s of all dataset/s which contain/s the input file/s. This argument optionally takes a value to display other information about the path. Possible values are: "target" or "directory", return the directory upon which the underlying dataset or device of the mount, "source" or "device" or "dataset", return the underlying dataset/device of the mount, and, "relative-path" or "relative", return the path relative to the underlying dataset/device of the mount. [aliases: mount] [possible values: source, target, directory, device, dataset, relative-path, relative, relpath]

-l, --last-snap[=<LAST_SNAP>...]

    automatically select and print the path of last-in-time unique snapshot version for the input file. This argument optionally takes a value. Possible values are: "any", return the last in time snapshot version, this is the default behavior/value, "ditto", return only last snaps which are the same as the live file version, "no-ditto-exclusive", return only a last snap which is not the same as the live version (argument "--no-ditto" is an alias for this option), "no-ditto-inclusive", return a last snap which is not the same as the live version, or should none exist, return the live file, and, "none" or "without", return the live file only for those files without a last snapshot. [aliases: last, latest] [possible values: any, ditto, no-ditto, no-ditto-exclusive, no-ditto-inclusive, none, without]

-n, --raw

    display the snapshot locations only, without extraneous information, delimited by a NEWLINE character. [aliases: newline]

-0, --zero

    display the snapshot locations only, without extraneous information, delimited by a NULL character. [aliases: null]

--not-so-pretty

    display the ordinary output, but tab delimited, without any pretty border lines. [aliases: tabs, plain-jane, not-pretty]

--json

    display the ordinary output, but as formatted JSON.

--omit-ditto

omit display of the snapshot version which may be identical to the live version.
    By

    default, `httm` displays all snapshot versions and the live version).

--no-filter

    by default, in the interactive modes, httm will filter out files residing upon non-supported datasets (like ext4, tmpfs, procfs, sysfs, or devtmpfs, etc.), and within any "common" snapshot paths. Here, one may select to disable such filtering. httm, however, will always show the input path, and results from behind any input path when that is the path being searched.

--no-hidden

    do not show information regarding hidden files and directories (those that start with a '.') in the recursive or interactive modes.

--one-filesystem

    limit recursive search to file and directories on the same filesystem/device as the target directory.

--no-traverse

in recursive mode, don't traverse symlinks.
    Although httm does its best to prevent

    searching pathologically recursive symlink-ed paths, here, you may disable symlink traversal completely. NOTE: httm will never traverse symlinks when a requested recursive search is on the root/base directory ("/").

--no-live

    only display information concerning snapshot versions (display no information regarding live versions of files or directories). [aliases: dead, disco]

--no-snap

    only display information concerning 'pseudo-live' versions in any Display Recursive mode (in --deleted, --recursive, but non-interactive modes). Useful for finding the "files that once were" and displaying only those pseudo-live/zombie files. [aliases: undead, zombie]

--map-aliases <MAP_ALIASES>

    manually map a local directory (eg. "/Users/<User Name>") as an alias of a mount point for ZFS or btrfs, such as the local mount point for a backup on a remote share (eg. "/Volumes/Home"). This option is useful if you wish to view snapshot versions from within the local directory you back up to your remote share. This option requires a value. Such a value is delimited by a colon, ':', and is specified in the form <LOCAL_DIR>:<REMOTE_DIR> (eg. --map-aliases /Users/<User Name>:/Volumes/Home). Multiple maps may be specified delimited by a comma, ','. You may also set via the environment variable HTTM_MAP_ALIASES. [aliases: aliases]

--num-versions[=<NUM_VERSIONS>...]

    detect and display the number of unique versions available (e.g. one, "1", version is available if either a snapshot version exists, and is identical to live version, or only a live version exists). This argument optionally takes a value. The default value, "all", will print the filename and number of versions, "graph" will print the filename and a line of characters representing the number of versions, "single" will print only filenames which only have one version, (and "single-no-snap" will print those without a snap taken, and "single-with-snap" will print those with a snap taken), and "multiple" will print only filenames which only have multiple versions. [possible values: all, graph, single, single-no-snap, single-with-snap, multiple]

--utc

    use UTC for date display and timestamps

--no-clones

    by default, when copying files from snapshots, httm will first attempt a zero copy "reflink" clone on systems that support it. Here, you may disable that behavior, and force httm to use the fall back diff copy behavior as the default. You may also set an environment variable to any value, "HTTM_NO_CLONE" to disable.

--debug

    print configuration and debugging info

--install-zsh-hot-keys

    install zsh hot keys to the users home directory, and then exit

-h, --help

    Print help information

-V, --version

    Print version information

SEE ALSO
The full documentation for httm is maintained as a Texinfo manual. If the info and httm programs are properly installed at your site, the command

    info httm

should give you access to the complete manual.