b5 1.1.7

b5 - simple and sane task runner

b5 Task Runner

b5 is the central task runner for all projects of our agency (TEAM23 - www.team23.de). It tries to be as simple as possible while empowering you to write your own tasks, extend existing ones and use b5 for all of the everyday project jobs.

Basic usage and concept

b5 {taskname} will look for a file called Taskfile found under build/ in your project root. It will then execute the function named task:{taskname} inside the Taskfile (which is a normal bash script). This means you may call b5 install to have the function task:install run.

The basic idea of b5 is to allow you to easily put your daily shell jobs into the Taskfile and provide a common schema for running these tasks. So b5 css for example will always build the CSS files for your project regardless of the CSS preprocessor used in this particular project (could be: less, sass, …). As b5 uses bash scripting as the Taskfile format it is easy to understand and enhance.

b5 in addition provides some modules to ease the usage of some common tools used in web development (like npm, composer, pipenv, docker, …). In addition it defines some common task names to introduce a good convention for your task naming schema. This will allow new developers to get on board faster - not need to care too much about the project setup itself.

You may pass parameters to your tasks like b5 some_task some_parameter and use normal bash parameter handling to use these parameters ($1, or better ${1}). Please note that b5 will abort when accessing a non existent parameter, use bash default values when necessary (${1:-default}).

Hint: You may add a file called Taskfile.local (build/Taskfile.local) for all your personal tasks. Make sure to never add this file to git. Please be sure to add this file to your .gitignore. Otherwise you might interfere with the local Taskfile of your colleges.

Quick start

Install b5 using pipsi install b5 or pip install b5 (For Mac OS X you may use brew install b5 after adding our tap). See detailed installation instructions.

Note for my TEAM23 colleagues: Please make sure to install the additional dependencies.

Starting your project

b5-init example-project
cd example-project
# start working on the new project

Note: You may use b5-init -s $SKELETON example to initialize the project using an skeleton. By default b5 will use the "basic" skeleton. See project initialization for more details.

Defining your tasks (build/Taskfile)

b5 initialized your project with an example Taskfile (see build/Taskfile). For adding new tasks just write bash functions prefixed with task:, like:

#!/usr/bin/env bash
# b5 Taskfile, see https://git.team23.de/build/b5 for details

task:make_it_happen() {
    echo "Yeah, it happened"
}

Running your tasks

Now you can use b5 make_it_happen and your code inside the function will run. As this code is a simple bash script you may use your normal command line tools. Feel free to use gulp, grunt, fabric, … for more complex task excution - and call these using your Taskfile.

Note: The Taskfile is always executed inside the "run-path", which defaults to build/. Make sure to switch path, when neccessary. I recommend using a subshell (see "( … )" subshell syntax) when doing so.

Going further

Now you set up a simple example project including an example Taskfile. The Taskfile is the central part of the b5 task runner which will include the calls to all of the provided tasks. Most of the tasks will call external tools like, gulp or fabric. This is the intended behavior.

See detailed installation instruction for some more details the installation of b5.

See core concepts for some more details about the b5 concepts.

See Taskfile format for more details on how to write your Taskfile.

See common tasks for information about which tasks your Taskfile needs to provide and what these tasks should do.

See Configuration for about how to add configuration to the build process and how to handle local configuration.

See modules for looking further into modules b5 already provides for a healthy project setup.

See project initialization for more information about how to b5-init a project.

b5 logo

You may use the b5 logo when referring to b5:

(see assets/ for other formats)

Also feel free to add a b5 badge to your project after you made it "b5 ready":

(see assets/badges/ for other formats)