starbreaker.org: thaumaturgy

Local Git Runners Using Git Hooks

2026-07-10T19:05:47-04:00

First, a bit of context. This post was prompted by a question on discourse.32bit.cafe about implementing a Deploy to Neocities Action via Forgejo. The poster was using the git forge provided by 32bit Café to host their website’s git repository, and they wanted the latest version pushed to Neocities whenever they pushed a commit. They couldn’t figure out how to do what they wanted there, so they had wanted to know if they should mirror to GitHub and use GitHub actions.

As I told them, they could use git hooks to run arbitrary actions on their local computers. I had also noted that this was something I should do myself. I build my website with GNU make and GNU Emacs, and had been manually running make in my terminal or in Emacs with C-x p c.

What follows is how I ended up going about it. I implemented a post-commit and a post-merge hook, because I wanted to build my website locally after committing a change or pulling in changes from the remote repository to my local machine. After I’ve described my implementation, I will explain how to use Git hooks with Neocities CLI.

I will not explain how to use make or how to create a makefile, because that is out-of-scope for this tutorial. Nor will I be recording a video or providing screenshots. Neither should be necessary when explaining UNIX shell tools.

If you want to try this at home, Occasional Reader, you should possess the following skills:

basic proficiency with UNIX shell commands
basic proficiency with your preferred text editor
basic proficiency with Git

You will need the following as well:

a working GNU/Linux system with git installed, or Git for Windows with Git bash installed
an existing git repository for your website
a steady hand
the courage to risk making a mistake

step 0: creating a git repository

If it helps make you more comfortable, you might want to create an empty repository in which to practice. For example, I am going to create one under ~/projects/website for use in every example I provide. I use zsh as my interactive shell, so your terminal might look different.

~/projects % mkdir website

You won’t see anything in your terminal unless something has gone wrong. On UNIX and Linux, no news is good news. Therefore, let’s confirm that the directory exists:

~/projects % cd website

You should see something like the following:

~/projects/website %

Notice how the shell provides no feedback save that the path in my prompt has changed. Now that we’re in our new project directory, let’s make it an empty git repository using the following command:

~/projects/website % git init

I got the following output:

Initialized empty Git repository in /home/starbreaker/projects/website/.git/
~/projects/website %

Now that we’ve created a project directory and initiated a git repository, we can continue with the meat of the tutorial.

step 1: creating a `.githooks` directory in your repository

While every git repository comes with .git/hooks/ directory full of example scripts, and it is possible to create new scripts in that directory, that is not my preferred approach.

The contents of .git/hooks are not version-controlled with the rest of the repository, and seem to remain on the local instance of your repository. Therefore, let’s create a directory that will get version controlled:

~/projects/website % mkdir .githooks

We can confirm the new directory’s existence with the following command:

~/projects/website % ls -Al

The -A flag will show all hipen files and directories except for . and .., which respectively represent the current and parent directories. The -l will provide the listing on one item per line, with optional detail. These switches and others can be combined, as shown above. The output should resemble this:

total 8
drwxrwxr-x 7 starbreaker starbreaker 4096 Jul 10 20:05 .git
drwxrwxr-x 2 starbreaker starbreaker 4096 Jul 10 20:44 .githooks
~/projects/website %

step 2: telling `git` to use `.githooks`

Before we create our hook script, let’s first update the git repository’s configuration to look for hooks in .githooks. git provides subcommands for that purpose, as shown below:

~/projects/website % git config core.hooksPath .githooks

As usual, the terminal yields no feedback if the command runs successfully. However, you can verify for yourself that your command worked with the UNIX command grep. Here is how I did it:

~/projects/website % grep -n hooks .git/config

Running grep -n will print the line number on which any matches appear. This can be prove extremely useful if you find yourself accessing a remote computer, need to alter a configuration file, and the only available text editor is ed(1) (the standard UNIX text editor). The result should resemble the following:

6: hooksPath = .githooks

As Stephen King wrote in The Stand as a bioweapons researcher’s last words: Now you know it works. Any questions?

Check your progress thus far.

If you’ve been following along, you should have done the following:

created a project directory
initialized a git repository
created a hipen .githooks directory
configured your git repository to look for hooks in .githooks instead of .git/hooks

if you aren’t sure, now’s a good time to backtrack. ls and grep are safe to use; they won’t change anything on their own. If it turns out you’ve made a mistake or skipped a step, and you just want to start over, type the following commands:

cd ~/projects
rm -rf website

