Run: Easily manage and invoke small scripts and wrappers

<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --> <!-- ALL-CONTRIBUTORS-BADGE:END -->

Do you find yourself using tools like make to manage non-build-related scripts?

Build tools are great, but they are not optimized for general script management.

Run aims to be better at managing small scripts and wrappers, while incorporating a familiar make-like syntax.

Runfile

Where make has the ubiquitous Makefile, run has the cleverly-named "Runfile"

By default, run will look for a file named "Runfile" in the current directory, exiting with error if not found.

Read below for details on specifying alternative runfiles, as well as other special modes you might find useful.

Commands

In place of make's targets, runfiles contain 'commands'.

Similar to make, a command's label is used to invoke it from the command-line.

Scripts

Instead of recipes, each runfile command contains a 'script' which is executed when the command is invoked.

You might be used to make's (default) behavior of executing each line of a recipe in a separate sub-shell.

In run, the entire script is executed within a single sub-shell.

TOC

• Examples
• Special Modes
• Installing
• Contributing
• Contact
• License
• Just Looking for Bash Arg Parsing?

---

Examples

• Simple Command Definitions
  • Naming Commands
• Simple Title Definitions
• Title & Description
• Arguments
• Command-Line Options
  • Making Options Required
  • Providing A Default Option Value
  • Boolean (Flag) Options
  • Getting -h & --help For Free
  • Passing Options Directly Through to the Command Script
• Run Tool Help
• Using an Alternative Runfile
  • Via Command-Line
  • Via Environment Variables
    • $RUNFILE
      • Using Direnv
    • $RUNFILE_ROOTS
• Runfile Variables
  • Local By Default
  • Exporting Variables
    • Per-Command Variables
    • Exporting Previously-Defined Variables
    • Pre-Declaring Exports
      • Forgetting To Define An Exported Variable
  • Referencing Other Variables
  • Shell Substitution
  • Conditional Assignment
• Runfile Attributes
  • .SHELL
  • .RUN
  • .RUNFILE
  • .RUNFILE.DIR
  • .SELF
  • .SELF.DIR
  • Exporting Attributes
    • Simple Export
    • Export With Name
• Assertions
• Includes
  • File Globbing
  • Working Directory
  • Required vs Optional
  • Avoiding Include Loops
  • Overriding Commands
    • Cannot Re-Register Command In Same Runfile
    • Overrides Are Case-Insensitive
    • First Registered Command Defines Case For Help
    • First Registered Command Defines Default Documentation
    • Commands Are Listed In The Order They Are Registered
• Includes - .ENV
  • Required vs Optional
• Invoking Other Commands & Runfiles
  • RUN / RUN.AFTER / RUN.ENV Actions
  • .RUN / .RUNFILE Attributes
• Hidden / Private Commands
  • Hidden Commands
  • Private Commands
• Script Shells
  • Per-Command Shell Config
  • Global Default Shell Config
  • Other Executors
    • Python Example
  • Custom #! Support
    • C Example

---

Simple Command Definitions

Runfile

hello:
  echo "Hello, world"

We'll see that hello shows as an invokable command, but has no other help text.

list commands

$ run list

Commands:
  list       (builtin) List available commands
  help       (builtin) Show help for a command
  version    (builtin) Show run version
  hello

show help for hello command

$ run help hello

hello: no help available.

invoke hello command

$ run hello

Hello, world

Naming Commands

Run accepts the following pattern for command names:

alpha ::= 'a' .. 'z' | 'A' .. 'Z'
digit ::= '0' .. '9'

CMD_NAME ::= [ alpha | '_' ] ( [ alpha | digit | '_' | '-' ] )*

Some examples:

• hello
• hello_world
• hello-world
• HelloWorld

Case Sensitivity

Registering Commands

When registering commands, run treats the command name as case-insensitive and subject to command override rules.

case-insensitive override example

For example, run will generate an error if a command name is defined multiple times in the same runfile, even if the names use different cases:

Runfile

hello-world:
  echo "Hello, world"

HELLO-WORLD:
  echo "HELLO, WORLD"

list commands

$ run list

run: Runfile: command hello-world defined multiple times in the same file: lines 1 and 4

Invoking Commands

When invoking commands, run treats the command name as case-insensitive:

Runfile

Hello-World:
  echo "Hello, world"

output

$ run Hello-World
$ run Hello-world
$ run hello-world

Hello, world

Displaying Help

When displaying help text, run displays command names as they are originally defined:

list commands

$ run list

Commands:
  ...
  Hello-World
  ...

show help for Hello-World command

$ run help hello-world

Hello-World: no help available.

---

Simple Title Definitions

We can add a simple title to our command, providing some help content.

Runfile

## Hello world example.
hello:
  echo "Hello, world"

output

$ run list

Commands:
  list       (builtin) List available commands
  help       (builtin) Show help for a command
  version    (builtin) Show run version
  hello      Hello world example.
  ...

$ run help hello

hello:
  Hello world example.

---

Title & Description

We can further flesh out the help content by adding a description.

Runfile

##
# Hello world example.
# Prints "Hello, world".
hello:
  echo "Hello, world"

output

$ run list

Commands:
  list       (builtin) List available commands
  help       (builtin) Show help for a command
  version    (builtin) Show run version
  hello      Hello world example.
  ...

$ run help hello

hello:
  Hello world example.
  Prints "Hello, world".

---

Arguments

Positional arguments are passed through to your command script.

Runfile

##
# Hello world example.
hello:
  echo "Hello, ${1}"

output

$ run hello Newman

Hello, Newman

---

Command-Line Options

You can configure command-line options and access their values with environment variables.

Runfile

##
# Hello world example.
# Prints "Hello, <name>".
# OPTION NAME -n,--name <name> Name to say hello to
hello:
  echo "Hello, ${NAME}"

output

$ run help hello

hello:
  Hello world example.
  Prints "Hello, <name>".
Options:
  -h, --help
        Show full help screen
  -n, --name <name>
        Name to say hello to

$ run hello --name=Newman
$ run hello -n Newman

Hello, Newman

Making Options Required

You can use ! to indicate that an option is required:

# OPTION NAME! -n,--name <name> Name to say hello to

Required Indicator on Help Text

Required options will be indicated in help text:

  -n, --name <name> (required)
        Name to say hello to

Error When Required Option Not Provided

An error will be generated if a required option is not provided:

hello: ERROR: Missing required option:
  -n, --name <name>
        Name to say hello to

Explicitly Marking Options as "Optional"

Although options are already optional by default, you can use ? to explicitly indicate that an option is optional:

# OPTION NAME? -n,--name <name> Name to say hello to

NOTE: This exists mostly for parity with ! and behaves the same as when it is not used

Providing A Default Option Va