{"id":13897831,"url":"https://github.com/Antynea/grub-btrfs","last_synced_at":"2025-07-17T15:30:43.580Z","repository":{"id":14060505,"uuid":"16763561","full_name":"Antynea/grub-btrfs","owner":"Antynea","description":"Include btrfs snapshots at boot options. (Grub menu)","archived":false,"fork":false,"pushed_at":"2024-06-08T11:12:45.000Z","size":479,"stargazers_count":703,"open_issues_count":29,"forks_count":73,"subscribers_count":19,"default_branch":"master","last_synced_at":"2024-08-07T18:44:38.900Z","etag":null,"topics":["boot","btrfs","grub","grub-btrfs","grub-menu","grub2","snapper","snapshot","timeshift"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Antynea.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2014-02-12T10:24:55.000Z","updated_at":"2024-08-07T14:00:18.000Z","dependencies_parsed_at":"2024-03-27T18:33:03.279Z","dependency_job_id":"f4ce0cc2-4e44-4144-9e39-fd20055f097f","html_url":"https://github.com/Antynea/grub-btrfs","commit_stats":null,"previous_names":[],"tags_count":59,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Antynea%2Fgrub-btrfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Antynea%2Fgrub-btrfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Antynea%2Fgrub-btrfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Antynea%2Fgrub-btrfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Antynea","download_url":"https://codeload.github.com/Antynea/grub-btrfs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226274542,"owners_count":17598834,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boot","btrfs","grub","grub-btrfs","grub-menu","grub2","snapper","snapshot","timeshift"],"created_at":"2024-08-06T18:03:54.011Z","updated_at":"2025-07-17T15:30:43.573Z","avatar_url":"https://github.com/Antynea.png","language":"Shell","funding_links":[],"categories":["Shell","Uncategorized"],"sub_categories":["Uncategorized"],"readme":"[![GitHub release](https://img.shields.io/github/release/Antynea/grub-btrfs.svg)](https://github.com/Antynea/grub-btrfs/releases)\n![](https://img.shields.io/github/license/Antynea/grub-btrfs.svg)\n\n## 💻 grub-btrfs \n\n##### BTC donation address: `1Lbvz244WA8xbpHek9W2Y12cakM6rDe5Rt`\n- - -\n### 🔎 Description:\ngrub-btrfs improves the grub bootloader by adding a btrfs snapshots sub-menu, allowing the user to boot into snapshots.\n\ngrub-btrfs supports manual snapshots as well as snapper, timeshift, and yabsnap created snapshots.\n\n##### Warning: booting read-only snapshots can be tricky\n\nIf you wish to use read-only snapshots, `/var/log` or even `/var` must be on a separate subvolume.\nOtherwise, make sure your snapshots are writable.\nSee [this ticket](https://github.com/Antynea/grub-btrfs/issues/92) for more info.\n\nThis project includes its own solution.\nRefer to the [documentation](https://github.com/Antynea/grub-btrfs/blob/master/initramfs/readme.md).\n\n- - -\n### ✨ What features does grub-btrfs have?\n* Automatically lists snapshots existing on the btrfs root partition.\n* Automatically detect if `/boot` is in a separate partition.\n* Automatically detect kernel, initramfs and Intel/AMD microcode in `/boot` directory within snapshots.\n* Automatically create corresponding menu entries in `grub.cfg`\n* Automatically detect the type/tags/triggers and descriptions/comments of Snapper/Timeshift/Yabsnap snapshots.\n* Automatically generate `grub.cfg` if you use the provided Systemd/ OpenRC service.\n\n- - -\n### 🛠️ Installation:\n#### Arch Linux\nThe package is available in the extra repository [grub-btrfs](https://archlinux.org/packages/extra/any/grub-btrfs/)\n```\npacman -S grub-btrfs\n```\n\n#### Gentoo\ngrub-btrfs is only available in the Gentoo User Repository (GURU) and not in the official Gentoo repository.  \nIf you have not activated the GURU yet, do so by running:\n```\nemerge -av app-eselect/eselect-repository \neselect repository enable guru \nemaint sync -r guru \n```\nIf you are using Systemd on Gentoo, make sure the USE-Flag `systemd` is set. (Either globally in make.conf or in package.use for the package app-backup/grub-btrfs)\nWithout Systemd USE-Flag the OpenRC-daemon of grub-btrfs will be installed.\n\nEmerge grub-btrfs via \n`emerge app-backup/grub-btrfs`\n\n#### Kali Linux\n[grub-btrfs](http://pkg.kali.org/pkg/grub-btrfs) is available in the Kali Linux repository and can be installed with:  \n```\napt install grub-btrfs\n```\nBooting into read-only snapshots is fully supported when choosing btrfs as the file system during a standard Kali Linux installation following [this walk-through](https://www.kali.org/docs/installation/btrfs/).\n\n#### Manual installation\n* Run `make install`\n* Run `make help` to check what options are available. \n* Dependencies:\n  * [btrfs-progs](https://archlinux.org/packages/core/x86_64/btrfs-progs/)\n  * [grub](https://archlinux.org/packages/core/x86_64/grub/)\n  * [bash \u003e4](https://archlinux.org/packages/core/x86_64/bash/)\n  * [gawk](https://archlinux.org/packages/core/x86_64/gawk/)\n  * (only when using the grub-btrfsd daemon)[inotify-tools](https://archlinux.org/packages/extra/x86_64/inotify-tools/)\n\n- - -\n### 📚 Manual usage of grub-btrfs\nTo manually generate grub snapshot entries you can run `sudo /etc/grub.d/41_snapshots-btrfs` which updates `grub-btrfs.cfg`. You then need to regenerate the GRUB configuration by running one of the following commands:\n\n* On **Arch Linux** or **Gentoo** use `grub-mkconfig -o /boot/grub/grub.cfg`.  \n* On **Fedora** use `grub2-mkconfig -o /boot/grub2/grub.cfg`  \n* On **Debian and Ubuntu based** distributions `update-grub` is a script that runs `grub-mkconfig ...`\n\nThis process can be automated to occur whenever you create or delete snapshots but this process is slightly different depending upon your distributions choice on init system. See the relevant instructions for your init system below.\n\n### ⚙️ Customization:\n\nYou have the possibility to modify many parameters in `/etc/default/grub-btrfs/config`.\nFor further information see [config file](https://github.com/Antynea/grub-btrfs/blob/master/config) or `man grub-btrfs`\n\n#### Warning:\nSome file locations and command names differ from distribution to distribution. Initially the configuration is set up to work with Arch and Gentoo (and many other distributions) out of the box, which are using the `grub-mkconfig` command. \nHowever Fedora, for example, uses a different command, `grub2-mkconfig`.\nEdit the `GRUB_BTRFS_MKCONFIG` variable in `/etc/default/grub-btrfs/config` file to reflect this. (e.g. `GRUB_BTRFS_MKCONFIG=/sbin/grub2-mkconfig` for Fedora)\n\nOn most distributions, the grub installation resides in `/boot/grub`. If grub is installed in a different place, change the variable `GRUB_BTRFS_MKCONFIG` in the config file accordingly. For Fedora this is `GRUB_BTRFS_GRUB_DIRNAME=\"/boot/grub2\"`. The command to check the grub scripts is different on some system, for Fedora it is `GRUB_BTRFS_SCRIPT_CHECK=grub2-script-check`\n\n#### Customization of the grub-btrfsd daemon\n\nGrub-btrfs comes with a daemon script that automatically updates the grub menu when it sees a snapshot being created or deleted in a directory it is given via command line. You must install `inotify-tools` before you can use grub-btrfsd.\n\nThe daemon can be configured by passing different command line arguments to it. \nThe available arguments are:\n* `SNAPSHOTS_DIRS`\nThis argument specifies the (space separated) paths where grub-btrfsd looks for newly created snapshots and snapshot deletions. It is usually defined by the program used to make snapshots.\nE.g. for Snapper or Yabsnap this would be `/.snapshots`. It is possible to define more than one directory here, all directories will inherit the same settings (recursive etc.).\nThis argument is not necessary to provide if `--timeshift-auto` is set. \n* `-c / --no-color`\nDisable colors in output.\n* `-l / --log-file`\nThis arguments specifies a file where grub-btrfsd should write log messages.\n* `-r / --recursive`\nWatch the snapshots directory recursively\n* `-s / --syslog`\n* `-o / --timeshift-old`\nLook for snapshots in `/run/timeshift/backup/timeshift-btrfs` instead of `/run/timeshift/$PID/backup/timeshift-btrfs.` This is to be used for Timeshift versions \u003c22.06. You must also use `--timeshift-auto` if using this option.\n* `-t / --timeshift-auto`\nThis is a flag to activate the auto-detection of the path where Timeshift stores snapshots. Newer versions (\u003e=22.06) of Timeshift mount their snapshots to `/run/timeshift/$PID/backup/timeshift-btrfs`. Where `$PID` is the process ID of the currently running Timeshift session. The PID changes every time Timeshift is opened. grub-btrfsd can automatically take care of the detection of the correct PID and directory if this flag is set. In this case the argument `SNAPSHOTS_DIRS` has no effect.\n* `-v / --verbose`\nLet the log of the daemon be more verbose\n* `-h / --help`\nDisplays a short help message.\n- - - \n### 🪀 Automatically update grub upon snapshot creation or deletion\nGrub-btrfsd is a daemon that watches the snapshot directory for you and updates the grub menu automatically every time a snapshot is created or deleted.\nBy default this daemon watches the directory `/.snapshots` for changes (creation or deletion of snapshots) and triggers the grub menu creation and re-installation of grub if any changes are noticed.\nTherefore, if Snapper or Yabsnap is used with its default directory, the daemon can just be started and nothing needs to be configured. See the instructions below to configure grub-btrfsd for use with Timeshift or when using an alternative snapshots directory with Snapper/Yabsnap.\n- - - \n#### grub-btrfsd systemd instructions\nTo start the daemon run:\n```bash\nsudo systemctl start grub-btrfsd\n```\n\nTo activate it during system startup, run:\n```bash\nsudo systemctl enable grub-btrfsd\n```\n\n##### 💼 Snapshots not in `/.snapshots` when using systemd\nBy default the daemon is watching the directory `/.snapshots`. If the daemon should watch a different directory, it can be edited with:\n```bash\nsudo systemctl edit --full grub-btrfsd \n```\nYou need to edit the `/.snapshots` part in the line that says `ExecStart=/usr/bin/grub-btrfsd --syslog /.snapshots`.\nThis is what the file should look like afterwards:\n``` bash\n[Unit]\nDescription=Regenerate grub-btrfs.cfg\n\n[Service]\nType=simple\nLogLevelMax=notice\n# Set the possible paths for `grub-mkconfig`\nEnvironment=\"PATH=/sbin:/bin:/usr/sbin:/usr/bin\"\n# Load environment variables from the configuration\nEnvironmentFile=/etc/default/grub-btrfs/config\n# Start the daemon, usage of it is:\n# grub-btrfsd [-h, --help] [-t, --timeshift-auto] [-l, --log-file LOG_FILE] SNAPSHOTS_DIRS\n# SNAPSHOTS_DIRS         Snapshot directories to watch, without effect when --timeshift-auto\n# Optional arguments:\n# -t, --timeshift-auto  Automatically detect Timeshifts snapshot directory\n# -o, --timeshift-old   Activate for timeshift versions \u003c22.06\n# -l, --log-file        Specify a logfile to write to\n# -v, --verbose         Let the log of the daemon be more verbose\n# -s, --syslog          Write to syslog\nExecStart=/usr/bin/grub-btrfsd --syslog /.snapshots\n\n[Install]\nWantedBy=multi-user.target\n```\n\nWhen done, the service should be restarted with:\n``` bash\nsudo systemctl restart grub-btrfsd \n```\n\n##### 🌟 Using Timeshift with systemd\nNewer Timeshift versions (\u003e= 22.06) create a new directory named after their process ID in `/run/timeshift` every time they are started. The PID will be different every time.\nTherefore the daemon cannot simply watch a directory. It monitors `/run/timeshift` and if a directory is created it gets Timeshifts current PID then watches a directory in that newly created directory from Timeshift.\nTo activate this mode of the daemon, `--timeshift-auto` must be passed to the daemon as a command line argument.\n\nTo pass `--timeshift-auto` to grub-btrfsd, the .service file of grub-btrfsd can be edited with\n```bash\nsudo systemctl edit --full grub-btrfsd \n```\n\nThe line that contains:\n```bash \nExecStart=/usr/bin/grub-btrfsd /.snapshots --syslog\n\n```\n\nShould be modified to read:\n``` bash\nExecStart=/usr/bin/grub-btrfsd --syslog --timeshift-auto\n```\n\nThe modified file should look like this:\n``` bash\n[Unit]\nDescription=Regenerate grub-btrfs.cfg\n\n[Service]\nType=simple\nLogLevelMax=notice\n# Set the possible paths for `grub-mkconfig`\nEnvironment=\"PATH=/sbin:/bin:/usr/sbin:/usr/bin\"\n# Load environment variables from the configuration\nEnvironmentFile=/etc/default/grub-btrfs/config\n# Start the daemon, usage of it is:\n# grub-btrfsd [-h, --help] [-t, --timeshift-auto] [-l, --log-file LOG_FILE] SNAPSHOTS_DIRS\n# SNAPSHOTS_DIRS         Snapshot directories to watch, without effect when --timeshift-auto\n# Optional arguments:\n# -t, --timeshift-auto  Automatically detect Timeshifts snapshot directory\n# -l, --log-file        Specify a logfile to write to\n# -v, --verbose         Let the log of the daemon be more verbose\n# -s, --syslog          Write to syslog\nExecStart=/usr/bin/grub-btrfsd --syslog --timeshift-auto\n\n[Install]\nWantedBy=multi-user.target\n```\n\nIf you are using an older release of Timeshift (before 22.06), you also need to add `--timeshift-old` so that your ExecStart line would look like:\n\n```\nExecStart=/usr/bin/grub-btrfsd --syslog --timeshift-auto --timeshift-old\n```\n\nWhen done, the service must be restarted with:\n``` bash\nsudo systemctl restart grub-btrfsd \n```\n\nNote:\nYou can view your change with `systemctl cat grub-btrfsd`.\nTo revert all the changes use `systemctl revert grub-btrfsd`.\n\n- - -\n#### grub-btrfsd OpenRC instructions\nTo start the daemon run:\n```bash\nsudo rc-service grub-btrfsd start \n```\n\nTo activate it during system startup, run:\n```bash\nsudo rc-config add grub-btrfsd default \n```\n\n##### 💼 Snapshots not in `/.snapshots` for OpenRC\nBy default the daemon is watching the directory `/.snapshots`. If the daemon should watch a different directory, it can be edited by passing different arguments to it.\nArguments are passed to grub-btrfsd via the file `/etc/conf.d/grub-btrfsd`. \nThe variable `snapshots` defines the path the daemon will monitor for snapshots.\n\nAfter editing, the file should look like this:\n``` bash\n# Copyright 2022 Pascal Jaeger\n# Distributed under the terms of the GNU General Public License v3\n\n## Where to locate the root snapshots\nsnapshots=\"/.snapshots\" # Snapper in the root directory\n#snapshots=\"/run/timeshift/backup/timeshift-btrfs/snapshots\" # Timeshift \u003c v22.06\n\n## Optional arguments to run with the daemon\n# Append options to this like this:\n# optional_args=\"--syslog --timeshift-auto --verbose\"\n# Possible options are:\n# -t, --timeshift-auto  Automatically detect Timeshifts snapshot directory for timeshift \u003e= 22.06\n# -o, --timeshift-old   Look for snapshots in directory of Timeshift \u003cv22.06 (requires --timeshift-auto)\n# -l, --log-file        Specify a logfile to write to\n# -v, --verbose         Let the log of the daemon be more verbose\n# -s, --syslog          Write to syslog\noptional_args=\"--syslog\"\n```\n\nAfter that, the daemon should be restarted with:\n``` bash\nsudo rc-service grub-btrfsd restart\n```\n\n##### 🔒 Snapshots on LUKS encrypted devices\nBy default, grub-btrfs generates entries that does not load modules for dealing with encrypted devices.\nEnable the `GRUB_BTRFS_ENABLE_CRYPTODISK` variable in `/etc/default/grub-btrfs/config` to load said modules and then execute the steps to mount encrypted root after selecting the snapshot.\n\n- - -\n### Troubleshooting\nIf you experience problems with grub-btrfs don't hesitate [to file an issue](https://github.com/Antynea/grub-btrfs/issues/new/choose).\n\n#### What version of grub-btrfs am I running?\nWhen requesting help or reporting bugs in grub-btrfs, please run:\n``` bash\nsudo /etc/grub.d/41_snapshots-btrfs --version\n```\nor \n``` bash\nsudo /usr/bin/grub-btrfsd --help\n```\nto get the currently running version of grub-btrfs and include this information in your ticket.\n\n#### Running grub-btrfsd in verbose mode\nIf you have problems with the daemon, you can run it with the `--verbose`-flag. To do so you can run:\n``` bash\nsudo /usr/bin/grub-btrfsd --verbose --timeshift-auto` (for timeshift)\n# or \nsudo /usr/bin/grub-btrfsd /.snapshots --verbose` (for snapper/yabsnap)\n```\nOr pass `--verbose` to the daemon using the Systemd .service file or the OpenRC conf.d file respectively.\n\nFor additional information on the daemon and its arguments, run `grub-btrfsd -h` or `man grub-btrfsd`\n\n- - -\n### Development\nGrub-btrfs uses a rudimentary system of automatic versioning to tell apart different commits. This is helpful when users report problems and it is not immediately clear what version they are using. \nWe therefore have the following script in `.git/hooks/pre-commit`:\n\n``` bash\n#!/bin/sh\n\necho \"Doing pre commit hook with version bump\"\nversion=\"$(git describe --tags --abbrev=0)-$(git rev-parse --abbrev-ref HEAD)-$(date -u -Iseconds)\"\necho \"New version is ${version}\"\nsed -i \"s/GRUB_BTRFS_VERSION=.*/GRUB_BTRFS_VERSION=${version}/\" config\ngit add config\n```\n\nThis automatically sets the version in the `config`-file to `[lasttag]-[branch-name]-[current-date-in-UTC]`.\nIn order to create a Tag we don't want to have this long version. In this case we set the version manually in `config` and commit with `git commit --no-verify`. This avoids running the hook. \n\n### Special thanks for assistance and contributions\n* [Maxim Baz](https://github.com/maximbaz)\n* [Schievel1](https://github.com/Antynea/grub-btrfs/discussions/173#discussioncomment-1438790)\n* [All contributors](https://github.com/Antynea/grub-btrfs/graphs/contributors)\n- - -\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAntynea%2Fgrub-btrfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAntynea%2Fgrub-btrfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAntynea%2Fgrub-btrfs/lists"}