IndexMergeTool rejects '--' as an unrecognized option because it compares the argument with ==

IndexMergeTool, the misc module's command-line program that merges indexes, has an option parser whose branch for the end-of-options marker -- compares the argument with == instead of equals. The launcher passes each command-line argument as a new String, not the interned literal, so for a command-line -- the branch does not fire: -- falls through to the option switch and the tool stops with "unrecognized option: '--'" and exit code 2 before opening any directory. The branch is also missing index++, so if Java code passes the interned literal "--" to the public main(), -- itself becomes the merged-index path. Both defects date from LUCENE-9206 (commit 93b83f635df, 2020-02-05), first released in 9.0.0, and are still on main. Only this tool is affected (its command line and its main()), no indexing or search API; nothing is lost, and ./-name works around it. The fix is two lines: args[index].equals("--") and index++ before the break.

All lines are in lucene/misc/src/java/org/apache/lucene/misc/IndexMergeTool.java at 645d4fe14a20.

1. Options.parse (:54-94) loops over the arguments and stops at the first one that does not start with - (:58-60); from there on the arguments are the target and the sources (:84-92).
2. Next comes if (args[index] == "--") { break; } (:61-63), with no comment. == compares object identity, and the launcher gives main() a new String for each command-line argument (on OpenJDK 25 a JVM given -- prints args[0] == "--" false and args[0].equals("--") true), so for a command-line -- this is false.
3. -- reaches switch (args[index]) (:64), which knows -merge-policy, -max-segments and -verbose; its default throws IllegalArgumentException("unrecognized option: '--'" + USAGE) (:77-79). main() prints the message and calls System.exit(2) (:99-104), before any directory is opened (:107-113).
4. When the branch does fire (Java code passing the interned literal "--" to main() or to the package-private Options.parse), the break skips the index++ at :81. So mergedIndexPath = args[index] is "--" (:90), and the intended target becomes the first source (:91-92). The target is opened with OpenMode.CREATE (:51).
5. Lucene's build had no Error Prone when this code landed; it came seven months later with LUCENE-9497 (17a3ba723ae, 2020-09-07), with its ReferenceEquality check off, and that check is still off ("ReferenceEquality:OFF", // noisy, build-tools/build-infra/src/main/java/org/apache/lucene/gradle/plugins/java/ErrorPronePlugin.java:738), so the build does not flag it.

Stock jars of 645d4fe14a20, two one-document source indexes src1 and src2:

From Java, IndexMergeTool.main(new String[] {"--", "target", "src1", "src2"}) merges into a new directory ./-- and reads target as a source; when target is not an index this ends in IndexNotFoundException (exit 1).

• Who is hit. Users of the command-line tool who type -- before the paths, and scripts that add it defensively. No query, document or index file reaches this parser.
• Default vs opt-in. It is the tool's only parser; no setting is involved, and assertions make no difference.
• Effect. A clean, immediate refusal with exit code 2 before any directory is opened; a probe found the working tree byte-for-byte unchanged. A target that starts with - cannot be passed with --; ./-name works.
• Wrong output only from Java. The case where -- becomes the target needs Java code that passes the interned literal "--"; the merge then lands in ./-- (an index already there would be replaced, because the target is opened with OpenMode.CREATE), and the named target is only read: an existing index stays byte-identical, and a target that does not exist is left behind as an empty directory holding write.lock.
• Reach. In the Lucene tree only the tool, its test, CHANGES.txt and MIGRATE.md mention it; a code search of Solr, Elasticsearch and OpenSearch (2026-10-26) found no use.

The one assertion covers both defects: on stock main the parse throws "unrecognized option: '--'"; with only the equals change it fails with expected:<[target]> but was:<[--]> (the missing index++); with the full fix it passes.

As the regression test: the same test, for example as a new method in TestIndexMergeTool.

cp TestIndexMergeToolDoubleDash.java $LUCENE/lucene/misc/src/test/org/apache/lucene/misc/
cd $LUCENE && ./gradlew :lucene:misc:test --tests org.apache.lucene.misc.TestIndexMergeToolDoubleDash -Ptests.seed=DEADBEEF
# assertions off: add -Ptests.asserts=false (same result)

# gradle, :lucene:misc:test, seed DEADBEEF, main 645d4fe14a20 (trimmed; the same with -Ptests.asserts=false)
TestIndexMergeToolDoubleDash > testDoubleDashEndsOptions FAILED
    java.lang.IllegalArgumentException: unrecognized option: '--'
    Usage: IndexMergeTool [OPTION...] <mergedIndex> <index1> <index2> [index3] ...
    Merges source indexes 'index1' .. 'indexN' into 'mergedIndex'
    (rest of the usage text)
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:205D5360B125C4B2]:0)
        at org.apache.lucene.misc.IndexMergeTool$Options.parse(IndexMergeTool.java:78)
        at org.apache.lucene.misc.TestIndexMergeToolDoubleDash.testDoubleDashEndsOptions(TestIndexMergeToolDoubleDash.java:26)

# the real command line, stock jars of 645d4fe14a20 (JVM start-up warnings filtered)
$ IndexMergeTool -- -merged src1 src2
unrecognized option: '--'
Usage: IndexMergeTool [OPTION...] <mergedIndex> <index1> <index2> [index3] ...
exit=2
$ IndexMergeTool ./-merged src1 src2
Merging...
Done.
exit=0

