Merge pull request #42 from wesbarnett/feature/man
Don't track changes in manpage since it is generated
This commit is contained in:
commit
ef889e198e
3 changed files with 7 additions and 550 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -1,3 +1,4 @@
|
|||
__pycache__
|
||||
venv
|
||||
docs/build
|
||||
man8
|
||||
|
|
|
|||
9
Makefile
9
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
|
||||
|
|
|
|||
547
man8/snap-pac.8
547
man8/snap-pac.8
|
|
@ -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\-<version>.tar.gz.sig
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
where \fB<version>\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.
|
||||
.
|
||||
Loading…
Add table
Reference in a new issue