Add reference directory support for grouped scan tools

Each included directory now has a "Ref" checkbox in the bottom panel.
When checked, the directory is marked as a reference — files in
reference directories are kept and never selected for deletion.

This matches the Krokiet (Slint) UI's reference path feature.

Changes:
- AppSettings: added reference_paths set, persisted in settings JSON
- BottomPanel: replaced QListWidget with QTreeWidget showing [Ref][Path]
  columns; Ref checkbox toggles reference_paths membership
- Backend: passes -r flag with reference directories for tools that
  support it (duplicates, similar images/videos/music)
- Non-grouped tools (empty files, broken files, etc.) ignore -r

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: EmanueleCannizzaro

czkawka_pyside6/app/backend.py

@@ -187,6 +187,15 @@ def _build_command(self) -> list[str]:
         if s.thread_number > 0:
             cmd.extend(["-T", str(s.thread_number)])
 
+        # Reference directories (only for grouped tools that support -r)
+        if s.reference_paths and self.tab in (
+            ActiveTab.DUPLICATE_FILES, ActiveTab.SIMILAR_IMAGES,
+            ActiveTab.SIMILAR_VIDEOS, ActiveTab.SIMILAR_MUSIC,
+        ):
+            ref_dirs = [p for p in s.reference_paths if p in s.included_paths]
+            if ref_dirs:
+                cmd.extend(["-r", ",".join(ref_dirs)])
+
         # Tool-specific args
         if self.tab == ActiveTab.DUPLICATE_FILES:
             cmd.extend(["-s", ts.dup_check_method.value])

czkawka_pyside6/app/bottom_panel.py

@@ -3,15 +3,21 @@
 from PySide6.QtWidgets import (
     QWidget, QVBoxLayout, QHBoxLayout, QLabel, QListWidget,
     QPushButton, QFileDialog, QTextEdit, QStackedWidget,
-    QSizePolicy
+    QTreeWidget, QTreeWidgetItem, QHeaderView
 )
 from PySide6.QtCore import Signal, Qt
 
 from .models import AppSettings
 
 
 class BottomPanel(QWidget):
-    """Bottom panel showing directories or error messages."""
+    """Bottom panel showing directories or error messages.
+
+    Included directories have a "Ref" checkbox — when checked, that
+    directory is a reference directory: its files are kept as references
+    and never selected for deletion in grouped tools (duplicates, similar
+    images/videos/music).
+    """
     directories_changed = Signal()
 
     def __init__(self, settings: AppSettings, parent=None):
@@ -32,32 +38,41 @@ def _setup_ui(self):
         dir_layout = QHBoxLayout(dir_widget)
         dir_layout.setContentsMargins(0, 0, 0, 0)
 
-        # Included directories
+        # ── Included directories (with Ref checkbox) ──
         inc_widget = QWidget()
         inc_layout = QVBoxLayout(inc_widget)
         inc_layout.setContentsMargins(0, 0, 0, 0)
         inc_layout.addWidget(QLabel("Included Directories:"))
 
-        self._inc_list = QListWidget()
-        self._inc_list.setMaximumHeight(120)
-        for path in self._settings.included_paths:
-            self._inc_list.addItem(path)
-        inc_layout.addWidget(self._inc_list)
+        self._inc_tree = QTreeWidget()
+        self._inc_tree.setMaximumHeight(120)
+        self._inc_tree.setHeaderLabels(["Ref", "Path"])
+        self._inc_tree.setColumnCount(2)
+        header = self._inc_tree.header()
+        header.setSectionResizeMode(0, QHeaderView.ResizeToContents)
+        header.setSectionResizeMode(1, QHeaderView.Stretch)
+        self._inc_tree.setRootIsDecorated(False)
+        self._inc_tree.itemChanged.connect(self._on_ref_toggled)
+
+        self._populate_included()
+        inc_layout.addWidget(self._inc_tree)
 
         inc_btns = QHBoxLayout()
         add_btn = QPushButton("+")
         add_btn.setFixedWidth(30)
+        add_btn.setToolTip("Add included directory")
         add_btn.clicked.connect(self._add_included)
         inc_btns.addWidget(add_btn)
         rem_btn = QPushButton("-")
         rem_btn.setFixedWidth(30)
+        rem_btn.setToolTip("Remove selected directory")
         rem_btn.clicked.connect(self._remove_included)
         inc_btns.addWidget(rem_btn)
         inc_btns.addStretch()
         inc_layout.addLayout(inc_btns)
         dir_layout.addWidget(inc_widget)
 
-        # Excluded directories
+        # ── Excluded directories ──
         exc_widget = QWidget()
         exc_layout = QVBoxLayout(exc_widget)
         exc_layout.setContentsMargins(0, 0, 0, 0)
@@ -72,10 +87,12 @@ def _setup_ui(self):
         exc_btns = QHBoxLayout()
         add_exc = QPushButton("+")
         add_exc.setFixedWidth(30)
+        add_exc.setToolTip("Add excluded directory")
         add_exc.clicked.connect(self._add_excluded)
         exc_btns.addWidget(add_exc)
         rem_exc = QPushButton("-")
         rem_exc.setFixedWidth(30)
+        rem_exc.setToolTip("Remove selected directory")
         rem_exc.clicked.connect(self._remove_excluded)
         exc_btns.addWidget(rem_exc)
         exc_btns.addStretch()
@@ -92,36 +109,57 @@ def _setup_ui(self):
 
         layout.addWidget(self._stack)
 
