Repository navigation
RFC: Reorganize Lua scripts folders #639
Description
The Lua scripts are currently organized into the following folders
- contrib - user contributed scripts maintained by the submitter (supposedly)
- data - used to contain assets required by the scripts
- examples - example scripts
- lib - libraries with common code used by all scripts and maintained by the darktable team
- official - scripts contributed and maintained by the darktable team
- tools - scripts that make the scripts run and odds and ends - maintained by the darktable team
Lately we've started developing/adding scripts that provide a service such as group_persistence.lua which is designed to add tags to grouped images so that the groups are maintained across database instances and can be reconstructed on import.
The scripts aren't meant to be interacted with, though in some instances they can be through shortcuts.
I propose adding a services folder for these scripts, since that's the purpose of them (providing a service).
Thoughts?
As I started I decided why not fix the whole thing. Below is a tree view of my thinking...
Activity
bigntallmike commentedon Mar 21, 2026
This makes perfect sense to me fwiw. I was having a hard time deciding where to put your recently-used script when testing tbh so this works.
wpferguson commentedon Mar 21, 2026
I just started working on reorganizing the whole thing...
├── broken
│ └── generate_image_txt.lua
├── ChangeLog.md
├── configuration
│ └── color_profile_manager.lua
├── darkroom
│ ├── auto_snapshot.lua
│ ├── harmonic_armature_guide.lua
│ ├── passport_guide_germany.lua
│ └── passport_guide.lua
├── deprecated
│ ├── check_for_updates.lua
│ └── image_path_in_ui.lua
├── examples
│ ├── api_version.lua
│ ├── darkroom_demo.lua
│ ├── gettextExample.lua
│ ├── gui_action.lua
│ ├── hello_world.lua
│ ├── lighttable_demo.lua
│ ├── moduleExample.lua
│ ├── multi_os.lua
│ ├── panels_demo.lua
│ ├── preferenceExamples.lua
│ ├── printExamples.lua
│ ├── running_os.lua
│ └── x-touch.lua
├── external
│ ├── enfuseAdvanced.lua
│ ├── enfuse.lua
│ ├── exportLUT.lua
│ ├── ext_editor.lua
│ ├── gimp.lua
│ ├── hugin.lua
│ ├── OpenInExplorer.lua
│ ├── pdf_slideshow.lua
│ ├── RL_out_sharp.lua
│ ├── slideshowMusic.lua
│ ├── ultrahdr.lua
│ ├── video_ffmpeg.lua
│ └── website_gallery_export.lua
├── image
│ ├── cr2hdr.lua
│ ├── HDRMerge.lua
│ └── image_stack.lua
├── import
│ ├── apply_camera_style.lua
│ ├── fujifilm_dynamic_range.lua
│ ├── fujifilm_ratings.lua
│ ├── import_filter_manager.lua
│ └── import_filters.lua
├── lib
│ ├── dtutils
│ │ ├── debug.lua
│ │ ├── file.lua
│ │ ├── log.lua
│ │ ├── string.lua
│ │ └── system.lua
│ └── dtutils.lua
├── lighttable
│ ├── AutoGrouper.lua
│ ├── autostyle.lua
│ ├── change_group_leader.lua
│ ├── CollectHelper.lua
│ ├── copy_paste_metadata.lua
│ ├── cycle_group_leader.lua
│ ├── hif_group_leader.lua
│ ├── image_time.lua
│ ├── jpg_group_leader.lua
│ ├── rate_group.lua
│ ├── regenerate_thumbnails.lua
│ ├── rename_images.lua
│ ├── save_selection.lua
│ ├── selection_to_pdf.lua
│ ├── select_non_existing.lua
│ ├── select_untagged.lua
│ └── transfer_hierarchy.lua
├── location
│ ├── clear_GPS.lua
│ ├── geoJSON_export.lua
│ ├── geoToolbox.lua
│ ├── gpx_export.lua
│ └── kml_export.lua
├── README.md
├── services
├── tags
│ ├── auto_tag_modified.lua
│ ├── copy_attach_detach_tags.lua
│ ├── delete_long_tags.lua
│ ├── delete_unused_tags.lua
│ ├── face_recognition.lua
│ ├── LabelsToTags.lua
│ ├── photils.lua
│ ├── quicktag.lua
│ └── rename-tags.lua
└── tools
├── dbmaint.lua
├── executable_manager.lua
├── get_libdoc.lua
├── get_lib_manpages.lua
└── script_manager.lua
@TurboGit thoughts?
wpferguson commentedon Mar 21, 2026
@bigntallmike that is where I'm planning on putting it. Great minds think alike 😄
[-]RFC: Add Services Folder[/-][+]RFC: Reorganize Lua scripts folders[/+]masterpiga commentedon Mar 21, 2026
Thanks, @wpferguson!
Since you are revamping stuff, what about going one step further?
Taxonomies inevitably suck. As soon as you formalize one, you find something that does not fit, or that fits more than one category.
Why not just a flat directory structure and tags to filter, instead of directories? It is a much more versatile approach, it does not force you to box stuff into exactly one category and it makes it easier to find stuff. E.g., a script can run both in the
#darkroomand in the#lighttable, deal with#tagsand#ratingsassigned by an#externaltool and be#communitycontributed.deekayhd commentedon Mar 21, 2026
It is a good idea to reorganize the scripts, IMO.
A folder called "broken" seems a little bit odd. Such scripts should either be fixed or become deprecated.
Also, the separation between "external" and "image" is difficult to make (why is ultrahdr in external, but cr2hdr in image?).
wpferguson commentedon Mar 21, 2026
That's my ultimate goal, let the users define their own categories and group it in a way that makes sense to them
I'm not sure about a flat directory structure from a maintenance point of view. I don't know if I want to sort through potentially 100+ files (though I have a directory called develop that probably has that many scripts (149) and it's a PITA).
The broken folder was a reminder to me that a function got removed in master that the script relied on and it needs to be restored.
I could probably add to the metadata block with a "tags" or categories, or whatever section since I read the metadata block when I'm finding all the scripts. So at least for the first round I guess I take a shot at the taxonomy.
Because I didn't correctly remember what ultrahdr did (I thought it exported).
Any suggested taxonomies? I might be too deep in the trees to see the forest.
wpferguson commentedon Mar 21, 2026
Started...
Here's the entry from clear_GPS.lua
script_data.categories = {_("lighttable"), _("location"), _("shortcut")}This script removes GPS information from the selected images. It can do it with a shortcut, but it also adds a button to the
actions on selected imagesmodule.EDIT: added
_("action button")masterpiga commentedon Mar 22, 2026
I meant that the scripts can declare their own tags for retrieval purposes. But then yes, users could also add their own tags, why not.
Then split them by initial, or some other deterministic criteria. My point is that any taxonomy that you can come up will eventually be inadequate to correctly represent all the script. And this makes finding things harder, not easier.
You taxonomy above already has design flaws. It is in part based on where the scripts live, in part of what they do. How do I know which criteria should I use to find the script that I am looking for? The official/contrib taxonomy currently in place is better in this respect, because at least it effectively shatters the data (i.e., either something is community contributed, or it is not).
A single prompt to Gemini or Claude can add tags to all files, create text entries for each script to be used in a fulltext search and refactor the scripts loader to use tags for filtering. Just saying... :)
deekayhd commentedon Mar 22, 2026
I agree with masterpiga's argument about the taxonomy. The categories for such a static assignment in folders should be exclusive, and the organization into the source of the script (like official, community, tools, etc.) is much better, IMO.
For the tags, I had the same idea to put it into the metadata. Then, in the script manager, an additional filter could be added like this:
The check button is only to get an event that triggers the filtering. There is probably a nicer way to implement it.