Run shell commands from a Kotlin script or application with ease.
Turtle simplifies the process of running external commands and processes from your Kotlin (or Java) code. It comes bundled with a selection of built-in functions, such as opening MacOS applications and dealing with Git. Running shell commands easily is particularly useful from within Kotlin scripts, command line applications and Gradle tasks.
Features • Install • Usage • Contributing
Features
▶︎ Run shell commands with minimal boilerplate
Simply specify the comamnd and its arguments to easily run and retrieve output.
▶︎ Call any of the built-in shell commands
Various commands are provided, such as creating a Git commit and opening files.
▶︎ Use the function syntax to run a series of commands
Specify a sequence of commands to run within a function block.
▶︎ Capture error exit code and output
When a command produces an error, the exit code and error output is thrown as an exception.
Install
Turtle is provided as a Gradle/Maven dependency.
- v0.5.0 onwards are available via Maven Central.
- v0.3.0 and v0.4.0 had issues, so please use v0.5.0 or later.
- Earlier releases were available via Bintray/JCenter.
▶︎ Gradle Kotlin DSL
dependencies {
implementation("com.lordcodes.turtle:turtle:0.5.0")
}
▶︎ Gradle Groovy DSL
dependencies {
implementation 'com.lordcodes.turtle:turtle:0.5.0'
}
Usage
To run a single custom command, just call shellRun() and provide the command and arguments.
val output = shellRun("git", listOf("rev-parse", "--abbrev-ref", "HEAD"))
println(output) // Current branch name, e.g. master
The working directory can be provided, to run the command in a particular location. ShellLocation provides easy access to some useful locations, such as the user's home directory.
val turtleProject = ShellLocation.HOME.resolve("projects/turtle")
val output = shellRun("git", listOf("rev-parse", "--abbrev-ref", "HEAD"), turtleProject)
println(output) // Current branch name, e.g. master
To run a series of commands or use the built-in commands, just call shellRun {}.
shellRun {
command("mkdir tortoise")
changeWorkingDirectory("tortoise")
git.commit("Initial commit")
git.addTag("v1.2", "Release v1.2")
files.openApplication("Spotify")
}
The initial working directory can be specified.
val turtleProject = ShellLocation.HOME.resolve("projects/turtle")
shellRun(turtleProject) {
…
}
Built-in commands
▶︎ Git
shellRun {
git.init()
git.status()
git.commit("Commit message")
git.commitAllChanges("Commit message")
git.push("origin", "master")
git.pull()
git.checkout("release")
git.clone("https://github.com/lordcodes/turtle.git")
git.addTag("v1.1", "Release v1.1")
git.pushTag("v1.1")
git.currentBranch()
}
▶︎ Files
shellRun {
files.openFile("script.kts")
files.openApplication("Mail")
files.createSymlink("target", "link")
files.readSymlink("link")
}
▶︎ More
Extra commands can easily be added by either calling command or by extending ShellScript. If you have created a command that you think should be built in, please feel free to open a PR.
Contributing or Help
If you notice any bugs or have a new feature to suggest, please check out the contributing guide. If you want to make changes, please make sure to discuss anything big before putting in the effort of creating the PR.
To reach out, please contact @lordcodes on Twitter.
9 Nov 28, 2022
6 Jun 7, 2022
50 Aug 8, 2022
10 Oct 25, 2022
1.5k Dec 30, 2022
1.4k Jan 9, 2023
479 Dec 25, 2022
64 Dec 29, 2022
28 Oct 17, 2022
1 Jan 9, 2022
2 Jun 26, 2022
1 Jan 28, 2022
98 Dec 15, 2022
14 Nov 5, 2022
19 Sep 8, 2022
1.4k Jan 4, 2023
56 Sep 16, 2022
67 Oct 3, 2022