Adds a dynamic group mirroring the file system (#10930) #14252

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

Changed or Added files

DirectoryGroup.java
DirectoryGroupTest.java
GroupNodeViewModel.java
GroupDialog.fxml
GroupDialogView.java
GroupDialogViewModel.java
GroupDialogViewModelTest.java
JabRef_en.properties
DirectoryUpdateListener.java
DirectoryUpdateMonitor.java
DummyDirectoryUpdateMonitor.java
DefaultDirectoryUpdateMonitor.java
JabRefGUI.java
GroupTreeViewModel.java
GroupTreeViewModelTest.java
GroupTreeView.java
CHANGELOG.md

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.

Next steps

There is a slight issue with the watcher on Windows : the user can't rename or move a local directory that is mirrored and not empty because it is detected as opened in an application. However, the deletion is working properly so we can bypass this issue.

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)

into fix-issue-10930

jablib/src/main/java/org/jabref/model/util/DummyDirectoryUpdateMonitor.java

InAnYan · 2025-11-13T16:12:31Z

jabgui/src/main/java/org/jabref/gui/JabRefGUI.java

        JabRefGUI.dialogService = new JabRefDialogService(mainStage);
        Injector.setModelOrService(DialogService.class, dialogService);

+        DefaultDirectoryUpdateMonitor directoryUpdateMonitor = new DefaultDirectoryUpdateMonitor(new BibDatabaseContext(), preferences, fileUpdateMonitor, countingUndoManager, stateManager, dialogService, taskExecutor);


I think you can remove the local variable and assign the new object to JabRefGUI.directoryUpdateMonitor, and then just use directoryUpdateMonitor, because you are already in JabRefGUI. This is just so the code looks the same manner as previous code

I tried this first but then I got an error in line 223 : JabRefGUI.directoryUpdateMonitor is not considered as Runnable during the call to HeadlessExecutorService.INSTANCE.executeInterruptableTask().

InAnYan · 2025-11-13T16:14:23Z

jabgui/src/main/java/org/jabref/gui/JabRefGUI.java

        JabRefGUI.dialogService = new JabRefDialogService(mainStage);
        Injector.setModelOrService(DialogService.class, dialogService);

+        DefaultDirectoryUpdateMonitor directoryUpdateMonitor = new DefaultDirectoryUpdateMonitor(new BibDatabaseContext(), preferences, fileUpdateMonitor, countingUndoManager, stateManager, dialogService, taskExecutor);


I'm haven't finished analyzing the code, but maybe you can hint how DefaultDirectoryUpdateMonitor understands to which database put the found entry? I think this will also help other reviewers

Honestly I don't know how it works neither, and it is not supposed to. I tried this because I needed a BibDatabaseContext to call the ImportHandler and add the PDFs in the watcher, but the BibDatabaseContext is not already initialized in JabRefGUI so this one is empty. When I tested the feature the newly created PDF in the mirrored structure seemed to be added to the right database for an unknown reason. I still need to figure out why.

I tested it today and it doesn't work anymore. At least that's the expected behaviour.

I think I fixed this in the commit n°669c37c : now the new entry should always be added to the database of the corresponding group. It also works if the user has multiple opened libraries.

InAnYan · 2025-11-13T16:16:53Z

jabgui/src/main/java/org/jabref/gui/groups/GroupTreeViewModel.java

