From ec959799b8c2f2ed4668d1fd855003b6ffb16722 Mon Sep 17 00:00:00 2001 From: Wes Barnett Date: Mon, 15 Mar 2021 08:03:23 -0400 Subject: [PATCH] update manpage; add docs to Makefile --- Makefile | 7 ++- man8/snap-pac.8 | 147 +++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 150 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index 3eab261..265cea3 100644 --- a/Makefile +++ b/Makefile @@ -20,7 +20,7 @@ PREFIX ?= /usr SHARE_DIR = $(DESTDIR)$(PREFIX)/share -.PHONY: install +.PHONY: install test docs install: @install -Dm755 scripts/snap_pac.py $(SHARE_DIR)/libalpm/scripts/snap-pac @@ -32,3 +32,8 @@ install: test: @python -m pytest -v . + +docs: + @sphinx-build -a docs/source docs/build + @rm -r man8 + @cd docs && make man && mv build/man ../man8 diff --git a/man8/snap-pac.8 b/man8/snap-pac.8 index 479f5bc..f137835 100644 --- a/man8/snap-pac.8 +++ b/man8/snap-pac.8 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SNAP-PAC" "8" "Mar 13, 2021" "" "snap-pac" +.TH "SNAP-PAC" "8" "Mar 14, 2021" "" "snap-pac" .SH NAME snap-pac \- Pacman hooks that use snapper to create pre/post btrfs snapshots like openSUSE's YaST . @@ -30,7 +30,6 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" 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 @@ -47,6 +46,43 @@ are output to the screen and to the pacman log for each snapper configuration du 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 @@ -102,6 +138,38 @@ I have signed the release tarball and commits with my PGP key. Starting with rel .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 +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 +sphinx\-build docs/source docs/build +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The resulting html documentation will then be located at \fBdocs/build/index.html\fP\&. .SH CONFIGURATION .sp Configuration is done via Python ini configuration files. The defaults @@ -155,7 +223,80 @@ separated list of packages that were installed, upgraded, or removed. \fBuserdata\fP \- list of strings; key\-value pairs that will be added to the userdata for the pair of snapshots. Default: [] .UNINDENT -.SS Environment Variables +.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: