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

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)

ErwanGou · 2025-11-23T18:25:32Z

@InAnYan

In the file GroupNodeViewModel.java we can choose whether it is possible or not to add entries manually in a group of a given type. I didn't allow it for DirectoryGroup because I thought it was supposed to be only automatic but I can easily change that if you think it's more relevant.
I still need to figure out why the error you sent had shown up.
Regarding the import dialog -if you are talking about the dialog that asks if you want to merge entries or not-, well it is not on my purpose : I use an ImportHandler to import the PDFs and it displays that each time a single file is imported. That means if you create a DirectoryGroup from a local directory structure that contains only 1 PDF the dialog will be displayed, but if there are multiple PDFs it won't. While monitoring the file system, the WatchService raise an event for each new file, so even if you paste or move multiple PDFs at the same time the dialog will show up as many times as there are PDFs. I don't know why it was implemented like that but it seems to be the best way to import files.

koppor · 2025-11-23T19:07:23Z

Then, I can't add any entry to the directory group or its subgroups.

Which is OK, isn't it?

Requirement was

Currently: Only inbound mirroring. Use WatchService to watch for changes.

And when I add a file in the directory group via file managers, JabRef really captures it (but... I got the import dialog like 4 times, IDK why)

There should be no popup at all. JabRef should import it using "best guess". We have org.jabref.logic.bibtex.comparator.FieldValuePlausibilityComparator. There could be more. Update See #14396 for the infrastructure.

koppor · 2025-11-23T19:13:37Z

I use an ImportHandler to import the PDFs and it displays that each time a single file is impored.

Can this be modified using #14396?

I currently get

Maybe, this involves "hiearchy" of PDF sources in case there is no comparator. Implement a list and we can re-order during code review.

koppor · 2025-11-23T19:16:58Z

It should not be possible to remove subgroups
It should be possible to sort A-Z and Z-A

koppor · 2025-11-23T19:23:16Z

Error log:

