Task automation tool on steroids for developers

Overview

devrc is an easy to use task runner on steroids. It's a small and fast utility written in Rust 🦀.

It's userful for project or common routine automation such as minification, compilation, unit testing, linting and many more.

It's just single binary and you don't need to install python, ruby or something else.

It allows you to run tasks that are stored in YAML file named Devrcfile. Just type command, e.g. devrc task_name_1 task_name_2 task_name_3.

Quick introduction

There are several ways to define task. Here are general variants:

Simple command definition without documentation string.
```
task_name: echo "Hello world"
```

More complex definition with documentation string.

task_name:
  desc: "Task description"
  exec: echo "Hello world"

To run task just type command devrc TASK_NAME, e.g.:

devrc task_name

For more details look into usage section or examples.

Features

Lets start with an overview of features that exist in devrc:

All tasks can be listed from the command line with documentation
Template engine and variables interpolation are supported
Environment variables customization
Command line completion scripts
devrc supports dotenv files
Writing task commands in different languages
Task parameters and user input
Remote command execution
Read Devrcfile contents from stdin
Global and local defined variables and environment variables

Why YAML is used?

There are many formats (e.g. TOML, Makefile, YAML, custom formats) that have been examining after many years of using Makefiles for project routine automation.

What are the benefits of using YAML for this purpose and why it's choosen:

YAML is designed to be human-friendly and easy to read;
Syntax highlight works out of the box;
YAML is used industry-wide for declarative configuration. For example, it's used by gitlab-ci, GitHub actions and ansible;
Many text editors and platforms have plugins or built-in tools to check YAML configuration syntax for you.
Good parsers for YAML already exist and I don't need to waste time for implementing and testing a self-written parser.

Overview
Installation
Usage
Contributing, feedback and suggestions

Installation

To install devrc, you can download a pre-compiled binary, or you can compile it from source. You may be able to install devrc using your OS’s package manager, depending on your platform.

Install from crates.io

devrc is written in Rust. You will need rustc version 1.48.0 or higher.

The recommended way to install Rust for development is from the official download page, using rustup.

If you have the Rust toolchain already installed on your local system, you can use the cargo install command:

rustup update stable
cargo install devrc

Cargo will build the devrc binary and place it in $HOME/.cargo.

Compile from sources

GitHub

Clone the repository and change it to your working directory.

git clone https://github.com/devrc-hub/devrc.git
cd devrc

rustup update stable
cargo install

Binary Releases

Binary releases are available in the github releases page for macOS, and Linux targets. The following binaries are available for each release:

x86_64-unknown-linux-musl
x86_64-apple-darwin

Usage

Tasks are stored as mappings (hashes/dictionaries/key-value pairs) in YAML file named Devrcfile by default. Or you can specify environment variable DEVRC_FILE with alternative file name. Also you can store global tasks in ~/.devrc in your home directory or overwrite shared project tasks or varibles by local Devrcfile.local file.

If command line option -f is used:

Loading ~/.devrc in home directory if it exists and if command line flag -g or option devrc_config.global are enabled;
Loading files which are specified by command line option -f;

If command line option -f isn't used:

Loading ~/.devrc in home directory if it exists and if command line flag -g or option devrc_config.global in Devrcfile are enabled;
Loading Devrcfile or file name which is defined by environment variable DEVRC_FILE in the current directory;
Loading Devrcfile.local.

The names of the files are a case sensitive.

Task defition is like to definition of job in .gitlab-ci files. Key is used as task name and value is used to create task logic. Some key names are reserved and described below.

Task definition

There are different types of tasks.

Executable task
Configuration task (it hasn't been implemented yet).

There are three styles of task definition:

Simple command definition without documentation string.

task_name: echo "Hello world"

or several commands in one task

task_name:
  - echo "Hello Alex!"
  - echo "Hello Alice!"

More complex definition with documentation string and variables.

variables:
  name: "Alex"
task_name:
  desc: "Task description"
  exec: echo "Hello {{ name }}"

variables:
  first_name: "Alex"
  second_name: "Alice"

environment:
  ENV_NAME: "{{ second_name }}"

task_name:
  desc: "Task description"
  exec:
    - echo "Hello {{ first_name }}!"
    - echo "Hello $ENV_NAME!"

If we write code to Devrcfile and type command devrc task_name in console it will output to console:

Hello Alex!
Hello Alice!

Pay attention that {{ first_name }} are replaced by Alex by template engine and $ENV_NAME! are replaced by Alice by bash.

More complex examples can be found in examples directory.

Reserved keywords

There are few reserved keywords that can't be used as task name:

devrc_config - global options such as shell, log_level, current_directory;
variables - global set of variables that are used by template engine;
environment - global set of environment variables that are passed to children process's environment;
before_script - is a task that are executed before first task;
after_script - is a task that are executed after last task;
before_task - is a task that are executed before each task;
after_task - is a task that are executed after each task;
env_file - is used for (dotenv files)[#dotenv-files-support];

Configuration


devrc_config:
  global: true
  interpreter: /bin/bash -c
  default: [task_1, task_2]

Variables

Variables are used by template engine to compute commands, another variables (global or local) or environment variables. If there exists global and local variables with the same name, then local will overwrite it's value.

Environment variables

Environment variables that are passed to children process's environment and they must be accessed using $VARIABLE_NAME in commands. Environment variables can be defined globally or locally in task. If there exists global and local environment variables with the same name, then local will overwrite it's value. The shell will expand or substitute the value of a variable into a command line if you put a Dollar Sign $ in front of the variable name.


tast_name:
  environment:
    name: "Alex"

  exec: Hello $name!

Dotenv files support

devrc can load environment variables from env (dotenv) files. These variables are environment variables, not template variables. By default if something goes wrong in dotenv loading, devrc will break and exit. You can change default behaviour by using option ignore_errors and if something goes wrong, devrc will continue.

If env file contains:

ENV_NAME=Alex

you can load environment varibles from files using one of variants:

env_file:
  - ./.env
  - file: ./.env_3
    ignore_errors: true
  - file: ./.env_2

task_name: echo "Hello $ENV_NAME"

File path can be absolute or relative. Part ./ substitute to current directory.

Execution and computation rules

devrc views commands, global or local task defined variables, global or local task defines environment variables as templates. It applies template engine for commands before executing them or before variable assignment.

devrc consistently reads variables from files and applies a template engine based on Jinja2/Django syntax.

In the example text variable_1 variable_2 is assigned to a variable var_2 and text env_var variable_1 variable_2 is assignet to an environment variable ENV_VAR:

variables:
    var_1: "variable 1"
    var_2: "variable_2 {{ var_1}}"

environment:
    ENV_VAR: "env_var {{ var_2 }}"

Task dependencies

Task may have dependencies from another tasks. Dependencies of a task always run before a task execution and before before_task hook. This is useful to make some job before given task, like clean cache, remove atrifacts, etc. Dependencies run in series.


task_1: echo "Hello world!"

task_2:
  exec: echo "Hello $USER!"
  deps: [task_1]

Template engine

Task parameters and user input

Task may have parameters or user input.

Notice: This feature has't been implemented yet.

Here task has a required parameter name, an optional parameter other with default value of Alice and host parameter host which is assigned after user input:


task_name:
  exec:
    - echo "Hello {{ name }} and {{ other}}"
    - curl -v {{ host }}

  params:
    name: required
    other: "Alice"
    host:
      type: input
      default: https://github.com


devrc task_name name="Alex"

Please, enter a value for parameter `host`:

Remote command execution

It's also possible to execute task on remote hosts.