Rename one source file, document package conflicts

- Renamed: package_resolution.sh -> package_conflict_resolution.sh

CHANGELOG

@@ -1,2 +1,4 @@
+0.2.1 2024-07-10: Rename package_resolution.sh, document package conflicts
+0.2.0 2024-07-10: Implement "uninstall/instal all" package resolution strategies
+0.1.1 2024-07-07: Handle missing tori.conf and invalid installation root path
 0.1.0 2024-07-07: Added configuration parsing
-0.1.1 2024-07-07: Handle missing configuration file and invalid installation root

docs/development/check.md

@@ -9,7 +9,7 @@ The second task is accomplished by resorting to the package management functions
 
 Through the parsed `packages` configuration file at the root of the configuration directory (`~/.config/tori/packages` by default), both package lists are sorted and deduplicated before they can be filtered by each other using `grep` inverted matching.
 
-This allows obtaining both differences and displaying them to the user. If no resolution strategy has been configured or passed through the command line interface, several options are displayed:
+This allows obtaining both differences and displaying them to the user. If no conflict resolution strategy has been configured or passed through the command line interface, several options are displayed:
 
 1. Install/uninstall all
 2. Enter packages to install/uninstall 

docs/usage/check.md

@@ -0,0 +1,6 @@
+When you run `tori check`, tori will look into your configuration files and perform two tasks:
+
+- Compare the files inside the `base` directory to the actual matching files on the system
+- Compare the package list in the `packages` file to the manually installed packages
+
+If any divergence is found, it will prompt you on what action to take.

docs/usage/configuration.md

@@ -30,7 +30,9 @@ Configuration values must _not_ contain the character `*`.
 
 tori will read the `packages` file and check if it matches the currently installed packages. If it does not match, it will ask you how to proceed.
 
-If you would prefer not to be asked how to proceed, you can configure a default action to be taken for package mismatch resolution.
+If you would prefer not to be asked how to proceed, you can configure a default action to be taken for package lists conflict resolution.
+
+The application only concerns itself with manually installed packages. Any dependencies pulled automatically should not be added to the removal list. This is done by querying your package manager specifically for a list of manually installed packages.
 
 ## Base files
 

docs/usage/package_conflict_resolution.md

@@ -0,0 +1,24 @@
+When running `tori check`, tori will generate two package lists: one with your installed packages and one from the `packages` file in your configuration directory.
+
+In case it finds differences between the two lists, its default behavior is to ask you what to do. This approach is described in the following section.
+
+You can also configure tori to automatically choose a given strategy in case you would prefer not to answer every time or if you are setting up an automated workflow. For details on this approach, see the section on **Non-Interactive Configuration**.
+
+## Interactive Resolution
+
+If it finds a difference between the two package lists, it will present you with a list of packages and a menu with several conflict resolution strategies.
+
+tori will perform two separate checks that may produce two separate dialogues like the one described above. It checks for packages found in the configuration that are missing from the system and for packages found in the system but missing from the configuration.
+
+If it finds packages in your configuration that are not installed on the system, it will present you with the following choices:
+
+- `Install all`: The exact list of packages just displayed is passed to the package manager's install option. The package manager may ask for additional confirmation.
+
+If it finds packages installed on the system but not listed in your configuration, it will present you with the following choices:
+
+- `Uninstall all`: The exact list of packages just displayed is passed to the package manager's uninstall option. The package manager may ask for additional confirmation.
+- `Cancel`: Do nothing and close the dialog
+
+## Non-Interactive Resolution
+
+Non-Interactive Resolution is not yet implemented.

src/index.sh

@@ -1,6 +1,6 @@
 . "$TORI_ROOT/src/check.sh"
 . "$TORI_ROOT/src/configuration.sh"
 . "$TORI_ROOT/src/package/package_manager.sh"
-. "$TORI_ROOT/src/package/package_resolution.sh"
+. "$TORI_ROOT/src/package/package_conflict_resolution.sh"
 . "$TORI_ROOT/src/utility.sh"
 . "$TORI_ROOT/src/system.sh"

tori

@@ -2,7 +2,7 @@
 
 main() {
   # paths
-  VERSION="0.1.1 2024-07-07"
+  VERSION="0.2.1 2024-07-10"
   TORI_ROOT="$HOME/.local/share/tori"
   CONFIG_ROOT="$HOME/.config/tori"
   TMP_DIR="/tmp/tori"