Get started

gw is a simple program, that you can use to pull changes from a remote repository and run scripts on the change.

Prerequisites #

First, make sure, that gw is installed successfully and is in your PATH. If you don't have it, start with Installation:

$ gw --version
0.4.1

The other necessary part is a git repository to which you have pull access. It is recommended to use a repository that you know, but if you don't have one at hand, you can use the daniel7grant/time repository. This is an example repository that is updated in every minute, so it is useful to test the auto update of gw. First clone this repository (if you are using your own, clone again), and enter the cloned directory:

git clone https://github.com/daniel7grant/time.git
cd time

Pull files automatically #

To get started, point gw to this local repository. By default it pulls the changes every minute. We can add the --verbose or -v flag to see when the changes occur:

gw /path/to/repo -v

If you are using your own repository, create a commit in a different place, and see how it gets automatically pulled (in the case of the time repo, there is a commit every minute). The verbose logs should print that a git pull happened:

$ gw /path/to/repo -v
# ...
2024-03-10T14:48:13.447Z [DEBUG] Checked out fc23d21 on branch main.
2024-03-10T14:48:13.447Z [INFO ] There are updates, pulling.

Also check the files or the git log to see that it the repository has been updated:

cat DATETIME  # it should contain the latest time
git log -1  # it should be a commit in the last minute

Run scripts on pull #

Pulling files automatically is useful but the --script or -s flag unlocks gw's potential: it can run any kind of custom script if there are any changes. For a simple example, we can print the content of a file to the log with cat:

gw /path/to/repo -v --script 'cat DATETIME'

This will run every time there is a new commit, and after the pull it will print the file contents. You can see that the results are printed in the log:

$ gw /path/to/repo -v --script 'cat DATETIME'
# ...
2024-10-18T16:28:53.907Z [INFO ] There are updates, running actions.
2024-10-18T16:28:53.907Z [INFO ] Running script "cat" in /path/to/repo.
2024-10-18T16:28:53.913Z [DEBUG] [cat] 2024-10-18T16:28:00+0000
2024-10-18T16:28:53.913Z [INFO ] Script "cat" finished successfully.

You can add multiple scripts, which will run one after another. Use these scripts to build source files, restarts deployments and anything else that you can imagine.

For more information, see Scripts.

Run subprocess, restart on pull #

It is often enough to run scripts, but many times you also want to maintain a long-running process e.g. for web services. gw can help you with this, using the --process or -p flag. This will start a process in the background and restart it on pull.

For example starting a python web server:

$ gw /path/to/repo -v --process "python -m http.server"
# ...
2024-10-06T21:58:21.306Z [DEBUG] Setting up ProcessAction "python -m http.server" on change.
2024-10-06T21:58:21.306Z [DEBUG] Starting process: "python" in directory /path/to/repo.
2024-10-06T21:58:56.211Z [DEBUG] [python] Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

This will run a python process in the background and stop and start it again if a git pull happened. Just wrap your deployment script with gw and see it gets updated every time you push to git.

For more information, see Processes.

Run actions on tags #

Pulling on every commit might not be the fit for every product, especially ones that needs to maintains compatibility or strictly versioned. For these, you can instead trigger on tags. Use the --on tag flag to only pull changes if there is a tag on the current branch.

$ gw /path/to/repo -v --on tag -S 'echo $GIT_TAG_NAME'
# ...
2024-10-18T16:28:53.907Z [INFO ] There are updates, running actions.
2024-10-18T16:28:53.907Z [INFO ] Running script "echo" in /path/to/repo.
2024-10-18T16:28:53.913Z [DEBUG] [echo] v0.1.0
2024-10-18T16:28:53.913Z [INFO ] Script "echo" finished successfully.

This will always fetch the current branch, check for the latest tag on it and pull only the commits up to that tag. To match some kind of commit, you can use the --on tag:v* which will only pull if the tag is matching the passed glob (in this case starting with v).

gw /path/to/repo -v --on 'tag:v*' -S 'echo "new version: $GIT_TAG_NAME"'

Next steps #

If you like gw, there are multiple ways to use it for real-life use-cases.

If you want to put the gw script in the background, you can:

If you are interested in some ideas on how to use gw: