IO-845 PathUtils.copyDirectory copies or follows symbolic links

[peterdemaeyer]

Defined the behavior of PathUtils.copyDirectory for symbolic links. It depends on the option LinkOption.NOFOLLOW_LINKS. Non-symbolic (hard) links are out of scope, given that the copy behavior for them was already well-defined: they're treated as regular files.
For the sake of conciseness, the following paragraphs use the term "link" for "symbolic link".

Without NOFOLLOW_LINKS option:

• Links are followed, so that there are no links in the target directory.
• Cyclic links result in FileSystemLoopException.
• Broken links are ignored, they are not copied at all.

With NOFOLLOW_LINKS option:

• Links are copied as links, so that there are links in the target directory for every link in the source directory.
• Links that link to a file or directory inside the source directory are copied to relative links inside the target directory, linking to the copied file or directory.
• Links that link to a file or directory outside the source directory are copied to links inside the target directory, linking to the same file or directory as the link in the source directory.
• Cyclic links are preserved, mirrored to cyclic links in the target directory.
• Broken links are ignored, they are not copied at all.

All of this is also explained in the updated JavaDoc.

Thanks for your contribution to Apache Commons! Your help is appreciated!

Before you push a pull request, review this list:

• Read the contribution guidelines for this project.
• Read the ASF Generative Tooling Guidance if you use Artificial Intelligence (AI).
• I used AI to create any part of, or all of, this pull request. Which AI tool was used to create this pull request, and to what extent did it contribute?
• Run a successful build using the default Maven goal with mvn; that's mvn on the command line by itself.
• Write unit tests that match behavioral changes, where the tests fail if the changes to the runtime are not applied. This may not always be possible, but it is a best practice.
• Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
• Each commit in the pull request should have a meaningful subject line and body. Note that a maintainer may squash commits during the merge process.

[garydgregory]

Hello @peterdemaeyer !
I have a comment in the copy visitor, and a small implementation issue about comparing enums.

[garydgregory]

Hello @peterdemaeyer

Thank you for your update. You'll want to run mvn by itself before you push to run all build checks; this runs the default Maven goal as defined in the POM.

[garydgregory]

Hi @peterdemaeyer

Trying to use headers like <h4> in Javadoc is an exercise in frustration. Different versions seems to have different rules. We do use <h2> without errors, for example in org.apache.commons.lang3.function.MethodInvokers's class Javadoc. I don't think you can use an HTML header in a way that'll work across all the versions we support, all LTS versions. I would keep it simple and use <strong> or <em>.

[peterdemaeyer]

Hi, beware that I’m on vacation this week, only phone access ans no GitHub access. Don’t expect an update before Sunday. The reason I used <h4> is because it’s an official/default JavaDoc guideline. I don’t have the reference here, I’ll reply more in detail when I’m back from vacation. Anyway, I have no problem changing it, I just wanted to point out that I didn’t invent it out of thin air. Op vr 13 feb 2026 om 22:21 schreef Gary Gregory ***@***.***>

…

*garydgregory* left a comment (apache/commons-io#827) <#827 (comment)> Hi @peterdemaeyer <https://github.com/peterdemaeyer> Trying to use headers like <h4> in Javadoc is an exercise in frustration. Different versions seems to have different rules. We do use <h2> without errors, for example in org.apache.commons.lang3.function.MethodInvokers's class Javadoc. — Reply to this email directly, view it on GitHub <#827 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAK7WUUYP5XKNBPJZQODPT34LY55ZAVCNFSM6AAAAACUEP6SS6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQOJZGU2DQMZYHA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[garydgregory]

Enjoy your vacation! Gary

…

On Sat, Feb 14, 2026, 16:27 Peter De Maeyer ***@***.***> wrote: *peterdemaeyer* left a comment (apache/commons-io#827) <#827 (comment)> Hi, beware that I’m on vacation this week, only phone access ans no GitHub access. Don’t expect an update before Sunday. The reason I used <h4> is because it’s an official/default JavaDoc guideline. I don’t have the reference here, I’ll reply more in detail when I’m back from vacation. Anyway, I have no problem changing it, I just wanted to point out that I didn’t invent it out of thin air. Op vr 13 feb 2026 om 22:21 schreef Gary Gregory ***@***.***> > *garydgregory* left a comment (apache/commons-io#827) > <#827 (comment)> > > Hi @peterdemaeyer <https://github.com/peterdemaeyer> > > Trying to use headers like <h4> in Javadoc is an exercise in frustration. > Different versions seems to have different rules. We do use <h2> without > errors, for example in org.apache.commons.lang3.function.MethodInvokers's > class Javadoc. > > — > Reply to this email directly, view it on GitHub > <#827 (comment)>, > or unsubscribe > < https://github.com/notifications/unsubscribe-auth/AAK7WUUYP5XKNBPJZQODPT34LY55ZAVCNFSM6AAAAACUEP6SS6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQOJZGU2DQMZYHA> > . > You are receiving this because you were mentioned.Message ID: > ***@***.***> > — Reply to this email directly, view it on GitHub <#827 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAJB6N3YZVP6RCZAKEMJKAD4L6HM7AVCNFSM6AAAAACUEP6SS6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTSMBSGU2TEMJTGY> . You are receiving this because you commented.Message ID: ***@***.***>

[peterdemaeyer]

Hi @peterdemaeyer

Trying to use headers like <h4> in Javadoc is an exercise in frustration. Different versions seems to have different rules. We do use <h2> without errors, for example in org.apache.commons.lang3.function.MethodInvokers's class Javadoc. I don't think you can use an HTML header in a way that'll work across all the versions we support, all LTS versions. I would keep it simple and use \<strong\> or \<em\>.

Okay, I'll change it, but beware that I didn't randomly pick <h4>, I was following this specification that says: "headings in the documentation comments for constructors, methods, fields and other members should start at heading level 4."

Your own example of <h2> for class JavaDoc is also in line with that same specification by the way: "comments for module, package, and type declarations (including nested types) should start at heading level 2".

[peterdemaeyer]

Enjoy your vacation! Gary

Thanks! I noticed you addressed your comment while I was on vacation. Perfect.

[peterdemaeyer]

@garydgregory, I see this hasn't been merged yet. AFAICT all your comments were addressed, but I'm not sure... Do you still expect me to change anything? Or is this good to merge?

[garydgregory]

Hello @peterdemaeyer

I am providing an alternate solution in PR #832

I am concerned that this issue should be generally addressed (see #832).

[garydgregory]

@peterdemaeyer
ping, see my previous comment.

[peterdemaeyer]

@garydgregory, I did see your previous comment, but it wasn't clear you expected me to do something. I was under the impression you were going to address it yourself in the context of another issue. Don't get me wrong, I'd be happy to make changes or contribute to this issue, but please tell me again what it is exactly that you want me to do.

[garydgregory]

Hi @peterdemaeyer
I'm looking for your opinion on the PR I created. Would you be able to test it for your use case? I think it might be a better more general solution.