Could not parse entry
java.io.IOException: Error in line 20: Expected { or ( but received B
...
	at org.jabref.jablib/org.jabref.logic.importer.Parser.parseEntries(Parser.java:18)
	at org.jabref.jablib/org.jabref.logic.importer.fileformat.pdf.PdfVerbatimBibtexImporter.importDatabase(PdfVerbatimBibtexImporter.java:34)
	at org.jabref.jablib/

...
org.jabref.logic.importer.fileformat.pdf.PdfMergeMetadataImporter.importDatabase(PdfMergeMetadataImporter.java:175)

at org.jabref.jablib/org.jabref.logic.externalfiles.ExternalFilesContentImporter.importPDFContent(ExternalFilesContentImporter.java:24)

I think, its an issue at PdfVerbatimBibtexImporter -- we should investigate your PDFs in a seperate issue (or private issue tracker)

Maybe, the log level at this point is too high -- the PdfVerbatimBibtexImporter could be simply be called on all PDFs and the exception should just be ignored than being output.

koppor · 2025-11-23T19:29:33Z

@ErwanGou Please do not reference the issue in your commits. Since you push to the branch Julien384760:fix-issue-10930 and you have this PR, it already correlates to the PR.

When mentioning the issue in the commit, all of these appear in the timeline of the issue, which is kind of strange, because all commits together solve the issue, not each single commit:

koppor · 2025-11-23T19:35:37Z

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

I think, the importers need to be checked if they add a file lock.

Can you test if this issue persists if you do a "dummy import" of the PDF files? - Meaning: not calling any importer, but creating a simple BibEntry manually?

        BibEntry entry = new BibEntry()
                .withFiles(List.of(new LinkedFile("", "example.pdf", StandardFileType.PDF.getName())));

koppor · 2025-11-23T20:36:46Z

I think, : should be escaped when writing and unescaped when reading

I did NOT get the exception when closing and opening the library in JabRef. But I got it when closing JabRef and re-opening JabRef again. -- OK, at another branch... -- But we need to be backwards compatible. That means, version 5.15 of JabRef should be able to open the library without any exception.

ErwanGou · 2025-11-24T14:04:06Z

It should not be possible to remove subgroups

It should be possible to sort A-Z and Z-A

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 and sort A-Z/ Z-A. The existing implementation is as follow :

case GROUP_SUBGROUP_REMOVE ->
          group.isEditable() && group.hasSubgroups() && group.canRemove()
               || group.isRoot();
case GROUP_SUBGROUP_SORT,
     GROUP_SUBGROUP_SORT_REVERSE ->
          group.isEditable() && group.hasSubgroups() && group.canAddEntriesIn()
               || group.isRoot();

That means we can remove the subgroups of a group that can be removed and it never checks if the given subgroups are really deletable, so even if only the root is deletable the user will still be allowed to use this feature.
Regarding the sort A-Z/ Z-A there is the same problem : it is recursive but never checks if it is allowed to sort the children --that's why we can currently sort DirectoryGroups using sort A-Z on the All entries node--. Moreover the sorting method never adds entries to the given group so I don't get why it is mandatory to have group.canAddEntriesIn() there. If we remove this test we could sort DirectoryGroups without any problem.

I think, the importers need to be checked if they add a file lock.

Can you test if this issue persists if you do a "dummy import" of the PDF files? - Meaning: not calling any importer, but creating a simple BibEntry manually?

I tried that and it still locks the file directory with a dummy import. I am pretty sure it comes from that line :

directory.register(watcher, StandardWatchEventKinds.ENTRY_CREATE, StandardWatchEventKinds.ENTRY_DELETE);

When a directory is registered the system automatically locks it. I don't know if there is a solution because I've never seen an application able to pass through this issue.

But we need to be backwards compatible. That means, version 5.15 of JabRef should be able to open the library without any exception.

Do you mean 5.15 is supposed to be able to open libraries that contain DirectoryGroups ? Unknown groups throw an error so is it even possible ?
It made me think about one last thing : what is the expected behaviour if the user mirrors its local directories, save the library, closes JabRef, modify its local directories and opens the old library ? Currently it displays the old version of the structure with directories that possibly don't exist anymore --or even worse, a root that was deleted--, which could lead to bugs. Do we recreate the mirrored structure from the root --if it still exists--, even if it could also duplicate the entries depending on how it is done ? Or do we store DirectoryGroups as ExplicitGroups to avoid conflicts and keep the stored library untouched even if that means to stop adapting to local changes ?

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

jabgui/src/main/java/org/jabref/gui/util/DefaultDirectoryUpdateMonitor.java

+    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

jabgui/src/main/java/org/jabref/gui/util/DefaultDirectoryUpdateMonitor.java

+                                 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

jablib/src/main/java/org/jabref/model/groups/DirectoryGroup.java

+
+    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

jablib/src/main/java/org/jabref/model/groups/DirectoryGroup.java

+        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

jablib/src/main/java/org/jabref/model/groups/DirectoryGroup.java

+    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

jablib/src/main/java/org/jabref/model/groups/DirectoryGroup.java

+        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.

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)

koppor mentioned this pull request Nov 23, 2025

Introduce PlausibilityComparatorFactory #14396

Merged

1 task

koppor mentioned this pull request Nov 23, 2025

Refine PR text instructions #14397

Merged

1 task

Merge branch 'main' into fix-issue-10930

55a2347

github-actions bot removed the status: changes-required Pull requests that are not yet complete label Nov 25, 2025

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

Open

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

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

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!

ErwanGou commented Nov 23, 2025

Uh oh!

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

Uh oh!

Uh oh!

koppor commented Nov 23, 2025

Uh oh!

koppor commented Nov 23, 2025

Uh oh!

koppor commented Nov 23, 2025

Uh oh!

koppor commented Nov 23, 2025

Uh oh!

koppor commented Nov 23, 2025

Uh oh!

koppor commented Nov 23, 2025

Uh oh!

ErwanGou commented Nov 24, 2025

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ErwanGou commented Nov 7, 2025 •

edited

Loading

koppor commented Nov 23, 2025 •

edited

Loading