Skip to content

feat(shell): add HatchZip to Thunar's right-click menu - #118

Merged
xevrion merged 6 commits into
xevrion:mainfrom
ardazeybek:feat/thunar-actions
Nov 21, 2026
Merged

xevrion merged 6 commits into
xevrion:mainfrom
ardazeybek:feat/thunar-actions

Conversation

@ardazeybek

@ardazeybek ardazeybek commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

What this changes

Adds HatchZip to Thunar's right-click menu, the "Thunar custom actions" item in TODO.md. --register-shell now also writes the five actions into $XDG_CONFIG_HOME/Thunar/uca.xml, under a HatchZip submenu, and --unregister-shell takes them out again.

Why

Thunar was the one common Linux file manager left out. It keeps every custom action in a single file the user edits too, which is why it was skipped before, so the change is careful about that file:

  • Only <action> blocks whose unique-id starts with hatchzip- are added or removed. Everything else stays byte for byte.
  • Thunar reads only the first uca.xml it finds. When the user has none yet, the system one from $XDG_CONFIG_DIRS is copied in first, otherwise "Open Terminal Here" would disappear from the menu.
  • A file that isn't an actions file is refused and left alone, and since Thunar goes first, no other menu is written in that case either.
  • Writes go through a temporary file and a rename.
  • A file HatchZip created from nothing is removed with its last action on unregister.

Dirs gets config and system_config for this; Windows and macOS leave them empty.

Verification

On Arch Linux with Thunar 4.20.10 (Hyprland), using register with a stand-in for hatchzip-gui that writes its arguments to a file:

  • Right-clicking My Games/a b.zip shows a HatchZip submenu with all five actions. "Open Terminal Here" is still in the menu.
  • "Extract here (keep archive)" ran the program with --keep-archive, --extract-here and the full path, the spaces intact.
  • Thunar rewrites uca.xml itself when it loads it (tabs, a generated unique-id for its own action). --unregister-shell on that rewritten file removed exactly HatchZip's five actions and left Thunar's.

Not verified: editing the actions through Thunar's "Configure custom actions" dialog, and Thunar versions before 4.18, which have no <submenu> and would show the five actions at the top level.

  • cargo fmt --all --check and cargo clippy --all-targets -- -D warnings pass (clippy for hatchzip-shell)
  • cargo test passes (hatchzip-shell; the change is limited to that crate and a comment in hatchzip-gui)
  • Any change to extraction, the journal or the truncation order was run against the crash tests (none)
  • Any number in the README this changes was re-measured (none)

@ardazeybek
ardazeybek requested a review from xevrion as a code owner November 15, 2026 23:37
@garvrao80

Copy link
Copy Markdown
Contributor

Thanks for adding Thunar support. I tested f2fe402 on Ubuntu 24.04 under WSL with isolated XDG directories. The shell tests passed with and without RAR, and repeated register/unregister preserved ordinary user actions and system defaults. A modeled expansion of the generated command also preserved paths with spaces.

I found four configuration cases worth handling before merge.

  • Registering against a valid config with a trailing XML comment containing </actions> writes inside the comment and leaves invalid XML. For example, <actions></actions><!-- Mentions </actions> here. --> parses before registration and fails afterward.
  • A broken action such as <actions><action><name>Incomplete</name></actions> is accepted and rewritten. Registration reports success and writes the other file-manager menus as well.
  • The valid empty root <actions /> is refused, while <actions/> is accepted.
  • With a pre-existing user file containing the same empty XML as HatchZip's template, register followed by unregister removes the original file. If system defaults exist, that removes the user's empty override and can bring the default actions back.

I verified these through hatchzip-shell and an XML parser. The live Thunar menu was outside this run. Happy to retest a revision.

@ardazeybek

Copy link
Copy Markdown
Contributor Author

Thanks for testing this so carefully, all four were real. Fixed in 73521a6.

The file is now read as XML instead of searched as text: comments, CDATA, processing instructions and the doctype are skipped while looking for the root and its actions, so the </actions> in your comment example no longer counts.

  • A file that isn't a well formed <actions> document is refused before anything is written. Your <actions><action><name>Incomplete</name></actions> example now fails and leaves the other menus alone too.
  • <actions /> is handled the same as <actions/>.
  • Unregister only removes uca.xml if HatchZip created it. Register leaves a small marker in $XDG_CONFIG_HOME/hatchzip/ when it had to create the file, since the content alone can't tell the two cases apart. A user's own empty file stays now.

