Popularity
1.9
Growing
Activity
6.9
-
70
2
1

Description

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 β€’ Installation β€’ Usage

Programming language: Kotlin
License: Apache License 2.0
Tags: Kotlin     Android     Gradle     Library     Shell     Command Line    
Latest version: v0.5.0

Turtle 🐒 alternatives and similar packages

Based on the "Kotlin" category.
Alternatively, view Turtle 🐒 alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of Turtle 🐒 or a related project?

Add another 'Kotlin' Package

README


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.