Deprecated names for CLI options

[joffrey-bion]

At the moment, renaming an option is a bit of a hassle. Unless I miss something, I need to:

1. create an entirely new option with the new name, configured the same way as the old
2. mark the old option as deprecated
3. remove the default value of the old option if it had one, or make it optional if it was required
4. add some property/local variable that gets the value of the old option first and then the new

For example:

internal class RootCommand : SuspendingCliktCommand(name = "amper") {

    // ...

    private val sharedCacheDir by option(
        "--shared-cache-dir",
        help = "Path to the cache directory shared between all Amper projects",
    )
        .path(canBeFile = false)
        .convert { AmperUserCacheRoot(it.toAbsolutePath()) }
        // It's ok to use a non-lazy default here because most of the time we'll use the default value anyway.
        // Detecting this path eagerly allows showing the default value in the help.
        .default(AmperUserCacheRoot.fromCurrentUserResult().unwrap())

    private val sharedCachesRoot by option(
        "--shared-caches-root",
        help = "Path to the cache directory shared between all Amper projects",
    )
        .path(canBeFile = false)
        .convert { AmperUserCacheRoot(it.toAbsolutePath()) }
        .deprecated("Use --shared-cache-dir instead")

    private val debuggingOptions by DebuggingOptions()

    override suspend fun run() {
        val effectiveSharedCacheDir = sharedCachesRoot ?: sharedCacheDir

        // use effectiveSharedCacheDir now
    }
}

It would be great if I could just do:

internal class RootCommand : SuspendingCliktCommand(name = "amper") {

    // ...

    private val sharedCacheDir by option(
        "--shared-cache-dir",
        deprecatedNames = setOf("--shared-caches-root"),
        help = "Path to the cache directory shared between all Amper projects",
    )
        .path(canBeFile = false)
        .convert { AmperUserCacheRoot(it.toAbsolutePath()) }
        // It's ok to use a non-lazy default here because most of the time we'll use the default value anyway.
        // Detecting this path eagerly allows showing the default value in the help.
        .default(AmperUserCacheRoot.fromCurrentUserResult().unwrap())

    override suspend fun run() {
        // use sharedCacheDir normally
    }
}

[ajalt]

That makes sense. The easiest current solution is probably to set the current and deprecated names as the option's names, and mention which ones are deprecated in help.

[joffrey-bion]

That's easier indeed, but then we don't have the deprecation message when users use the deprecated name