• The branch. if (args[index] == "--") { break; } (IndexMergeTool.java:61-63) matches only -- and leaves the option loop; every verifier and the adjudication read it as the end-of-options rule.
• History. LUCENE-9206 (#10246) added the whole parser in 93b83f635df; its discussion covers defaults, merge policy, -max-segments and forbidden-apis and never mentions --, and its patch already had the ==.
• Tests. The upstream TestIndexMergeTool (7 tests) has no -- case. Its tests pass string literals, which are interned, so a test with the literal "--" would have hit the second defect, not the first.
• The rest of the parser compares text. The switch on args[index] (:64) uses equals, as do other Lucene command-line parsers, for example "-level".equals(arg) in CheckIndex (lucene/core/src/java/org/apache/lucene/index/CheckIndex.java:4787).
• Related precedent. #9095 (LUCENE-8047, open since 2017) lists String == comparisons in analysis code, which committers defended because only the same static final constants flow in. That reasoning does not hold for command-line arguments.

The strongest case (the review and the works-as-designed review, two reading-only runs of the same reviewer from another model family, OpenAI GPT-5.6, with different lenses; the intended-behaviour checker): -- is documented nowhere in the repository (USAGE :36-45 lists only -merge-policy, -max-segments and -verbose; the class javadoc :29-32 names no option; lucene/CHANGES.txt:4866-4868 and lucene/MIGRATE.md:1280-1284 name only -max-segments; no upstream test uses --); the tool fails closed with a clear message; ./-name works; no other Lucene command-line tool supports --; and Lucene turned ReferenceEquality off on purpose.

Why it fails: this shows that -- support is undocumented, not that rejecting it was chosen. The author wrote a branch whose only purpose is to recognise --. Turning ReferenceEquality off was a project-wide call about a noisy check (LUCENE-9497, lucene-solr#1816), not a decision about this line. These points limit impact, not validity. The refute-lens review gave a procedural "not real" (it could not run code) while agreeing on both defects and rating the works-as-designed case weak; the works-as-designed review also rated it weak; the devil's advocate found the bug real with high confidence that it is not intended. A later cross-model fact check (2026-11-01) rated the works-as-designed case moderate, mainly because -- is documented nowhere, while agreeing that a branch written only for --, plus the missing index++, points to an unfinished implementation rather than a chosen rejection. Maintainers may well prefer to delete the branch, a legitimate answer that keeps today's behaviour.

Two options, both run through gradle in a scratch worktree of 645d4fe14a20 (removed afterwards); a third, half fix is not enough.

Makes the existing branch do what it was written for, the usual end-of-options rule. args[index] cannot be null here, because the line before already called startsWith on it.

         if (!args[index].startsWith("-")) {
           break;
         }
-        if (args[index] == "--") {
+        if (args[index].equals("--")) {
+          index++;
           break;
         }

Trade-offs

No API change; one new accepted input. Arguments after -- are read as paths, which adds no new filesystem reach, since ./-name already reaches the same directories. It does change the public main() for a Java caller that passes the interned "--": today the merge goes to ./--, with the fix to the next argument. One line in USAGE could mention --.

What the checks validated

Gradle in a scratch worktree of 645d4fe14a20 (2026-11-01): stock, the minimal test fails with assertions on and off; with this fix it passes with assertions on and off, TestIndexMergeTool passes 7 of 7 with it, and the whole :lucene:misc:test passes (24 classes, 317 tests, 0 failures, 9 skipped in other classes). Earlier, the same two source edits (the hunt's diff, which differs only in headers and paths) passed the hunt's 4 tests, the independent reproducer's 5 (including a real command-line run) and the minimal test as a standalone run.

Remove IndexMergeTool.java:61-63, so -- is rejected on purpose, as it is today in practice.

         if (!args[index].startsWith("-")) {
           break;
         }
-        if (args[index] == "--") {
-          break;
-        }
         switch (args[index]) {

Trade-offs

Keeps today's command-line behaviour and removes the wrong-target path for Java callers; since -- was not documented or tested, this is a legitimate, contract-preserving choice maintainers may well prefer, but a target that starts with - still needs ./-name. The minimal test would then be the wrong test: a regression test would assert the rejection instead.

What the checks validated

Gradle in the same scratch worktree: TestIndexMergeTool passes 7 of 7; the minimal test still fails with "unrecognized option: '--'", as expected for this option.

Without index++, a command-line -- would become the target path.

Trade-offs

Worse than today's clean error: the merge would go to ./--. The minimal test fails with expected:<[target]> but was:<[--]>.

Method: non-formal (static analysis, then execution). The hunt unit swept the non-sandbox modules with Error Prone 2.50, with ReferenceEquality enabled (it is off in Lucene's build), and PMD 7.28 (UseEqualsToCompareStrings, CompareObjectsWithEquals); every ReferenceEquality warning was read at the code. The unit was chosen by method, not with this bug in mind. A JUnit on the stock jars that calls Options.parse the way TestIndexMergeTool does then failed on main, 10.5.2 and 9.12.3; an independent reproducer added a run of the real command line in a child JVM, and the test was later cut to the one shown here.