Final README \o/

README.md

@@ -53,7 +53,10 @@ For an example of a multi-host setup, you can check out [my own ~/.git-build](ht
 
 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). 
+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/`
 
 Here's an example simple task that writes the current time to `~/.git-build/t.log` and appends random characters to another file:
 
@@ -71,15 +74,63 @@ hexdump -n 16 -e ' /1 "%02x"' /dev/urandom >> ~/random.list
 
 ## Shared build scripts
 
-A script for multiple tasks
+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
+```
+
+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`:
+
+- ~/.git-build/task1 task1 # when task1.source was updated
+- ~/.git-build/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`.
 
 ## Ordering tasks 
 
-Auto-updater example and lockfile mechanisms
+`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`.
+
+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:
+
+```
+# Wait for git-build.sh to stop running
+SECONDS=0
+while [[ $SECONDS < 60 ]]; do
+	if [ ! -f $GITBUILDDIR/.LOCK ]; then
+		# We're done waiting, the road is free!
+	fi
+	sleep 1
+	SECONDS=$(( SECONDS + 1 ))
+done
+
+exit 1 # TIMEOUT
+```
 
 ## Versioning
 
-Keeping your ~/.git-build in git \o/
+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:
+
+```
+#! /bin/bash
+
+cd ..
+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`:
+
+```
+*.log
+*.err
+.*/
+```
+
+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.
 
 ## Auto-run tasks