Merge pull request #41 from wesbarnett/feature/important

Add a few scenarios when userdata important=yes is used, update documentation

.github/workflows/docs.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Install dependencies
         run: python -m pip install --upgrade pip sphinx
       - name: Build docs
-        run: cd docs && sphinx-build source build
+        run: sphinx-build -a docs/source docs/build
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
         with:

README.md

@@ -40,11 +40,12 @@ self-explanatory.
 
 ## Documentation
 
-Run `man 8 snap-pac` after installation.
+See the [documentation here](https://wesbarnett.github.io/snap-pac/) or `man 8 snap-pac`
+after installation.
 
 ## Troubleshooting
 
-After reviewing the man page, [check the issues page] and file a new issue if your
+After reviewing the documentation, [check the issues page] and file a new issue if your
 problem is not covered.
 
 [download the latest release]: https://github.com/wesbarnett/snap-pac/releases

docs/source/conf.py

@@ -50,3 +50,16 @@ html_theme = 'alabaster'
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+
+html_theme_options = {
+    'badge_branch': 'main',
+    'fixed_sidebar': True,
+    'github_banner': True,
+    'github_user': 'wesbarnett',
+    'github_repo': 'snap-pac',
+    'github_type': 'star',
+    'show_related': True
+}
+
+man_pages = [("index", "snap-pac", "Pacman hooks that use snapper to create pre/post btrfs snapshots like openSUSE's YaST", "Wes Barnett", "8")]
+manpages_url = 'https://man.archlinux.org/man/{page}.{section}'

docs/source/configuration.rst

@@ -21,7 +21,26 @@ self-explanatory.
 
 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.
+is snapshotted. Additionally you can add a section named ``DEFAULT`` with options that
+apply to all snapper configurations unless overridden in a later section.
+
+Each section can have the following entries:
+
+* ``desc_limit`` - integer; maximum length of description string before being truncated.
+  Default: 72
+* ``important_packages`` - list of strings; names of packages that if involved in a pacman
+  transaction will add ``important=yes`` to the snapper userdata for the pair of
+  snapshots. Default: []
+* ``important_commands`` - list of strings; parent commands that will add
+  ``important=yes`` to the snapper userdata for the pair of snapshots. Default: []
+* ``pre_description`` - string; description for the pre snapshot. Default: the parent
+  command that called the pacman hook.
+* ``post_description`` - string; description for the post snapshot. Default: space
+  separated list of packages that were installed, upgraded, or removed.
+* ``snapshot`` - boolean; whether or not to snapshot the configuration. Default: True for
+  ``root`` configuration; False otherwise.
+* ``userdata`` - list of strings; key-value pairs that will be added to the userdata for
+  the pair of snapshots. Default: []
 
 Environment Variables
 ---------------------

docs/source/examples.rst

@@ -67,9 +67,8 @@ Here is what changed during the transaction:
 	+..... /usr/share/doc/nano/fr/nanorc.5.html
 	+..... /usr/share/doc/nano/fr/rnano.1.html
 
-The above output is truncated, but it continues. See the `snapper(8)
+The above output is truncated, but it continues. See :manpage:`snapper(8)` to for what each
-<http://snapper.io/manpages/snapper.html>`_ to for what each symbol means. You can also
+symbol means. You can also do ``snapper diff`` in the same way.
-do ``snapper diff`` in the same way.
 
 Then, to undo the pacman transaction:
 

docs/source/index.rst

@@ -3,17 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to snap-pac's documentation!
+snap-pac
-====================================
+========
-
-.. toctree::
-   :maxdepth: 2
-
-   installation
-   configuration
-   examples
-   troubleshooting
-   faq
 
 This is a set of `pacman <https://archlinux.org/pacman/>`_ hooks and script that causes
 `snapper <http://snapper.io/>`_ to automatically take a pre and post snapshot before and
@@ -29,9 +20,8 @@ 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.
 
-To undo changes from a pacman transaction, use ``snapper undochange``. See the `snapper
+To undo changes from a pacman transaction, use ``snapper undochange``. See the :manpage:`snapper(8)`
-documentation <http://snapper.io/documentation.html>`_ for more details as well as
+for more details as well as examples.
-examples.
 
 If you have severe breakage—like snapper is gone for some reason and you can't get it
 back—you'll have to resort to more extreme methods, such as taking a snapshot of the pre
@@ -39,3 +29,12 @@ snapshot and making it the default subvolume or mounting it as /. Most likely yo
 need to use a live USB to get into a chroot environment to do any of these things.
 Snapper has a ``snapper rollback`` feature, but your setup has to be properly configured to
 use it. The exact procedure depends on your specific setup. Be careful.
+
+.. toctree::
+   :maxdepth: 1
+
+   installation
+   configuration
+   examples
+   troubleshooting
+   faq

docs/source/troubleshooting.rst

@@ -20,4 +20,4 @@ The pre/post snaphots are taken while pacman is running, so this is expected.  F
 the instructions pacman gives you (*e.g.*, removing the lock file). You can add the
 database lock file to a snapper filter so that snapper  won't consider it when
 performing snapper diff, snapper status, snapper undochange, etc. See the Filters
-section in `snapper(8) <http://snapper.io/manpages/snapper.html>`_ for more information.
+section in :manpage:`snapper(8)` for more information.

extra/snap-pac.ini

@@ -2,6 +2,7 @@
 
 # Each section corresponds with a snapper configuration. Add additional sections to add
 # other configurations to be snapshotted. By default, only the root configuration is snapshotted.
+# Create a setion named [DEFAULT] to have a setting apply for all snapper configurations
 
 [root]
 # How many characters to limit the description for snapper.
@@ -19,6 +20,15 @@ cleanup_algorithm = number
 # Post snapshot description. Default is the list of packages involved in the pacman transaction
 #post_description = pacman post snapshot
 
+# Uncomment to add "important=yes" to userdata for snapshots referring to these packages
+#important_packages = ["linux", "linux-lts]
+
+# Uncomment to add "important=yes" to userdata for snapshots that were created with the following commands
+#important_commands = ["pacman -Syu"]
+
+# Add custom userdata. Each key-value pair should be an item in the list
+#userdata = ["key=value","foo=bar"]
+
 # Example for another snapper configuration named "home"
 # [home]
 # snapshot = True

man8/snap-pac.8

@@ -1,67 +1,197 @@
-'\" t
+.\" Man page generated from reStructuredText.
-.TH SNAP-PAC 8 2021-01-29 SNAP-PAC
+.
+.TH "SNAP-PAC" "8" "Mar 13, 2021" "" "snap-pac"
 .SH NAME
-snap-pac \- Pacman hooks that use snapper to create pre/post btrfs snapshots
+snap-pac \- Pacman hooks that use snapper to create pre/post btrfs snapshots like openSUSE's YaST
-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 \fIpacman\fR hooks and script that causes \fIsnapper\fR to
+This is a set of \fI\%pacman\fP hooks and script that causes
-automatically take a pre and post snapshot before and after pacman transactions,
+\fI\%snapper\fP to automatically take a pre and post snapshot before and
-similar to how YaST does with OpenSuse. This provides a simple way to undo
+after pacman transactions, similar to how \fI\%YaST\fP does with
-changes to a system after a pacman transaction.
+OpenSuse. This provides a simple way to undo changes to a system after a pacman
-
+transaction.
-Because these are pacman hooks, it doesn't matter how you call pacman—whether
+.sp
-directly, through an AUR helper, or using an alias—snapper will create the
+Because these are pacman hooks, it doesn\(aqt matter how you call pacman—whether
-snapshots when pacman installs, upgrades, or removes a package. The pacman
+directly, through an AUR helper, or using an alias—snapper will create the snapshots
-command used is logged in the snapper description for the snapshots.
+when pacman installs, upgrades, or removes a package. The pacman command used is
-Additionally the snapshot numbers are output to the screen and to the pacman log
+logged in the snapper description for the snapshots. Additionally the snapshot numbers
-for each snapper configuration during the pacman transaction, so that the user can
+are output to the screen and to the pacman log for each snapper configuration during the
-easily find which changes he or she may want to revert.
+pacman transaction, so that the user can easily find which changes he or she may want to
-
+revert.
-To undo changes from a pacman transaction, use \fIsnapper undochange\fR. See 
+.sp
-\fBsnapper\fR(8) and \fBEXAMPLES\fR.
+To undo changes from a pacman transaction, use \fBsnapper undochange\fP\&. See the \fBsnapper(8)\fP
-
+for more details as well as examples.
-If you have severe breakage—like snapper is gone for some reason and you can't
+.sp
-get it back—you'll have to resort to more extreme methods, such as taking a
+If you have severe breakage—like snapper is gone for some reason and you can\(aqt get it
-snapshot of the pre snapshot and making it the default subvolume or mounting it
+back—you\(aqll have to resort to more extreme methods, such as taking a snapshot of the pre
-as \fI/\fR. Most likely you'll need to use a live USB to get into a chroot
+snapshot and making it the default subvolume or mounting it as /. Most likely you\(aqll
-environment to do any of these things. Snapper has a snapper rollback feature,
+need to use a live USB to get into a chroot environment to do any of these things.
-but your setup has to be properly configured to use it. The exact procedure
+Snapper has a \fBsnapper rollback\fP feature, but your setup has to be properly configured to
-depends on your specific setup. Be careful.
+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\&.
 .SH CONFIGURATION
-Configuration is done via Python ini configuration files. The defaults of the
+.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 "root" snapper configuration is snapshotted.
+By default only the \fBroot\fP snapper configuration is snapshotted.
-
+.sp
-A commented example configuration files is located at \fI/etc/snap-pac.ini.example\fR.
+A commented example configuration files is located at \fB/etc/snap\-pac.ini.example\fP\&.
-
+.sp
-.SH ENVIRONMENT VARIABLES
+To configure, copy the example configuration file:
-
+.INDENT 0.0
-To temporarily prevent snapshots from being performed for a single
+.INDENT 3.5
-pacman command, set the environment variable \fISNAP_PAC_SKIP\fR. For
+.sp
-example:
+.nf
-
+.ft C
-.EX
+cp /etc/snap\-pac.ini{.example,}
-
+.ft P
-    $ sudo SNAP_PAC_SKIP=y pacman -Syu
+.fi
-
+.UNINDENT
-.EE
+.UNINDENT
-
+.sp
-
+Then edit with your favorite editor. The file is commented and should be
-.SH EXAMPLES
+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 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 \fBnano\fR package is installed:
+transaction. Here the nano package is installed:
-
+.INDENT 0.0
-.EX
+.INDENT 3.5
-
+.sp
-    # pacman -S nano
+.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
+Packages (1) nano\-2.5.3\-1
 
 Total Installed Size:  2.14 MiB
 
@@ -71,36 +201,62 @@ transaction. Here the \fBnano\fR package is installed:
 (1/1) loading package files                                  [######################################] 100%
 (1/1) checking for file conflicts                            [######################################] 100%
 (1/1) checking available disk space                          [######################################] 100%
-    :: Running pre-transaction hooks...
+:: 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...
+:: Running post\-transaction hooks...
 (1/1) Performing snapper post snapshots for the following configurations...
 => root: 1034
-
+.ft P
-.EE
+.fi
-
+.UNINDENT
-The snapper snapshot number is given for each snapper configuration that is
+.UNINDENT
-used. This is also logged in pacman's log.
+.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
-.EX
+.INDENT 3.5
-
+.sp
-    # snapper -c root list -t pre-post | tail -n 1
+.nf
-    1033  | 1034   | Fri 22 Apr 2016 01:54:13 PM CDT | Fri 22 Apr 2016 01:54:14 PM CDT | pacman -S nano      | 
+.ft C
-
+snapper \-c root list \-t pre\-post | tail \-n 1
-.EE
+.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
-.EX
+.INDENT 3.5
-
+.sp
-    # snapper -c root status 1033..1034
+.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
+c..... /etc/snapper/.snap\-pac\-pre
 +..... /usr/bin/nano
 +..... /usr/bin/rnano
 +..... /usr/share/doc/nano
@@ -109,56 +265,86 @@ Here is what changed during the transaction:
 +..... /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
-.EE
+.fi
-
+.UNINDENT
-The above output is truncated, but it continues. See the \fBsnapper\fR(8) to
+.UNINDENT
-for what each symbol means. You can also do \fBsnapper diff\fR in the same way.
+.sp
-
+The above output is truncated, but it continues. See \fBsnapper(8)\fP to for what each
-Then, to undo the \fBpacman\fR transaction:
+symbol means. You can also do \fBsnapper diff\fP in the same way.
-
+.sp
-.EX
+Then, to undo the pacman transaction:
-
+.INDENT 0.0
-    # snapper -c root undochange 1033..1034
+.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
-.EE
+.fi
-
+.UNINDENT
+.UNINDENT
+.sp
 Now nano is no longer installed, along with all the files it changed:
-
+.INDENT 0.0
-.EX
+.INDENT 3.5
-
+.sp
-    $ pacman -Qi nano
+.nf
-    error: package 'nano' was not found
+.ft C
-
+pacman \-Qi nano
-.EE
+.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
-.SS snap-pac is only taking snapshots of the root configuration.
+\fBsnap\-pac is only taking snapshots of the root configuration.\fP
-That's the default behavior. See \fBCONFIGURATION\fR.
+.sp
-
+That\(aqs the default behavior. See configuration\&.
-.SS No snapshots are being taken when I run pacman.
+.sp
-No snapper configurations are set up for snap-pac's pacman hooks. By default
+\fBNo snapshots are being taken when I run pacman.\fP
-snap-pac will take snapshots for the root configuration and any other
+.sp
-configuration which has SNAPSHOT set to yes in its configuration file.
+No snapper configurations are set up for snap\-pac\(aqs pacman hooks. By default snap\-pac
-See \fBCONFIGURATION\fR.
+will take snapshots for the root configuration and any other configuration which has
-
+SNAPSHOT set to yes in its configuration file. See configuration\&.
-.SS After restoring snapshot from snap-pac, the pacman database is locked.
+.sp
-The pre/post snaphots are taken while pacman is running, so this is expected.
+\fBAfter restoring snapshot from snap\-pac, the pacman database is locked.\fP
-Follow the instructions pacman gives you (e.g., removing the lock file). You can add the
+.sp
-database lock file to a snapper filter so that snapper won't consider it when performing
+The pre/post snaphots are taken while pacman is running, so this is expected.  Follow
-\fBsnapper diff\fR, \fBsnapper status\fR, \fBsnapper undochange\fR, etc. See the
+the instructions pacman gives you (\fIe.g.\fP, removing the lock file). You can add the
-\fBFilters\fR section in \fBsnapper\fR(8) for more information.
+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
-.SS Does snap-pac backup non-btrfs /boot partitions?
+.sp
-No, but you can add a hook that does it for you. It would be
+\fBDoes snap\-pac backup non\-btrfs /boot partitions?\fP
-something like the following:
+.sp
-
+No, but you can add a hook that does it for you. It would be something like the following:
-.EX
+.INDENT 0.0
-
+.INDENT 3.5
+.sp
+.nf
+.ft C
 [Trigger]
 Operation = Upgrade
 Operation = Install
@@ -169,13 +355,20 @@ something like the following:
 [Action]
 Description = Backing up /boot...
 When = PreTransaction
-    Exec = /usr/bin/rsync -avzq --delete /boot /.bootbackup
+Exec = /usr/bin/rsync \-avzq \-\-delete /boot /.bootbackup
-
+.ft P
-.EE
+.fi
-
+.UNINDENT
-.SS How do I link old kernel modules automatically when the kernel is upgraded?
+.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
@@ -186,17 +379,14 @@ This behavior is no longer a part of this package. Use a pacman hook like the fo
 [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 'END{print $1}')/snapshot/usr/lib/modules/$(uname -r) /usr/lib/modules/"
+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
-.SH HOMEPAGE
+.fi
-https://github.com/wesbarnett/snap-pac
+.UNINDENT
-
+.UNINDENT
-.SH AUTHORS
+.SH AUTHOR
-Wes Barnett <wes@wbarnett.us>
+Wes Barnett
-
+.SH COPYRIGHT
-.SH SEE ALSO
+2021, Wes Barnett, PhD
-.BR alpm-hooks (5),
+.\" Generated by docutils manpage writer.
-.BR snapper (8),
+.
-.BR snapper-configs (5),
-.BR pacman (8)
-

scripts/snap_pac.py

@@ -18,6 +18,7 @@
 
 from argparse import ArgumentParser
 from configparser import ConfigParser
+import json
 import logging
 from pathlib import Path
 import os
@@ -30,7 +31,8 @@ logging.basicConfig(format="%(message)s", level=logging.INFO)
 
 class SnapperCmd:
 
-    def __init__(self, config, snapshot_type, cleanup_algorithm, description="", nodbus=False, pre_number=None):
+    def __init__(self, config, snapshot_type, cleanup_algorithm, description="",
+                 nodbus=False, pre_number=None, userdata=""):
         self.cmd = ["snapper"]
         if nodbus:
             self.cmd.append("--no-dbus")
@@ -40,6 +42,8 @@ class SnapperCmd:
         self.cmd.append("--print-number")
         if description:
             self.cmd.append(f"--description \"{description}\"")
+        if userdata:
+            self.cmd.append(f"--userdata \"{userdata}\"")
         if snapshot_type == "post":
             if pre_number is not None:
                 self.cmd.append(f"--pre-number {pre_number}")
@@ -69,8 +73,11 @@ def setup_config_parser(ini_file, parent_cmd, packages):
         "snapshot": False,
         "cleanup_algorithm": "number",
         "pre_description": parent_cmd,
-        "post_description": packages,
+        "post_description": " ".join(packages),
-        "desc_limit": 72
+        "desc_limit": 72,
+        "important_packages": [],
+        "important_commands": [],
+        "userdata": set()
     }
     config["root"] = {
         "snapshot": True
@@ -100,13 +107,30 @@ def get_pre_number(snapshot_type, prefile):
     return pre_number
 
 
+def check_important_commands(config, snapper_config, parent_cmd):
+    important_commands = json.loads(config.get(snapper_config, "important_commands"))
+    return parent_cmd in important_commands
+
+
+def check_important_packages(config, snapper_config, packages):
+    important_packages = json.loads(config.get(snapper_config, "important_packages"))
+    return any(x in important_packages for x in packages)
+
+
+def get_userdata(config, snapper_config, important):
+    userdata = set(json.loads(config.get(snapper_config, "userdata")))
+    if important:
+        userdata.add("important=yes")
+    return ",".join(sorted(list(userdata)))
+
+
 def main(snap_pac_ini, snapper_conf_file, args):
 
     if os.getenv("SNAP_PAC_SKIP", "n").lower() in ["y", "yes", "true", "1"]:
         return False
 
     parent_cmd = os.popen(f"ps -p {os.getppid()} -o args=").read().strip()
-    packages = " ".join([line.rstrip("\n") for line in sys.stdin])
+    packages = [line.rstrip("\n") for line in sys.stdin]
     config = setup_config_parser(snap_pac_ini, parent_cmd, packages)
     snapper_configs = get_snapper_configs(snapper_conf_file)
     chroot = os.stat("/") != os.stat("/proc/1/root/.")
@@ -123,7 +147,13 @@ def main(snap_pac_ini, snapper_conf_file, args):
             description = get_description(args.type, config, snapper_config)
             pre_number = get_pre_number(args.type, prefile)
 
-            snapper_cmd = SnapperCmd(snapper_config, args.type, cleanup_algorithm, description, chroot, pre_number)
+            important = (check_important_commands(config, snapper_config, parent_cmd) or
+                         check_important_packages(config, snapper_config, packages))
+
+            userdata = get_userdata(config, snapper_config, important)
+
+            snapper_cmd = SnapperCmd(snapper_config, args.type, cleanup_algorithm,
+                                     description, chroot, pre_number, userdata)
             num = snapper_cmd()
             logging.info(f"==> {snapper_config}: {num}")
 

tests/test_script.py

@@ -6,8 +6,8 @@ import os
 import pytest
 
 from scripts.snap_pac import (
-   SnapperCmd, get_pre_number, get_snapper_configs, main, setup_config_parser,
+   SnapperCmd, check_important_commands, check_important_packages, get_pre_number, get_snapper_configs,
-   get_description
+   get_userdata, main, setup_config_parser, get_description
 )
 
 
@@ -19,7 +19,10 @@ def config():
         "cleanup_algorithm": "number",
         "pre_description": "foo",
         "post_description":  "bar",
-        "desc_limit": 72
+        "desc_limit": 72,
+        "important_packages": [],
+        "important_commands": [],
+        "userdata": set()
     }
     config["root"] = {
         "snapshot": True
@@ -54,6 +57,16 @@ def prefile():
         SnapperCmd("root", "post", "number", "bar", True, 1234),
         "snapper --no-dbus --config root create --type post --cleanup-algorithm number --print-number"
         " --description \"bar\" --pre-number 1234"
+    ),
+    (
+        SnapperCmd("root", "post", "number", "bar", False, 1234, "important=yes"),
+        "snapper --config root create --type post --cleanup-algorithm number --print-number"
+        " --description \"bar\" --userdata \"important=yes\" --pre-number 1234"
+    ),
+    (
+        SnapperCmd("root", "post", "number", "bar", False, 1234, "foo=bar,important=yes"),
+        "snapper --config root create --type post --cleanup-algorithm number --print-number"
+        " --description \"bar\" --userdata \"foo=bar,important=yes\" --pre-number 1234"
     )
 ])
 def test_snapper_cmd(snapper_cmd, actual_cmd):
@@ -84,7 +97,7 @@ def test_setup_config_parser(config):
         f.write("desc_limit = 3\n")
         f.write("post_description = a really long description\n")
         name = f.name
-    config2 = setup_config_parser(name, "foo", "bar")
+    config2 = setup_config_parser(name, "foo", ["bar"])
     assert config == config2
 
 
@@ -104,3 +117,45 @@ def test_no_prefile():
 @pytest.mark.parametrize("snapshot_type, description", [("pre", "foo"), ("post", "a r")])
 def test_get_description(snapshot_type, description, config):
     assert get_description(snapshot_type, config, "home") == description
+
+
+def test_important_commands():
+    parent_cmd = "pacman -Syu"
+    with tempfile.NamedTemporaryFile("w", delete=False) as f:
+        f.write("[DEFAULT]\n")
+        f.write("important_commands = [\"pacman -Syu\"]\n")
+        name = f.name
+    config = setup_config_parser(name, parent_cmd, ["bar"])
+    important = check_important_commands(config, "root", parent_cmd)
+    assert important
+
+
+def test_important_packages():
+    packages = ["bar", "linux", "vim"]
+    with tempfile.NamedTemporaryFile("w", delete=False) as f:
+        f.write("[DEFAULT]\n")
+        f.write("important_packages = [\"linux\"]\n")
+        name = f.name
+    config = setup_config_parser(name, "pacman -S", packages)
+    important = check_important_packages(config, "root", packages)
+    assert important
+
+
+def test_load_userdata():
+    with tempfile.NamedTemporaryFile("w", delete=False) as f:
+        f.write("[DEFAULT]\n")
+        f.write("userdata = [\"foo=bar\", \"requestid=42\"]\n")
+        name = f.name
+    config = setup_config_parser(name, "pacman -Syu", ["bar"])
+    userdata = get_userdata(config, "root", False)
+    assert userdata == "foo=bar,requestid=42"
+
+
+def test_load_userdata_and_important():
+    with tempfile.NamedTemporaryFile("w", delete=False) as f:
+        f.write("[DEFAULT]\n")
+        f.write("userdata = [\"foo=bar\", \"requestid=42\"]\n")
+        name = f.name
+    config = setup_config_parser(name, "pacman -Syu", ["bar"])
+    userdata = get_userdata(config, "root", True)
+    assert userdata == "foo=bar,important=yes,requestid=42"