A shell-script based task runner.

cargo install --force runme

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

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

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

First, run runme --runme-create build test to quickly create boilerplate Runmefile.sh

#!/usr/bin/env bash

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

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

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

To define a new task, simply create the bash function and add the @cmd above it. Task is just function

$ runme -h
USAGE: Runmefile.sh <COMMAND>

COMMANDS:
  build  build project [aliases: b]
  test   test project

$ runme test
Run test
$ runme b
Run build

Runme uses argc to parse Runmefile.

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

runme depends on bash which already built into linux/macos. In windows, runme automatically locates and uses bash that comes with git by default.

Gnu tools like ls, rm, grep, sed, awk... also provided with bash, so you can uses them freely and confidently in the Runmefile.

Use comment tags to define task parameters.

• @arg: define positional argument
• @option: define option argument
• @flag: define flag argument

# @cmd Download a file
# @alias    d
# @flag     -f --force              Override existing file
# @option   -t --tries <NUM>        Set number of retries to NUM
# @arg      source!                 Url to download from
# @arg      target                  Save file to
download() {
    echo "cmd:                      download"
    echo "flag:   --force           $argc_force"
    echo "option: --tries           $argc_tries"
    echo "arg:    source            $argc_source"
    echo "arg:    target            $argc_target"
}

$ runme download -h
Download a file

USAGE: Runmefile.sh download [OPTIONS] <SOURCE> [TARGET]

ARGS:
  <SOURCE>  Url to download from
  [TARGET]  Save file to

OPTIONS:
  -f, --force        Override existing file
  -t, --tries <NUM>  Set number of retries to NUM
  -h, --help         Print help information

$ runme download  -f --tries 3 from.txt to.txt
cmd:                      download
flag:   --force           1
option: --tries           3
arg:    source            from.txt
arg:    target            to.txt

You can also use shell variables to access task parameters.

# @cmd
run() {
  echo $2 $1 $#
}

$ runme run foo bar
bar foo 2

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

$ runme t
Test...

Dependencies are established by function calling.

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

# @cmd
foo() {
  echo foo
}

# @cmd
baz() { 
  echo baz
}

$ runme bar
foo
bar
baz

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

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

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

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
}

# @cmd
foo() {
  echo foo
}

$ runme
foo

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

You can use environment variable RUNME_SHELL to customize shell path.

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

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

Copyright (c) 2022 runme-developers.

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.