-                dialogService.notify(Localization.lang("Added group \"%0\".", group.getName()));
+                if (group instanceof DirectoryGroup directoryStructureRoot) {
+                    try {
+                        writeGroupChangesToMetaData();


Maybe you can put writeGroupChangesToMetaData() before the if?

You're right I can delete the second call to writeGroupChangesToMetaData() thanks to that. I'll fix this in the next commit.

InAnYan · 2025-11-13T16:19:04Z

jablib/src/main/java/org/jabref/model/util/DirectoryUpdateListener.java

+
+    void directoryDeleted();
+
+    void PDFDeleted(Path PDFPath);


I'm a bit worried, that this follow pascal-case instead of camel-case

That's right, I'll fix it soon to follow camel-case instead.

InAnYan · 2025-11-13T16:21:40Z

Is this PR work in progress?

into fix-issue-10930

ErwanGou · 2025-11-13T20:29:14Z

Is this PR work in progress?

Not really. The recent commits are minor changes to try fixing the issues raised by the jabref bot, but I don't understand why it is still not working. I also regularly update my branch. Apart from that the feature lacks some improvements as detailled in the 'Next steps' section, but I need your help for those.

into fix-issue-10930

InAnYan · 2025-11-13T21:13:02Z

But why there are TODO comments?

ErwanGou · 2025-11-13T21:56:00Z

But why there are TODO comments?

The issue in its entirety is not resolved by the actual code that I propose so I detailled what is missing in the 'Next steps' section of the PR and to remember it I added some TODO comments that I can delete if you prefer. For now I'm a bit stuck on these missing features so I wanted some feedback about the existing code before continuing.

InAnYan · 2025-11-13T22:00:43Z

Ah, okay, you made this PR not draft, so we could give you feedback. Now I understand

koppor · 2025-11-14T13:31:04Z

CHANGELOG.md

 - We added "IEEE" as another option for parsing plain text citations. [#14233](github.com/JabRef/jabref/pull/14233)
 - We added automatic date-based groups that create year/month/day subgroups from an entry’s date fields. [#10822](https://github.com/JabRef/jabref/issues/10822)
 - We added `doi-to-bibtex` to `JabKit`. [#14244](https://github.com/JabRef/jabref/pull/14244)
+- We added groups that mirror the local structure. [#10930](https://github.com/JabRef/jabref/issues/10930)


Proposal to refinement, because "structure" alone is a very vague term.

Suggested change

- We added groups that mirror the local structure. [#10930](https://github.com/JabRef/jabref/issues/10930)

- We added groups that mirror the local file directory structure. [#10930](https://github.com/JabRef/jabref/issues/10930)

Thank you for your review, I applied the change.

into fix-issue-10930

jabref-machine · 2025-11-14T21:02:55Z

You ticked that you modified CHANGELOG.md, but no new entry was found there.

If you made changes that are visible to the user, please add a brief description along with the issue number to the CHANGELOG.md file. If you did not, please replace the cross ([x]) by a slash ([/]) to indicate that no CHANGELOG.md entry is necessary. More details can be found in our Developer Documentation about the changelog.

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 5 commits November 13, 2025 13:31

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

541724d

into fix-issue-10930

Merge branch 'main' into fix-issue-10930

eb3cf11

Merge branch 'main' into fix-issue-10930

d598f2f

Merge branch 'main' into fix-issue-10930

2045919

Rewrite the CHANGELOG.md (JabRef#10930)

55101bb

InAnYan reviewed Nov 13, 2025

View reviewed changes

jablib/src/main/java/org/jabref/model/util/DummyDirectoryUpdateMonitor.java Show resolved Hide resolved

InAnYan reviewed Nov 13, 2025

View reviewed changes

ErwanGou added 4 commits November 13, 2025 18:09

Improve the JUnit tests (JabRef#10930)

8b7c241

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

f7aea89

into fix-issue-10930

Improve the JUnit tests (JabRef#10930)

2cb5a53

Merge branch 'main' into fix-issue-10930

b1def84

ErwanGou added 2 commits November 13, 2025 22:05

Delete useless call (JabRef#10930)

4e45369

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

99706a4

into fix-issue-10930

Rewrite to fit camel-case (JabRef#10930)

f59085d

Rewrite to fit camel-case (JabRef#10930)

16bd339

koppor reviewed Nov 14, 2025

View reviewed changes

ErwanGou added 5 commits November 14, 2025 15:02

Ensure that new pdfs are added to the right database (JabRef#10930)

669c37c

Refine the CHANGELOG.md (JabRef#10930)

329c308

Merge branch 'main' into fix-issue-10930

9fcbed9

Add pdf import and deletion in the watcher (JabRef#10930)

6efbcf0

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

14fce1d

into fix-issue-10930

	- We added groups that mirror the local structure. [#10930](https://github.com/JabRef/jabref/issues/10930)
	- We added groups that mirror the local file directory structure. [#10930](https://github.com/JabRef/jabref/issues/10930)

Uh oh!

Adds a dynamic group mirroring the file system (#10930) #14252

Are you sure you want to change the base?

Adds a dynamic group mirroring the file system (#10930) #14252

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

InAnYan commented Nov 13, 2025

Uh oh!

ErwanGou commented Nov 13, 2025

Uh oh!

InAnYan commented Nov 13, 2025

Uh oh!

ErwanGou commented Nov 13, 2025

Uh oh!

InAnYan commented Nov 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jabref-machine commented Nov 14, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ErwanGou commented Nov 7, 2025 •

edited

Loading