-    def show_directories(self):
-        self._stack.setCurrentIndex(0)
-        self.setVisible(True)
-
-    def show_text(self):
-        self._stack.setCurrentIndex(1)
-        self.setVisible(True)
-
-    def hide_panel(self):
-        self.setVisible(False)
+    # ── Included directory helpers ────────────────────────────
 
-    def set_text(self, text: str):
-        self._text_area.setPlainText(text)
-
-    def append_text(self, text: str):
-        self._text_area.append(text)
+    def _populate_included(self):
+        """Rebuild the included paths tree from settings."""
+        self._inc_tree.blockSignals(True)
+        self._inc_tree.clear()
+        for path in self._settings.included_paths:
+            item = QTreeWidgetItem()
+            item.setFlags(item.flags() | Qt.ItemIsUserCheckable)
+            is_ref = path in self._settings.reference_paths
+            item.setCheckState(0, Qt.Checked if is_ref else Qt.Unchecked)
+            item.setText(1, path)
+            item.setToolTip(0, "Check to mark as reference directory.\n"
+                               "Files in reference directories are never selected for deletion.")
+            self._inc_tree.addTopLevelItem(item)
+        self._inc_tree.blockSignals(False)
+
+    def _on_ref_toggled(self, item, column):
+        """Handle Ref checkbox toggle."""
+        if column != 0:
+            return
+        path = item.text(1)
+        if item.checkState(0) == Qt.Checked:
+            self._settings.reference_paths.add(path)
+        else:
+            self._settings.reference_paths.discard(path)
+        self.directories_changed.emit()
 
     def _add_included(self):
         path = QFileDialog.getExistingDirectory(self, "Select Directory to Include")
         if path and path not in self._settings.included_paths:
             self._settings.included_paths.append(path)
-            self._inc_list.addItem(path)
+            self._populate_included()
             self.directories_changed.emit()
 
     def _remove_included(self):
-        row = self._inc_list.currentRow()
-        if row >= 0:
-            self._inc_list.takeItem(row)
-            self._settings.included_paths.pop(row)
-            self.directories_changed.emit()
+        items = self._inc_tree.selectedItems()
+        if not items:
+            # Try current item
+            item = self._inc_tree.currentItem()
+            if item:
+                items = [item]
+        for item in items:
+            path = item.text(1)
+            if path in self._settings.included_paths:
+                self._settings.included_paths.remove(path)
+            self._settings.reference_paths.discard(path)
+        self._populate_included()
+        self.directories_changed.emit()
+
+    # ── Excluded directory helpers ────────────────────────────
 
     def _add_excluded(self):
         path = QFileDialog.getExistingDirectory(self, "Select Directory to Exclude")
@@ -137,6 +175,31 @@ def _remove_excluded(self):
             self._settings.excluded_paths.pop(row)
             self.directories_changed.emit()
 
+    # ── Public API ────────────────────────────────────────────
+
+    def show_directories(self):
+        self._stack.setCurrentIndex(0)
+        self.setVisible(True)
+
+    def show_text(self):
+        self._stack.setCurrentIndex(1)
+        self.setVisible(True)
+
+    def hide_panel(self):
+        self.setVisible(False)
+
+    def set_text(self, text: str):
+        self._text_area.setPlainText(text)
+
+    def append_text(self, text: str):
+        self._text_area.append(text)
+
+    def refresh_lists(self):
+        self._populate_included()
+        self._exc_list.clear()
+        for path in self._settings.excluded_paths:
+            self._exc_list.addItem(path)
+
     def dragEnterEvent(self, event):
         if event.mimeData().hasUrls():
             event.acceptProposedAction()
@@ -147,13 +210,5 @@ def dropEvent(self, event):
             if path and os.path.isdir(path):
                 if path not in self._settings.included_paths:
                     self._settings.included_paths.append(path)
-                    self._inc_list.addItem(path)
+                    self._populate_included()
                     self.directories_changed.emit()
-
-    def refresh_lists(self):
-        self._inc_list.clear()
-        for path in self._settings.included_paths:
-            self._inc_list.addItem(path)
-        self._exc_list.clear()
-        for path in self._settings.excluded_paths:
-            self._exc_list.addItem(path)

czkawka_pyside6/app/models.py

@@ -288,6 +288,7 @@ class ToolSettings:
 class AppSettings:
     """Global application settings."""
     included_paths: list = field(default_factory=lambda: [str(Path.home())])
+    reference_paths: set = field(default_factory=set)  # subset of included_paths marked as reference
     excluded_paths: list = field(default_factory=list)
     excluded_items: str = ""
     allowed_extensions: str = ""

czkawka_pyside6/app/state.py

@@ -79,6 +79,7 @@ def save_settings(self):
         config_file = self._config_path / "settings.json"
         data = {
             "included_paths": self.settings.included_paths,
+            "reference_paths": list(self.settings.reference_paths),
             "excluded_paths": self.settings.excluded_paths,
             "excluded_items": self.settings.excluded_items,
             "allowed_extensions": self.settings.allowed_extensions,
@@ -109,6 +110,7 @@ def load_settings(self):
                 data = json.loads(config_file.read_text())
                 s = self.settings
                 s.included_paths = data.get("included_paths", s.included_paths)
+                s.reference_paths = set(data.get("reference_paths", []))
                 s.excluded_paths = data.get("excluded_paths", s.excluded_paths)
                 s.excluded_items = data.get("excluded_items", s.excluded_items)
                 s.allowed_extensions = data.get("allowed_extensions", s.allowed_extensions)