Hello Gerd,
The documentation indeed looks incorrect here. I've filed
https://bugs.openjdk.org/browse/JDK-8390615.
My understanding is that the "jar" tool in the JDK closely follows the
well known "tar" tool and some of the options and their semantics are
motivated from the "tar" tool. It looks like "tar" supports archiving
mulitple files after using "-C" to switch to a directory:
$> tar -czf test.tar.gz -C somedir foo.txt bar.txt
generates a tar file with foo.txt and bar.txt in it:
$> tar -tf test.tar.gz
bar.txt
foo.txt
The jar tool's behaviour here differs from that and it's too late to
change that now. So this will merely be a document update/fix in the
"jar --help" output and the man page.
As for:
> BTW: Filing bug reports via https://bugreport.java.com/bugreport
didn’t work in the last 24 hours.
I see that this mail was sent on 14th August and as far as I know there
wasn't any known outage during those days. I'll let people who manage
that site know internally. If you have specific details about what error
you saw (or still see) then that will help too.
-Jaikiran
On 14/08/26 5:44 pm, Gerd Aschemann wrote:
Hello,
While migrating the Apache Maven JAR plugin (apache/maven-jar-plugin#508
<https://github.com/apache/maven-jar-plugin/pull/508>) to create archives with the
"jar" tool (via ToolProvider) instead of a library, I ran into a documentation
inconsistency around the -C option that I would like to check before reporting it.
The "jar --help" option description reads
-C DIR Change to the specified directory and include the following file
i.e. a single following file, which matches the implementation in
src/jdk.jartool/share/classes/sun/tools/jar/Main.java (it joins the directory to the
single next argument). Two other parts of the documentation, however, suggest that
"-C dir" applies to several following files -- the usage synopsis
jar [OPTION...] [ [--release VERSION] [-C dir] files] ...
(note "files", plural) and the example
-C foo/ classes resources
(two operands after one "-C"). The man page, e.g.
https://docs.oracle.com/en/java/javase/25/docs/specs/man/jar.html, reads the same way.
In practice only the operand immediately after "-C" is resolved relative to
that directory; any further operand is resolved relative to the current working
directory. For example,
mkdir d && touch d/a d/b d/c
jar --create --file x.jar -C d a b c
fails with
b : no such file or directory
c : no such file or directory
(only "a" is archived), because "b" and "c" are looked up in the current directory rather
than in "d".
The forms that work all produce the same archive, with entries a, b and c. One
can repeat the option before each file,
jar --create --file x.jar -C d a -C d b -C d c
add the whole directory,
jar --create --file x.jar -C d .
or write the later operands relative to the current directory,
jar --create --file x.jar -C d a d/b d/c
where "b" and "c" are found as "d/b" and "d/c", and because the "-C" directory "d" is
stripped from every matching entry name the entries are still a, b and c. What does not work is listing several bare file names after a single
"-C dir", which is exactly what the synopsis and the example suggest.
I reproduced this identically on Eclipse Temurin 17, 21 and 25, Azul Zulu 17 and Amazon
Corretto 21, on macOS and Linux; the behaviour and the "--help" wording are the
same everywhere, as expected for the shared jdk.jartool.
The runtime behaviour looks correct and intentional, so this seems to be a documentation issue only. It might be enough to
adjust the synopsis so that each "-C dir" binds to a single following operand, to correct the "-C foo/
classes resources" example (for instance "-C foo/ ."), to align the man page, and perhaps to add a note that
several inputs relative to a directory require repeating "-C dir" per input or using "-C dir .”.
I do not have JBS credentials to file this myself; could someone confirm
whether it is worth a documentation issue and, if so, file it?
BTW: Filing bug reports via https://bugreport.java.com/bugreport didn’t work in
the last 24 hours.
Thanks,
Gerd Aschemann
--
Gerd Aschemann (er/he) --- Veröffentlichen heißt Verändern (Carmen Thomas)
+49/173/3264070 -- [email protected] -- https://aschemann.net
