You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cassandra.apache.org by "Stefan Miklosovic (Jira)" <ji...@apache.org> on 2026/10/23 08:30:00 UTC

[jira] [Updated] (CASSANDRA-21732) Add usage examples to nodetool help and fix help output regressions after the picocli migration

     [ https://issues.apache.org/jira/browse/CASSANDRA-21732?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Stefan Miklosovic updated CASSANDRA-21732:
------------------------------------------
    Change Category: Operability
         Complexity: Normal
        Component/s: Tool/nodetool
      Fix Version/s: 7.x
          Reviewers: Maxim Muzafarov
             Status: Open  (was: Triage Needed)

> Add usage examples to nodetool help and fix help output regressions after the picocli migration
> -----------------------------------------------------------------------------------------------
>
>                 Key: CASSANDRA-21732
>                 URL: https://issues.apache.org/jira/browse/CASSANDRA-21732
>             Project: Apache Cassandra
>          Issue Type: Improvement
>          Components: Tool/nodetool
>            Reporter: Arvind Kandpal
>            Assignee: Arvind Kandpal
>            Priority: Normal
>             Fix For: 7.x
>
>          Time Spent: 1h 40m
>  Remaining Estimate: 0h
>
> Many nodetool commands take arguments in a format that is not obvious from the help text, such as SSTable file lists, token ranges, compound partition keys, durations, sizes and comma-separated lists. Users often have to read the source code or search online to find the correct syntax.
> For example, the help for compact does not show how to run a user-defined compaction on more than one SSTable:
> nodetool compact --user-defined <file1> <file2>
> This ticket adds an EXAMPLES section to the help of such commands. Because the nodetool docs are generated from the help output (ant gen-nodetool-text), the examples also appear in the docs.
> While working on this, I found that some help output in the default (airline) layout differs from 5.0 since the move to picocli (CASSANDRA-17445). These are fixed as part of this ticket.
> Proposed changes:
>  * Show a subcommand's own footer in the default help layout, and add examples to commands with non-obvious arguments (for example compact, rebuild, getsstables, snapshot, repair, toppartitions and setguardrailsconfig).
>  * Show optional positional arguments in brackets and required options without brackets in SYNOPSIS, as in 5.0.
>  * Show every line of a positional argument's description. This restores the 5.0 usage text of altertopology, setautorepairconfig and help.
>  * Do not break words when the synopsis wraps, and add the missing space before <command> in removenode.
>  * Correct help text that does not match the code: the setautorepairconfig parameter name, the truncatehints usage, and the list of valid auth cache names.
>  * Allow profile start -e to take a comma-separated list, as its help text already describes.
> All changes are limited to help output, except the profile start -e change, which keeps the existing repeated -e form working.



--
This message was sent by Atlassian Jira
(v10.3.26#10030026)

---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cassandra.apache.org
For additional commands, e-mail: commits-help@cassandra.apache.org