# git-build.sh Lightweight, KISS system to start tasks that depend on a remote git project. Depending on your needs, git-build.sh can: - check updates for one or more repositories, and start corresponding tasks if there was any update (`git-build.sh [tasks]`) - run one or more local tasks, whether there were updates or not (`git-build.sh -f [tasks]`) - [use task settings](#configuration), or for [host-specific settings](#multihost-setup) # Setup 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. # Usage 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. A task may also have the following optional files: - t.branch: checkout the specified branch on the repository - t.host: only run the task on a specific host, see [multihost setup](#multihost-setup) **TLDR**: a task `t` needs `t` (executable) and `t.source`, and accepts `t.branch` and `t.host` ## Running tasks 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: ``` #! /bin/bash date # STDOUT is automatically appended to task log hexdump -n 16 -e ' /1 "%02x"' /dev/urandom >> ~/random.list ``` **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. # Contribute 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).