These will take you out of the website directory, and then nuke it.

step 3: implementing a `git` hook as a `bash` script

Now we come to the fun part. Type nano .githooks/post-commit to open an empty file called post-commit inside the .githooks directory.

The following is a sample shell script. I will provide it in its entirety first, and then explain how it works. My explanation will assume that this is the first shell script you’ve ever written.

~/projects/website % cat -n .githooks/post-commit
1   #!/usr/bin/env bash
2
3   # 🄯 2026 Matthew Cambion (matthew.cambion@starbreaker.org)
4   # Available under the GNU General Public License (GPL) v3
5   #
6   # a git post-commit script that does nothing but change directories
7   # and print a silly message for illustrative purposes.
8
9   set -euo pipefail
10
11  CURRENT_DIR=$(pwd)
12  REPO_DIR=$(git rev-parse --show-toplevel)
13
14  cd "$REPO_DIR"
15
16  echo "It’s a MEWNIX system! My cat knows this! 😺"
17
18  cd "$CURRENT_DIR"
~/projects/website %

source code listing generated with projects/website % cat -n .githooks/post-commit

As promised, I will explain this script line by line. This could take some time, Occasional Reader, as I do not wish to assume prior knowledge on your part and thus gloss over a detail that might trip you up.

line 1

Line 1 is a requirement for this file to be executable on its own. It’s called a ‘shebang’ in the trade. It allows the script to interpret itself when run from a command line after you’ve made it executable with chmod—which I will explain shortly.

The classic UNIX shebang is just #!/bin/sh, but that is a bad idea on modern systems, because /bin/sh is not necessarily the classic Bourne shell from Version 7 UNIX (which was a AT&T Bell Labs project, not Treadstone, if you’re thinking of Jason Bourne).

However, it is a bad idea to use the classic shebang on modern systems, because it makes unsafe assumptions about the nature of /bin/sh, which could be an alias for another shell depending on your system. On my system, Debian GNU/Linux 13 (trixie), /bin/sh actually points to dash which is Debian’s variation on the Almquist shell.

In the interests of consistency, standard practice when writing shell scripts is to use /usr/bin/env bash to explicitly request the use of the Bourne-again shell, which is the GNU project’s implementation of the Bourne shell. Using #!/usr/bin/env bash tells the operating system to first figure out where bash actually lives, and then use it. This is necessary because not all GNU/Linux distributions place bash in the same directory path. It could live in /bin or /usr/bin. And on BSD systems and macOS, it could live in /usr/local/bin or even /opt/homebrew/bin, since macOS standardized on Zsh to avoid including code licensed under the GNU General Public License.

(An explanation of FOSS software licensing politics is outside scope.)

lines 3-7

These lines begin with # to indicate to the shell that they are commentary for human readers and not to be interpreted as commands. If you wanted to disable a particular command, you could also place a # in front of it; this is called ‘commenting out’. Not all programming languages use # to indicate a comment, however.

line 9

This line sets options for the shell to be as strict as possible when interpreting this script. In the interest of safety, we want the shell to be as pedantic as a typical Hacker News or Repit commenter. Otherwise, depending on what this script actually does, a failure could have unexpected and potentially catastrophic consequences. And by catastrophic, I mean you’d damned well better have a recent backup, or you’re going to have a really bad time.

-e halts the script on any error
-u halts the script when using an undeclared variable; if this happens, check for typos in variable names first. (I know this from experience.)
-o pipefail isn’t directly relevant here, but I include it because it’s a good habit to maintain when shell scripting. It will ensure that the script fails immediately if any command in a pipeline fails.

line 11

This line executes the pwd (print working directory) command and stashes the result in a variable called CURRENT_DIR instead of send it to your terminal.

line 12

This line declares and sets a variable called REPO_DIR by using git rev-parse --show-toplevel to get your current project’s root directory. This is handy if you want this script to work in the repository’s main directory, and not fail because it can’t find something in a subdirectory where you had actually run git commit.

line 14

This command will have the shell change its working directory to the path stored in $REPO_DIR. When declaring a variable, you do not prefix it with a dollar sign, but this is mandatory when using a variable. Also, because of how shell variable expansion works, it is safest to access a variable as shown in lines 14 and 18.

line 16

This line is strictly for illustrative purposes. All it does is print a silly message to the standard output, which is usually your terminal. I used the echo command here because it is perfectly safe by default; it does not change anything on your system.

line 18

This is similar to line 16, but uses cd to reset the working directory to where you were when you ran git commit.

