Simply place git-build.sh in your $PATH. If you want git-build.sh to install itself (via the autoupdater), you can `cp .git-build.sh ~/.git-build.sh && ./git-build.sh` which will create ~/bin/, add it to your $PATH in ~/.bashrc, and keep git-build.sh updated in the future.
git-build.sh looks up your ~/.git-build/ to find tasks to run. A task `t` is defined by a `t.source` file containing a git remote, and a `t` executable file that will be run on updates to the corresponding repository.
Simply running `git-build.sh` will update task repositories, and run tasks which received updates. When positional arguments are passed to git-build.sh, only the corresponding tasks are triggered. For example, `git-build.sh foo bar` will only check updates for tasks `foo` and `bar`, and run them if updates were found.
Additionally, git-build.sh can take a `-f` or `--force` flag which triggers task runs even when no updates were found. This flag is useful when you want to trigger a task which failed because of side-effects outside of the reach of git-build.sh, such as a missing package on the system. Similarly to without the `-f` flag, you can give git-build.sh a specific list of tasks to trigger.
**Note**: Please remember to make your task scripts executable! `chmod +x` is your friend.
## Logging
Task output is stored in `t.log` for STDOUT, and `t.err` for STDERR. These files are removed on a task run, so that they always contain information about the last build.
If your task respects STDOUT/STDERR convension, you can simply check the size of `t.err` to figure out whether a task failed. If some people would want that, we could further [track task progress/errors](https://tildegit.org/southerntofu/git-build.sh/issues/10) and/or introduce [configurable loglevels](https://tildegit.org/southerntofu/git-build.sh/issues/9).
## Configuration
Some tasks may need additional settings in order to run. A website building task may wish to know about a base URL and a destination folder, for instance. Such information may be placed in the `~/.git-build/config/` folder.
Any task receives the `$GITBUILDCONF` environment variable pointing to this repository, unless specific host configuration is found, as will be explained in the next section.
## Multihost setup
The distinctive feature of `git-build.sh` is the host-based configuration system. If a folder matching `$HOSTNAME` is found in your `~/.git-build/`, this folder will be passed to the task as `$GITBUILDCONF`, instead of the default configuration folder. If no host-specific configuration is found, the default configuration is used as explained previously.
Additionally, tasks can be configured to always/never run on a specific host. To run a task `t` on a single host, place a `t.host` file containing the target `$HOSTNAME` in `~/.git-build/`. To ignore a task on a specific host, place an empty `t.ignore` file in `~/.git-build/$HOSTNAME/`.
For an example of a multi-host setup, you can check out [my own ~/.git-build](https://tildegit.org/southerntofu/my-git-build).
# Building your own task
To build your own task, you simply need an executable program. If your task executable is a script, don't forget to add the [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) (eg `#! /bin/bash`) at the top of your script or it will fail. Please ensure your task is executable (`chmod +x t`) or it will fail.
A task can be any program in any language, that takes exactly one positional argument containing the task name, and an environment variable called `$GITBUILDCONF` containing the current configuration directory, which is either `~/.git-build/$HOSTNAME` or `~/.git-build/config` (in this order).
Here's an example simple task that writes the current time to `~/.git-build/t.log` and appends random characters to another file:
**Note**: The task name is passed to the task because the task may be a symlink to a program located somewhere else on the system. This is further described in the [Shared build scripts](#shared-build-scripts) section.
# Advanced usage
## Shared build scripts
A script for multiple tasks
## Ordering tasks
Auto-updater example and lockfile mechanisms
## Versioning
Keeping your ~/.git-build in git \o/
## Auto-run tasks
Auto-triggering updates/builds is beyond the scope of this project! You should consider using standard [cronjobs](https://en.wikipedia.org/wiki/Cron) for that.
I'm also interested in running this script through a webhook endpoint for Github/Gitlab/Gitea webhooks, in order to build a simple and reliable CI/CD system. This is not implemented yet and will not be part of this repository, but i will update this README when a such solution is available. If you want to contribute this feature in the meantime, you are more than welcome!
# Auto-update
Yes, you read that correctly! The `.git-build/git-build{,.source}` task provided in this repository is a proof-of-concept autoupdater that will download and install git-build.sh updates on every run.
It's a terrible idea for security to autoupdate executables in your $PATH and you probably do not want to do that. But i thought it was a nice demo and it can be useful for people new to the command-line, although this project should not receive too many updates in the future as it is already doing what it is supposed to.
Right now the state of this project is "works for me". It could be useful for other people which is why i just spent a full hour writing this README. However, there could be ways in which `git-build.sh` fails you!
If a feature is missing for you, or you encounter a bug, please report it on [tildegit](https://tildegit.org/southerntofu/git-build.sh/issues) (requires an account on a [tildeverse](https://tildeverse.org) server) or send a mail to southerntofu (@) thunix.net. If you can contribute the feature or fix the bug yourself, your patches are welcome!
This project abides by the [~fr operating principles](https://fr.tild3.org/en/#operating-principles).
