sfdupes/exclude.go

package main

// This file holds two rules for the walk (README "Rules for the walk"):
// the default excludes, the paths a scan's walk does not enter below an
// operand unless scan is given --no-default-excludes, and the
// filesystems that are not persistent, on which the walk never records
// anything.

import (
	"bufio"
	"errors"
	"fmt"
	"io"
	"io/fs"
	"path/filepath"
	"slices"
	"strings"
)

// The systems that have default excludes, as runtime.GOOS names them.
const (
	goosLinux   = "linux"
	goosDarwin  = "darwin"
	goosWindows = "windows"
)

// The fields of a line of mountInfoPath that readMountInfo reads,
// counted from 0 (see proc(5)): the mount point is the fifth field, and
// after the sixth come optional fields, then a field holding "-", then
// the filesystem type.
const (
	mountPointField     = 4
	optionalFieldsStart = 6
)

// typesPerHelpLine is how many filesystem types the scan command's help
// lists on each line.
const typesPerHelpLine = 6

// errMountInfoLine reports a line of mountInfoPath without the fields
// readMountInfo reads.
var errMountInfoLine = errors.New("unexpected line")

// walkRules holds the two rules for the walk that a scan sets up as it
// starts. excludes are the default excludes, or none with
// --no-default-excludes. nonPersistent maps the device ID of every
// mounted filesystem that is not persistent to its type; the walk
// records nothing on one of those, whatever the flags.
type walkRules struct {
	excludes      []string
	nonPersistent map[uint64]string
}

// defaultExcludes returns the default excludes of the system goos
// names, as runtime.GOOS does: a fixed list on Linux, macOS and
// Windows, and none on any other system.
func defaultExcludes(goos string) []string {
	switch goos {
	case goosLinux:
		return []string{"/proc", "/sys", "/dev", "/run", "/tmp", "/var/tmp"}
	case goosDarwin:
		// A walk of / reaches everything in /System/Volumes/Data through
		// the firmlinks, so walking it as well would record each of
		// those files twice.
		return []string{
			"/dev", "/private/tmp", "/private/var/tmp", "/private/var/vm",
			"/System/Volumes/VM", "/System/Volumes/Data",
		}
	case goosWindows:
		// Relative to the root of the drive an operand lies on. The
		// first three are the page, swap and hibernation files.
		return []string{
			"pagefile.sys", "swapfile.sys", "hiberfil.sys",
			"System Volume Information", "$Recycle.Bin", `Windows\Temp`,
			`Users\*\AppData\Local\Temp`,
		}
	default:
		return nil
	}
}

// isDefaultExclude reports whether path is one of excludes, in which a
// * matches one path component.
func isDefaultExclude(path string, excludes []string) bool {
	for _, pattern := range excludes {
		// The patterns are fixed, so none is malformed.
		if ok, _ := filepath.Match(pattern, path); ok {
			return true
		}
	}

	return false
}

// nonPersistentFilesystemTypes returns the filesystem types that are
// not persistent: filesystems that the kernel makes up or that are kept
// in memory. devfs is the macOS filesystem of /dev; the others are
// Linux names.
func nonPersistentFilesystemTypes() []string {
	return []string{
		"proc", "sysfs", "devtmpfs", "devpts", "tmpfs", "ramfs",
		"cgroup", "cgroup2", "debugfs", "tracefs", "securityfs", "pstore",
		"bpf", "configfs", "fusectl", "mqueue", "hugetlbfs", "efivarfs",
		"binfmt_misc", "autofs", "nsfs", "rpc_pipefs", "selinuxfs", "devfs",
	}
}

// nonPersistentFilesystems returns the device ID of every mounted
// filesystem that is not persistent, with its type, read with lstat on
// its mount point. mountedFilesystems lists the mounts. A mount point
// that lstat cannot reach is left out.
func nonPersistentFilesystems() (map[uint64]string, error) {
	mounts, err := mountedFilesystems()
	if err != nil {
		return nil, err
	}

	types := nonPersistentFilesystemTypes()
	devices := make(map[uint64]string)

	for mountPoint, fsType := range mounts {
		if !slices.Contains(types, fsType) {
			continue
		}

		if dev, ok := deviceOfPath(mountPoint); ok {
			devices[dev] = fsType
		}
	}

	return devices, nil
}

// nonPersistentLine returns the line the scan prints for path when fi,
// its lstat, puts it on a filesystem in rules.nonPersistent, and ""
// when it is on any other.
func (rules walkRules) nonPersistentLine(path string, fi fs.FileInfo) string {
	dev, ok := deviceOfInfo(fi)
	if !ok {
		return ""
	}

	fsType, found := rules.nonPersistent[dev]
	if !found {
		return ""
	}

	return fmt.Sprintf("scan: skipped %s (%s, not a persistent filesystem)",
		path, fsType)
}

// readMountInfo reads mountinfo, laid out as mountInfoPath is, and
// returns every mount point with the type of its filesystem. Where one
// filesystem is mounted over another, a later line names the one on
// top, so the last line for a mount point decides.
func readMountInfo(mountinfo io.Reader) (map[string]string, error) {
	// The kernel writes a space, tab, newline or backslash in a mount
	// point as an octal escape.
	unescape := strings.NewReplacer(
		`\040`, " ", `\011`, "\t", `\012`, "\n", `\134`, `\`)

	mounts := make(map[string]string)
	lines := bufio.NewScanner(mountinfo)

	for lines.Scan() {
		fields := strings.Fields(lines.Text())

		sep := slices.Index(fields, "-")
		if sep < optionalFieldsStart || sep+1 >= len(fields) {
			return nil, fmt.Errorf("%w: %q", errMountInfoLine, lines.Text())
		}

		mounts[unescape.Replace(fields[mountPointField])] = fields[sep+1]
	}

	return mounts, lines.Err()
}

// defaultExcludesHelp describes, for the scan command's help, the
// default excludes of the system goos names and, where the scan lists
// the mounted filesystems, the types it never records anything on.
func defaultExcludesHelp(goos string) string {
	var help strings.Builder

	dirs := defaultExcludes(goos)
	if len(dirs) == 0 {
		help.WriteString("This system has no default excludes.\n")
	} else {
		help.WriteString("Below an operand, the walk does not enter these " +
			"default excludes, unless\n--no-default-excludes is given:\n\n")

		for _, dir := range dirs {
			fmt.Fprintf(&help, "  %s\n", dir)
		}
	}

	if goos == goosLinux || goos == goosDarwin {
		help.WriteString("\nWith or without --no-default-excludes, the scan " +
			"records nothing on a\nfilesystem that is not persistent, " +
			"one of these types:\n\n")

		types := nonPersistentFilesystemTypes()
		for line := range slices.Chunk(types, typesPerHelpLine) {
			fmt.Fprintf(&help, "  %s\n", strings.Join(line, ", "))
		}
	}

	return help.String()
}