revernomad17/arma-modlist-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README and VI guide for orphan cleanup and test count

Browse Source 
- Add quick-reference card at top of README (short-form cheat sheet)
- Document clean_orphans.py in ToC, Individual Scripts, folder structure
- Update GUI Tools view table: note Clean Orphans tab
- Fix Running Tests: 96 → 142, remove stale '1 failing test' note, list all 15 groups
- Add clean_orphans.py to folder structure tree
- Add cleaner.py to arma_modlist_tools/ listing
- VI guide: add summary table for Tools tabs, document Clean Orphans tab in full
- VI guide: add 'Mod thừa / Orphan' to glossary
This commit is contained in:
Tran G. (Revernomad) Khoa
2026-04-08 20:11:41 +07:00
parent 5c824280c6
commit e0c2dfb32a
2 changed files with 110 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
README.md
View File

@@ -4,6 +4,31 @@ Python toolchain for managing Arma 3 mod presets: parse launcher exports, compar
---
## Quick Reference
```bash
# First time setup
cp config.template.json config.json # fill in server URL + credentials + arma_dir
python check_deps.py # verify dependencies
# Day-to-day: full pipeline
python run.py # parse → compare → download → link
# GUI (recommended)
python gui.py
# Maintenance
python clean_orphans.py --dry-run # find stale mod folders from old presets
python update_mods.py # re-download changed files (size-check)
python sync_missing.py # retry mods that were absent from server
python check_names.py --fix # fix folder name mismatches
# Testing
python test_suite.py # 142 tests (network tests auto-skip if offline)
```
---
## Table of Contents
1. [Prerequisites](#prerequisites)
@@ -20,6 +45,7 @@ Python toolchain for managing Arma 3 mod presets: parse launcher exports, compar
- [sync_missing.py](#sync_missingpy)
- [update_mods.py](#update_modspy)
- [check_names.py](#check_namespy)
- [clean_orphans.py](#clean_orphanspy)
- [run.py](#runpy)
- [gui.py](#guipy)
6. [Migrating Existing Mods](#migrating-existing-mods)
@@ -468,6 +494,36 @@ python check_names.py --fix --fix-ids
---
### clean_orphans.py
Find and optionally delete orphaned mod folders — `downloads/{group}/@ModName` folders that are no longer referenced in `comparison.json`. These accumulate when you switch presets and re-run the pipeline without cleaning up old downloads.
```bash
python clean_orphans.py # list orphans, prompt for confirmation
python clean_orphans.py --dry-run # list orphans, do not delete
python clean_orphans.py --yes # list and delete without prompting
```
```
Group Folder Size
---------------------------- -------------------------------- ----------
shared @OldMod 124.5 MB
150th_WW2_2026_V1.0 @SomeMod 88.2 MB
2 orphan(s) found — 212.7 MB total
Delete all orphans? [y/N]
```
- Matches by normalized name (same logic as the fetcher), so spacing/capitalization differences are handled correctly
- Junction-safe: uses `os.rmdir()` on junctions rather than `shutil.rmtree` to avoid deleting target files
**Requires:** `modlist_json/comparison.json` (run `run.py --skip-fetch --skip-link` first).
The same functionality is available as the **Clean Orphans** tab in the GUI.
---
### run.py
Orchestrator that chains all four pipeline steps. Described in [Quick Start](#quick-start--full-pipeline) above.
@@ -488,10 +544,12 @@ Opens a CustomTkinter desktop window with a sidebar navigation and the following
|------|---------|
| Dashboard | Overview: status, quick stats, recent activity |
| Mods | Browse and manage downloaded mods by group |
| Tools | Link/unlink, rename, sync missing, check server |
| Tools | Link/unlink, rename, sync missing, check server, **clean orphans** |
| Logs | Real-time log output from pipeline operations |
| Settings | Edit `config.json` (server URL, paths, credentials) |
The **Tools** view has five tabs: Check Names, Update Mods, Link Mods, Sync Missing / Report Missing, and **Clean Orphans** (find and delete stale mod folders from old presets).
On first launch (no `config.json`), a setup wizard walks you through creating one.
**Requires:** `customtkinter` (`pip install customtkinter`).
@@ -543,6 +601,7 @@ arma-modlist-tools/
| |- fetcher.py # Caddy server downloader
| |- linker.py # Junction/symlink manager
| |- reporter.py # Missing-mod report builder
| |- cleaner.py # Orphan folder detection
| |- config.py # config.json loader
| |- compat.py # OS detection + encoding fix
|
@@ -591,8 +650,9 @@ arma-modlist-tools/
|- sync_missing.py # Sync newly available missing mods
|- update_mods.py # Re-download updated mod files
|- check_names.py # Diagnose and fix folder name / steam_id issues
|- clean_orphans.py # Find and delete orphaned mod folders
|- check_deps.py # Dependency checker
|- test_suite.py # Test suite
|- test_suite.py # Test suite (142 tests)
```
---
@@ -631,7 +691,7 @@ arma-modlist-tools/
## Running Tests
The test suite covers all modules with 96 tests. No network connection required.
The test suite covers all modules with 142 tests. Network tests (section 15) auto-skip when the server is unreachable.
```bash
python test_suite.py
@@ -639,19 +699,21 @@ python test_suite.py
```
------------------------------------------------------------
compat 6 tests
config 5 tests
parser 9 tests
compare 8 tests
fetcher 19 tests (pure functions, no network)
reporter 8 tests
linker 12 tests (uses temp dirs)
__init__ 2 tests
check_names 16 tests
integration 2 tests
gui._io 11 tests (QueueWriter, no GUI required)
compat 11 tests
config 5 tests
parser 9 tests
compare 8 tests
fetcher 24 tests (pure functions + mock)
reporter 8 tests
linker 12 tests (uses temp dirs)
__init__ 2 tests
check_names 16 tests
integration 2 tests
gui._io 11 tests (QueueWriter, no GUI required)
cleaner 8 tests
e2e — clean_orphans 6 tests (subprocess CLI)
coverage gaps 23 tests (mocked platform branches)
live server 9 tests (skipped if server unreachable)
------------------------------------------------------------
Results: 95 passed, 1 failed, 0 skipped (96 total)
Results: 142 passed, 0 failed, 0 skipped (142 total)
```
> The 1 failing test is a pre-existing comparison snapshot mismatch unrelated to the GUI changes.