This method may create new extents and as such isn’t recommended for large directories, since it may take longer and also use greater space.

1: # Create empty subvolume in place of directory
2: mv /parent/dir /parent/dir-old
3: sudo btrfs subvol create /parent/dir
4: # Copy contents over
5: mv /parent/dir-old/* /parent/dir-old/.* /parent/dir/
6: # Delete what should now be an empty directory
7: rm -d /parent/dir-old

The previous approach, which copied files across a subvolume boundary, can result in new file extents being created. The way to ensure that that doesn’t happen is to create a subvolume via the snapshot mechanism. This is a little more involved.

1. First, we create a new subvolume as a Btrfs snapshot

   1: sudo btrfs subvolume snapshot /parent /parent/dir-new
   

2. Then we cleanup subvolume contents by deleting unneeded items and moving needed items to the root of the subvolume

    2: # [1/3]: delete unneeded items
    3: cd /parent/dir-new
    4: for dir in ./*; do
    5:     [ "$dir" = ./"dir" ] && continue
    6:     rm -rf "$dir"
    7: done
    8: rm -rf ./.* # also the hidden files
    9: # [2/3]: move items to root of subvolume
   10: mv /parent/dir-new/dir /parent/dir-new/dir-ref-to-old
   11: mv /parent/dir-new/dir-ref-to-old/* /parent/dir-new/dir-ref-to-old/.* /parent/dir-new/
   12: # [3/3]: cleanup: delete what should now be an empty directory
   13: rm -d /parent/dir-new/dir-ref-to-old
   

3. Replace the directory with the subvolume

   14: rm -rf /parent/dir && mv /parent/dir-new /parent/dir
   

OpenSUSE documentation has a section on enabling Snapper in user home directories. That guide is intended to allow individual users to manage their snapshots and rollbacks independently. It requires that the user directories are subvolumes of /home and accomplishes this via the pam_snapper_homeconvert.sh script, which is a part of the pam_snapper package on openSUSE. The pam_snapper_homeconvert.sh script can be used both to create additional users with their $HOME as a subvolume as well as to convert the $HOME of an existing user into a subvolume.⁵⁵See the relevant CONVERTUSERDIR flag in pam_snapper_homeconvert.sh.

For users of openSUSE LEAP, the official documentation is probably the best source to consult. For users of openSUSE Tumbleweed, the steps in the LEAP documentation can probably be followed with minimal changes. For users of other operating systems, the code of the pam_snapper_homeconvert.sh script is worth perusing.

Now that we’ve covered some ways of creating subvolumes, let’s consider some practical situations where this knowledge can be put to use.

There are several ways of creating and managing Python virtual environments. Conda and Mamba are two notable options.⁷⁷ Conda is a cross-platform package and environment management system. Mamba adds features on top of Conda offering “higher speed and more reliable environment solutions”.

If Conda (or Mamba) is already installed, follow the steps to convert an existing directory to a subvolume to convert the root prefix into a subvolume.

Otherwise, if neither is installed on the system, the easiest way is to:

• Create a subvolume to host the virtual environments (assuming the current user is user).

  1: sudo btrfs subvolume create /home/user/miniconda3
  2: sudo chown user:user /home/user/miniconda3
  

• Then install conda using it as the installation prefix.

• Finally (optionally) install mamba in the base environment.

  4: conda install conda-forge::mamba -n base
  

Assuming that snapper is installed,⁸⁸Snapper binaries for different operating systems can be downloaded from the openSUSE website. the Python environment root prefix is /home/user/miniconda3, and the user is user:

• We first create a snapper configuration.

  1: sudo snapper -c home_user_conda create-config /home/user/miniconda3
  

• By default snapper requires root access to take and list snapshots. Assuming that the snapper configurations are stored in /etc/snapper/configs/, we take steps to grant access to non-root users.

  2: sudo sed -i -e "s/ALLOW_USERS=\"\"/ALLOW_USERS=\"user\"/g" /etc/snapper/configs/home_user_conda
  3: # allow user to browse .snapshots without 'sudo'
  4: # NOTE: it is necessary that the owner of the snapshot directory remain root so
  5: #       we alter the group to be a group that includes the user
  6: sudo chmod a+rx ~/miniconda3/.snapshots
  7: sudo chown root:user ~/miniconda3/.snapshots
  

The default Snapper configuration is configured to take hourly snapshots. While this is a reasonable default for the $HOME directory, we can do better for the Python environment.

• First we alter the configuration created in the previous step to disable hourly snapshots from being created.

  1: sudo sed -i -e "s/TIMELINE_CREATE=\"yes\"/TIMELINE_CREATE=\"no\"/g" /etc/snapper/configs/home_user_conda
  

• Then we create wrappers⁹⁹In addition to delimiting a command with a pre and post snapshot, one can also create standalone snapshots. as desired, and put these in our ~/.bashrc or equivalent. For instance,

  conda_update() {
      snapper -c home_user_conda create -p -d "${CONDA_DEFAULT_ENV}: Update" -c number \
              --command "mamba update --all"
  }
  conda_install() {
      snapper -c home_user_conda create -p -d "${CONDA_DEFAULT_ENV}: Installing [${@}]" -c number \
              --command "mamba install ""$@"
  }
  

• One can list existing snapper snapshots via

  1: snapper -c home_user_conda list
  

• If one has been taking snapshots in pre/post pairs diligently, one can also do

  1: snapper -c home_user_conda list -t pre-post
  

• One can see a file-level summary of changes between snapshots via

  1: # Format:  snapper -c <config> status <start>..<end>
  2: snapper -c home_user_conda status 1..2 # changes between 1 and 2
  3: snapper -c home_user_conda status 2..0 # changes since 2 (till present)
  

• Diffs can be reviewed between snapshots via

  1: # Format: snapper -c <config> diff <start>..<end> [files]
  2: snapper -c home_user_conda diff 1..2 /home/user/miniconda3/pkgs/urls.txt
  

• Changes can be reverted via the undochange command. For instance in order to restore snapshot version 2, we undo the changes since 2.

  1: # Format: snapper -c <config> undochange <start>..<end> [files]
  2: snapper -c home_user_conda undochange 2..0
  

This is only relevant on platforms where one has the ability to revert OS state (i.e., openSUSE).

We want to ensure that when we revert the root filesystem, that we also don’t revert the Nix store. Ensuring that the Nix store is within a separate subvolume is necessary for this purpose. Since Nix uses /nix as its store location, for reasons mentioned before, we want to ensure that /nix is robust to changes in the default subvolume.²²²²Which is what gets mounted at /.

We achieve this by following the convention used for other subvolumes mounted under²³²³As opposed to “mounted at”. /, and make nix a subvolume of @ ²⁴²⁴In openSUSE, the toplevel subvolume contains a single subvolume called @. All other subvolumes are descendents of @. and mount it as /nix.

Below, code Listing 1 assumes that Nix isn’t yet installed.²⁵²⁵If it already is installed, we’d need to follow steps to convert an existing directory to a subvolume.

 1: # Mount the top-level subvolume explicitly
 2: # mount -o <subvol> <partition> <mount point>
 3: # e.g., mount -o subvolid=0 /dev/sda2 /mnt
 4: # when using luks encryption, on openSUSE, the decrypted partition is at
 5: # /dev/system/root
 6: sudo mount -o subvolid=0 /dev/system/root /mnt
 7: # On openSUSE, the toplevel subvolume, has a single subvolume within it called
 8: # '@'. the '@' subvolume acts as the ancestor of all other subvolumes and
 9: # represents a "stable" target
10: sudo btrfs subvol create /mnt/@/nix
11: sudo umount /mnt

12: sudo sh -c 'echo "/dev/system/root  /nix  btrfs  subvol=/@/nix  0  0" >> /etc/fstab'
13: sudo mkdir /nix # make the mount target
14: sudo mount -a # mount /nix (and test the fstab config)

And now we can follow the steps to install Nix.

A Btrfs subvolume is a part of [the] filesystem with its own independent file/directory hierarchy and inode number namespace. Subvolumes can share file extents. … A subvolume has always inode number 256.³¹³¹Except in the case of the toplevel subvolume.

A subvolume looks like a normal directory, with some additional operations.… Subvolumes can be renamed or moved, nesting subvolumes is not restricted but has some implications regarding snapshotting. The numeric id (called subvolid or rootid) of the subvolume is persistent and cannot be changed.

The default subvolume is what gets mounted via mount unless a subvolid or subvol is specified.³²³²See Btrfs-specific mount options.

• The default subvolume can be queried via

  1: sudo btrfs subvolume get-default /
  

• The default subvolume can be set via the set-default command.

A freshly created [Btrfs] filesystem is also a subvolume, called top-level, internally has [sic] an id [of] 5.³³³³subvolid=5, which corresponds to the Btrfs_FS_TREE_OBJECTID. This subvolume cannot be removed or replaced by another subvolume. This is also the subvolume that will be mounted by default, unless the default subvolume has been changed …

In addition, when mounting, subvolid​=0 is an alias for the toplevel subvolume.³⁴³⁴Since Linux kernel version 2.6.34.

A snapshot is a subvolume like any other, with given initial content. By default, snapshots are created read-write. File modifications in a snapshot do not affect the files in the original subvolume.³⁵³⁵ Btrfs subvolume and snapshot.

[…]

[S]napshotting is not recursive, so a subvolume or a snapshot is effectively a barrier and no files in the nested appear in the snapshot. Instead there’s a stub subvolume (also sometimes empty subvolume with the same name as original subvolume, with inode number 2). This can be used intentionally but could be confusing in case of nested layouts.³⁶³⁶Btrfs Nested subvolumes.