After going through the documentation, I found it. JabRef can have a directory per database. But what if you and me have different directories? Do we have to agree to one? Normally, it's simply the directory of the .bib file (meaning . is used as database directory). But what if the users somehow share a bibliography and use different directories? Then, this feature comes in. I can set another directory then you do. Both settings are serialized in the bib file. With -<loginname> as suffix in the jabref-meta field. If JabRef saves a file and my loginname matches the name stored in the bib file, it chooses that directory. If no match is found, it uses the "General file directory" of the bib file. If that is not found, it uses the one configured at "Options -> Preferences -> External programs" ("Main file directory").

Here some text from the documentation and mailing lists, but I think, the documentation has to be improved. 🌅

When thinking of it, we should offer the users a button "use current directory" next to "General file directory" and add a little help text that "." denotes that. Or render . as <directory of the bib file is used>. Then, hopefully, the "User-specific file directory" can be dropped. - I don't see any other use case. Why would I share a bib file and not share the PDFs? If I share the PDFs together with the bib file, a relative directory can be put in "General file directory".

Possibly, the "General file directory" should be stored relatively from the current directory of the bib file.

FAQ

http://jabref.sourceforge.net/faq.php: "Then at the field “General file directory” choose the directory specific for the database. If you want to set a directory for you only and other users should use the default directory, use the field “User-specific file directory”"

File help

http://jabref.sourceforge.net/help/FileLinks.php:
"Finally, in the Database properties dialog you can set a user-specific file directory, which will be valid only when you are the one working on the bib file."

Mail from the mailing list

(by @ThomasA)
https://sourceforge.net/p/jabref/mailman/message/27008930/
"As of revision 3449, JabRef supports an
option to specify a user- and host-specific file directory in the
database properties. This allows each user of a particular database to
store her/his personal path setting in the database. It furthermore
allows the same user to specify different paths on different computers
(must have different host names)."

Thanks @koppor for this detailed clarification! I think we might simplify this somehow 😄

We need a better internal datastructure.