rename git-build.sh to forgebuild
This commit is contained in:
parent
cc0d8d4c92
commit
101fa77894
78
README.md
78
README.md
|
|
@ -1,20 +1,36 @@
|
|||
# git-build.sh
|
||||
# forgebuild.sh
|
||||
|
||||
Lightweight, KISS system to start tasks that depend on a remote git project. Depending on your needs, git-build.sh can:
|
||||
Lightweight, KISS system to start tasks that depend on a remote git project. Depending on your needs, forgebuild 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]`)
|
||||
- check updates for one or more repositories, and start corresponding tasks if there was any update (`forgebuild [tasks]`)
|
||||
- run one or more local tasks, whether there were updates or not (`forgebuild -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.
|
||||
To automatically setup forgebuild.sh, you can run the setup.sh script, like so:
|
||||
|
||||
**Note**: In order to download translations, you need to download the i18n git submodule with `git clone --recursive https://tildegit.org/southerntofu/git-build.sh` (TODO: better documentation)
|
||||
```
|
||||
$ git clone https://tildegit.org/forge/build.sh
|
||||
$ build.sh/setup.sh
|
||||
```
|
||||
|
||||
The setup script is very short and simple so you may take the time to inspect it. But if you'd rather do things your way, you should:
|
||||
|
||||
- copy forgebuild.sh as `forgebuild` somewhere on your $PATH (`sudo cp forgebuild.sh /usr/local/bin/forgebuild`)
|
||||
- clone the git submodule with the translation files (`git submodule init && git submodule update`)
|
||||
- copy the translations to $HOME/.local/share/forgebuild (`mkdir $HOME/.local/share/forgebuild/ && cp -R spec/i18n $HOME/.local/share/forgebuild/`)
|
||||
|
||||
That's it! You can now start using forgebuild to build all your amazing things.
|
||||
|
||||
TODO: should also check /usr/local/share
|
||||
|
||||
|
||||
If you want to do this your way, you need to:
|
||||
|
||||
# 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.
|
||||
forgebuild looks up your ~/.forgebuild/ folder 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:
|
||||
|
||||
|
|
@ -25,9 +41,9 @@ A task may also have the following optional files:
|
|||
|
||||
## 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.
|
||||
Simply running `forgebuild.sh` will update task repositories, and run tasks which received updates. When positional arguments are passed to forgebuild, only the corresponding tasks are triggered. For example, `forgebuild 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.
|
||||
Additionally, forgebuild.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 forgebuild, such as a missing package on the system. Similarly to without the `-f` flag, you can give forgebuild a specific list of tasks to trigger.
|
||||
|
||||
**Note**: Please remember to make your task scripts executable! `chmod +x` is your friend.
|
||||
|
||||
|
|
@ -35,21 +51,21 @@ Additionally, git-build.sh can take a `-f` or `--force` flag which triggers task
|
|||
|
||||
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).
|
||||
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/forgebuild.sh/issues/10) and/or introduce [configurable loglevels](https://tildegit.org/forge/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.
|
||||
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 `~/.forgebuild/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.
|
||||
The distinctive feature of `forgebuild.sh` is the host-based configuration system. If a folder matching `$HOSTNAME` is found in your `~/.forgebuild/`, 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/`.
|
||||
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 `~/.forgebuild/`. To ignore a task on a specific host, place an empty `t.ignore` file in `~/.forgebuild/$HOSTNAME/`.
|
||||
|
||||
For an example of a multi-host setup, you can check out [my own ~/.git-build](https://tildegit.org/southerntofu/my-git-build).
|
||||
For an example of a multi-host setup, you can check out [my own ~/.forgebuild](https://tildegit.org/southerntofu/my-git-build).
|
||||
|
||||
# Building your own task
|
||||
|
||||
|
|
@ -57,10 +73,10 @@ To build your own task, you simply need an executable program. If your task exec
|
|||
|
||||
A task can be any program in any language, that takes exactly one positional argument containing the task name, and the following environment variables:
|
||||
|
||||
- `$GITBUILDCONF` containing the current configuration directory, which is either `~/.git-build/$HOSTNAME` or `~/.git-build/config` (in this order)
|
||||
- `$GITBUILDDIR` which is always `~/.git-build/`
|
||||
- `$GITBUILDCONF` containing the current configuration directory, which is either `~/.forgebuild/$HOSTNAME` or `~/.forgebuild/config` (in this order)
|
||||
- `$GITBUILDDIR` which is always `~/.forgebuild/`
|
||||
|
||||
Here's an example simple task that writes the current time to `~/.git-build/t.log` and appends random characters to another file:
|
||||
Here's an example simple task that writes the current time to `~/.forgebuild/t.log` and appends random characters to another file:
|
||||
|
||||
```
|
||||
#! /bin/bash
|
||||
|
|
@ -79,26 +95,26 @@ hexdump -n 16 -e ' /1 "%02x"' /dev/urandom >> ~/random.list
|
|||
If you need to use the same task script for different tasks, you can use [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link):
|
||||
|
||||
```
|
||||
$ ln -s ~/.git-build/task1 ~/.git-build/task2
|
||||
$ ln -s ~/.forgebuild/task1 ~/.forgebuild/task2
|
||||
```
|
||||
|
||||
This is possible because the task receives the current task name as first (and only) positional argument (`$1`). In the above example, the following commands are run when running `git-build.sh`:
|
||||
This is possible because the task receives the current task name as first (and only) positional argument (`$1`). In the above example, the following commands are run when running `forgebuild.sh`:
|
||||
|
||||
- ~/.git-build/task1 task1 # when task1.source was updated
|
||||
- ~/.git-build/task1 task2 # when task2.source was updated
|
||||
- ~/.forgebuild/task1 task1 # when task1.source was updated
|
||||
- ~/.forgebuild/task1 task2 # when task2.source was updated
|
||||
|
||||
This allows for instance to build different websites to different folders, from the same task script. A complex example for that is available in the [zola script](https://tildegit.org/southerntofu/my-git-build/src/branch/master/zola) in my `~/.git-build`.
|
||||
This allows for instance to build different websites to different folders, from the same task script. A complex example for that is available in the [zola script](https://tildegit.org/southerntofu/my-forgebuild/src/branch/master/zola) in my `~/.forgebuild`.
|
||||
|
||||
## Ordering tasks
|
||||
|
||||
`git-build.sh` supports naive ordering of tasks because it uses a [glob pattern](https://en.wikipedia.org/wiki/Glob_%28programming%29) (`~/.git-build/*.source`) to iterate over files with alphanumeric ordering. This means task `abcd` runs before `dcba`, but `10-dcba` runs before `20-abcd`.
|
||||
`forgebuild.sh` supports naive ordering of tasks because it uses a [glob pattern](https://en.wikipedia.org/wiki/Glob_%28programming%29) (`~/.forgebuild/*.source`) to iterate over files with alphanumeric ordering. This means task `abcd` runs before `dcba`, but `10-dcba` runs before `20-abcd`.
|
||||
|
||||
However, tasks can take some time and are therefore run in the background (in parallel). So if you need to run a task precisely after another one, the first task should create a [lockfile](https://en.wikipedia.org/wiki/Glob_%28programming%29), which it removes once done. Then, the second task waits for the first to finish its job.
|
||||
|
||||
For example, this is how the autoupdater waits for `git-build.sh` to stop running:
|
||||
For example, this is how the autoupdater waits for `forgebuild.sh` to stop running:
|
||||
|
||||
```
|
||||
# Wait for git-build.sh to stop running
|
||||
# Wait for forgebuild.sh to stop running
|
||||
SECONDS=0
|
||||
while [[ $SECONDS < 60 ]]; do
|
||||
if [ ! -f $GITBUILDDIR/.LOCK ]; then
|
||||
|
|
@ -113,7 +129,7 @@ exit 1 # TIMEOUT
|
|||
|
||||
## Versioning
|
||||
|
||||
Of course, you can version your `~/.git-build/` in git. This allows you to easily share the same folder across serves and keep them in sync. You can use the following task script to auto-update your folder:
|
||||
Of course, you can version your `~/.forgebuild/` in git. This allows you to easily share the same folder across serves and keep them in sync. You can use the following task script to auto-update your folder:
|
||||
|
||||
```
|
||||
#! /bin/bash
|
||||
|
|
@ -124,7 +140,7 @@ git pull
|
|||
|
||||
**Note:** You should probably not do something so simple, as other tasks may be running which would make the pull fail, as those files are busy and git cannot write to them. In the future, a more integrated approach to this problem may be taken.
|
||||
|
||||
When keeping your `~/.git-build/` in git, you need need to tell git to ignore local artifacts, by appending the following to your `.gitignore`:
|
||||
When keeping your `~/.forgebuild/` in git, you need need to tell git to ignore local artifacts, by appending the following to your `.gitignore`:
|
||||
|
||||
```
|
||||
*.log
|
||||
|
|
@ -132,7 +148,7 @@ When keeping your `~/.git-build/` in git, you need need to tell git to ignore lo
|
|||
.*/
|
||||
```
|
||||
|
||||
You can check out my own [~/.git-build](https://tildegit.org/southerntofu/my-git-build) for an example of how to version your build scripts.
|
||||
You can check out my own [~/.forgebuild](https://tildegit.org/southerntofu/my-git-build) for an example of how to version your build scripts.
|
||||
|
||||
## Auto-run tasks
|
||||
|
||||
|
|
@ -142,14 +158,14 @@ I'm also interested in running this script through a webhook endpoint for Github
|
|||
|
||||
# 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.
|
||||
Yes, you read that correctly! The `.forgebuild/forgebuild{,.source}` task provided in this repository is a proof-of-concept autoupdater that will download and install forgebuild 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!
|
||||
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 `forgebuild.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!
|
||||
If a feature is missing for you, or you encounter a bug, please report it on [tildegit](https://tildegit.org/forge/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