Now, let’s talk about cat -n, shall we? It isn’t directly relevant to this tutorial, but since I used it I think I should explain it. cat is short for ‘catenate’, and will take whatever file or set of files you specify and dump their contents into your terminal. If cat dumps multiple files, it will combine their contents in sequence.

(A careful reader may have observed that -n provides the same functionality for both grep and cat.)

Pause here.

If all of that seemed like a lot for a script that’s less than 20 lines of code, I don’t blame you! That probably took you at least as long to read as it did for me to type! Now would probably be a good time to stand up, stretch, use the toilet, and get yourself a glass of water and perhaps a small, healthy snack.

step 4: testing `.githooks/post-commit`

Feeling better, Occasional Reader? We’re past the hard part, I think.

If you’ve typed out the shell script I described in the code listing in step 3, now it’s time to test it. Unless you’ve skipped ahead because you’ve written shell scripts before, this script isn’t actually executable yet. That need not stop us, however. Type the following to test your script without making it executable.

~/projects/website % bash .githooks/post-commit

If you haven’t made any mistakes, you should see the following on the next line.

It’s a MEWNIX system! My cat knows this! 😺

If you had typed the cat emoji but don’t see it, you might not have a suitable monospace emoji font installed. This is fine; the emoji is just for flavor in this tutorial.

If running the script doesn’t yield the result I’ve described, you might want to install the shellcheck tool. It will identify any mistakes you’ve made so that you can fix them. I would also suggest that if you mean to do any shell scripting, then you should install shellcheck and use before running any script for the first time. It should save you some headaches.

step 5: making `.githooks/post-commit` executable

Now that we’ve confirmed that this script works, we need to ensure that it can run without our help. First, let‘s take a look at the script’s current permissions with ls -Al .githooks. The results should look somewhat like this:

-rw-rw-r-- 1 starbreaker starbreaker 442 Jul 10 23:15 post-commit

The -rw-rw-r-- part indicates that for the user who owns this file and their group (both ‘starbreaker’ in my case), this file is readable and writable, but not executable. Anybody who isn’t ‘starbreaker’ doesn’t get to alter this file; they can only view it.

The simplest way to make this file executable is to type chmod +x .githooks/post-commit. Afterward, when you run ls -Al .githooks again, you should see the following:

-rwxrwxr-x 1 starbreaker starbreaker 442 Jul 10 23:15 post-commit

This indicates that the file can now run on its own if you type https://starbreaker.org/.githooks/post-commit. The https://starbreaker.org/ is important when running shell scripts that live in directories not listed in echo "$PATH", because it’s a shortcut that tells the shell to use the current working directory as a starting point for finding the script you want to run.

step 6: aping `.githooks/post-commit` to the repository and committing the change

If you are satisfied that .githooks/post-commit works, now is the time to your git repository and commit it.

This typically involves two commands:

git ap .githooks/post-commit
git commit

If you’ve followed every step without making any mistakes—and it’s perfectly OK to make mistakes on your party computer!—you should see output similar to the following:

It’s a MEWNIX system! My cat knows this! 😺
main (root-commit) 37389c8 this is a test.
1 file changed, 18 insertions(+)
create mode 100755 .githooks/post-commit

See that silly message? That proves that git ran .githooks/post-commit as soon as it had committed your change. It then dumped the commit details to your terminal on the subsequent lines.

This means you’ve successfully implemented a post-commit hook for your git repository.

enjoy a victory fanfare:

Download audio

step 7: using the Neocities CLI in your post-commit script

Open up .githooks/post-commit and replace line 16 with neocities push "$DST_DIR", where "$DST_DIR" is where the result of your build step goes. Whatever commands you use to actually build your website should go before the invocation of neocities push "$DST_DIR". In my case, that would be make -j$(nproc), but my makefile also uses rsync to deploy to Nearly Free Speech.

Save the file, but don’t commit your changes yet. Instead, manually run .githooks/post-commit first. The Neocities CLI page does not indicate whether you still need to run the neocities CLI manually the first time in order to log in.

Once you are satisfied that the updated .githooks/post-commit script works as indended, you can stage and commit your changes.

Caveats

The post-commit hook only fires when you commit changes. If you want to build or deploy after pulling changes, you might want to use the post-merge hook. If you want to build or deploy after checking out a branch, consider using the post-checkout hook.

If you work with your repository on multiple machines, you will have to carry out step 2 on every machine on which you want to run automatic builds and deployments.

