Deprecated names for CLI options #633
Description
At the moment, renaming an option is a bit of a hassle. Unless I miss something, I need to:
- create an entirely new option with the new name, configured the same way as the old
- mark the old option as deprecated
- remove the default value of the old option if it had one, or make it optional if it was required
- 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
}
}
Activity
ajalt commentedon Jan 16, 2026
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 commentedon Jan 16, 2026
That's easier indeed, but then we don't have the deprecation message when users use the deprecated name