# kdave/btrfsmaintenance

Scripts for btrfs maintenance tasks like periodic scrub, balance, trim or defrag on selected mountpoints or directories.

Repository: https://github.com/kdave/btrfsmaintenance
Canonical: https://ross.abutalabs.com/products/btrfsmaintenance
Language: Shell
License: GPL-2.0
License Family: copyleft
Topics: btrfs, administration
Last push: 2025-08-28T15:55:50+00:00

## Health v2 (maintenance only)
Score: 40/100 (v2, computed 2026-09-02T17:46:02.011165+00:00)
- activity 39, release rhythm 8, longevity 100
- inputs: {"age_days": 4349, "days_push": 370, "days_rel": null, "gap_med": null, "n_releases_24m": 0}
- flags: none
- formula: round(0.45*activity + 0.35*rhythm + 0.20*longevity); archived -> min(score, 10)

## Adoption (not part of the score)
Stars 1121, forks 88 (observed 2026-08-28T04:03:39.920755+00:00)

## What it is
A set of shell scripts that automate periodic btrfs filesystem maintenance tasks such as scrub, balance, trim, and defragmentation on selected mountpoints or directories. Each task can be independently enabled, configured, and scheduled via cron or systemd timers.

## Use cases
- schedule periodic btrfs scrub to detect bit rot and checksum errors
- automatically reclaim space with btrfs balance on underused chunks
- run periodic SSD trim on btrfs filesystems
- defragment btrfs directories on a schedule
- automate btrfs health maintenance on a root filesystem
- set up btrfs maintenance timers on a Linux server

## When to choose
- you run Linux with btrfs as a root or data filesystem and want hands-off maintenance
- you want early detection of failing hardware or bit rot via scheduled scrubs
- you need to prevent btrfs metadata allocation corner cases with periodic balance
- you want distro-integrated cron/systemd timers for filesystem upkeep

## When to avoid
- your filesystem is ext4, XFS, or anything other than btrfs
- you need a GUI for filesystem administration
- you cannot tolerate periodic IO-heavy background activity on latency-sensitive systems
- you need advanced btrfs features like snapshot management or send/receive orchestration

## Facets
- artifact type: cli-tool
- maturity: active
- function: developer-tools, file-system, workflow-automation, scheduling
- domain: operating-systems, developer-tools, self-hosted
- platform: cli
- tags: btrfs, filesystem-maintenance, shell-scripts, system-administration, cron, scrub, balance, trim, linux

## Member repositories
- kdave/btrfsmaintenance (main) score 40

## Provenance
- Observed fields: from GitHub, fetched 2026-08-28T04:03:39.920755+00:00.
- Health v2: computed from the inputs above; adoption is never an input.
- Inferred fields (summary, facets, guidance): AI-extracted, prompt v1, taxonomy v1, on 2026-08-30T06:41:00.933780+00:00, confidence not recorded.
  - readme: https://github.com/kdave/btrfsmaintenance (fetched 2026-08-28T04:03:39.920755+00:00, sha 631cad4187c0)
- Data as of 2026-08-30T08:39:29.467469+00:00.