From 22b815b3dd30cda2a2669f3e8fb89d9370faf508 Mon Sep 17 00:00:00 2001
From: Michele Cereda <cereda.michele@gmail.com>
Date: Wed, 29 Mar 2023 22:54:44 +0200
Subject: [PATCH] chore: added references to the official documentation

---
 .vscode/settings.json                         |  5 +++
 knowledge base/btrfs.md                       | 39 +++++++++++++++++--
 ...create, mount and use an encrypted disk.md |  4 +-
 3 files changed, 43 insertions(+), 5 deletions(-)

diff --git a/.vscode/settings.json b/.vscode/settings.json
index d3b39c1..0884c84 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -12,7 +12,9 @@
         "btrfs",
         "byod",
         "cereda",
+        "chattr",
         "chezmoi",
+        "compsize",
         "cpulimit",
         "cryptsetup",
         "csma",
@@ -24,6 +26,7 @@
         "duperemove",
         "eeprom",
         "epel",
+        "fallocate",
         "fastboot",
         "fdupes",
         "firewalld",
@@ -70,6 +73,8 @@
         "slurm",
         "sshpass",
         "subvolume",
+        "swapfile",
+        "swapon",
         "tclsh",
         "templating",
         "tfvars",
diff --git a/knowledge base/btrfs.md b/knowledge base/btrfs.md
index 51df613..3abf4eb 100644
--- a/knowledge base/btrfs.md	
+++ b/knowledge base/btrfs.md	
@@ -1,5 +1,8 @@
 # BTRFS
 
+Copy on write (COW) filesystem for Linux.<br/>
+Features and benefits [here][introduction]. (Meta)Data profiles [here][mkfs.btrfs].
+
 ## TL;DR
 
 ```sh
@@ -76,6 +79,7 @@ btrfs property set -ts 'path/to/subvolume' 'ro' 'true'
 sudo btrfs subvolume show 'path/to/subvolume'
 
 # Check the compress ratio of a compressed volume.
+# Requires `compsize`.
 sudo compsize '/mnt/volume'
 
 # Show the status of a running or paused balance operation.
@@ -118,6 +122,20 @@ btrfs-convert '/dev/sdb1'
 
 # Convert btrfs to ext3/ext4.
 btrfs-convert -r '/dev/sdb1'
+
+# Create and activate a 2GB swapfile.
+# Generic procedure. Valid for all `btrfs`' versions.
+truncate -s '0' 'path/to/swapfile'
+chattr +C 'path/to/swapfile'
+fallocate -l '2G' 'path/to/swapfile'
+chmod '0600' 'path/to/swapfile'
+mkswap 'path/to/swapfile'
+swapon 'path/to/swapfile'
+
+# Create and activate a 2GB swapfile.
+# `btrfs` >= 6.1 only.
+btrfs filesystem mkswapfile --size '2G' 'path/to/swapfile'
+swapon 'path/to/swapfile'
 ```
 
 ## Check differences between 2 snapshots
@@ -128,23 +146,36 @@ See also [snapper].
 sudo btrfs send --no-data -p '/old/snapshot' '/new/snapshot' \
 | sudo btrfs receive --dump
 
-# requires you to be using snapper for your snapshots
-sudo snapper -c config diff 445..446
+# Requires one to be using `snapper` to manage the snapshots.
+sudo snapper -c 'config' diff '445..446'
 ```
 
 ## Further readings
 
+- Official [documentation]
+- [Swapfile]
 - [Gentoo wiki]
 - [Snapper]
 
 ## Sources
 
 - [cheat.sh]
-- [does btrfs have an efficient way to compare snapshots?]
-- [determine if a btrfs subvolume is read-only]
+- [Does BTRFS have an efficient way to compare snapshots?]
+- [Determine if a BTRFS subvolume is read-only]
+
+<!-- project's references -->
+
+[documentation]: https://btrfs.readthedocs.io/en/latest/
+[introduction]: https://btrfs.readthedocs.io/en/latest/Introduction.html
+[mkfs.btrfs]: https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html
+[swapfile]: https://btrfs.readthedocs.io/en/latest/Swapfile.html
+
+<!-- internal references -->
 
 [snapper]: snapper.md
 
+<!-- external references -->
+
 [cheat.sh]: https://cheat.sh/btrfs
 [gentoo wiki]: https://wiki.gentoo.org/wiki/Btrfs
 
diff --git a/knowledge base/create, mount and use an encrypted disk.md b/knowledge base/create, mount and use an encrypted disk.md
index f5f9c6a..5ca4c9c 100644
--- a/knowledge base/create, mount and use an encrypted disk.md	
+++ b/knowledge base/create, mount and use an encrypted disk.md	
@@ -30,7 +30,8 @@ parallel -j1 \
   'sudo btrfs send source/volume/.snapshots/{} | sudo btrfs receive destination/volume' \
   ::: $(ls source/volume/.snapshots)
 parallel -q \
-  btrfs subvolume snapshot volume/{} volume/.snapshots/$(date +%FT%T)/{} ::: $(ls source/volume)
+  btrfs subvolume snapshot -r volume/{} volume/.snapshots/$(date +%FT%T)/{} \
+  ::: $(ls source/volume)
 
 # Umount the volume.
 sudo umount 'path/to/mount/point'
@@ -49,6 +50,7 @@ All the references in the [further readings] section, plus the following:
 - script: [Create an encrypted ZFS device]
 
 <!-- project's references -->
+
 <!-- internal references -->
 
 [further readings]: #further-readings