Quickstart

This quickstart has two parts. First you run a one-task workflow that needs nothing but the ginkgo command. Then you run the bioinformatics example from the Ginkgo repository, which uses Pixi and a container.

You need the ginkgo command first. See Installation.

1. Run Your First Workflow

In an empty directory, save the minimal workflow from the docs front page as flow.py. Then run it:

ginkgo run flow.py

Ginkgo shows a table of tasks as they run. When the run ends, the table shows write_text as succeeded, and hello.txt is in the directory.

2. Run It Again To See The Cache

Run the same command again:

ginkgo run flow.py

This time nothing runs. Ginkgo reports the task as cached:

┌────────────┬──────────┬─────────────┬──────┐
│ Task       │ Status   │ Environment │ Time │
├────────────┼──────────┼─────────────┼──────┤
│ write_text │ ↺ cached │ local       │ 0.0s │
└────────────┴──────────┴─────────────┴──────┘

⏱ Completed in 0.1s - 0 tasks executed, 1 cached

Ginkgo reused the result because nothing changed. It decides this from the task’s code, its inputs and its environment. Cache Identity gives the exact rule. Change message in flow.py and run again, and write_text runs again.

3. Get The Bioinformatics Example

The example lives in the Ginkgo repository:

git clone https://github.com/sanjaynagi/ginkgo.git
cd ginkgo/examples/bioinfo

It needs Pixi and Docker or Podman on your PATH (see Runtime Prerequisites). workflow/flow.py has four tasks:

• filter_fastq filters each sample’s reads with seqkit, in a Pixi environment.
• fastq_stats computes quality-control statistics for each filtered sample, in the same environment.
• count_reads counts the reads in each filtered sample, in a Docker container.
• build_summary merges the statistics and counts into one table.

Example: Bioinformatics Workflow walks through the code.

4. Preview With A Dry Run

Check the workflow before you run it for real:

ginkgo run --dry-run

A dry run checks the workflow and prints a plan. No task runs. The plan lists which tasks would run, which would reuse cached results, and the resources each task declares.

5. Run The Workflow

ginkgo run

With no file named, ginkgo run looks for workflow/flow.py in the current directory. To name the file yourself:

ginkgo run workflow/flow.py

6. Look At The Outputs

After a successful run, look at:

• results/filtered/ for the filtered reads
• results/qc/ for each sample’s statistics
• results/read_counts/ for the read counts made in the container
• results/summary.csv for the merged table
• logs/ for the tool logs

Ginkgo also records the run, which is the run’s provenance. The last line of the run output names the run’s directory under .ginkgo/runs/. To list your runs and show one of them:

ginkgo runs ls
ginkgo runs show <run_id>

Querying Provenance covers the other ways to read the record.

What To Read Next

Read Core Concepts next. It explains why calling a task doesn’t run it, and how a task can add new tasks while the workflow runs.