There's a test for each in thunar_reads_the_file_as_xml_not_text. One small thing I left as it is: with everything on one line (<actions></actions>), unregister leaves a bit of whitespace inside the root rather than restoring it byte for byte. It's still valid and Thunar reformats the file on load anyway.

@garvrao80

Copy link
Copy Markdown
Contributor

Thanks for the update. I retested 73521a6 on Ubuntu 24.04 under WSL with disposable XDG configs. All nine original checks pass now, including the four I reported. The shell tests passed with default features and with RAR, as did formatting and strict shell Clippy.

I found two more ways an existing config or action can be lost:

  • Stale ownership marker. Start with no user uca.xml, register, then remove the generated uca.xml and unregister. The ownership marker remains. If the user then creates an empty override using the same XML as HatchZip's empty template, the next register/unregister cycle deletes that file. I verified that normal cleanup removes the marker and that a generated config with a user-added action keeps that action.
  • Action ownership ignores the actual ID. A valid action with <unique-id>user-preview</unique-id> and a comment mentioning <unique-id>hatchzip-test</unique-id> is removed on registration. Looking at the actual direct unique-id element would let the action survive.

The XML scan still accepts some malformed input. I tried a user action named Preview & open with the ampersand unescaped. The XML parser rejects the source, but registration returns success, rewrites uca.xml, and writes the other menus. This case and the comment case also reproduce on f2fe402.

These results come from the shell registration code. They don't cover the live Thunar menu.

@ardazeybek

Copy link
Copy Markdown
Contributor Author

