📚 Orbit - Awesome Go Library for Software Packages
A simple tool for running commands and generating files from templates.
Detailed Description of Orbit
Orbit
A cross-platform task runner for executing commands and generating files from templates
Orbit started with the need to find a cross-platform alternative of make
and sed -i
commands. As it does not aim to be as powerful as these two
commands, Orbit offers an elegant solution for running tasks and generating
files from templates, whatever the platform you're using.
Menu
Install
Download the latest release of Orbit from the releases page. You can get Orbit for a large range of OS and architecture.
The file you downloaded is a compressed archive. You'll need to extract the Orbit binary and move it into a folder where you can execute it easily.
Linux/MacOS:
tar -xzf orbit*.tar.gz orbit
sudo mv ./orbit /usr/local/bin && chmod +x /usr/local/bin/orbit
Windows:
Right click on the file and choose Extract All.
Move the binary to a folder like C:\Orbit
.
Then, add it in your Path system environment variables. Click
System, Advanced system settings, Environment Variables... and
open Path under System variables. Edit the Variable value by adding
the folder with the Orbit binary.
Alright, you're almost done :metal:! Let's check your installation by running:
orbit version
Generating a file from a template
Orbit uses the Go package text/template
under the hood as a template
engine. It provides a interesting amount of logic for your templates.
The Go documentation and the Hugo documentation cover a lot of features that aren't mentioned here. Don't hesitate to take a look at these links to understand the Go template engine! :smiley:
Also, Orbit provides Sprig library and three custom functions:
os
which returns the current OS name at runtime (you may find all available names in the official documentation).verbose
which returnstrue
if logging is set to info level.debug
which returnstrue
if logging is set to debug level.
Command description
Base
orbit generate [flags]
Flags
-f --file
Specify the path of the template. This flag is required.
-o --output
Specify the output file which will be generated from the template.
Good to know: if no output is specified, Orbit will print the result to Stdout.
-p --payload
The flag -p
allows you to specify many data sources which will be applied to your template:
orbit generate [...] -p "key_1,file_1.yml"
orbit generate [...] -p "key_1,file_1.yml;key_2,file_2.toml;key_3,file_3.json;key_4,.env;key_5,some raw data"
As you can see, Orbit handles 5 types of data sources:
- YAML files (
*.yaml
,*.yml
) - TOML files (
*.toml
) - JSON files (
*.json
) - .env files
- raw data
The data will be accessible in your template through {{ .Orbit.my_key.my_data }}
.
If you don't want to specify the payload each time your running orbit generate
,
you may also create a file named orbit-payload.yml
in the folder where your running your command:
payload:
- key: my_key
value: my_file.yml
- key: my_other_key
value: Some raw data
By doing so, running orbit generate [...]
will be equivalent to
running orbit generate [...] -p "my_key,my_file.yml;my_other_key,Some raw data"
.
Note: you are able to override a data source from the file orbit-payload.yml
if
you set the same key in the -p
flag.
-t --templates
The flag -t
allows you to specify additional templates which are used in your template:
orbit generate [...] -t "template_1.txt"
orbit generate [...] -t "template_1.txt,template_2.yml"
orbit generate [...] -t "template_1.txt,template_2.yml,../../template_3.toml"
So, in order to generate a file from this template:
{{ template "additional_template.txt" }}
You should run:
orbit generate [...] -t "path/to/additional_template.txt"
If you don't want to specify the templates each time your running orbit generate
,
you may also use the file orbit-payload.yml
in the folder where your running your command:
payload:
[...]
templates:
- template_1.txt
- template_2.yml
By doing so, running orbit generate [...]
will be equivalent to
running orbit generate [...] -t "template_1.txt,template_2.yml"
.
--delimiters
The flag --delimiters
allows you to specify an alternative template delimiter pair (left/open, right/close). If unspecified, the Go defaults ({{
and }}
) will be used. Note that, if this option is used, exactly two delimiters must be specified.
Examples:
orbit generate [...] --delimiters "<<,>>"
orbit generate [...] --delimiters "<<" --delimiters ">>"
The first delimiter (<<
in the examples above) is used for the left/opening delimiter while the second delimiter (>>
in the examples above) is used for the right/closing delimiter. This applies regardless of whether the delimiters are specified as a comma-separated pair (first example) or by repeated use of the option (second example).
-v --verbose
Sets logging to info level.
-d --debug
Sets logging to debug level.
Basic example
Let's create our simple template template.yml
:
companies:
{{- range $company := .Orbit.Values.companies }}
- name: {{ $company.name }}
launchers:
{{- range $launcher := $company.launchers }}
- {{ $launcher }}
{{ end }}
{{- end }}
And the data provided a YAML file named data-source.yml
:
companies:
- name: SpaceX
launchers:
- Falcon 9
- Falcon Heavy
- name: Blue Origin
launchers:
- New Shepard
- New Glenn
agencies:
- name: ESA
launchers:
- Ariane 5
- Vega
The command for generating a file from this template is quite simple:
orbit generate -f template.yml -p "Values,data-source.yml" -o companies.yml
This command will create the companies.yml
file with this content:
companies:
- name: SpaceX
launchers:
- Falcon 9
- Falcon Heavy
- name: Blue Origin
launchers:
- New Shepard
- New Glenn
Defining and running tasks
Command description
Base
orbit run [tasks] [flags]
Flags
-f --file
Like the make
command with its Makefile
, Orbit requires a
configuration file (YAML, by default orbit.yml
) where you define
your tasks:
tasks:
- use: my_first_task
short: My first task short description
run:
- command [args]
- command [args]
- ...
- use: my_second_task
private: true
run:
- command [args]
- command [args]
- ...
- the
use
attribute is the name of your task. - the
short
attribute is optional and is displayed when runningorbit run
. - the
private
attribute is optional and hides the considered task when runningorbit run
. - the
run
attribute is the stack of commands to run. - a command is a binary which is available in your
$PATH
.
Once you've created your orbit.yml
file, you're able
to run your tasks with:
orbit run my_first_task
orbit run my_second_task
orbit run my_first_task my_second_task
Notice that you may run nested tasks :metal:!
Also a cool feature of Orbit is its ability to read its configuration through a template.
For example, if you need to execute a platform specific script, you may write:
tasks:
- use: script
run:
{{ if ne "windows" os }}
- my_script.sh
{{ else }}
- .\my_script.bat
{{ end }}
Orbit will automatically detect the shell you're using (with the SHELL
environment variable on POSIX system
and COMSPEC
on Windows).
Running the task script
from the previous example will in fact executes cmd.exe /c .\my_script.bat
on
Windows or /bin/sh -c my_script.sh
(or /bin/zsh -c my_script.sh
etc.) on others OS.
Of course, if you want to specify the binary which is calling your commands, there is a shell
attribute available:
tasks:
- use: script
shell: /bin/bash -c
run:
- command [args]
- ...
Last but not least, a task is able to call others tasks within the same context thanks to the run
function:
tasks:
- use: task
run:
- {{ run "subtask_1" "subtask_2" }}
- use: subtask_1
run:
- command [args]
- ...
- use: subtask_2
run:
- command [args]
- ...
-p --payload
The flag -p
allows you to specify many data sources which will be applied to your configuration file.
It works the same as the -p
flag from the generate
command.
Of course, you may also create a file named orbit-payload.yml
in the same folder where you're executing Orbit.
-t --templates
The flag -t
allows you to specify additional templates which are used in your configuration file.
It works the same as the -t
flag from the generate
command.
Of course, you may also create a file named orbit-payload.yml
in the same folder where you're executing Orbit.
-v --verbose
Sets logging to info level.
-d --debug
Sets logging to debug level.
Basic example
Let's create our simple configuration file orbit.yml
:
tasks:
- use: prepare
run:
- orbit generate -f configuration.template.yml -o configuration.yml -p "Data,config.json"
- echo "configuration.yml has been succesfully created!"
You are now able to run the task prepare
with:
orbit run prepare
This task will:
- create a file named
configuration.yml
- print
configuration.yml has been succesfully created!
to Stdout
Voilà! :smiley:
Would you like to update this documentation ? Feel free to open an issue.