1
0
Fork
You've already forked buttercup
0
tool to make backups buttery smooth
  • Shell 86.4%
  • Nix 13.6%
2026年04月02日 14:28:01 -07:00
LICENSES make repo REUSE compliant 2026年03月24日 13:39:15 -07:00
.envrc flake: init 2026年03月24日 13:16:19 -07:00
.gitignore gitignore: init 2026年03月24日 15:13:39 -07:00
buttercup confirm: always return true if input is not a tty 2026年03月24日 16:27:42 -07:00
flake.lock flake: init 2026年03月24日 13:16:19 -07:00
flake.nix flake.nix: fix devshell 2026年03月24日 16:26:26 -07:00
README.md docs(readme): add implementation details section 2026年04月02日 14:28:01 -07:00
REUSE.toml make repo REUSE compliant 2026年03月24日 13:39:15 -07:00

buttercup

tool to make backups buttery smooth

only for backups between btrfs filesystems!

Install

nix profile install git+https://codeberg.org/electria/buttercup

Or you could always just download buttercup from this repo; it's just a single fish script.

(dependencies are detailed in flake.nix)

Usage

buttercup SRC DEST [SSH]

For instance, if ~/data is a subvolume you want to back up, and /mnt/backup is the local subvolume you want to back up to:

buttercup ~/data /mnt/disk/@data-backup

That would:

  1. create a snapshot in ~/data/.snapshots, its name being the current unix time

  2. send it over to /mnt/backup

  3. create a link /mnt/backup/result pointing to the newly sent snapshot

  4. prompt the user to clean up any extra snapshots in both the source and destination

    (that would run without prompting if stdin is not a tty, for automatic use)

If SSH is specified (eg root@192.168.67.67) then it will simply run the relevant commands for the destination through ssh; meaning that /mnt/backup would be a path on the remote. (sometimes expressed as root@192.168.67.67:/mnt/backup)

Tips

Often, what you want to backup isn't a subvolume yet; luckily it's very simple to convert it:

(replace path with the directory to convert!)

mv "$path" "$path-tmp" && \
btrfs subvolume create "$path" && \
cp -a "$path-tmp/." "$path" && \ # this is btrfs, so this would be a light copy
trash "$path-tmp" # all done!

Implementation details

  1. buttercup excecutes most (if not all) btrfs-progs commands with sudo, even when it might not be necessary (eg when all directories/subvolumes are owned by the current user)

    Also, it isn't wrapped with sudo since I'd like to avoid pulling in any specific implementation, and it could fail in specific cases if the system isn't configured for sudo anyways.

    It would likely be best to use a more flexible system for priveledge escallation, to both support tools other than sudo as well as not use it when it's not needed.

  2. The current argument parsing system is extremely simple (which is a good thing)

    However, the fact that I don't want a config file either means that I can only have one optional option; which of course must be used for SSH.

    Therefore, snapshotsToKeep is hardcoded to 2