restic ls

restic ls is the command-line way to browse your backups without mounting them. It lists the files, directories, sizes, and permissions stored in a specific snapshot ID or the latest snapshot.

Quick Summary

If snapshots lists the backup "dates," ls lists the "files" within those dates. It is essential for verifying what exactly was captured in a backup before you start a restore.

Basic Syntax

restic ls [snapshotID] [flags]

Usage Patterns

# List files in the absolute latest snapshot
restic ls latest

# List files in a specific snapshot
restic ls d8f3e2a1

# List files in a specific subdirectory within a snapshot
restic ls latest /var/www/html

Key Flags

Flag	Description
-l or --long	Detailed listing (permissions, owner, group, size, time)
--host HOSTNAME	Filter by host when using latest
--tag TAG	Filter by tag when using latest
--path PATH	Filter by path when using latest
--json	Output the file list in JSON format

Practical Examples

1. Detailed Listing of Config Files

See the exact permissions and sizes of files in your /etc backup.

restic ls -l latest /etc

2. Hunting for Large Files

List all files in a snapshot and sort them to find what is taking up space (requires shell tools).

restic ls -l latest | sort -k 5 -n

3. Verify Path Patterns

Ensure your --exclude rules worked by checking if a directory exists in the latest snapshot.

restic ls latest | grep "node_modules"

Output Columns (Long Format)

When using restic ls -l, the output resembles standard ls -l:

Example Output Column	Description
drwxr-xr-x	File type and permissions
0	UID (Owner ID)
0	GID (Group ID)
4096	File size in bytes
2024-01-10 12:00:00	Last modification time
/etc/nginx	Full path within the snapshot

ls vs mount

command	use case	efficiency
ls	Quick terminal check of a few paths	High (Fast, no FUSE needed)
mount	Deep exploration or GUI browsing	Medium (High latency on cloud repos)

search instead of scroll

If you are looking for a specific filename but don't know the exact path, skip ls and use restic find.

Common Pitfalls

Pitfall	Consequence	Prevention
Running ls on Huge Snapshots	A massive flood of text in your terminal.	Always specify a path (e.g., restic ls latest /home) to limit output.
Forgetting -l	You only see filenames without context (size/time).	Use -l as your default for restic ls.
Thinking ls is a local command	It requires repository access and a password.	Ensure your environment variables are set.

Examples with Output

Examples with Output

1. Simple Listing (Latest Snapshot)

Command:

restic ls latest /etc/nginx

Output:

repository a7b2c9d opened successfully, password is correct
snapshot d8f3e2a1 of [/etc] at 2024-01-15 03:00:00):
/etc/nginx
/etc/nginx/conf.d
/etc/nginx/nginx.conf
/etc/nginx/sites-available
/etc/nginx/sites-enabled

2. Long Listing (Permissions & Size)

Command:

restic ls -l latest /etc/nginx/nginx.conf

Output:

snapshot d8f3e2a1 of [/etc] at 2024-01-15 03:00:00):
-rw-r--r--     0     0   1492 2024-01-01 10:00:00 /etc/nginx/nginx.conf

3. List Specific Snapshot ID

Command:

restic ls d8f3e2a1 /var/www

Output:

snapshot d8f3e2a1 of [/var/www] at 2023-12-25 12:00:00):
/var/www
/var/www/html
/var/www/html/index.php
/var/www/html/wp-config.php

4. JSON Output

Command:

restic ls latest --json /etc/hosts

Output:

{"name":"/etc/hosts","type":"file","path":"/etc/hosts","uid":0,"gid":0,"size":245,"mode":33188,"mtime":"2024-01-01T10:00:00Z","atime":"2024-01-01T10:00:00Z","ctime":"2024-01-01T10:00:00Z","struct_type":"node"}

5. List with Host Filter

Command:

restic ls latest --host db-01 /var/lib/mysql

Output:

snapshot a1b2c3d4 of [/var/lib/mysql] at 2024-01-16 03:00:00):
/var/lib/mysql
/var/lib/mysql/ibdata1
/var/lib/mysql/mysql

What's Next?

Compare the differences between two snapshots with restic diff.