Update documentation to recommend installing/upgrading borgmatic with pipx instead of pip.

NEWS

@@ -2,6 +2,10 @@
  * #743: Add a monitoring hook for sending backup status and logs to to Grafana Loki. See the
    documentation for more information:
    https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook
+ * Update documentation to recommend installing/upgrading borgmatic with pipx instead of pip. See the
+   documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation
+   https://torsion.org/borgmatic/docs/how-to/upgrade/#upgrading-borgmatic
 
 1.8.2
  * #345: Add "key export" action to export a copy of the repository key for safekeeping in case

docs/how-to/develop-on-borgmatic.md

@@ -7,7 +7,12 @@ eleventyNavigation:
 ---
 ## Source code
 
-To get set up to develop on borgmatic, first clone it via HTTPS or SSH:
+To get set up to develop on borgmatic, first [`install
+pipx`](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation)
+to make managing your borgmatic environment easy without impacting other
+Python applications on your system.
+
+Then, clone borgmatic via HTTPS or SSH:
 
 ```bash
 git clone https://projects.torsion.org/borgmatic-collective/borgmatic.git
@@ -19,39 +24,33 @@ Or:
 git clone ssh://git@projects.torsion.org:3022/borgmatic-collective/borgmatic.git
 ```
 
-Then, install borgmatic
-"[editable](https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs)"
+Finally, install borgmatic
+"[editable](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs)"
 so that you can run borgmatic actions during development to make sure your
-changes work.
+changes work:
 
 ```bash
 cd borgmatic
-pip3 install --user --editable .
+pipx install --editable .
 ```
 
