Coder Social home page Coder Social logo

saku's Introduction

saku (作) v1.2.4

CircleCI Build status codecov Go Report Card

Markdown-based task runner

saku is a simple task runner based on markdown syntax. You can define and describe your tasks in markdown file saku.md and execute them with saku command.

(You can optionally define tasks in README.md. See The below for details.)

🔖 More background stories are explained in an article.

💿 Install

Go users

go get -u github.com/kt3k/saku

Mac OS users

brew install kt3k/tap/saku

Or download binary from the release page.

🍃 Usage

First, create a markdown file saku.md:

# build
> Build the go binary.

    go build -v -i main.go

# test
> Run all the go tests.

    go test -race ./...

# js

    minify -o public/script.js src/js

# css

    minify -o public/style.css src/css

The above defines 4 tasks build test js css. (A heading (#) is a task title!)

If you hit saku (without arguments) it shows the list of the descriptions of the all tasks.

If you hit the command saku build, it invokes build task, go build -v -i main.go in the above example.

Note: 4-space or tab indent makes code block in markdown syntax. See here

    echo hello
    echo world

The above makes the code block of the 2 lines echo hello and echo world.

saku.md Rules

  • Heading (# title) starts the task definition.
    • Different levels of headings (#, ##, ###,...) forms the groups of tasks. Tasks of the lower level headings belong to the previous task which has the upper level heading. See below for the details.
  • Code blocks are commands.
    • Code blocks can have multiple commands. They will be executed sequentially.
  • Blockquotes are description of the task.
  • Anything else is ignored.
  • Anything before the first heading is ignored.

For example:

# build
> Build the go binary.

    echo Starting build go binary
    go build -v -i main.go

The above defines the task build, which has the description Build the go binary.. It has two commands echo Starting build go binary and go build -v -i main.go and they run in sequence.

Parallel execution

With -p, --parallel option, you can run tasks in parallel like the below:

saku -p watch-scripts run-server

Race execution

With -r, --race option, you can run tasks in parallel and terminate tasks when the first task finished. This is useful for testing servers.

This option takes effect only when -p option is specified.

saku -p -r run-server test-server

Grouping tasks

You can create the group of tasks by the levels of headings.

For example:

# foo

## bar

    echo bar

## baz

    echo baz

This defines 3 task foo, bar and baz. foo becomes the parent of bar and baz. So when you invoke saku foo, it executes both bar and baz:

$ saku foo
[saku] Run foo
[saku] foo > Run bar, baz in sequence
+echo bar
bar
+echo baz
baz
[saku] foo > Finish bar, baz in sequence
[saku] ✨  Finish foo

The tasks of the lower level headings belong to the upper level heading and which forms the groups of tasks.

Use parallel in task grouping

If you need to run the children tasks in parallel, you can use <!-- saku parallel --> directive in the parents' contents:

# foo

<!-- saku parallel -->

## bar

    echo bar

## baz

    echo baz

This executes bar and baz in parallel:

$ saku foo
[saku] Run foo
[saku] foo > Run bar, baz in parallel
+echo bar
+echo baz
bar
baz
[saku] foo > Finish bar, baz in parallel
[saku] ✨  Finish foo

Nesting tasks (Dependency of tasks)

You can use saku in saku.md like below:

# dist

    saku js minify

# js

    browserify src/main.js > build/app.js

# minify

    uglify-js < build/app.js > build/app.min.js

In this way, you can express the dependencies of tasks.

If you need to invoke tasks in parallel from another task, use saku -p.

# start

    saku -p serve watch

# watch

    my-watcher

# serve

    my-server

CLI Usage

Usage: saku [options] <task, ...> [-- extra-options]

Options:
  -v, --version   - - - Shows the version number and exits.
  -h, --help  - - - - - Shows the help message and exits.
  -i, --info  - - - - - Shows the task information and exits.
  -p, --parallel  - - - Runs tasks in parallel. Default false.
  -s, --sequential  - - Runs tasks in serial. Default true.
  -c, --config <path> - Specifies the config file. Default is 'saku.md'.
  -r, --race  - - - - - Sets the flag to kill all tasks when a task
                        finished with zero. This option is valid only
                        with 'parallel' option.
  -q, --quiet   - - - - Prints less messages.

The extra options after '--' are passed to each task command.

Notes

Embed saku.md in README.md

You can optionally embed saku.md in README.md. See the below for details.

README.md

# Development

These are the commands for development. You can invoke them with `saku` command.

<!-- saku start -->

## build

    go build -v -i main.go

## test

    go test -race ./...

<!-- saku end -->

The contents between <!-- saku start --> and <!-- saku end --> are used as saku.md. You can write them as if they are the part of your README.md.

Example use cases

Note: Please add yours if you use saku in your OSS project!

The origin of the name

Saku is the Japanese name for the Chinese character "作", which means "make". Saku is intended to be an alternative of make command (of a task runner use case).

Prior Art

Who use saku?

See this search.

License

MIT

saku's People

Contributors

dependabot[bot] avatar kt3k avatar toruuetani avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar

saku's Issues

Task model

  • run single command
  • run multiple commands

Emoji handling

  • when terminal is dumb, then do not show emoji, otherwise show it.

Task grouping

  • task_stack
  • task.children is TaskCollection
  • task.parent
  • parse hierarchy
  • update action info
  • testing
  • <!-- saku parallel --> <!-- saku parallel race -->
  • Describe task grouping in README.md

Run code blocks as scripts

Currently each command in a code block is executed separately which makes a different process. This prevents using variables and only shell commands are easily used.
For example:

export TEST="Hello World"
echo $TEST

The result will be empty:

+ export TEST="Hello World"
+ echo $TEST

saku initializer

script for downloading saku wrapper, set up saku.md, and show intructions how to start using saku.

Pass arguments to tasks?

Hello!
     I'm terribly sorry if this has already been asked, or, more likely, you considered this, however, would there be any possible way to pass arguments to saku? I absolutely love the fact that you can embed it into the README, which is the second reason I chose this, the first being it's speed.
     I understand that this may cause issues with cross-compatibility, so no rush in implementing this, if you have plans to at all.
     Thank you kindly for your help on the matter!

Group tasks with headers

Use headers levels for grouping multiple tasks. For example:

# My project
## Setup
### a
### b

Will be used as:

saku Setup
[saku] Run Setup
[saku]   Run a
[saku]   ✨  Finish a
[saku]   Run b
[saku]   ✨  Finish b
[saku] ✨  Finish Setup

parallel run

  • impl parallel
  • impl parallel race
  • test parallel
  • test parallel race

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.