Ls

The -l (el) option shows more details similar to the Unix ls -l command, including the file modification time, backup time, and version number.

The -v option must be used with -l, and shows even more details.

The -r option selects a specific version to display and lists files that are backed up at this version or an earlier version. With -r1, some of the files may be from version 1 and some may be from version zero.

The -1 (one) option shows only the files backed up in the -r version, without showing previously saved files. If -r is omitted, -1 shows files saved in the latest backup.

The -a option displays all versions of matching files, including deleted files. For example, the file /etc/hosts might be backed up in versions 2 and 3. Without -a, only the most recent version is listed. With -a, all versions are listed.

The -d option shows all versions of directory pathnames. These are normally not shown, even with -a. -d automatically enables -a.

The -i option makes pathname searches case-insensitive, so pattern ABC matches filenames abc, aBc, AbC, etc. This is the default on Apple systems since their filesystems are normally case-insensitive.

The -h option shows file sizes in KB, MB, and GB rather than in bytes, making them easier to read. 1234567 is shown as 1.2MB with -h.

The -x option shows all pathnames in the backup, including deleted paths. If a pattern is used with -x, it is a regular expression pattern rather than a glob pattern and only pathnames matching the regular expression are shown. All options except -i are ignored with -x.

There are two ways to search for pathnames matching a pattern: glob searches, without -x, and regular expression searches with -x. These searches have different patterns, matching criteria, and performance. It’s easy to get the two confused, so the details are important to understand how to find pathnames when the full pathname is not known.

Without -x, the search pattern is a glob search pattern. These are similar to the Unix command line, and may contain wildcards or not. Matching defaults to case-sensitive on Linux and case-insensitive on Apple. Use the -i opton on Linux to enable case-insensitive searches.

There are two wildcard characters with glob patterns:

The simplest glob pattern does not have wildcards or slashes, and matches any pathname component. In the pathname /my/backup/path, there are 3 components: my, backup, and path. Glob patterns try to match entire components. So using a simple pattern of backup would match the pathname /my/backup/path. A simple pattern of back would not match this pathname since it does not match any component exactly.

Adjacent components can be matched using slashes. The pattern backup/path matches the pathname /my/backup/path and /your/backup/path/test, but not /backup/to/my/path. Using a complete pathname like /my/backup/path as a pattern matches that pathname.

Glob patterns match whole pathname components, for example:

If the pattern begins with a slash, ls shows only the matches beginning at the root. If you’re not sure where a pathname is located, omit the leading slash. If the pattern begins with ./ (dot slash), ls adds the current directory to the beginning of the pattern.

For more flexible matching, a wildcard pattern without -x uses Unix "glob" rules:

Glob searches are much faster than -x regular expression searches and are usually powerful enough to find most files. For example, a glob search for '*jim*' (jim anywhere in the pathname) takes less than 3 seconds in a backup of 10M files, whereas a regular expression search -x jim takes 12x longer.

Keep in mind that glob patterns must match entire pathname components, so to search for "jim" anywhere in a pathname component, leading and trailing star wildcards are required. Without the wildcards, the glob pattern "jim" will only match a file or directory named "jim", exactly.

Directories are only listed 1 level deep by default. To list all files under a directory, similar to the Unix find command, add /* to the end of the pattern. Remember to single quote all patterns!

The -x option shows all pathnames in the backup, including deleted files still in the backup, without details such as permissions, size, etc. It is intended to help find files when the pathname, or maybe even the filename, is not known.

There are big differences between glob pattern matching and regex pattern matching:

If a pattern follows -x, it is a regular expression pattern. These are much more powerful than glob patterns, and allow searching across multiple pathname components when a file’s position in the filesystem hierarchy may not be known. See below for a list of all regex wildcards. Regular expressions are slower than glob patterns, sometimes much slower. If possible, try a glob pattern first.

Instead of using HashBackup’s built-in regular expression engine, pathnames can be "piped" into an external filter program. For example, to use grep to filter pathnames:

Pathnames can be sent to a file for futher processing using a standard redirect. This can be more efficient for multiple searches since it avoids redundant database operations.

For more regular expression info, check out this RegexOne online tutorial.

#1. Find all .pdf files, similar to the glob pattern '*.pdf' without -x

#2. Show files up to 3 levels deep

The fields are:

Adding -v gives more details:

The fields are the same for the first line, then on the second line: