Update README
This commit is contained in:
parent
3dc6be35c1
commit
c0bf8eaf84
102
README.md
102
README.md
|
|
@ -1,42 +1,102 @@
|
|||
# git-build.sh
|
||||
|
||||
Lightweight, KISS system to rebuild some git projects when they change.
|
||||
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 don't know where to put it, the script .git-build/git-build will put it in ~/bin/ and add the folder to your $PATH in ~/.bashrc.
|
||||
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/ folder to find stuff to build:
|
||||
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.
|
||||
|
||||
- config/ <-- additional settings/files for use in scripts
|
||||
- PROJECT.source <-- URL to the git repo for PROJECT
|
||||
- PROJECT.branch (optional) <-- branch to checkout
|
||||
- PROJECT <-- script to execute when the project is updated
|
||||
- PROJECT.log <-- STDOUT of PROJECT last run
|
||||
- PROJECT.err <-- STDERR of PROJECT last run
|
||||
A task may also have the following optional files:
|
||||
|
||||
Additionally, for each PROJECT a .PROJECT/ folder is created to clone the repository.
|
||||
- t.branch: checkout the specified branch on the repository
|
||||
- t.host: only run the task on a specific host, see [multihost setup](#multihost-setup)
|
||||
|
||||
To clone/update your repo and start your build scripts, start the git-build.sh command.
|
||||
**TLDR**: a task `t` needs `t` (executable) and `t.source`, and accepts `t.branch` and `t.host`
|
||||
|
||||
Note: the PROJECT script needs to be executable!
|
||||
## Running tasks
|
||||
|
||||
# Example
|
||||
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.
|
||||
|
||||
As an example on how to get started, this repo includes a .git-build/ folder. It's the configuration that generates [this site](https://thunix.net/~southerntofu/rfc) and keeps git-build.sh updated.
|
||||
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. If you copy .git-build/git-build{,.source} to ~/.git-build/ git-build.sh will automatically be updated on each run.
|
||||
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.
|
||||
|
||||
You may not want to do that but i thought that was a nice proof of concept that the updater can update itself.
|
||||
|
||||
# Auto-execute
|
||||
|
||||
You need CRON for that. Additionally, i'm interested to run this script through a webhook endpoint for Github/Gitlab/Gitea webhooks.
|
||||
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 it seems to be working. If you find a bug please report it or open a merge request :)
|
||||
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).
|
||||
|
|
|
|||
Loading…
Reference in New Issue