From 6e7797a3f0525a8f48af7182157da0d045600ac2 Mon Sep 17 00:00:00 2001 From: oSumAtrIX Date: Wed, 14 Aug 2024 16:06:58 +0400 Subject: [PATCH] feat: Simplify command and option names and descriptions (#338) BREAKING CHANGE: Options have been renamed. --- docs/1_usage.md | 44 +++---- .../cli/command/ListCompatibleVersions.kt | 8 +- .../cli/command/ListPatchesCommand.kt | 12 +- .../app/revanced/cli/command/PatchCommand.kt | 118 +++++++++--------- .../cli/command/utility/InstallCommand.kt | 8 +- .../cli/command/utility/UninstallCommand.kt | 8 +- 6 files changed, 100 insertions(+), 98 deletions(-) diff --git a/docs/1_usage.md b/docs/1_usage.md index 7e51542..1e5b2de 100644 --- a/docs/1_usage.md +++ b/docs/1_usage.md @@ -13,7 +13,7 @@ java -jar revanced-cli.jar -h ## 📃 List patches ```bash -java -jar revanced-cli.jar list-patches --with-packages --with-versions --with-options revanced-patches.rvp +java -jar revanced-cli.jar list-patches --with-packages --with-versions --with-options patches.rvp ``` ## 💉 Patch an app @@ -21,48 +21,48 @@ java -jar revanced-cli.jar list-patches --with-packages --with-versions --with-o To patch an app using the default list of patches, use the `patch` command: ```bash -java -jar revanced-cli.jar patch -b revanced-patches.rvp input.apk +java -jar revanced-cli.jar patch -p patches.rvp input.apk ``` -You can also use multiple patch bundles: +You can also use multiple files containing patches: ```bash -java -jar revanced-cli.jar patch -b revanced-patches.rvp -b another-patches.rvp input.apk +java -jar revanced-cli.jar patch -p patches.rvp -b another-patches.rvp input.apk ``` -To change the default set of used patches, use the option `-i` or `-e` to use or disuse specific patches. -You can use the `list-patches` command to see which patches are used by default. +To change the default set of enabled or disabled patches, use the option `-e` or `-d` to enable or disable specific patches. +You can use the `list-patches` command to see which patches are enabled by default. -To only use specific patches, you can use the option `--exclusive` combined with `-i`. -Remember that the options `-i` and `-e` match the patch's name exactly. Here is an example: +To only enable specific patches, you can use the option `--exclusive` combined with `-e`. +Remember that the options `-e` and `-d` match the patch's name exactly. Here is an example: ```bash -java -jar revanced-cli.jar patch -b revanced-patches.rvp --exclusive -i "Patch name" -i "Another patch name" input.apk +java -jar revanced-cli.jar patch -p patches.rvp --exclusive -e "Patch name" -e "Another patch name" input.apk ``` -You can also use the options `--ii` and `--ie` to use or disuse patches by their index. -This is useful, if two patches happen to have the same name. +You can also use the options `--ei` or `--di` to enable or disable patches by their index. +This is useful, if two patches happen to have the same name, or if typing the names is too cumbersome. To know the indices of patches, use the command `list-patches`: ```bash -java -jar revanced-cli.jar list-patches revanced-patches.rvp +java -jar revanced-cli.jar list-patches patches.rvp ``` -Then you can use the indices to use or disuse patches: +Then you can use the indices to enable or disable patches: ```bash -java -jar revanced-cli.jar patch -b revanced-patches.rvp --ii 123 --ie 456 input.apk +java -jar revanced-cli.jar patch -b patches.rvp --ei 123 --di 456 input.apk ``` -You can combine the option `-i`, `-e`, `--ii`, `--ie` and `--exclusive`. Here is an example: +You can combine the option `-e`, `-d`, `--ei`, `--di` and `--exclusive`. Here is an example: ```bash -java -jar revanced-cli.jar patch -b revanced-patches.rvp --exclusive -i "Patch name" --ii 123 input.apk +java -jar revanced-cli.jar patch -p patches.rvp --exclusive -i "Patch name" --ei 123 input.apk ``` > [!TIP] -> You can use the option `-d` to automatically install the patched app after patching. +> You can use the option `-i` to automatically install the patched app after patching. > Make sure ADB is working: > > ```bash @@ -83,7 +83,7 @@ Patches can have options you can set using the option `-O` alongside the option To know the options of a patch, use the option `--with-options` when listing patches: ```bash -java -jar revanced-cli.jar list-patches --with-options revanced-patches.rvp +java -jar revanced-cli.jar list-patches --with-options patches.rvp ``` Each patch can have multiple options. You can set them using the option `-O`. @@ -91,10 +91,10 @@ For example, to set the options for the patch with the name `Patch name` with the key `key1` and `key2` to `value1` and `value2` respectively, use the following command: ```bash -java -jar revanced-cli.jar patch -b revanced-patches.rvp -i "Patch name" -Okey1=value1 -Okey2=value2 input.apk +java -jar revanced-cli.jar patch -b patches.rvp -e "Patch name" -Okey1=value1 -Okey2=value2 input.apk ``` -If you want to set a value to `null`, you can omit the value: +If you want to set the option value to `null`, you can omit the value: ```bash java -jar revanced-cli.jar patch -b revanced-patches.rvp -i "Patch name" -Okey1 input.apk @@ -102,7 +102,7 @@ java -jar revanced-cli.jar patch -b revanced-patches.rvp -i "Patch name" -Okey1 > [!WARNING] > Option values are usually typed. If you set a value with the wrong type, the patch can fail. -> Option value types can be seen when listing patches with the option `--with-options`. +> The value types can be seen when listing patches with the option `--with-options`. > > Example option values: > @@ -131,7 +131,7 @@ java -jar revanced-cli.jar patch -b revanced-patches.rvp -i "Patch name" -Okey1 > Example command with an escaped integer as a string: > > ```bash -> java -jar revanced-cli.jar -b revanced-patches.rvp -i "Patch name" -OstringKey=\'1\' input.apk +> java -jar revanced-cli.jar -p patches.rvp -e "Patch name" -OstringKey=\'1\' input.apk > ``` ## 📦 Install an app manually diff --git a/src/main/kotlin/app/revanced/cli/command/ListCompatibleVersions.kt b/src/main/kotlin/app/revanced/cli/command/ListCompatibleVersions.kt index ba993c7..a72a0cd 100644 --- a/src/main/kotlin/app/revanced/cli/command/ListCompatibleVersions.kt +++ b/src/main/kotlin/app/revanced/cli/command/ListCompatibleVersions.kt @@ -12,17 +12,17 @@ import java.util.logging.Logger name = "list-versions", description = [ "List the most common compatible versions of apps that are compatible " + - "with the patches in the supplied patch bundles.", + "with the patches in the supplied files containing patches.", ], ) internal class ListCompatibleVersions : Runnable { private val logger = Logger.getLogger(this::class.java.name) @CommandLine.Parameters( - description = ["Paths to patch bundles."], + description = ["One or more paths to files containing patches."], arity = "1..*", ) - private lateinit var patchBundles: Set + private lateinit var patchesFiles: Set @CommandLine.Option( names = ["-f", "--filter-package-names"], @@ -56,7 +56,7 @@ internal class ListCompatibleVersions : Runnable { appendLine(versions.buildVersionsString().prependIndent("\t")) } - val patches = loadPatchesFromJar(patchBundles) + val patches = loadPatchesFromJar(patchesFiles) patches.mostCommonCompatibleVersions( packageNames, diff --git a/src/main/kotlin/app/revanced/cli/command/ListPatchesCommand.kt b/src/main/kotlin/app/revanced/cli/command/ListPatchesCommand.kt index fcdb3a5..8dac2ad 100644 --- a/src/main/kotlin/app/revanced/cli/command/ListPatchesCommand.kt +++ b/src/main/kotlin/app/revanced/cli/command/ListPatchesCommand.kt @@ -11,16 +11,16 @@ import app.revanced.patcher.patch.Option as PatchOption @Command( name = "list-patches", - description = ["List patches from supplied patch bundles."], + description = ["List patches from supplied files containing patches."], ) internal object ListPatchesCommand : Runnable { private val logger = Logger.getLogger(this::class.java.name) @Parameters( - description = ["Paths to patch bundles."], + description = ["One or more paths to files containing patches."], arity = "1..*", ) - private lateinit var patchBundles: Set + private lateinit var patchesFiles: Set @Option( names = ["-d", "--with-descriptions"], @@ -59,7 +59,7 @@ internal object ListPatchesCommand : Runnable { @Option( names = ["-i", "--index"], - description = ["List the index of each patch in relation to the supplied patch bundles."], + description = ["List the index of each patch in relation to the supplied files containing patches."], showDefaultValue = ALWAYS, ) private var withIndex: Boolean = true @@ -111,6 +111,8 @@ internal object ListPatchesCommand : Runnable { if (withDescriptions) append("\nDescription: ${patch.description}") + append("Enabled: ${patch.use}") + if (withOptions && patch.options.isNotEmpty()) { appendLine("\nOptions:") append( @@ -135,7 +137,7 @@ internal object ListPatchesCommand : Runnable { compatiblePackages?.any { (compatiblePackageName, _) -> compatiblePackageName == name } ?: withUniversalPatches - val patches = loadPatchesFromJar(patchBundles).withIndex().toList() + val patches = loadPatchesFromJar(patchesFiles).withIndex().toList() val filtered = packageName?.let { patches.filter { (_, patch) -> patch.filterCompatiblePackages(it) } } ?: patches diff --git a/src/main/kotlin/app/revanced/cli/command/PatchCommand.kt b/src/main/kotlin/app/revanced/cli/command/PatchCommand.kt index 96d8d7c..b441f3a 100644 --- a/src/main/kotlin/app/revanced/cli/command/PatchCommand.kt +++ b/src/main/kotlin/app/revanced/cli/command/PatchCommand.kt @@ -34,23 +34,23 @@ internal object PatchCommand : Runnable { internal class Selection { @ArgGroup(exclusive = false, multiplicity = "1") - internal var include: IncludeSelection? = null + internal var enabled: EnableSelection? = null - internal class IncludeSelection { + internal class EnableSelection { @ArgGroup(multiplicity = "1") - internal lateinit var selector: IncludeSelector + internal lateinit var selector: EnableSelector - internal class IncludeSelector { + internal class EnableSelector { @CommandLine.Option( - names = ["-i", "--include"], - description = ["The name of the patch."], + names = ["-e", "--enable"], + description = ["Name of the patch."], required = true, ) internal var name: String? = null @CommandLine.Option( - names = ["--ii"], - description = ["The index of the patch in the combined list of all supplied patch bundles."], + names = ["--ei"], + description = ["Index of the patch in the combined list of all supplied files containing patches."], required = true, ) internal var index: Int? = null @@ -58,7 +58,7 @@ internal object PatchCommand : Runnable { @CommandLine.Option( names = ["-O", "--options"], - description = ["The option values keyed by the option keys."], + description = ["Option values keyed by option keys."], mapFallbackValue = CommandLine.Option.NULL_VALUE, converter = [OptionKeyConverter::class, OptionValueConverter::class], ) @@ -66,23 +66,23 @@ internal object PatchCommand : Runnable { } @ArgGroup(exclusive = false, multiplicity = "1") - internal var exclude: ExcludeSelection? = null + internal var disable: DisableSelection? = null - internal class ExcludeSelection { + internal class DisableSelection { @ArgGroup(multiplicity = "1") - internal lateinit var selector: ExcludeSelector + internal lateinit var selector: DisableSelector - internal class ExcludeSelector { + internal class DisableSelector { @CommandLine.Option( - names = ["-e", "--exclude"], - description = ["The name of the patch."], + names = ["-d", "--disable"], + description = ["Name of the patch."], required = true, ) internal var name: String? = null @CommandLine.Option( - names = ["--ie"], - description = ["The index of the patch in the combined list of all supplied patch bundles."], + names = ["--di"], + description = ["Index of the patch in the combined list of all supplied files containing patches."], required = true, ) internal var index: Int? = null @@ -92,14 +92,14 @@ internal object PatchCommand : Runnable { @CommandLine.Option( names = ["--exclusive"], - description = ["Only include patches that are explicitly specified to be included."], + description = ["Disable all patches except the ones enabled."], showDefaultValue = ALWAYS, ) private var exclusive = false @CommandLine.Option( names = ["-f", "--force"], - description = ["Bypass compatibility checks for the supplied APK's version."], + description = ["Don't check for compatibility with the supplied APK's version."], showDefaultValue = ALWAYS, ) private var force: Boolean = false @@ -108,7 +108,7 @@ internal object PatchCommand : Runnable { @CommandLine.Option( names = ["-o", "--out"], - description = ["Path to save the patched APK file to. Defaults to the same directory as the supplied APK file."], + description = ["Path to save the patched APK file to. Defaults to the same path as the supplied APK file."], ) @Suppress("unused") private fun setOutputFilePath(outputFilePath: File?) { @@ -116,8 +116,8 @@ internal object PatchCommand : Runnable { } @CommandLine.Option( - names = ["-d", "--device-serial"], - description = ["ADB device serial to install to. If not supplied, the first connected device will be used."], + names = ["-i", "--install"], + description = ["Serial of the ADB device to install to. If not specified, the first connected device will be used."], // Empty string to indicate that the first connected device should be used. fallbackValue = "", arity = "0..1", @@ -126,7 +126,7 @@ internal object PatchCommand : Runnable { @CommandLine.Option( names = ["--mount"], - description = ["Install by mounting the patched APK file."], + description = ["Install the patched APK file by mounting."], showDefaultValue = ALWAYS, ) private var mount: Boolean = false @@ -134,28 +134,28 @@ internal object PatchCommand : Runnable { @CommandLine.Option( names = ["--keystore"], description = [ - "Path to the keystore to sign the patched APK file with. " + + "Path to the keystore file containing a private key and certificate pair to sign the patched APK file with. " + "Defaults to the same directory as the supplied APK file.", ], ) - private var keystoreFilePath: File? = null + private var keyStoreFilePath: File? = null @CommandLine.Option( names = ["--keystore-password"], - description = ["The password of the keystore to sign the patched APK file with. Empty password by default."], + description = ["Password of the keystore. Empty password by default."], ) private var keyStorePassword: String? = null // Empty password by default @CommandLine.Option( names = ["--keystore-entry-alias"], - description = ["The alias of the keystore entry to sign the patched APK file with."], + description = ["Alias of the private key and certificate pair keystore entry."], showDefaultValue = ALWAYS, ) private var keyStoreEntryAlias = "ReVanced Key" @CommandLine.Option( names = ["--keystore-entry-password"], - description = ["The password of the entry from the keystore for the key to sign the patched APK file with."], + description = ["Password of the keystore entry."], ) private var keyStoreEntryPassword = "" // Empty password by default @@ -175,15 +175,15 @@ internal object PatchCommand : Runnable { private var aaptBinaryPath: File? = null @CommandLine.Option( - names = ["-p", "--purge"], - description = ["Purge the temporary resource cache directory after patching."], + names = ["--purge"], + description = ["Purge temporary files directory after patching."], showDefaultValue = ALWAYS, ) private var purge: Boolean = false @CommandLine.Parameters( - description = ["APK file to be patched."], - arity = "1..1", + description = ["APK file to patch."], + arity = "1", ) @Suppress("unused") private fun setApk(apk: File) { @@ -199,19 +199,19 @@ internal object PatchCommand : Runnable { private lateinit var apk: File @CommandLine.Option( - names = ["-b", "--patch-bundle"], - description = ["One or more bundles of patches."], + names = ["-p", "--patches"], + description = ["One or more path to files containing patches."], required = true, ) @Suppress("unused") - private fun setPatchBundles(patchBundles: Set) { - patchBundles.firstOrNull { !it.exists() }?.let { - throw CommandLine.ParameterException(spec.commandLine(), "Patch bundle ${it.name} does not exist") + private fun setPatchesFile(patchesFiles: Set) { + patchesFiles.firstOrNull { !it.exists() }?.let { + throw CommandLine.ParameterException(spec.commandLine(), "${it.name} can't be found") } - this.patchBundles = patchBundles + this.patchesFiles = patchesFiles } - private var patchBundles = emptySet() + private var patchesFiles = emptySet() @CommandLine.Option( names = ["--custom-aapt2-binary"], @@ -242,7 +242,7 @@ internal object PatchCommand : Runnable { ) val keystoreFilePath = - keystoreFilePath ?: outputFilePath.parentFile + keyStoreFilePath ?: outputFilePath.parentFile .resolve("${outputFilePath.nameWithoutExtension}.keystore") // endregion @@ -251,7 +251,7 @@ internal object PatchCommand : Runnable { logger.info("Loading patches") - val patches = loadPatchesFromJar(patchBundles) + val patches = loadPatchesFromJar(patchesFiles) // endregion @@ -274,11 +274,11 @@ internal object PatchCommand : Runnable { logger.info("Setting patch options") val patchesList = patches.toList() - selection.filter { it.include != null }.associate { - val includeSelection = it.include!! + selection.filter { it.enabled != null }.associate { + val enabledSelection = it.enabled!! - (includeSelection.selector.name ?: patchesList[includeSelection.selector.index!!].name!!) to - includeSelection.options + (enabledSelection.selector.name ?: patchesList[enabledSelection.selector.index!!].name!!) to + enabledSelection.options }.let(filteredPatches::setOptions) patcher += filteredPatches @@ -365,21 +365,21 @@ internal object PatchCommand : Runnable { packageName: String, packageVersion: String, ): Set> = buildSet { - val includedPatchesByName = - selection.asSequence().mapNotNull { it.include?.selector?.name }.toSet() - val includedPatchesByIndex = - selection.asSequence().mapNotNull { it.include?.selector?.index }.toSet() + val enabledPatchesByName = + selection.asSequence().mapNotNull { it.enabled?.selector?.name }.toSet() + val enabledPatchesByIndex = + selection.asSequence().mapNotNull { it.enabled?.selector?.index }.toSet() - val excludedPatches = - selection.asSequence().mapNotNull { it.exclude?.selector?.name }.toSet() - val excludedPatchesByIndex = - selection.asSequence().mapNotNull { it.exclude?.selector?.index }.toSet() + val disabledPatches = + selection.asSequence().mapNotNull { it.disable?.selector?.name }.toSet() + val disabledPatchesByIndex = + selection.asSequence().mapNotNull { it.disable?.selector?.index }.toSet() this@filterPatchSelection.withIndex().forEach patchLoop@{ (i, patch) -> val patchName = patch.name!! - val isManuallyExcluded = patchName in excludedPatches || i in excludedPatchesByIndex - if (isManuallyExcluded) return@patchLoop logger.info("\"$patchName\" excluded manually") + val isManuallyDisabled = patchName in disabledPatches || i in disabledPatchesByIndex + if (isManuallyDisabled) return@patchLoop logger.info("\"$patchName\" disabled manually") // Make sure the patch is compatible with the supplied APK files package name and version. patch.compatiblePackages?.let { packages -> @@ -409,11 +409,11 @@ internal object PatchCommand : Runnable { return@let } ?: logger.fine("\"$patchName\" has no package constraints") - val isIncluded = !exclusive && patch.use - val isManuallyIncluded = patchName in includedPatchesByName || i in includedPatchesByIndex + val isEnabled = !exclusive && patch.use + val isManuallyEnabled = patchName in enabledPatchesByName || i in enabledPatchesByIndex - if (!(isIncluded || isManuallyIncluded)) { - return@patchLoop logger.info("\"$patchName\" excluded") + if (!(isEnabled || isManuallyEnabled)) { + return@patchLoop logger.info("\"$patchName\" disabled") } add(patch) diff --git a/src/main/kotlin/app/revanced/cli/command/utility/InstallCommand.kt b/src/main/kotlin/app/revanced/cli/command/utility/InstallCommand.kt index 6fbb546..7ecddee 100644 --- a/src/main/kotlin/app/revanced/cli/command/utility/InstallCommand.kt +++ b/src/main/kotlin/app/revanced/cli/command/utility/InstallCommand.kt @@ -10,27 +10,27 @@ import java.util.logging.Logger @Command( name = "install", - description = ["Install an APK file to devices with the supplied ADB device serials"], + description = ["Install an APK file."], ) internal object InstallCommand : Runnable { private val logger = Logger.getLogger(this::class.java.name) @Parameters( - description = ["ADB device serials. If not supplied, the first connected device will be used."], + description = ["Serial of ADB devices. If not supplied, the first connected device will be used."], arity = "0..*", ) private var deviceSerials: Array? = null @Option( names = ["-a", "--apk"], - description = ["APK file to be installed"], + description = ["APK file to be installed."], required = true, ) private lateinit var apk: File @Option( names = ["-m", "--mount"], - description = ["Mount the supplied APK file over the app with the supplied package name"], + description = ["Mount the supplied APK file over the app with the supplied package name."], ) private var packageName: String? = null diff --git a/src/main/kotlin/app/revanced/cli/command/utility/UninstallCommand.kt b/src/main/kotlin/app/revanced/cli/command/utility/UninstallCommand.kt index 6f825c6..3477e8a 100644 --- a/src/main/kotlin/app/revanced/cli/command/utility/UninstallCommand.kt +++ b/src/main/kotlin/app/revanced/cli/command/utility/UninstallCommand.kt @@ -13,27 +13,27 @@ import java.util.logging.Logger @Command( name = "uninstall", - description = ["Uninstall a patched app from the devices with the supplied ADB device serials"], + description = ["Uninstall a patched app."], ) internal object UninstallCommand : Runnable { private val logger = Logger.getLogger(this::class.java.name) @Parameters( - description = ["ADB device serials. If not supplied, the first connected device will be used."], + description = ["Serial of ADB devices. If not supplied, the first connected device will be used."], arity = "0..*", ) private var deviceSerials: Array? = null @Option( names = ["-p", "--package-name"], - description = ["Package name of the app to uninstall"], + description = ["Package name of the app to uninstall."], required = true, ) private lateinit var packageName: String @Option( names = ["-u", "--unmount"], - description = ["Uninstall by unmounting the patched APK file"], + description = ["Uninstall the patched APK file by unmounting."], showDefaultValue = ALWAYS, ) private var unmount: Boolean = false