Adds a dynamic group mirroring the file system (#10930) by ErwanGou · Pull Request #14252 · JabRef/jabref

ErwanGou · 2025-11-07T17:59:23Z

Changed or Added files

The class DirectoryGroup.java contains the new type of group. There are some tests in DirectoryGroupTest.java but most of the feature cannot be tested because it needs the WatchService.

The changes in GroupNodeViewModel.java allow directory groups to be edited or removed. The root node of the mirrored structure can be dragged.

The changes in GroupDialog.fxml, GroupDialogView.java and GroupDialogViewModel.java add the button to mirror the user's local structure within JabRef. The GroupDialogViewModelTest.java was updated to fit the new constructor and to test the new feature.

The new version of JabRef_en.properties contains the English text displayed to the user when trying to mirror its local structure.

The files DirectoryUpdateListener.java, DirectoryUpdateMonitor.java, DummyDirectoryUpdateMonitor.java and DefaultDirectoryUpdateMonitor.java implement a watcher for directories. The file JabRefGUI.java is now able to initialize this watcher.

The file GroupTreeViewModel.java can now create a directory structure. It needed new attributes in the constructor so GroupTreeViewModelTest.java has been updated.

The changes in GroupTreeView.java correct a bug : the user could use "Sort subgroups Z-A" on groups that are not sortable.

In the file CHANGELOG.md there is the description of what was changed in the code.

There are many other changes to create a DirectoryGroup from a string representation.

Next steps

There is an issue with the watcher on Windows : the user can't rename, move or delete a local directory that is not empty because it is detected as opened in an application.

I chose not to allow the user to add entries in a directory group because it is supposed to work only automatically, but due to this choice they are not sortable. About this point I think the existing implementation of sortAlphabeticallyRecursive() and sortReverseAlphabeticallyRecursive() in GroupTreeViewModel.java is a bit weird :

It is recursive but never checks if the subgroup is sortable so we can actually sort Directory Groups if we sort the AllEntries node.
Furthermore I didn't get why it is mandatory that group.canAddEntriesIn() should be true because it seems the sorted method never uses that.

Steps to test

Start JabRef and open a library, empty or not :

You can add a new group by clicking on the 'Add group' button. A dialog should show up. Select 'Directory structure' under the 'Collect by' title :

Here you can select the root folder of the structure you want to mirror by clicking on the folder icon button :

Once the root is set it should automatically fill the 'Root path'. It also fills the 'Name' of the group if and only if it was empty and set the hierarchical context to 'Union', which means a group contains the entries of its subgroups -it is not mandatory to use that but it is recommended because it is how local folders work. You can also write or paste the root path instead of selecting the folder but remember that the 'OK' button won't be active until a valid path and a valid name are provided. You can add a description, an icon, a color or even change the hierarchical context if you want :

Then click on the 'OK' button, your local structure should appear :

The entries created with the local PDFs should appear a little while later :

Now feel free to test the feature. You can either add, delete, rename or move PDFs or folders in your local directory structure, you should see the consequences on your library groups. You can also edit those groups with a right-click. Remember that if you remove a group or change its type it won't adapt to your local changes anymore. If you create an entry that has a file within the mirrored structure it should automatically be added to the respective group. The feature also works if you have multiple opened libraries.

Mandatory checks

I own the copyright of the code submitted and I license it under the MIT license
I manually tested my changes in running JabRef (always required)
I added JUnit tests for changes (if applicable)
I added screenshots in the PR description (if change is visible to the user)
I described the change in CHANGELOG.md in a way that is understandable for the average user (if change is visible to the user)
I checked the user documentation: Is the information available and up to date? If not, I created an issue at https://github.com/JabRef/user-documentation/issues or, even better, I submitted a pull request updating file(s) in https://github.com/JabRef/user-documentation/tree/main/en.

…sting group sibling (JabRef#10930)

…#10930)

into fix-issue-10930

)

into fix-issue-10930

…e's root (JabRef#10930)

…group or edit its type (JabRef#10930)

…ory structure (JabRef#10930)

…irectory was suppressed (JabRef#10930)

…x-issue-10930 # Conflicts: # jabgui/src/main/java/org/jabref/gui/groups/GroupDialogView.java # jabgui/src/main/java/org/jabref/gui/groups/GroupDialogViewModel.java # jabgui/src/main/java/org/jabref/gui/groups/GroupNodeViewModel.java # jabgui/src/main/resources/org/jabref/gui/groups/GroupDialog.fxml

github-actions · 2025-11-07T17:59:39Z

Hey @ErwanGou!

Thank you for contributing to JabRef! Your help is truly appreciated ❤️.

We have automatic checks in place, based on which you will soon get automated feedback if any of them are failing. We also use TragBot with custom rules that scans your changes and provides some preliminary comments, before a maintainer takes a look. TragBot is still learning, and may not always be accurate. In the "Files changed" tab, you can go through its comments and just click on "Resolve conversation" if you are sure that it is incorrect, or comment on the conversation if you are doubtful.

Please re-check our contribution guide in case of any other doubts related to our contribution workflow.

…ry Group (JabRef#10930)

koppor · 2025-11-25T20:22:45Z

It should not be possible to remove subgroups
[...]
I can make it so that only the root of the mirrored directory structure can be removed but there would still be a problem with remove subgroups

I don't understand how NOT remove relates to "remove subgroups" issue.

Do you say you want to implement subgroup removal?

ErwanGou · 2025-11-26T01:04:43Z

I don't understand how NOT remove relates to "remove subgroups" issue.

Do you say you want to implement subgroup removal?

Sorry, my explanation wasn't clear.

In fact the subgroup removal is already implemented and it works properly because of the cleanupListenersAccordingToJabRefChanges() method in DefaultDirectoryUpdateMonitor. It stops monitoring local directories which are no longer mirrored in JabRef. I did it because I wanted the user to be able to edit a DirectoryGroup, mostly to change the group's color, icon or description, and I realised that they could also change the group's type --which is allowed even if the group is not removable even though it is basically a deletion--.

However, I agree that it would be better if the mirrored group structure in JabRef were immutable, and it lacks few things :

Remove group must be disabled for a DirectoryGroup, except for the root of the structure --all or nothing--. This point is easy and has already been done but not commited.
Regarding Remove subgroups however --and it's more of an implementation choice than a problem --, it never checks if all the subgroups are really removable, so this feature would still be allowed on the root of the structure. Since the parent group can be deleted it has never been an issue to remove the subgroups and keep the parent, but here it would leave the root of the structure empty. To fix that I can either rewrite the recursive method to delete removable subgroups only, or modify this part of the code :

case GROUP_SUBGROUP_REMOVE ->
          group.isEditable() && group.hasSubgroups() && group.canRemove()
               || group.isRoot();

I could add the test && !(group.getGroupNode().getGroup() instanceof DirectoryGroup) --but it breaks the consistency-- or change group.canRemove() to group.canRemoveSubgroups and add this method --sounds to be the best option to me--. Since it impacts an already existing feature I would like your opinion about that.

Finally there is the issue with the group editor. Maybe we should find a way to allow minor changes only for certain types of group.

koppor

This seems not to work with a library already having files attached. Maybe try with https://github.com/JabRef/jabref-demonstration-libraries/blob/main/chocolate/Chocolate.bib

Absolute paths should not be required. The directory should be resolved .

See https://devdocs.jabref.org/code-howtos/#get-absolute-filename-or-path-for-file-in-file-directory and also the library properties - the button on the right side.

koppor · 2025-11-30T21:09:08Z

+    private void notifyAboutDirectoryCreation(Path newPath) {
+        Path parentPath = newPath.toAbsolutePath().getParent();
+        for (DirectoryUpdateListener listener : listeners.get(parentPath)) {
+            if (listener instanceof DirectoryGroup parentGroup) {


Code like this should not be there, because the UpdateMonitor should be agnostic of the listeners -- the listener should handle this.

Also importFilesInDatabase should go to a listener.

koppor · 2025-11-30T21:10:40Z

+                                 dialogService.notify(Localization.lang("Failed to import %0 PDF.", nbPDFs));
+                             } else {
+                                 dialogService.notify(Localization.lang("Failed to import %0 PDFs.", nbPDFs));


Wrong localizations. See "Pluralizations" at https://devdocs.jabref.org/code-howtos/localization.html#general-hints

I think, you were not aware of https://phrase.com/blog/posts/pluralization/

koppor · 2025-11-30T21:12:39Z

+
+    private final Path absoluteDirectoryPath;
+    private final DirectoryUpdateMonitor directoryUpdateMonitor;
+    private BibDatabaseContext database;


Use context as variable name or the full name.

database is wrong, because a database is "nested" in a databaseContext.

koppor · 2025-11-30T21:14:28Z

+        entry.setFiles(cleanedFiles);
+    }
+
+    private void cleanupFilesOfAllEntries() {


This method is wrong here - it matches entries of the complete library - and not just of some directory.

koppor · 2025-11-30T21:15:53Z

+    private void cleanupFilesOfAnEntry(BibEntry entry) {
+        List<LinkedFile> cleanedFiles = new ArrayList<>();
+        for (LinkedFile file : entry.getFiles()) {
+            if (Files.exists(Path.of(file.getLink()).toAbsolutePath())) {


This might work for DirectoryGroups as imlemented for now - but it won't work if relative paths are used.

koppor · 2025-11-30T21:16:47Z

+        return group;
+    }
+
+    // without DirectoryUpdateMonitor


github-actions · 2025-12-01T00:11:23Z

Your pull request conflicts with the target branch.

Please merge with your code.
For a step-by-step guide to resolve merge conflicts, see https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line.

koppor · 2025-12-01T16:37:44Z

Remove group must be disabled for a DirectoryGroup, except for the root of the structure --all or nothing--. This point is easy and has already been done but not commited.

Maybe, its time for two Group objects: DirectoryGroup (containing the start directory) and SubDirectoryGroup

it never checks if all the subgroups are really removable

With two different group objects, this should be easily solved.

ErwanGou · 2025-12-02T09:43:38Z

Thank you for all your reviews, sadly I'm very busy right now --it is the end of the semester-- so I'll be less active for the next few weeks. I'll be happy to continue working on this project but probably in January. I see that I still have many things to change so I'll convert this PR to draft.

koppor · 2025-12-04T07:43:57Z

I found this in my drafts - maybe

Remove group must be disabled for a DirectoryGroup, except for the root of the structure --all or nothing--.

Yes!

This point is easy and has already been done but not commited.

Nice! Pay attention that I merged main and thus you need to pull before you can push.

Regarding Remove subgroups however --and it's more of an implementation choice than a problem --, it never checks if all the subgroups are really removable,

I don't get this. I just think of directory groups now, because we are focussing on this - and not other groups.

Case 1: Current group is not a directory group
Case 2: Current group is a directory group
Case 3: Current group is a subdirectory group

With these, it can be distinguished

koppor · 2025-12-04T07:50:27Z

Thank you for all your reviews, sadly I'm very busy right now --it is the end of the semester-- so I'll be less active for the next few weeks. I'll be happy to continue working on this project but probably in January.

Would be nice to read!

I see that I still have many things to change so I'll convert this PR to draft.

Thank you.

Note: The issue is a good third issue; Meaning it is harder than the "good first" and "good second" issues; and it is OK to take more time.

koppor · 2025-12-18T21:23:46Z

I think, we all lost context here. Seeing all the merge conflicts and the comments, its time to start from scratch. Therefore, I close this PR. I hope, everyone learned something.

ErwanGou and others added 25 commits November 3, 2025 15:16

Added a watcher for directories (JabRef#10930)

63d6af2

Added a new group type that mirrors local directories (JabRef#10930)

14fecbe

Allowed the creation of directory groups (JabRef#10930)

368de2b

Added the button to create directory groups (JabRef#10930)

621b25f

Directory groups are now editable and removable (JabRef#10930)

07830f0

Merge branch 'JabRef:main' into fix-issue-10930

2545df1

Correcting a bug : now directory groups can't have the name of an exi…

21bb443

…sting group sibling (JabRef#10930)

Modified the watcher structure to consider directory deletion (JabRef…

b3e713a

…#10930)

Merge branch 'fix-issue-10930' of https://github.com/Julien384760/jabref

8aea30f

into fix-issue-10930

Merge branch 'JabRef:main' into fix-issue-10930

9453828

Renamed an attribute for more clarity (JabRef#10930)

94f410d

The root node of the mirrored structure can be dragged now (JabRef#10930

2a610d1

)

Merge branch 'fix-issue-10930' of https://github.com/Julien384760/jabref

eb30f50

into fix-issue-10930

Fixed a bug : "Sort subgroups Z-A" is not always allowed

30d16c8

Cleanup the useless watchers after a directory deletion (JabRef#10930)

fc267c2

Autofill the name only if it is empty after browsing for the structur…

92dc780

…e's root (JabRef#10930)

Improved getNode() method (JabRef#10930)

b616ddf

Renamed an attribute for more clarity (JabRef#10930)

5748690

Now also remove the watcher if the user decide to remove a directory …

befa0b3

…group or edit its type (JabRef#10930)

Fixed a bug : too many directory creation after Ctrl+V a whole direct…

563718b

…ory structure (JabRef#10930)

Fixed a bug : the watcher was deleted before the group when a local d…

b307d2d

…irectory was suppressed (JabRef#10930)

Deleted useless data display (JabRef#10930)

7114844

Resolved issues that appeared while merging branch (JabRef#10930)

6b72829

Add the new feature in the CHANGELOG.md (JabRef#10930)

3e8b521

github-actions Bot added the first contrib label Nov 7, 2025

ErwanGou added 3 commits November 7, 2025 19:47

Rewrite a test properly (JabRef#10930)

582ecd5

Fix test failure (JabRef#10930)

6491f52

Pressing 'Enter' after selecting the root path now create the Directo…

b351345

…ry Group (JabRef#10930)

ErwanGou added 2 commits November 25, 2025 08:28

Merge branch 'main' into fix-issue-10930

2bf4b4a

Resolve issues that appeared while merging

85d4ebc

koppor added the status: waiting-for-feedback The submitter or other users need to provide more information about the issue label Nov 25, 2025

Merge branch 'main' into fix-issue-10930

5c5209f

This was referenced Nov 27, 2025

Enable "mark as read" tsantalis/RefactoringMiner#1016

Closed

Use sticky headers tsantalis/RefactoringMiner#1017

Open

koppor added the status: changes-required Pull requests that are not yet complete label Nov 28, 2025

koppor added 3 commits November 30, 2025 21:19

Merge branch 'main' into fix-issue-10930

669ce95

Fix ordering

3cfae7e

Fix ordering

33bdf52

koppor requested changes Nov 30, 2025

View reviewed changes

Fix method parameters

6e4e450

github-actions Bot added status: changes-required Pull requests that are not yet complete and removed status: changes-required Pull requests that are not yet complete labels Nov 30, 2025

koppor removed the status: waiting-for-feedback The submitter or other users need to provide more information about the issue label Dec 1, 2025

ErwanGou marked this pull request as draft December 2, 2025 09:43

koppor added the 📌 Pinned label Dec 4, 2025

calixtus added component: groups component: ui labels Dec 12, 2025

koppor mentioned this pull request Dec 18, 2025

Change log levels from INFO to DEBUG for AI export #14649

Merged

2 tasks

koppor closed this Dec 18, 2025

NiMv1 mentioned this pull request Dec 20, 2025

Add DirectoryGroup for mirroring file system structure #14668

Closed

6 tasks

Uh oh!

Conversation

ErwanGou commented Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changed or Added files

Next steps

Steps to test

Mandatory checks

Uh oh!

github-actions Bot commented Nov 7, 2025

Hey @ErwanGou!

Uh oh!

koppor commented Nov 25, 2025

Uh oh!

ErwanGou commented Nov 26, 2025

Uh oh!

koppor left a comment

Choose a reason for hiding this comment

Uh oh!

koppor Nov 30, 2025

Choose a reason for hiding this comment

Uh oh!

koppor Nov 30, 2025

Choose a reason for hiding this comment

Uh oh!

koppor Nov 30, 2025

Choose a reason for hiding this comment

Uh oh!

koppor Nov 30, 2025

Choose a reason for hiding this comment

Uh oh!

koppor Nov 30, 2025

Choose a reason for hiding this comment

Uh oh!

koppor Nov 30, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Dec 1, 2025

Uh oh!

koppor commented Dec 1, 2025

Uh oh!

ErwanGou commented Dec 2, 2025

Uh oh!

koppor commented Dec 4, 2025

Uh oh!

koppor commented Dec 4, 2025

Uh oh!

koppor commented Dec 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ErwanGou commented Nov 7, 2025 •

edited

Loading