Project Configuration Reference

The genesis.toml file is created in each project generated by Genesis. It defines the project’s template source and tasks that can be run in the project.

File Structure

version = "1.0"  # Required

[project]
  template_url = "https://github.com/example/template"
  template_version = "v1.0.0"  # Optional: commit hash, tag, or branch

[tasks]
  test = { 
    description = "Run tests", 
    cmd = "go test ./...",
    env = { "GO_ENV" = "test" },  # Optional environment variables
    dir = "src"  # Optional working directory
  }
  build = { 
    description = "Build the project", 
    cmd = "go build -o bin/app" 
  }

Version Field

The version field is required and should be set to "1.0". This helps Genesis ensure compatibility with future configuration formats.

Project Section

The project section contains information about the template used to create the project:

Field	Type	Required	Description
template_url	string	Yes	URL of the Git repository containing the template
template_version	string	No	Specific version of the template (commit hash, tag, or branch)

Example:

[project]
  # Using a specific tag
  template_url = "https://github.com/example/template"
  template_version = "v1.0.0"

  # Using a commit hash
  template_url = "https://github.com/example/template"
  template_version = "4eeee43170429c82eb2fc4eeef52fbd2d8b2d0ca"

  # Using a branch
  template_url = "https://github.com/example/template"
  template_version = "main"

Tasks Section

The tasks section defines commands that can be run in the project using genesis run <task-name>.

Each task has the following properties:

Property	Type	Required	Description
description	string	Yes	Description shown in task list
cmd	string	Yes	Command to execute
env	map[string]string	No	Environment variables for the command
dir	string	No	Working directory for the command

Basic Tasks

Simple tasks just need a description and command:

[tasks]
  test = { description = "Run tests", cmd = "go test ./..." }
  build = { description = "Build project", cmd = "go build" }
  clean = { description = "Clean build files", cmd = "rm -rf bin/*" }

Tasks with Environment Variables

You can set environment variables for tasks:

[tasks]
  test = {
    description = "Run tests",
    cmd = "go test ./...",
    env = {
      "GO_ENV" = "test",
      "DEBUG" = "true"
    }
  }

Tasks with Working Directory

You can specify a working directory for tasks:

[tasks]
  frontend_build = {
    description = "Build frontend",
    cmd = "npm run build",
    dir = "frontend"
  }

Complex Tasks

Tasks can combine all features:

[tasks]
  deploy = {
    description = "Deploy to staging",
    cmd = "./deploy.sh",
    env = {
      "ENV" = "staging",
      "DEBUG" = "true"
    },
    dir = "scripts/deploy"
  }

Using Tasks

List available tasks:

genesis run list

Run a specific task:

genesis run test

Best Practices

1. Task Names:
   • Use descriptive names
   • Stick to lowercase letters and underscores
   • Group related tasks with prefixes (e.g., db:migrate, db:seed)
2. Task Descriptions:
   • Be clear and concise
   • Include important flags or options
   • Mention prerequisites if any
3. Commands:
   • Use full paths for scripts
   • Quote arguments with spaces
   • Consider platform compatibility
4. Environment Variables:
   • Use uppercase names
   • Document required variables
   • Set sensible defaults
5. Working Directories:
   • Use relative paths from project root
   • Ensure directories exist
   • Document directory requirements