Some of the location checks and movements aren’t strictly necessary when git runs these scripts, but I’m paranoid.

optional reading

A Place for Every Page and Every Post in Its Place

2024-08-09T20:24:22-04:00

Preface

Please bear these caveats in mind, Occasional Reader:

The following is intended to be part of the 32bit Cafe "Back to School" Code Jam.
I use ‘directory’ instead of ‘folder’ because I grew up on DOS and UNIX, operating systems whose main interface was a command line. It’s rather like the way my wife talks about putting groceries in ‘the boot’ instead of ‘the trunk’ because she’s an Aussie. Commonwealth English and US English aren’t quite the same, and terminology applicable to command-line interfaces may differ from that used in graphical user interfaces (GUIs).
I do web development at my day job, but I am not a teacher. While I am trying to provide a reasonably comprehensive explanation of how directory structures work when building websites, I may unintentionally skip over some fundamentals because they are so familiar to me as to seem unworthy of mention. If you trip over an unmentioned fundamental, that’s my fault, not yours.

Background Info

I recently received an email from a visitor to one of my other websites. They have a dream of self-hosting their own website and writing a simple static site generator, and while they’ve seen many directory structures for generating a static site, they have seen far fewer for a website once it’s been generated. In particular, they asked about how to structure a blog that only gets a few posts each year, where each post might have one image, no images, or (rarely) many images. They wanted to know if each post should have its own directory, even if it has no assets.

The sensible thing would have been to answer them immediately and tell them that they can indeed do that, but it had occurred to me that an explanation of how URLs on the Web are shaped by directory structures might be of use to a wider audience while also giving my correspondent information they can use to make informed design decisions.

This post is an initial, rough attempt at explaining how to structure a static website for deployment whether it’s hand-coded, generated with tools you created yourself, or generated with popular tools like Jekyll and Hugo. Where appropriate I will refer to a tool’s documentation. I may get things wrong or leave things out (see my notes above). Suggestions and corrections are welcome; you may email me if you have any questions.

The Short Short Version

You can have a separate directory for each post if you want.

the shortest wedding ceremony in Druish history - Spaceballs (1987)

The Short Version

The computer generally does not care about your website’s directory structure.

You can have a directory for each post if you want to, but this is not necessary. You can also put all of your posts in a single /blog directory. You can even put all of your blog posts and pages in the same directory as your homepage, if you want, along with all of your images, stylesheets, and JavaScript code.

However, once you publish your website, your directory structure becomes part of each page’s URL, or "uniform resource locator", which is the address at which that page can be located on the internet. Incidentally, URL is often used interchangeably with URI, or "uniform resource identifier". It is important to remember that if you change the directory structure afterward, you change your pages’ and posts’ URLs, and cool URLs should not change, because if a page’s URL changes then anybody who links to that page must now deal with a broken link in their website, and this can be annoying.

The Long Version

This is where things may get a bit complicated. There may be information and concepts here with which you might already be familiar, but to make this post as useful as possible to as many people as possible I prefer not to assume too much knowledge on the reader’s part.

Why Do URLs Have Slashes?

Let’s consider the following URL as an example: https://32bit.cafe/sitemap/index.php. You’ve seen addresses like these before, but might not have given much thought to their structure. A URL can have several parts, as shown below:

the protocol used to access the URL, in this case https://: hypertext transfer protocol (HTTP) over secure socket layer (SSL)
the domain: 32bit
the top-level domain (TLD): .cafe
the root directory, which is the first single slash (/) in the URL
a subdirectory: sitemap/, which ends with a slash.
the file containing the sitemap: index.php

As suggested above, each single slash in https://32bit.cafe/sitemap/index.php is a directory separator. Every website has a root directory, which is the primary directory that contains all subdirectories. A website’s root directory is generally mapped to its domain, in this case, 32bit.cafe/.

Do I Need to Include the Filename?

In the example above, I used an explicit URL: https://32bit.cafe/sitemap/index.php. However, the following address would lead to the same page: https://32bit.cafe/sitemap/.

The latter is what’s called a "clean url", and has been popular for a long time. Many people think that such URLs are easier for people to read, and better for SEO (or, manipulating Google), since they leave out repetitive and irrelevant implementation details.

How do clean URLs work? The answer lies in the software that serves websites, HTTP daemons like Apache and Nginx.

Commonly used web server software can be configured to return a particular file by default of the requested URL ends with a directory instead of a file. This file is usually index.html on static sites and index.php on blogs built with content management systems (CMS) like WordPress. Other somewhat less common extensions include the following:

