ska

README

SKA

SKA is a "skaffolding" tool that allows you to expand folders based on local or remote blueprints (GitHub hosted)

Additionally, you can update your folder structure from the upstream blueprint to onboard new changes that are maintained centrally and added overtime to upstream.

SKA is designed for simplicity and quick usage. If you want to integrate SKA capabilities in your app or framework you can leverage the package under pkg/.

SKA in action

Get Started

SKA is distributed via Homebrew, so you can install it with the commands below:

brew tap gchiesa/ska
brew install ska

How To Use

SKA is very simple to use. Just run create with the upstream blueprint you want to use. See below example for scaffolding a golang command line tool:

ska create --blueprint https://github.com/gchiesa/ska-golang-cli-template@master --output ~/workspace/myNewApp

This will load the remote template, collect the required variable via Terminal UI and create the project for you.

In the root of the project you can find the SKA configuration file .ska-config.yml that will keep track from now on of state and upstream reference.

When you want to update your project, just use:

cd ~/workspace/myNewApp
ska update --path .

you can modify the variables or accept the current version. Your project will be updated based on latest changes in the upstream blueprint.

More information are available with ska --help.

Concepts and Templating

Upstream Blueprint

This is the typically centrally maintained template that everyone can use to expand its own folder structure. You can specify the blueprint both locally and remotely with specific URIs:

• file:// for local blueprints. E.g. file:///Users/gchiesa/git/ska-example-template
• https:// for GitHub or GitLab (soon) blueprints. You can optionally pin a specific reference (tag or branch with the @ symbol. E.g. https://github.com/gchiesa/ska-example-template@v1.2.3

Update from upstream

Whenever the upstream template changes, you might want to onboard the changes yourself. This is natively supported by SKA, by offering a simple update command with not additional arguments required.

See How To Use section for more information.

Upstream Template Language

SKA currently fully supports primarily Go Template framework for templating your upstream blueprint.

Moreover, in addition to Go Template you can use the extensions offered by Sprig functions

If you are not familiar with Go Template have a look to this simple how-to.

NOTE: SKA supports also a Jinja2 like engine (use the --engine jinja argument) that will make your life easier when you need to deal with native go code. However, the function set is limited. The support is based on Pongo2 project.

Templating with partial sections

SKA offers the capability to manage only part of files.
This is generally useful to keep only a specific part of the file centrally managed by the upstream blueprint and let the user change the rest of the file. See as example the codecov.yml here

This is achievable with the named partials, a type of block you can use in the SKA template.

For example, if we want to have only a section of a larger file managed by SKA we can use the approach below:

# this is an example YAML and we want SKA to only manage the section `key4`
---
root:
  key1: value1
  key2: {{.notManaged}}
  key3: value3
  # ska-start:key/4
  key4:
    subkey: "{{.appName}}"
    subkey2: value2
  # ska-end
  key5: value5

by using the ska-start:<blockName> and ska-end tags, you instruct SKA to only process the block and leave the rest of the file as it is.

This is quite useful for files where only a part should be centrally managed and the rest will be customized by the user, after the initial creation.

Contribute

You are more than welcome! please have a look to CONTRIBUTING.md

Credits

SKA is made with 💙 by Giuseppe Chiesa as exercise to learn a bit better GoLang.