kickoff

kickoff

Bootstrap projects from skeleton directories.

Contents

• Features
• Installation
• Quickstart
• Using skeleton repositories
• Project Skeletons
• Environment variables
• Shell completion
• Skeleton inheritance
• Skeleton composition

Features

• Templating of filenames, directory names and file contents via Go templates and Sprig.
• Extensible by allowing users to pass arbitrary values to templates via config files or CLI flags.
• Automatically populate LICENSE file with an open source license obtained from the GitHub Licenses API.
• Automatically add a .gitignore created from templates obtained from gitignore.io.
• Set local author, repository and skeleton defaults using custom config file.
• Dry run for project creation.
• Skeleton inheritance: skeletons can inherit files and values from an optional parent skeleton.
• Skeleton composition: projects can be created by composing multiple skeletons together. This is similar to inheritance but allows for way more flexible use of skeletons.

Installation

From binary release

Currently only Linux and MacOSX are packaged as binary releases. Check out the releases for all available versions.

curl -SsL -o kickoff "https://github.com/martinohmann/kickoff/releases/latest/download/kickoff_$(uname -s)_$(uname -m)"
chmod +x kickoff
mv kickoff $GOPATH/bin/

From source

git clone https://github.com/martinohmann/kickoff
cd kickoff
make install

This will install the kickoff binary to $GOPATH/bin/kickoff.

You can verify the installation by printing the version:

kickoff version

Quickstart

Initialize the kickoff config and create a new project:

kickoff init
kickoff project create default ~/path/to/my/new/project --license mit --gitignore go,hugo

The kickoff cli comes with detailed examples on each subcommand, so be sure to check them out. Showing the help is a good starting point:

# List of all available commands.
kickoff help

# Help for the `project create` subcommand.
kickoff project create help

Using skeleton repositories

Kickoff supports local and remote skeleton repositories. If you want, you can use the repository that come along with kickoff. Head over to the kickoff-skeletons repository for ready-to-use skeletons and to get some inspiration to create your own.

You can add the kickoff-skeletons repository to your config to directly create projects from the available skeletons:

kickoff repository add kickoff-skeletons https://github.com/martinohmann/kickoff-skeletons

Local skeleton repositories

Kickoff supports local repositories which do not necessarily need to be git repos. If you did not create a local repository via kickoff init, you can create one like this:

kickoff repository create ~/path/to/new/repo
kickoff repository add myrepo ~/path/to/new/repo

The kickoff repository create command will create a new repository which already contains a minimal default skeleton with a commented .kickoff.yaml file and a README.md.skel skeleton to get you started. You can delete it or customize it to your needs.

You can verify that your local repository was correctly created and added by listing the available kickoff repositories:

kickoff repository list

Remote skeleton repositories

Add a remote skeleton repository and create a new project:

kickoff repository add myremoterepo https://github.com/myuser/myskeletonrepo?revision=v1.0.0
kickoff repository list
kickoff project create myremoterepo:myskeleton ~/path/to/my/new/project

Remote repository urls can contain an optional revision query parameter which may point to a commit, tag or branch. If omitted master is assumed.

Project Skeletons

A skeleton is just a subdirectory of the skeletons/ directory inside your local repository. The skeleton directory must contain a .kickoff.yaml file (which may be empty).

Creating skeletons in a local repository

Creating a new skeleton with some boilerplate can be done like this:

kickoff skeleton create ~/path/to/local/skeleton-repository/skeletons/myskeleton

You can verify it by listing all available skeletons:

kickoff skeleton list

Skeleton templating

Any file with the .skel extension is treated as a Go templates and can be fully templated. When creating a project the resolved .skel templates will be written to the target directory with the .skel extension stripped, e.g. README.md.skel becomes README.md.

Template variables

Kickoff makes available a couple of variables to these templates:

Templating file and directory names

Kickoff will try to resolve Go template variables in file and directory names. E.g. a directory cmd/{{.Project.Name}} will be resolved to cmd/myproject if the project is named myproject. It is also possible to put arbitrary files into these directories. These will be moved to the correct place after the directory name was resolved. You can check out this example skeleton which makes use of this feature: kickoff-skeletons:golang/cli.

Environment variables

The following environment variables can be used to configure kickoff:

Shell completion

Add to your ~/.bashrc for bash completion:

. <(kickoff completion bash)

Add to your ~/.zshrc for zsh completion:

. <(kickoff completion zsh)

Skeleton inheritance

Skeletons can inherit from other skeletons. Just add the parent configuration to the .kickoff.yaml of the skeleton like this:

parent:
  repositoryURL: https://github.com/martinohmann/kickoff-skeletons?revision=master
  skeletonName: my-parent-skeleton

If repositoryURL is omitted, the same repository as the one of the skeleton is assumed. repositoryURL can be a remote URL or local path. Remote repository urls can contain an optional revision query parameter which may point to a commit, tag or branch. If omitted master is assumed.

Skeleton composition

Projects can be created by composing multiple skeletons together. This is just as simple as providing multiple skeletons instead of one as comma separated list on project creation:

kickoff project create skeleton1,skeleton2,skeleton3 /path/to/project

Note that the skeletons are merged left to right, so files and values from skeletons on the right will override files and values of the same name from other skeletons.

License

The source code of kickoff is released under the MIT License. See the bundled LICENSE file for details.