-Note that this will typically install the borgmatic commands into
-`~/.local/bin`, which may or may not be on your PATH. There are other ways to
-install borgmatic editable as well, for instance into the system Python
-install (so without `--user`, as root), or even into a
-[virtualenv](https://virtualenv.pypa.io/en/stable/). How or where you install
-borgmatic is up to you, but generally an editable install makes development
-and testing easier.
-
 To get oriented with the borgmatic source code, have a look at the [source
 code reference](https://torsion.org/borgmatic/docs/reference/source-code/).
 
 
 ## Automated tests
 
-Assuming you've cloned the borgmatic source code as described above, and
-you're in the `borgmatic/` working copy, install tox, which is used for
-setting up testing environments:
+Assuming you've cloned the borgmatic source code as described above and you're
+in the `borgmatic/` working copy, install tox, which is used for setting up
+testing environments. You can either install a system package of tox (likely
+called `tox` or `python-tox`) or you can install tox with pipx:
 
 ```bash
-pip3 install --user tox
+pipx install tox
 ```
 
-Finally, to actually run tests, run:
+Finally, to actually run tests, run tox from inside the borgmatic
+sourcedirectory:
 
 ```bash
 tox

docs/how-to/set-up-backups.md

@@ -7,43 +7,30 @@ eleventyNavigation:
 ---
 ## Installation
 
-Many users need to backup system files that require privileged access, so
-these instructions install and run borgmatic as root. If you don't need to
-backup such files, then you are welcome to install and run borgmatic as a
-non-root user.
-
-First, manually [install
+First, [install
 Borg](https://borgbackup.readthedocs.io/en/stable/installation.html), at least
 version 1.1. borgmatic does not install Borg automatically so as to avoid
 conflicts with existing Borg installations.
 
-Then, download and install borgmatic as a [user site
-installation](https://packaging.python.org/tutorials/installing-packages/#installing-to-the-user-site)
-by running the following command:
+Then, [install pipx](https://pypa.github.io/pipx/installation/) as the root
+user (with `sudo`) to make installing borgmatic easy without impacting other
+Python applications on your system. If you have trouble installing pipx with
+pip, then you can install a system package instead. E.g. on Ubuntu or Debian,
+run:
 
-```bash
-sudo pip3 install --user --upgrade borgmatic
+```
+sudo apt update
+sudo apt install pipx
+sudo pipx ensurepath
 ```
 
-This installs borgmatic and its commands at the `/root/.local/bin` path.
-
-Your pip binary may have a different name than "pip3". Make sure you're using
-Python 3.7+, as borgmatic does not support older versions of Python.
-
-The next step is to ensure that borgmatic's commands available are on your
-system `PATH`, so that you can run borgmatic:
+Finally, install borgmatic with pipx by running the following command:
 
 ```bash
-echo export 'PATH="$PATH:/root/.local/bin"' >> ~/.bashrc
-source ~/.bashrc
+sudo pipx install borgmatic
 ```
 
-This adds `/root/.local/bin` to your non-root user's system `PATH`.
-
-If you're using a command shell other than Bash, you may need to use different
-commands here.
-
-You can check whether all of this worked with:
+Check whether all of this worked with:
 
 ```bash
 sudo borgmatic --version
@@ -51,30 +38,11 @@ sudo borgmatic --version
 
 If borgmatic is properly installed, that should output your borgmatic version.
 
-As an alternative to adding the path to `~/.bashrc` file, if you're using sudo
-to run borgmatic, you can configure [sudo's
-`secure_path` option](https://man.archlinux.org/man/sudoers.5) to include
-borgmatic's path.
-
-
-### Global install option
-
-If you try the user site installation above and have problems making borgmatic
-commands runnable on your system `PATH`, an alternate approach is to install
-borgmatic globally.
-
-The following uninstalls borgmatic and then reinstalls it such that borgmatic
-commands are on the default system `PATH`:
-
-```bash
-sudo pip3 uninstall borgmatic
-sudo pip3 install --upgrade borgmatic
-```
-
-The main downside of a global install is that borgmatic is less cleanly
-separated from the rest of your Python software, and there's the theoretical
-possibility of library conflicts. But if you're okay with that, for instance
-on a relatively dedicated system, then a global install can work out fine.
+Many users need to backup system files that require privileged access, so
+these instructions install and run borgmatic as the root user. But if you
+don't need to backup such files, you're welcome to install and run borgmatic
+as a non-root user. To do that, run the `pipx` and `borgmatic` commands
+above without `sudo`.
 
 
 ### Other ways to install

docs/how-to/upgrade.md

@@ -7,26 +7,36 @@ eleventyNavigation:
 ---
 ## Upgrading borgmatic
 
-In general, all you should need to do to upgrade borgmatic is run the
-following:
+In general, all you should need to do to upgrade borgmatic if you've
+[installed it with
+pipx](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation)
+is to run the following:
 
 ```bash
-sudo pip3 install --user --upgrade borgmatic
+sudo pipx upgrade borgmatic
 ```
 
-See below about special cases with old versions of borgmatic. Additionally, if
-you installed borgmatic [without using `pip3 install
---user`](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#other-ways-to-install),
-then your upgrade process may be different.
+(Or without `sudo` if you installed borgmatic as a non-root user.)
+
+If you originally installed borgmatic with `sudo pip3 install --user`, you can
+uninstall it first with `sudo pip3 uninstall borgmatic` and then [install it
+again with
+pipx](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation),
+which should better isolate borgmatic from your other Python applications.
+
+But if you [installed borgmatic without pipx or
+pip3](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#other-ways-to-install),
+then your upgrade method may be different.
+
 
 
 ### Upgrading your configuration
 
-The borgmatic configuration file format is almost always backwards-compatible
-from release to release without any changes, but you may still want to update
-your configuration file when you upgrade to take advantage of new
-configuration options. This is completely optional. If you prefer, you can add
-new configuration options manually.
+The borgmatic configuration file format is usually backwards-compatible from
+release to release without any changes, but you may still want to update your
+configuration file when you upgrade to take advantage of new configuration
+options or avoid old configuration from eventually becoming unsupported. If
+you prefer, you can add new configuration options manually.
 
 If you do want to upgrade your configuration file to include new options, use
 the `borgmatic config generate` action with its optional `--source` flag that
@@ -64,45 +74,10 @@ and, if desired, replace your original configuration file with it.
 
 borgmatic changed its configuration file format in version 1.1.0 from
 INI-style to YAML. This better supports validation and has a more natural way
-to express lists of values. To upgrade your existing configuration, first
-upgrade to the last version of borgmatic to support converting configuration:
-borgmatic 1.7.14.
-
-As of version 1.1.0, borgmatic no longer supports Python 2. If you were
-already running borgmatic with Python 3, then you can upgrade borgmatic
-in-place:
-
-```bash
-sudo pip3 install --user --upgrade borgmatic==1.7.14
-```
-
-But if you were running borgmatic with Python 2, uninstall and reinstall instead:
-
-```bash
-sudo pip uninstall borgmatic
-sudo pip3 install --user borgmatic==1.7.14
-```
-
-The pip binary names for different versions of Python can differ, so the above
-commands may need some tweaking to work on your machine.
-
-
-Once borgmatic is upgraded, run:
-
-```bash
-sudo upgrade-borgmatic-config
-```
-
-That will generate a new YAML configuration file at /etc/borgmatic/config.yaml
-(by default) using the values from both your existing configuration and
-excludes files. The new version of borgmatic will consume the YAML
-configuration file instead of the old one.
-
-Now you can upgrade to a newer version of borgmatic:
-
-```bash
-sudo pip3 install --user borgmatic
-```
+to express lists of values. Modern versions of borgmatic no longer include
+support for upgrading configuration files this old, but feel free to [file a
+ticket](https://torsion.org/borgmatic/#issues) for help with upgrading any old
+INI-style configuration files you may have.
 
 
 ## Upgrading Borg