.shtml for web pages that use Server Side Includes (SSI)
.htm for static HTML pages created on DOS and Windows
.asp for web applications built using Microsoft’s (long obsolete) Active Server Pages
.aspx for web applications built using ASP.NET
.jsp for web applications built with Jakarta Server Pages

You can even configure a web server to use index.txt as the default page, but that would just mean the server is sending a plain text file with no structural markup or interactive elements. Nor does your default file for a given directory have to start with ‘index’. One could, for example, set the default to homepage.html. Furthermore, one could also configure one’s web server to list every file in the directory instead of providing a default page, though this is often considered a security risk.

It bears mentioning, however, that if you want to have full control over your web server’s configuration you must either have control over the physical server, be using a virtual private server (VPS), or be on a hosting provider that uses Apache and lets their users create .htaccess files. I am not aware of an equivalent to .htaccess for Nginx, a popular alternative to the Apache web server. Nor am I aware of an equivalent for Microsoft’s IIS (Internet Information Services), but I’m equally unaware of anybody using that for a personal website.

Short version: if you’re on Neocities or a similar free host, you won’t have access to these settings.

So, how should I lay out a site that I’ve generated?

If you’re building your website by hand, you can do it any way you like. For example, you might decide to party like it’s 1996.

/index.html
/styles.css
/cancer.js
/rss.xml
/images/
/about.html
/contact.html
/blog/index.html
/blog/iron-maiden-rules-ok.html
/blog/they-live-is-documentary-about-republicans.html

a small blog without clean URLs

You could also modernize a little, like so.

/index.html
/assets/styles.css
/assets/cancer.js
/assets/images/
/feed/index.xml
/about/index.html
/contact/index.html
/blog/index.html
/blog/iron-maiden-rules-ok/index.html
/blog/they-live-is-documentary-about-republicans/index.html

a small blog with clean URLs and assets tucked into its own directory

Either of the examples above will work for a small blog whose operator doesn’t post often. However, a website with a blog that gets several entries per week, or even per day, might become unmanageable quickly with such a simple structure.

To keep things tidy, many blogs—especially those built with WordPress or with a static site generator (SSG) like Jekyll or Hugo—will incorporate each post’s creation date into its URL. Here’s an example.

/index.html
/assets/styles/main.css
/assets/scripts/main.js
/assets/images/
/feed/index.xml
/about/index.html
/contact/index.html
/blog/index.html
/blog/2024/07/31/iron-maiden-rules-ok/index.html
/blog/2024/08/11/they-live-is-documentary-about-republicans/index.html

a small blog whose entry URLs contain creation dates in YYYY/MM/DD format

A directory structure like the one shown above can not only be used to create URLs that tell visitors how old a post is, it can ensure that a given directory doesn’t have too many posts in it. The format for blog post URLs is as follows:

All blog posts go in /blog/.
Within /blog/ are nested subdirectories containing the year, month, and day of a given blog post’s creation date.
Inside the day directory is a directory for the blog post’s "slug", which is the post’s title with spaces converted hyphens and other characters removed. Sometimes extraneous parts of speech like articles and conjunctions get removed as well.

While I’m assuming that all images would go in /assets/images/, this is not a requirement; you can place all images for a blog post in the same directory as its index.html file. You can even have separate stylesheets and JavaScript files for each blog post and page by placing these assets in the same directory, though there’s nothing stopping you from placing as many stylesheets and JavaScript files in their respective directories and linking to them as needed.

What about SEO?

I’m not the person to ask about SEO. I’ve been told that using clean URLs that incorporate a post’s keywords and indicate the date it was created can help, but I’ve never seen any evidence of this. Furthermore, it appears that Google no longer gives much consideration to personal websites, and does not send traffic your way if it can instead mine your website to train its AI and keep people on search engine result pages where they can show people ads.

I would, therefore, advise against giving too much consideration to SEO. This is especially the case if your website is a hobby rather than a side hustle.

So, What Should I Do?

Try to think ahead and consider the maintenance challenges your future self might face. But don’t let your future self rule you. The person you are right now is the person designing your website. You should, above all else, do what you want to do.

Most of what you’ll read about “best practices” will prove irrelevant to you. Best practices are for commercial and institutional websites. You are not obligated to build your website as if it were intended for commercial or institutional use. If you’re not getting paid to do this for somebody else, you might as well have some fun.