Thanks for another careful pass. All three reproduced here and are fixed in 359ddce.

  • Stale ownership marker. Unregister now clears the marker even when uca.xml is already gone or holds no HatchZip actions. Register also drops a marker that sits next to a file without HatchZip's actions, since a file HatchZip created would still have them. That covers the case where the user replaces the file without unregistering first.
  • Action ownership. An action counts as HatchZip's only when its direct <unique-id> child starts with hatchzip-. Your user-preview example with the comment survives register and unregister.
  • Unescaped &. Every & in text and tags must now start a reference (&amp;, &#38;, &#x26;), so Preview & open is refused before any menu is written. Escaped names still go through.

Each case has a test in thunar_reads_the_file_as_xml_not_text; the new ones fail on 73521a6. cargo test -p hatchzip-shell passes with default features and with rar, and shell Clippy is clean. I did not try the live Thunar menu.

@xevrion xevrion left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this is careful work: ownership by the direct <unique-id> child, everything else copied byte for byte, and the stale-marker fixes all hold up. Two things before merging:

  1. Unregister leaves behind a uca.xml HatchZip created from the system defaults. When the user has none, thunar_current copies $XDG_CONFIG_DIRS/Thunar/uca.xml and writes the marker, but thunar_unregister only deletes the file when what's left equals THUNAR_EMPTY. A copy of the defaults never does, so it stays and shadows later distro updates to them (the test thunar_keeps_every_action_that_is_not_hatchzips pins that). When the marker exists and what's left equals what the file was created from, remove it; storing a hash of the source in the marker would do.
  2. A Thunar file HatchZip can't edit now blocks every other file manager. Thunar goes first and errors, so a KDE, GNOME or Nemo user with an odd ~/.config/Thunar/uca.xml (non-UTF-8, or anything the parser refuses) gets no menus at all, where on main they would. The GUI switch hits the same path (main_window.rs:684). Please skip Thunar with a "Thunar: skipped, " line and still register the others.

Smaller, here or as a follow-up:

  1. Thunar reads uca.xml once at startup and doesn't watch it, and in an Xfce session it usually runs as a daemon. So the actions don't appear until it restarts, and if the user then edits custom actions in Thunar, it rewrites the file from its stale list and drops ours. The result line should say to restart Thunar (thunar -q).
  2. Thunar matches patterns case-sensitively (g_pattern_match_simple), so *.zip misses GAME.ZIP. Upper-case variants would cover it.
  3. write_atomic has no sync_all before the rename, so a crash on XFS or btrfs can leave an empty uca.xml and lose the user's actions. It also replaces a symlinked uca.xml (stow and other dotfile managers) with a regular file, and drops the original permissions.
  4. Minor:
    • When the copied system file can't be parsed, the error names the user path, which doesn't exist yet.
    • An unreadable system file is skipped silently.
    • entities_ok accepts any named entity, but GMarkup only takes the five predefined ones.
    • is_registered still only checks the KDE file, so existing installs won't get the Thunar actions until the switch is toggled.
    • TODO.md's Thunar lines can be ticked.

@ardazeybek

Copy link
Copy Markdown
Contributor Author

Thanks, went through all of it in 4822547.

  1. Register now puts a hash of the system file it copied into the marker. Unregister removes uca.xml and the marker when what's left still matches that hash, and keeps the file if the user edited the copy. thunar_keeps_every_action_that_is_not_hatchzips now expects the copy to be gone, and there's a second case for an edited copy.
  2. Any Thunar error turns into a Thunar: skipped, <reason> line and the other file managers still register. Non-UTF-8 is treated as "not an actions file". set_menu returns the skipped lines so the GUI switch shows the menus as added plus a warning for Thunar. New test: thunar_skips_what_it_cannot_edit.
  3. The CLI line now ends with "run thunar -q so a running Thunar reads it". I left it out of the GUI notice for now so the string stays translatable, happy to add it there too.
  4. Every pattern has an upper-case twin (*.zip;*.ZIP); *.001 is left alone.
  5. write_atomic calls sync_all before the rename, writes through a symlinked uca.xml so the link stays, keeps the target's permissions and removes the temp file if something fails.
  6. Parse errors name the system file, an unreadable system file is reported, entities_ok only takes the five predefined entities plus numeric refs, is_registered checks Thunar too, and TODO.md is ticked. Unregister also only reads the user's own file now, so a broken system file can't make it fail.

fmt, clippy (CI flags) and the tests pass with and without rar. I haven't tried it against a running Thunar.

@xevrion

xevrion commented Nov 20, 2026

Copy link
Copy Markdown
Owner

Thanks, the six points look right in the code. CI found something on Linux, though, and it's a useful one: the Ubuntu runner has a real ~/.config/Thunar/uca.xml that the parser refuses, so it's a sample of what users' machines have.

  1. The --register-shell path still fails as a whole. crates/gui/tests/cli.rs:43 (register_and_unregister_without_a_window) gets exit 1 with hatchzip-gui: /home/runner/.config/Thunar/uca.xml is not a Thunar actions file HatchZip can edit; it was left as it is.... The GUI switch path turns it into the "Thunar: skipped" note (ui.rs:897 now sees Context menu entries added. Thunar: skipped, ...), but the command line one still returns the error, so the other menus aren't registered there either. Both register and unregister should skip Thunar with that line and carry on.
  2. The tests use the real config folder. Both tests reached the runner's own ~/.config/Thunar. Please point XDG_CONFIG_HOME (and XDG_CONFIG_DIRS) at a temp folder for the GUI tests that register menus, the way the shell crate's tests do, so a test never reads or writes a real user's Thunar file.
  3. Why it was refused. Could you add a step in CI to print that file (e.g. cat ~/.config/Thunar/uca.xml before the tests), or check what the Ubuntu 24.04 image ships? If it's a valid Thunar file (a doctype, a comment before the root, a BOM, or an entity), the parser should accept it rather than skip it, since most Xfce users will have the same one.

@garvrao80

Copy link
Copy Markdown
Contributor

I reproduced both CI failures on 4822547 under Ubuntu 24.04 WSL. The original CLI tests failed at the unregister assertion on line 43 in 11 of 120 runs with two test threads. All 11 left malformed uca.xml, with bytes after </actions>. All 15 serial runs passed. Seeding the GUI test with one of those files reproduced its line 897 failure.

The two CLI tests use separate data directories and share the Thunar config. Both registrations open the same uca.xml.hatchzip-tmp. A direct two-process check reproduced the malformed output, and all 30 pairs using separate config directories passed. Per-test XDG_CONFIG_HOME and XDG_CONFIG_DIRS address the test isolation issue. Unique temporary names would also keep concurrent app invocations from sharing the same file.

Ubuntu Noble's packaged uca.xml includes a doctype and passes a clean register/unregister round trip. With broken or non-UTF-8 XML, register already exits 0 with a Thunar skip. Unregister preserves the XML and removes the other file-manager menus, then exits 1.

@garvrao80

Copy link
Copy Markdown
Contributor

I also tested 4822547 in Thunar 4.18.8 on Ubuntu 24.04. The right-click Test action worked for both .zip and .ZIP, including two selected archives in one run.

With no user edits, Thunar assigned a missing ID to Ubuntu’s stock “Open Terminal Here” action and rewrote uca.xml when it loaded the generated copy. Unregister removed all five HatchZip actions and the ownership marker, but the rewritten user copy remained and can hide future updates to the system defaults. In the CLI-only control, unregister removed the generated copy before Thunar had loaded it.

Thunar keeps all custom actions in one uca.xml the user edits too, so only
the action blocks with a hatchzip- unique-id are added or removed. When the
user has no uca.xml yet, the system one is copied in first so "Open Terminal
Here" doesn't disappear, and a file that isn't an actions file is left alone.
The end tag and actions are now found by walking the elements, skipping
comments, CDATA, processing instructions and the doctype. A file that
isn't a well formed <actions> document is refused before any menu is
written, <actions /> is handled like <actions/>, and unregister only
deletes uca.xml when HatchZip created it, so a user's own empty file
stays.
An action is HatchZip's only when its direct <unique-id> child starts with
hatchzip-, so an id mentioned in a comment no longer removes a user action.
Text and tags with an unescaped & are refused, as Thunar's parser would.
Unregister clears the ownership mark even when the file is already gone, and
register drops a mark that sits next to a file without HatchZip's actions.
…real config

- unregister returns the skipped lines like register does, so a Thunar file
  HatchZip can't edit no longer fails --unregister-shell or the switch
- each write_atomic call uses its own temp name, so two registrations at once
  can't interleave into one file
- a generated copy that Thunar has rewritten on load still goes on unregister
  when its actions match the system file's
- GUI tests point XDG_CONFIG_HOME and XDG_CONFIG_DIRS at a temp folder
@ardazeybek

Copy link
Copy Markdown
Contributor Author

Rebased on main (the conflict was the Settings window change in shell_menu_toggled) and went through the open points in 863ceee.

@xevrion

  1. Unregister now skips Thunar the same way register does: unregister returns the skipped lines, --unregister-shell prints them and exits 0, and the switch shows them after "removed" too. The Latin-1 case in thunar_skips_what_it_cannot_edit now checks that the other menus are gone and the file is untouched.
  2. tests/cli.rs and the ui.rs end-to-end test set XDG_CONFIG_HOME and XDG_CONFIG_DIRS to a temp folder, so they never touch a real ~/.config/Thunar.
  3. I didn't add the CI step: @garvrao80 tracked the refusal down to the two CLI tests racing on one uca.xml.hatchzip-tmp, and Noble's own file goes through a clean round trip. So it wasn't a file shape the parser missed. write_atomic now uses a temp name with the pid and a counter, so two HatchZips registering at once can't mix their writes. I ran the CLI tests 30 times in a row with no failures.

@garvrao80, thanks for the live Thunar run. When Thunar rewrites the copy on load, unregister now compares the actions that are left with the system file's (child elements and their text, ignoring unique-id and empty elements Thunar fills in) and removes the copy if they match. A copy the user actually changed is still kept. There's a test for it in thunar_keeps_every_action_that_is_not_hatchzips.

fmt, clippy with -D warnings and the tests pass with and without rar. I haven't tried it in a live Thunar session.

@xevrion

xevrion commented Nov 21, 2026

Copy link
Copy Markdown
Owner

Thanks, this covers everything from my last comment. --register-shell and --unregister-shell now skip Thunar with the "Thunar: skipped" line and still handle the other file managers, and the tests use their own XDG_CONFIG_HOME and XDG_CONFIG_DIRS. The race on the shared temp file explains the bad uca.xml on the runner, and the pid plus counter temp name fixes it. Thanks @garvrao80 for tracking that down and for the live Thunar run. The skip line also shows up in the new Settings window's notice. I've approved the CI runs and will merge once they pass.

One small optional thing: a uca.xml that starts with a UTF-8 BOM is still refused (linux.rs:136, trim() doesn't strip U+FEFF). If GMarkup accepts a BOM, stripping it before parsing is a one-liner, here or in a follow-up.

@ardazeybek

Copy link
Copy Markdown
Contributor Author

GMarkup skips a leading BOM, so parse_uca now allows one before the root and the file keeps it after the edit. Added a register/unregister round trip with a BOM to the Thunar test, in 67d3b69.

@xevrion xevrion left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, great work @ardazeybek and @garvrao80!

@xevrion
xevrion merged commit 7d111cb into xevrion:main Nov 21, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants