runme-0.2.0 is not a library.

runme

A cli task runner.

demo

runme

Install

With cargo

cargo install --force runme

Binaries on macOS, Linux, Windows

Download from Github Releases, unzip and add runme to your $PATH.

GitHub Actions

extractions/setup-crate can be used to install just in a GitHub Actions workflow.

- uses: extractions/setup-crate@v1
  with:
    owner: sigoden
    name: runme

Get Started

First, define a simple Runmefile.sh in your project.

#!/usr/bin/env bash

set -e

# @cmd build project
# @alias b
build() {
    echo Run build
}

# @cmd test project
test() {
    echo Run test
}

eval $(runme --runme-eval "$0" "$@")

Then, try running one of your commands!

runme build
runme test

You can also run runme --runme-create build test to quickly create boilerplate Runmefile.sh.

Runme uses argc to parse Runmefile.

@cmd, @alias are comment tags.

Why use runme?

runme provides a cross platform way to define and execute custom commands specific to a codebase.

The less work you have to do when performing repetitive tasks like building, testing, linting, etc, the easier your job becomes. After you've configured it through a Runmefile.sh, a task runner can do most of that mundane work for you—and your team—with basically zero effort.

Cross-platform support for Windows / macOS and Linux

runme binary is available in linux, macos, and windows.

runme depends on bash. Linux/macos has built-in bash. In windows, git is frequently used, runme automatically locates and uses bash that comes with git.

Environments that support bash usually also support GNU tools, so you can use ls, rm, grep, sed, awk... in Runmefile freely and confidently.

Task is just function

To define a new task foo, simply create the foo function and add the @cmd comment tag above it.

# @cmd
task1() {
  echo Run task1
}

Task accepts flags, options and positional arguments

# @cmd     A simple task
# @flag    -f --flag      A flag
# @option  --opt          A option
# @arg     arg            A positional argument
task2() {
  echo "flag: $argc_flag"
  echo "opt:  $argc_opt"
  echo "arg:  $argc_arg"
}

$ runme cmd -h
A simple task

USAGE:
    Runmefile.sh cmd [OPTIONS] [ARG]

ARGS:
    <ARG>    A positional argument

OPTIONS:
    -f, --flag         A flag
    -h, --help         Print help information
        --opt <OPT>    A option

$ runme cmd -f --opt=v1 v2
flag: 1
opt:  v1
arg:  v2

Shell variables are also available.

# @cmd
build() {
  echo '$@:' $@
  echo '$1:' $1
  echo '$2:' $2
  echo '$#:' $#
}

$ runme build foo bar
$@: foo bar
$1: foo
$2: bar
$#: 2

Task can have aliases

# @cmd
# @alias t,tst
test() {
  echo "Test..."
}

$ runme t
Test...

Task can have pre and post dependencies

Tasks can depend on other tasks. Dependencies are established by calling functions.

# @cmd
bar() { foo;
  echo bar
baz; }

# @cmd
foo() {
  echo foo
}

# @cmd
baz() { 
  echo baz
}

$ runme bar
foo
bar
baz

Task can be semantically grouped

Tasks can be grouped with _, -, @, ., :.

# @cmd
test@unit() {}
# @cmd
test@bin() {}

# @cmd
app.build() {}
# @cmd
app.test() {}

The default task

When runme is invoked without a task name, it runs the main function. If the main function does not exist, runme will print help information.

main() { 
  foo
  bar
}

# @cmd
foo() {
  echo foo
}

# @cmd
bar() {
  echo baz
}

$ runme
foo
bar

Informative tasks listings and beautiful help printings

runme --help or runme --h will print a help text listing all tasks along with their descriptions and aliases.

runme <task> --help or runme <task> -h will print a help text containing the description of task's flags, options and positional arguments.

Advanced Topics

Completions

Shell completion scripts are available for bash/zsh/powershell.

Customize shell path

You can use environment variable RUNME_SHELL to customize shell path.

RUNME_SHELL="C:\\Program Files\\Git\\bin\\bash.exe"

Customize script name

By default, runme searches for runme script file of the following:

Runmefile.sh or Runmefile
runmefile.sh or runmefile
RUNMEFILE.sh or RUNMEFILE

You can use environment variable RUNME_SCRIPT to custom script name.

RUNME_SCRIPT=taskfile.sh

License

runme is made available under the terms of either the MIT License or the Apache License 2.0, at your option.

See the LICENSE-APACHE and LICENSE-MIT files for license details.

runme 0.2.0