runme

A task runner using bash.

• runme
  • Install
    • With cargo
    • Binaries on macOS, Linux, Windows
    • GitHub Actions
  • Why use runme?
    • Linux, MacOS, and Windows are supported
    • Task is just function
    • Task accepts flags, options and positional arguments
    • Task can have aliases
    • Task can have pre and post dependencies
    • Task can be semantically grouped
    • The default task
    • Informative tasks listings and beautiful help printings
  • Advanced Topics
    • CLI Usage
    • Completions
    • Customize shell path
    • Customize script name
  • License

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

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, running, 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.

Linux, MacOS, and Windows are supported

runme binaries are available in linux, macos, and windows.

runme depends on bash. Linux/macos has built-in bash. If git is installed on windows, runme will automatically find and use git bash

GNU tools like ls, rm, grep, find, sed, awk... are also available, use them freely and confidently.

Task is just function

Adds a task by putting @cmd above a function.

# @cmd Build project
build() {
  echo Run build
}

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

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

Run runme --runme-crate build test to quickly create a boilerplate Runmefile.sh.

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
cmd() {
  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 foo README.md
flag: 1
opt:  foo
arg:  README.md

@cmd, @flag, option, @arg are comment tags. see argc comment tags for more details.

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

If the main function exists, calling runme without any subcommands will call the function, otherwise print a help message and exit.

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

$ runme
foo
bar

Informative tasks listings and beautiful help printings

See snippets above, runme prints a beautiful help message listing all tasks along with their descriptions and aliases.

You can also use runme <task> -h to print a help message containing the description of task flags, options and positional arguments.

Advanced Topics

CLI Usage

In order to distinguish with task script's flags and options, all runme cli options are prefixed with --runme

runme --help display task script's help information, runme --runme-help display runme cli's help information.

A task management & automation tool using bash - https://github.com/sigoden/runme

USAGE:
    runme --runme-eval SCRIPT [ARGS...]        Parse arguments `eval $(runme --runme-eval "$0" "$@")`
    runme --runme-create [TASKS...]            Create a boilerplate runmefile
    runme --runme-file                         Print runmefile path
    runme --runme-help                         Print help information
    runme --runme-version                      Print version information

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
• runmefile.sh
• RUNMEFILE.sh
• Runmefile
• runmefile
• RUNMEFILE

You can use environment variable RUNME_SCRIPT to custom script name.

RUNME_SCRIPT=taskfile.sh

License

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.