From 328851739525775b46ca329cde95de2bace197f7 Mon Sep 17 00:00:00 2001 From: Wes Barnett Date: Sun, 4 Apr 2021 18:11:12 -0400 Subject: [PATCH] Don't track changes in manpage since it is generated --- .gitignore | 1 + Makefile | 9 +- man8/snap-pac.8 | 547 ------------------------------------------------ 3 files changed, 7 insertions(+), 550 deletions(-) delete mode 100644 man8/snap-pac.8 diff --git a/.gitignore b/.gitignore index 2995d99..a2d662f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ __pycache__ venv docs/build +man8 diff --git a/Makefile b/Makefile index 4a74168..b50ad1a 100644 --- a/Makefile +++ b/Makefile @@ -22,7 +22,7 @@ SHARE_DIR = $(DESTDIR)$(PREFIX)/share .PHONY: install test docs -install: +install: man @install -Dm755 scripts/snap_pac.py $(SHARE_DIR)/libalpm/scripts/snap-pac @install -Dm644 hooks/* -t $(SHARE_DIR)/libalpm/hooks/ @install -Dm644 LICENSE -t $(SHARE_DIR)/licenses/$(PKGNAME)/ @@ -33,7 +33,10 @@ install: test: @python -m pytest -v . -docs: - @sphinx-build -a docs/source docs/build +man: @cd docs && make man + @mkdir -p man8 @awk 'NR==33{print ".SH DESCRIPTION"}7' docs/build/man/snap-pac.8 > man8/snap-pac.8 + +docs: man + @sphinx-build -a docs/source docs/build diff --git a/man8/snap-pac.8 b/man8/snap-pac.8 deleted file mode 100644 index ca03a43..0000000 --- a/man8/snap-pac.8 +++ /dev/null @@ -1,547 +0,0 @@ -.\" Man page generated from reStructuredText. -. -.TH "SNAP-PAC" "8" "Mar 28, 2021" "" "snap-pac" -.SH NAME -snap-pac \- Pacman hooks that use snapper to create pre/post btrfs snapshots like openSUSE's YaST -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.SH DESCRIPTION -.sp -This is a set of \fI\%pacman\fP hooks and script that causes -\fI\%snapper\fP to automatically take a pre and post snapshot before and -after pacman transactions, similar to how \fI\%YaST\fP does with -OpenSuse. This provides a simple way to undo changes to a system after a pacman -transaction. -.sp -Because these are pacman hooks, it doesn\(aqt matter how you call pacman—whether -directly, through an AUR helper, or using an alias—snapper will create the snapshots -when pacman installs, upgrades, or removes a package. The pacman command used is -logged in the snapper description for the snapshots. Additionally the snapshot numbers -are output to the screen and to the pacman log for each snapper configuration during the -pacman transaction, so that the user can easily find which changes he or she may want to -revert. -.sp -When you run pacman, the snapper pre/post snapshots are created automatically. For a fuller example see examples\&. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ sudo pacman \-S vim -resolving dependencies... -looking for conflicting packages... - -Packages (1) vim\-8.2.2489\-1 - -Total Installed Size: 3.79 MiB -Net Upgrade Size: 0.00 MiB - -:: Proceed with installation? [Y/n] -(1/1) checking keys in keyring [############] 100% -(1/1) checking package integrity [############] 100% -(1/1) loading package files [############] 100% -(1/1) checking for file conflicts [############] 100% -(1/1) checking available disk space [############] 100% -:: Running pre\-transaction hooks... -(1/1) Performing snapper pre snapshots for the following configurations... -==> root: 7394 -:: Processing package changes... -(1/1) installing vim [############] 100% -:: Running post\-transaction hooks... -(1/4) Arming ConditionNeedsUpdate... -(2/4) Updating icon theme caches... -(3/4) Updating the desktop file MIME type cache... -(4/4) Performing snapper post snapshots for the following configurations... -==> root: 7395 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To undo changes from a pacman transaction, use \fBsnapper undochange\fP\&. See the \fBsnapper(8)\fP -for more details as well as examples. -.sp -If you have severe breakage—like snapper is gone for some reason and you can\(aqt get it -back—you\(aqll have to resort to more extreme methods, such as taking a snapshot of the pre -snapshot and making it the default subvolume or mounting it as /. Most likely you\(aqll -need to use a live USB to get into a chroot environment to do any of these things. -Snapper has a \fBsnapper rollback\fP feature, but your setup has to be properly configured to -use it. The exact procedure depends on your specific setup. Be careful. -.SH INSTALLATION -.sp -Install the \fBsnap\-pac\fP package using pacman: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -pacman \-S snap\-pac -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternatively download the \fI\%latest release and signature\fP\&. Then, verify the download: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -gpg \-\-verify snap\-pac\-.tar.gz.sig -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -where \fB\fP is the version number you downloaded. -.sp -Finally, run: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -make install -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -I have signed the release tarball and commits with my PGP key. Starting with release -2.2, the tarballs are signed with my key with fingerprint -\fBF7B28C61944FE30DABEEB0B01070BCC98C18BD66\fP\&. -.sp -For previous releases, the key\(aqs fingerprint was -\fB8535CEF3F3C38EE69555BF67E4B5E45AA3B8C5C3\fP\&. -.SS Dependencies -.sp -\fBpython\fP, \fBpacman\fP, and \fBsnapper\fP are all required. -.SS Testing -.sp -For testing, \fBpytest\fP is required. To run the tests do: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -make test -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Documentation -.sp -Typically, you will not need to build the documentation on your own and can simply -access it by visiting the \fI\%online documentation\fP or by accessing the manpage: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -man 8 snap\-pac -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To build the documentation, \fBsphinx\fP is required. To build the documentation you can -do: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -make docs -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The resulting html documentation will then be located at \fBdocs/build/index.html\fP\&. -Additionally, this generates the manpage which will be located under \fBman8\fP\&. -.SH CONFIGURATION -.sp -Configuration is done via Python ini configuration files. The defaults -should be suitable for most users, so you may not need to do any configuration at all. -By default only the \fBroot\fP snapper configuration is snapshotted. -.sp -A commented example configuration files is located at \fB/etc/snap\-pac.ini.example\fP\&. -.sp -To configure, copy the example configuration file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -cp /etc/snap\-pac.ini{.example,} -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Then edit with your favorite editor. The file is commented and should be -self\-explanatory. -.sp -Each section corresponds with a snapper configuration. Add additional sections to add -other snapper configurations to be snapshotted. By default, only the root configuration -is snapshotted. Additionally you can add a section named \fBDEFAULT\fP with options that -apply to all snapper configurations unless overridden in a later section. -.sp -Each section can have the following entries: -.INDENT 0.0 -.IP \(bu 2 -\fBdesc_limit\fP \- integer; maximum length of description string before being truncated. -Default: 72 -.IP \(bu 2 -\fBimportant_packages\fP \- list of strings; names of packages that if involved in a pacman -transaction will add \fBimportant=yes\fP to the snapper userdata for the pair of -snapshots. Default: [] -.IP \(bu 2 -\fBimportant_commands\fP \- list of strings; parent commands that will add -\fBimportant=yes\fP to the snapper userdata for the pair of snapshots. Default: [] -.IP \(bu 2 -\fBpre_description\fP \- string; description for the pre snapshot. Default: the parent -command that called the pacman hook. -.IP \(bu 2 -\fBpost_description\fP \- string; description for the post snapshot. Default: space -separated list of packages that were installed, upgraded, or removed. -.IP \(bu 2 -\fBsnapshot\fP \- boolean; whether or not to snapshot the configuration. Default: True for -\fBroot\fP configuration; False otherwise. -.IP \(bu 2 -\fBuserdata\fP \- list of strings; key\-value pairs that will be added to the userdata for -the pair of snapshots. Default: [] -.UNINDENT -.SS Examples -.sp -Turn off snapshots for \fBroot\fP configuration and turn on for \fBhome\fP configuration: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[root] -snapshot = False - -[home] -snapshot = True -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Set the snapper to add the userdata \fBimportant=yes\fP for every snapshot in the \fBroot\fP -configuration when a system upgrade is performed: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[root] -important_commands = ["pacman \-Syu"] -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Set the snapper to add the userdata \fBimportant=yes\fP for every snapshot in the \fBroot\fP -configuration when a pacman transaction handles the packages \fBlinux\fP and \fBlinux\-lts\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[root] -important_packages = ["linux", "linux\-lts"] -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Here\(aqs a fuller example, with several options set for different configurations. In this -case the \fBroot\fP configuration snapshot will have \fBimportant=yes\fP when \fBlinux\fP and -\fBlinux\-lts\fP packages are part of the transaction. Additionally when full system -upgrades are performed \fBroot\fP snapshots will be marked \fBimportant=yes\fP\&. Note that -you don\(aqt have to add \fBsnapshot = True\fP for the \fBroot\fP configuration since that is -the default. -.sp -This file also turns one snapshots for the \fBhome\fP snapper configuration and adds the -userdata \fBrequestid=42,user=arthur\fP to all snapshots for that configuration. -Additionally he post snapshot description is overridden. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[root] -important_packages = ["linux", "linux\-lts"] -important_commands = ["pacman \-Syu"] - -[home] -snapshot = True -userdata = ["requestid=42", "user=arthur"] -post_description = "pacman transaction post snapshot" -.ft P -.fi -.UNINDENT -.UNINDENT -.SH ENVIRONMENT VARIABLES -.sp -To temporarily prevent snapshots from being performed for a single pacman -command, set the environment variable \fBSNAP_PAC_SKIP\fP\&. For example: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -sudo SNAP_PAC_SKIP=y pacman \-Syu -.ft P -.fi -.UNINDENT -.UNINDENT -.SH EXAMPLE -.sp -Here is an example of how the snapshots are created and how to rollback and pacman -transaction. Here the nano package is installed: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -pacman \-S nano -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -resolving dependencies... -looking for conflicting packages... - -Packages (1) nano\-2.5.3\-1 - -Total Installed Size: 2.14 MiB - -:: Proceed with installation? [Y/n] Y -(1/1) checking keys in keyring [######################################] 100% -(1/1) checking package integrity [######################################] 100% -(1/1) loading package files [######################################] 100% -(1/1) checking for file conflicts [######################################] 100% -(1/1) checking available disk space [######################################] 100% -:: Running pre\-transaction hooks... -(1/1) Performing snapper pre snapshots for the following configurations... -=> root: 1033 -:: Processing package changes... -(1/1) installing nano [######################################] 100% -:: Running post\-transaction hooks... -(1/1) Performing snapper post snapshots for the following configurations... -=> root: 1034 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The snapper snapshot number is given for each snapper configuration that is used. This -is also logged in pacman\(aqs log. -.sp -Here are the snapshots created before and after the pacman transaction: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -snapper \-c root list \-t pre\-post | tail \-n 1 -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -1033 | 1034 | Fri 22 Apr 2016 01:54:13 PM CDT | Fri 22 Apr 2016 01:54:14 PM CDT | pacman \-S nano | -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Here is what changed during the transaction: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -snapper \-c root status 1033..1034 -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -+..... /etc/nanorc -c..... /etc/snapper/.snap\-pac\-pre -+..... /usr/bin/nano -+..... /usr/bin/rnano -+..... /usr/share/doc/nano -+..... /usr/share/doc/nano/faq.html -+..... /usr/share/doc/nano/fr -+..... /usr/share/doc/nano/fr/nano.1.html -+..... /usr/share/doc/nano/fr/nanorc.5.html -+..... /usr/share/doc/nano/fr/rnano.1.html -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The above output is truncated, but it continues. See \fBsnapper(8)\fP to for what each -symbol means. You can also do \fBsnapper diff\fP in the same way. -.sp -Then, to undo the pacman transaction: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -snapper \-c root undochange 1033..1034 -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -create:0 modify:3 delete:100 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Now nano is no longer installed, along with all the files it changed: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -pacman \-Qi nano -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -error: package \(aqnano\(aq was not found -.ft P -.fi -.UNINDENT -.UNINDENT -.SH TROUBLESHOOTING -.sp -\fBsnap\-pac is only taking snapshots of the root configuration.\fP -.sp -That\(aqs the default behavior. See configuration\&. -.sp -\fBNo snapshots are being taken when I run pacman.\fP -.sp -No snapper configurations are set up for snap\-pac\(aqs pacman hooks. By default snap\-pac -will take snapshots for the root configuration and any other configuration which has -SNAPSHOT set to yes in its configuration file. See configuration\&. -.sp -\fBAfter restoring snapshot from snap\-pac, the pacman database is locked.\fP -.sp -The pre/post snaphots are taken while pacman is running, so this is expected. Follow -the instructions pacman gives you (\fIe.g.\fP, removing the lock file). You can add the -database lock file to a snapper filter so that snapper won\(aqt consider it when -performing snapper diff, snapper status, snapper undochange, etc. See the Filters -section in \fBsnapper(8)\fP for more information. -.SH FAQ -.sp -\fBDoes snap\-pac backup non\-btrfs /boot partitions?\fP -.sp -No, but you can add a hook that does it for you. It would be something like the following: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[Trigger] -Operation = Upgrade -Operation = Install -Operation = Remove -Type = Package -Target = linux - -[Action] -Description = Backing up /boot... -When = PreTransaction -Exec = /usr/bin/rsync \-avzq \-\-delete /boot /.bootbackup -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBHow do I link old kernel modules automatically when the kernel is upgraded?\fP -.sp -This behavior is no longer a part of this package. Use a pacman hook like the following: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[Trigger] -Operation = Upgrade -Operation = Install -Operation = Remove -Type = Package -Target = linux - -[Action] -Description = Symlinking old kernel modules... -When = PostTransaction -Exec = /usr/bin/bash \-c "find /usr/lib/modules \-xtype l \-delete; ln \-sv /.snapshots/$(snapper \-c root list | awk \(aqEND{print $1}\(aq)/snapshot/usr/lib/modules/$(uname \-r) /usr/lib/modules/" -.ft P -.fi -.UNINDENT -.UNINDENT -.SH AUTHOR -Wes Barnett -.SH COPYRIGHT -2021, Wes Barnett, PhD -.\" Generated by docutils manpage writer. -.