markjgsmith

I've been having to switch a lot between git's high level and low level mental models the past few days. It's a bit jarring initially as you realise a lot of the things you rely on day to day aren't actually real. I wrote about that yesterday in my It's all an illusion post. It's not actually all that bad, but it does take a bit of getting used to. I put this cheatsheet together so I have something to refresh my memory next time I need to switch between the different models.

1. The Core Mental Model (The Chain of Commits)

At its absolute foundation, a Git repository is a web of history built from commits linked together in a Directed Acyclic Graph (DAG). Rather than a single straight chain, commits can branch out into parallel lines of development and merge back together. Every commit explicitly points backward to its parent commit(s), zero parents for a root commit, one for a standard commit, and two or more for a merge commit. Pretty much everything else in Git—branches, tags, remotes, and HEAD—does not store code or alter this fundamental graph. They are simply lightweight, mobile pointers that sit on top of specific commit nodes within this network.

2. Pointers & References (The Imaginary Layers)

• Tags: Lightweight tags are literally just text files in .git/refs/tags/ containing a single 40-character commit hash. (Annotated tags add a tiny metadata object pointing to a commit).

• Branches (and Backup Branches): A branch is just a text file in .git/refs/heads/ containing a hash that points to a specific commit. When checked out, Git automatically updates this pointer to the newest commit created. Because it isn't a special entity, creating a "backup branch" is simply placing another pointer file on a specific commit node. This guarantees you can always navigate back to those commits by traversing backward through parent references in the acyclic graph.

• Remotes (Remote Tracking Branches): Files in .git/refs/remotes/ containing a hash pointing to the commit your local Git thinks a remote server's branch was pointing to the last time you communicated.

• HEAD: A single reference file (.git/HEAD) pointing to the active branch file (or directly to a commit hash when detached). It tells Git where to attach the next commit.

3. Objects & Storage (The Underbelly)

At the lowest level, everything in Git falls into two distinct categories: files on disk inside .git/ (the plumbing implementation) and content-addressable objects (the logical data structures).

• The Staging Area (The Index): Located at .git/index, this is a single binary manifest file. Think of it like an embedded key-value database stored in a flat file—mapping file paths directly to blob hash keys alongside cached file system metadata. git add writes file contents into the object store as blobs, then records their paths, hashes, and permissions into this index.

• The Object Store (.git/objects/): This is just a flat directory on disk where Git stores all immutable core objects as individual files (compressed using zlib, named by their SHA-1 hash). Unlike the index, it is not a database file; it is simply a content-addressable storage folder containing four primary types of objects:

  1. Blobs: Raw file contents stored without names or paths. If two files anywhere in your repo have identical content, Git stores them only once.

  2. Trees: Directory structures that map filenames and permissions to specific blob hashes or sub-trees.

  3. Commits: Objects that bind a top-level root tree pointer, parent commit hashes, author metadata, and a commit message.

  4. Tag Objects: Metadata wrappers (containing tagger info, date, and messages) that point explicitly to a commit object (as opposed to lightweight tags, which are just text pointer files).

4. Graph Operations & Commits

The 5 Components of a Commit: Every commit object is constructed from exactly 5 pieces of information:

• Rebase as Copying: A rebase is an automated copy operation. It takes a sequence of commits and recreates their changes as brand-new commit objects with new hashes and updated committer timestamps (while retaining original author dates), chaining them onto your target destination commit.

• Reset (git reset): git reset is the primary operation you use when you want to "delete" or "undo" commits. However, technically it is purely pointer manipulation rather than actual deletion: all it does is make your active branch pointer point at a different commit in the acyclic graph commit history. Optionally, it leaves changes in your working directory and staging area (--soft, --mixed) or clears them out (--hard), leaving any unreferenced commits behind in the object store.

5. Connecting High-Level to Low-Level (Plumbing vs. Porcelain)

• Porcelain vs. Plumbing Commands: High-level user commands (git checkout, git commit, git merge) are called Porcelain. Low-level internal inspection/manipulation commands (git cat-file -p <hash>, git ls-tree, git update-ref) are called Plumbing. Looking at objects via plumbing reveals that the high-level commands are just convenience wrappers over reading/writing .git/ pointer files and object hashes.

• Orphaned (Dangling) Commits & Reflog: When references move away (via reset, rebase, or branch deletion), old commits remain in the object store. They become "dangling" or orphaned commits simply because they are no longer reachable by walking backward from any active branch or tag reference. The Reflog (.git/logs/) acts as a safety journal recording every past position of HEAD over the last 90 days, enabling recovery of any unreferenced node by repointing a reference back to it.

• Three-Way Merge Engine: A merge isn't a magical comparison between two branch tips. Git finds their Common Ancestor node in the DAG, generates diffs from Ancestor → Ours and Ancestor → Theirs, combines those diffs, and creates a single Merge Commit with two parent hashes.

It can seem a bit daunting at first, but this is often the way with software when you look under the surface level because the way humans think about things often isn't the most optimum from a computer architecture perspective. The cool thing about git though is you can easily look underneath the surface level when you need or want to, and it's mostly all just text files so you can open them and see exactly where the various references point to.

In fact reading this cheatsheet and then dumping it into an LLM and then having a conversation about a particular situation you are in will likely lead to good results. You can paste output from commands you run, maybe even have the LLM generate commands for you. Then ask it to analyse the output, showing you which reference points to which commit. You can even get it to generate some ASCII art diagrams representing the situation at hand, that use actual real data from your command output. Be a bit careful, follow the logic through and ask questions because it doesn't always get things right. The LLM is just a probabilistic prediction machine trained on crazy amounts of data, so there are times when it starts getting things wrong, or it suddenly tells you the complete opposite of the thing it said just a few turns before. However it's normally possible to get to the answer to the problem you are looking for eventually.

Just had to do quite the deep dive into git to figure out some issues I was having with my new betas, tags and release candidates system. At some point when you deep dive into git the imaginary edifice of branches, the staging area, your working directory, it all disappears and it's acyclic graphs all the way down, and your head starts to hurt.

OMG branches aren't real! Argh.

Hold on, if branches aren't real what even is happening when I create a quick backup branch? Oh shit backup branches aren't real either.

The staging area where you put your files before you commit them. Not real!

What about the working directory, aka the worktree, not real!

Oh and remotes, not real!

It's all an illusion.

But then after a while you realise it doesn't really matter, everything just kind of keeps working even though it's all completely made up.

Every time I deep dive into git and resurface, it's always weird. It's like you see it's all an illusion, but then you just kind of have to go with it because otherwise you just can't function, because acyclic graphs are gnarly. It‘s very weird to have to switch between these two mental models, from real to imaginary, and back and forth all the time. If you haven't done a deep dive for a while you forget that the metaphors aren't real. It‘s so strange.

Underneath git is really made up of blobs, trees, commits and tags. Everything else, just convenient metaphors built ontop of pointers and files.

I had to put my main development work on the back burner for a few weeks and so I'm just getting back into things the past couple of days. Before I stepped back I had updated my dev workflows to use tags, betas and release candidates, and boy am I glad I did that, because of course when I picked back up the various plates I had spinning, of course several things had stopped working, none of which were anything to do with my code, and all of which had to do with things shifting underneath me.

The project is at the stage where the complexity is on a new level, and had I not come up with the new setup, I would have been drowning in a nightmare, that much is clear. As it happens, I was able to get back into things reasonably quickly and with the LLM summarizing things, analysing code paths, pulling out details from past commit messages etc, I got situated fast and was able to formulate a plan.

One of the reasons I had started to use the new system was kind of a bit vain I suppose. For most of the project I had been using git very heavily locally making very sure to create a very nice and readable git history. That's great if you are reading the history, it make it look like everything in the project was like a perfect story with no gnarly bits. The reality is of course far from that. In reality there were all sorts of really horrendous moments and tons of places where everything was f-ed, but I got through it and made all the commit history look nice. But as I hit this new level of complexity it occurred to me that people might look at the history and think to themselves, did this guy really write this perfect and beautiful code and in such a perfect and beautiful way, or was it just one shotted by an LLM? That thought kind of freaked me out, given how much time and effort I have put into this.

So I decided basically to stop squashing all my commits into nice and perfect larger commits where everything is just perfect and instead keep much more of the intermediate commits along the way. I'm still squashing a bit, but it's more warts and all than before. I reckon it would be much harder to later tell me, you didn't write that. And the tags and betas and release candidates are a way to manage that extra complexity. You create small PRs along the way for all the commits, then when you have a release candidate you do a large beta PR, and in the body of the PR you get the LLM so summarise all the work, and it helpfully sorts all the changes, grouping like commits together, so you still get the nice high level view, and that is followed by a long list of all the detailed commit titles along with their short hashes, which you can cross reference if you need to. It's kind of the best of both worlds.

I have a couple of extra beta releases to do, but I'm running the latest betas in prod with the new functionality which isn't quite finished yet behind feature flags, and so I can be sure that the existing functionality is still working every step of the way, hopefully much less regressions. Seems to be working.

I‘ve been using LLMs now in coding for many months, both for writing code and for writing commit messages. Overall it's tremendous, but there are things to remember.

The code it writes is much better at the function level, than the code I write by hand, because it has been trained on so much code that it can anticipate all the annoying syntax errors that typically can trip you up, but it also has a much better repertoire of the latests and greatest best practices, so it's always coming up with patterns that I would never have thought of. Now while it writes great code at a detailed level, I constantly find that it's not so great at putting those pieces together in a consistent way that makes sense.

Sure it's amazing at one-shoting things, but real code isn't all one-shotted. Real code, you built over time, you remove parts, you add parts, you refactor and re-structure. I've found that I am much better at that than the LLMs, who operate in a world where they have no real sense of the past of or the future, and to the extent that they do, as they run, their memory is constantly getting deleted and compacted.

The other way I use it in code is to write commit messages. In that area, I now use it almost exclusively. It is just so much better at summarizing the code changes I have made than I am. I can copy and paste a git diff of all the changes I have made in a particular feature branch, and it effortlessly returns a perfect commit message, describing the changes using the much better terms and descriptions than I would ever come up with. It does quite often miss things, or add in irrelevant stuff, so I do always have to read and review the messages carefully, but basically I hardly ever write complex commit messages now. There is just no point. The commit messages are much better than what I could have written, they communicate the information I want to get across to the reader much better. Do they sound like they are written by me? Probably not, but that is in my opinion not actually that important when it comes to code and commit messages.

So that's the background, how about with writing content for the blog? How am I using LLMs for that? For day to day posts, like for instance this one, I don't use them hardly at all. Maybe I lookup a few bits of information, but I write the post completely, it's just less tedious, but also I don't want the post to sound like it was written by an LLM.

What about other types of posts, like the latests content creation blog posts I am currently writing? Well honestly I'm just trying to figure that out as I write them. I have been planning them using the LLMs, coming up with an outline of the topics I want to talk about, and generating images. We discuss the various topics, the overall themes and the narrative structure. I often get it to read previous posts I have written on the subject and it accurately and effortlessly summarizes them, extracting the core points, which is enormously helpful. It then generates a rough skeleton of the post, and summaries and images and example code snippets. At some point I decide we have covered all I want to cover and I write the post.

Do the posts sound like I wrote them? I am writing them, but there are times, like with the commit message summaries, when the list of stuff it has extracted or generated based on our conversation, where it's version is just better than what I could come up with, and I have to make a judgement call, and sometimes I just use the exact words it came up with because, it gets across the idea I want to communicate better. And that's what is most important in these technical tutorial style blog posts. I could spend an hour re-writing the entire thing so I came up with every single word and the grammar and punctuation, but you know what, imho that's just not the best use of my time, something which I have very very little to spare.

So that's the current situation. I'm guessing over time I will come up with better ways to work with the LLMs, and iron out the creases, but at the minute I'm sort of in this in between place where I'm not using them as freely in my blogging as I do in my coding, but I am using them. All that to say that if things sometimes sound a little off, well that's probably why.

I‘ve written before about how useful Pull Requests (PRs) are when it comes to content creation, so no need to go into too much detail here again. Basically you can use PRs as content quality gates, a place to house changes before incorporating them into production, work on them collaboratively whether that's with humans or LLMs, run automated processes on said content, and finally safely merge the content into the main production branch.

You want to make content creation as frictionless as possible, using draft branches as collaboration sandboxes, but have explicit control on what makes it into production, and PRs are a tried and tested way to do that. The PR is an explicit decision point where you can promote or reject content, ensuring you not only have complete control on what ends up in production, but that you also have an audit trail should you later want to remember what changes were made along the way.

By using Git branches as flexible sandboxes and PRs as intentional quality gates, content production becomes both frictionless and reliable. You get the freedom to draft rapidly, alongside human colleagues and AI agents, without sacrificing total editorial control over what hits production.

The last few days I wrote a several blog posts about git powered content creation workflows. I wanted something that I could point to that pulled together some of the main concepts, so somebody that was wanting to build such a thing would have a quick way to get up to speed on the possibilities:

• Files, folders, exports, aliases and functions: Explores how to leverage standard OS primitives, flat files and directories, as a resilient, long-lasting storage layer. It details how combining shell exports, shortcuts (aliases), and custom functions transforms the terminal into an efficient, personalized computing and content workspace.

• Templates, Markdown, and Frontmatter: Breaks down how to achieve frictionless document creation. Templates automate structural consistency, Markdown offers a clean and portable text formatting layer with HTML pass-through, and Frontmatter adds structured metadata for easy querying, SEO, and AI integration.

• Git branches and remotes: Discusses why version control isn't just for code. It explains how using a small subset of Git commands, relying on isolated branches as safe drafting sandboxes and remote repositories for backups and syndication, creates a stress-free environment for human and AI collaboration.

• Review and approve workflows: Highlights the power of Pull Requests (PRs) as explicit content quality gates. It shows how PRs function as decision points to promote or reject changes collaboratively, combining rapid drafting freedom with total editorial control before hitting production.

When you are creating documents over and over again, whether it be a document, blog post or configuration files, by copying an old one and deleting/updating the old contents. That's a very error prone process, from getting the file naming, and location right, to ensuring consistent formating throughout.

Wouldn't it be great if there was a repeatable generation process for any text file? Well that's what templates are for, they can eliminate friction and ensure consistency across everything you write.

Also wouldn't it be great if there was a easy going file format for content creation, that wasn't too complex, with just enough syntax to write basic documents. And wouldn't it be great if there was a way to attach arbitrary meta data to these documents which you could use in all sorts of interesting ways, including seamlessly flowing them through LLMs/AI? Well that's what Markdown and Frontmatter are for.

We are going to look at all 3 of these things.

Templates

First let's demystify templates, what they are and how to use them.

A template is a skeleton file containing static structure combined with placeholder dynamic data.

Here's a basic example:

Template source (src/template/hello.hbs):

This example uses the handlebars templating language:

Hello {{recipient}}!

Here are your tasks for today:
{{#each tasks}}
- {{this}}
{{/each}}

Data file (data.json):

{
  "recipient": "World",
  "tasks": [
    "Review pull request",
    "Update documentation",
    "Publish blog post"
  ]
}

You can then render the template by running the cli:

$ handlebars src/templates/hello.hbs -d data.json -o output.txt

To get the following output (output.txt):

Hello World!

Here are your tasks for today:
- Review pull request
- Update documentation
- Publish blog post

Notice how not only has the recipient variable has been replaced by the corresponding value from the data file, but also that the template rendering process has iterated over all the tasks in the data file using the #each loop and inserted them into the template.

You can use templates for virtually any text format: source code scaffolding, configuration files, daily notes, and blog post drafts just to name a few.

You typically execute templates in one of two ways:

1. Via CLI commands: Executed directly in your terminal to quickly scaffold new files and automate workflows. You would need to install a community built CLI such as hbs-cli.

2. Programmatically: Integrated via libraries and packages in various programming languages to generate files dynamically within software.

There are many template languages, here are some of the most popular:

• Handlebars: A popular logic-less templating engine using braces {{ }} and block helpers like {{#each}}, serving as a robust default for many text-generation tasks.

• EJS (Embedded JavaScript): Uses standard JavaScript syntax inside tags (<% %>) for simple scriptable templating.

• Pug (formerly Jade): Focuses on clean, indentation-based syntax to write concise HTML structures without closing tags.

• Twig: A robust, feature-rich templating engine widely used across PHP ecosystems.

The point is that templating is a mature technology that has many different implementations. You don't need to learn all of them. You will normally settle on one based on both your personal experience with programming languages and perhaps the domain you will be operating in.

To give you a sense for the universal utility of templates, here is how they can fit in across industries, they aren't just for software engineers. They can streamline repetitive text creation for any professional or industry:

• Software Engineering & DevOps: Scaffolding microservices, Kubernetes manifests, boilerplate configuration (.env, CI/CD pipelines), and API documentation.

• Writing & Content Creation: Standardizing blog post layouts, newsletter issues, video production scripts, and editorial checklists.

• Business & Operations: Generating client invoices, project proposals, meeting agendas, weekly status updates, and customer support responses.

• Legal, Finance & Healthcare: Auto-filling standard contract clauses, compliance reports, patient intake structures, and recurring financial statements.

• Personal & Knowledge Management: Structuring daily log entries, workout trackers, travel planning sheets, and book summaries.

Markdown

Markdown is a text file format that implements the most common text formating features you actually need when writing, like headings of different sizes, bold or italic text, numbered lists, bulleted lists, hyperlinked text. Checkout this cheatsheet for the full feature set.

Here is an example markdown file:

# Building Portability First

When constructing workflows, **simplicity** is key. 

Key principles:
- Keep files flat and readable
- Store metadata near the content
- Rely on unix primitives

For detailed dotfile examples, visit github.com/mjgs/dotfiles.

<div class="callout-box">
  <p>HTML elements like this pass straight through to rendered output!</p>
</div>

It's a little odd to look at initially, but what you'll find is that very quickly you are able to parse full markdown documents as if they were typical text documents. They strike just the right balance of text and markup language. And most often you will be editing them in Markdown editors in any case, that render a beautiful UI ontop of them, and you can switch between the raw markdown and the nicely rendered text with one click or a button press. It's nice to know that no matter what, you can move them to any system and at least bee able to read them with a classic text editor. They are extremely portable.

With markdown you can keep your focus on content rather than on styling tags.

One of the other nice things about markdown is the HTML pass-through. Markdown files are very often rendered to HTML. A key feature is its flexibility: you can drop plain HTML directly into the text file (as shown above), and it passes straight through to the rendered HTML page whenever you need custom control.

Also with markdown files you get AI-native readiness by default. Because LLMs are trained extensively on plain text and Markdown, your notes, posts, and documentation are instantly readable and processable by AI tools without custom parsing layers.

Frontmatter

Frontmatter acts as a structured metadata layer at the very top of a plain text document (typically using YAML, TOML, or JSON enclosed in triple-dash --- delimiters).

Here's an example markdown file with YAML frontmatter:

---
title: "Templates, Markdown, and Frontmatter"
date: 2026-10-31
draft: false
tags:
  - workflow
  - markdown
  - handlebars
author: mjgs
---

# Building Portability First

Here is where the body prose begins...

While it shines brightest when paired with Markdown, frontmatter can augment many different text file formats by injecting variables, dates, titles, tags, and status flags.

Some practical applications of metadata:

• Website & Static Site Generators: Tools extract frontmatter to generate tags (page title, SEO meta tags, social sharing cards), populate layout navigation, render publication dates, and filter content by categories or tags.

• Content Querying & Indexing: Build dynamic archive pages, search indexes, or tag clusters based on frontmatter properties without having to parse the full body prose.

• Publishing Workflows: Automated build scripts can check flags like draft: true to skip unpublished posts during site generation or deployment pipelines.

There is broad ecosystem support for both markdown and frontmatter, from static site generators and web frameworks (Hugo, Jekyll, Astro, 11ty) to knowledge management and note-taking apps (Obsidian, Logseq), to headless CMS' and flat file platforms (Decap CMS, Ghost).

That's the general idea. You would typically have this integrated into your computing envrionment in some way, for example using exports, aliases and functions, and your .bashrc file, or you might have a custom app.

While templates enforce consistency, markdown provides a clean, flexible container with HTML pass-through, and frontmatter adds structured metadata. Together, they turn your local filesystem into a powerful, extensible system for managing content and code across any domain. The key take away is that by standardising on markdown and frontmatter and designing a sensible file structure, you can have a portable setup that you fully own and control, which you can easily work on with LLMs/AI agents.

I have written many articles over the years about why using git for content is worth considering, but now in the age of LLMs and AI, there are even more reasons to move to git powered content workflows. Here are some of the main ones:

• Commits as precise save points: Ditch messy file names like draft_v1_final_revised_2.docx for a clean history where every change has an explicit, readable reason attached to it.

• Everything is a file: Storing content as plain text or Markdown means you aren't locked into proprietary, closed-ecosystem databases. Your content remains fully portable, future-proof, and entirely yours.

• Pull Requests (PRs) as clean conceptual boundaries: Instead of editing everything live in one chaotic space, every piece of writing (a blog post, note, or resource) lives in its own isolated branch/PR. This gives you a high-level view of your project's evolution without drowning in micro-edits.

• Automated pipelines and syndication: Treating content as version-controlled files lets you hook up continuous integration (CI/CD) to automatically validate formatting, trigger static site builds, or syndicate RSS content across platforms.

• The Agentic Era & Ubiquitous AI: Content workflows are no longer just human-to-human. With AI and LLMs available everywhere, your Git repository acts as the ultimate workspace for human-agent collaboration—allowing autonomous tools to draft, review, lint, and refine your text seamlessly via standard PR workflows.

Another thing to consider is that fact that for content creation day to day you really only need 5% of git. You can completely skip advanced concepts like interactive rebasing, cherry-picking, submodules, or complex merge tools. You just don't need them. However they are there if you ever do for some reason need them, if you are doing something advanced, or working with programmers who do use them.

The point of this post isn't to be a tutorial on git, but just to give a sense for the terminology and the small subset of commands you actually need, here is a list of the most common commands you would be running:

• git status – See what files you've changed.

• git branch – List your local branches so you always know where you are.

• git checkout -b <branch> – Open a fresh drafting workspace.

• git add <file> & git commit -m "..." – Save a local snapshot.

• git log --oneline – View a clean, single-line history of your commit titles.

• git push – Back up your work to your remote host.

• git merge – Bring your finished draft into production.

And it's worth remembering that you can setup exports, aliases and functions in your shell configuration for many of these commands, so that you literally only need to type a few keystrokes to do each task.

Git branches are your risk-free drafting spaces. The main branch of a repo is production. It holds the live published version of your blog, docs, site, configuration files, or whatever text files your project consists of. Feature/draft branches are sandboxes to test bold structural changes, alternative introductions, controversial takes. If an idea fails, delete the branch with no impact on main. You can have multiple articles or edits in progress simultaneously without cluttering up your main workspace. Once you are sure the draft branch fits correctly, you safely merge it into the main branch.

For backup, collaboration and auto-publishing you can make use of remotes. With git you always have a full copy locally, but remotes serve as a full mirror. If your hardware fails, or you accidentally delete something important, your entire writing history remains safe. You also gain automated publishing capabilities, for example pushing your main branch to a remote can automatically trigger static site generators, to build and deploy your live site. You also get asynchronous review, editors and co-authors can review pull requests and leave line-by-line feedback using standard code review-tools.

The thing that really makes git powered content workflows feasible is that modern LLM/AI tools can be used to troubleshoot any git issues you run into. In the past running into a detached HEAD state or a merge conflict meant deciphering terminal errors or searching forum threads, but modern LLMs are trained on a ridiculous amount of scenarios. They have seen it all, and any hiccup is trivial to fix. Simply paste your command and the error output into ChatGPT or Claude and ask "How do I get back to a clean state without losing my text?". The AI is your instant Git coach. You can experiment freely knowing you have an on-demand assistant to guide you out of any state.

Git branches and remotes turn writing from a risky, file-juggling process into a structured, stress-free system. With a tiny command footprint and LLMs on standby to handle edge cases, while opening the door to automated pipelines and agentic collaboration. Treating your words like code gives you maximum control with minimal friction.

It‘s tempting to instinctively reach for databases, proprietary apps or complex SaaS tools when starting new projects, but it‘s worth remembering that there is an incredibly flexible set of tools baked right into the OS. What's more is that they have been tried and tested over many years. That's not to say that they should be used for everything, but they are a great foundation to start building, and often compliment other more complex tools. They are a great way to bootstrap your own custom computing environment, no matter the task.

The first thing might seem very obvious, but they are perhaps the most well known primitive in all of computing: files and folders. They are your agnostic storage layer. In fact on unix / linux operating systems, "everything is a file" is literally part of the entire philosophy. Flat files (markdown, plain text, etc) outlive platforms and apps. They are portable-human readable and naturally ready for AI/LLM tools without custom data pipelines. By designing a thoughtful naming hierarchy and using timestamped paths (e.g. content/posts/2026/2026-01-12-235959-title.md), your directory tree is your database. Standard filesystem tools handle sorting, filtering and indexing out of the box.

On the other hand exports, aliases and functions form your personal workspace engine, turning your terminal into a tailored environment for any task.

• Exports: Give you a way to set environment variables to hold values like the paths to often used directories, so your setup translates seamlessly across machines.

• Aliases: Compress daily repetitive commands into 2-to-3 letter muscle memory commands that you can trigger in an instant. Launch applications with pre-prepared options, navigate quickly across the file system, and a lot more.

• Functions: When aliases start getting too complex, switch to using functions, a way to add logic, accepting arguments, and chaining commands to automate workflows right inside your environment.

A new project is an evolutionary journey. The way to build great architectures is to evolve them out of real usage, real friction, actually using tools to achieve your goal, as opposed to guessing and building everything at once. You start with raw files and folders, add aliases for speed, write shell functions for multi-step tasks, and only build dedicated CLIs or servers when your workflow patterns solidify. Many of my projects started out as a collection of exports, aliases, and bash functions.

This might seem a bit complex, but remember with the help of LLMs, these days you can write functions and more complex custom scripts effortlessly.

Once you have your exports, aliases and functions you can easily add them to your .bashrc file so they are auto loaded when you boot the OS, ready in the background on every terminal you open. While I focus on linux systems, the same features are available on Windows via PowerShell profile scripts.

To give you a better idea of what is possible, take a look at my dotfiles.

Start simple, stay portable, and let your tools grow out of your actual needs.

I had a chance to check out the iPhone Duo earlier in a real life store. After reading a lot of reviews, I was thinking it was going to be some sort of massive brick phone from the 80s or something, but actually it was smaller than I had expected. I mean it is thicker than most phones for sure but each pane is actually kind of thin, it's just thick when its folded. It felt quite sturdy.

The outer screen is about big enough to do simple emailing and web browsing. I tried both Mail and Safari on the outer screen and it looked okay. It took me a little while to figure out the new gestures. Once I got the hang of swiping an app out of full screen mode, it was very usable.

Of course the big draw is the fully open screen, which is very impressive. It's basically a small iPad. Would be great for watching videos. I only had a few minutes to get a sense of the general shape, size and weight.

I didn't get a chance to have two apps open side by side, I couldn't figure out how to do that. That was a bit disappointing, because since I know it can run apps side by side, of course I am wondering if you can run a text editor on the left and a web browser on the right, and use it as a mobile web development machine.

I think if I was just a regular tech user I would probably really like it. As a web developer though, I can't help but wonder what a slightly bigger size would be like. The passport size seems like it might be a bit too small.

I currently have Galaxy A05s, and I am left wondering how cool it would be if the big screen, folded out to a massive double big screen. That would defo be able to run a text editor and a web browser side by side. The other thing, to be honest is that as slick as Apple products are, I am really quite happy with Android as an OS, especially when it comes to running a terminal using Termux.

Anyway, it's an interesting form factor, I was pleasantly surprised.

I just spent all morning searching through all my Gemini chat sessions for a particular conversation thread we had several weeks ago. I remembered that the later part of the thread had the useful information I wanted, where we went slightly off topic and discovered something really interesting.

The search features are kind of limited as far as I can see. It's basically just simple text string matching, with no obvious way to search using date ranges for example. The results do have a date associated with them, but individual threads don't have a created on timestamp when you are just browsing.

In the end I gave up and got on with the day. Much later I realised that perhaps I had had the conversation in ChatGPT, and sure enough when looked I found it pretty quickly. Seems to me we need better search functionality inside the chats but we also need a way to search across all the different vendor chat sessions all at once.

I think over the next few months we are going to start seeing a massive wave of new software releases. It's been a good number of months now that AI agents have been of a high enough quality that many software developers are using them extensively. While so far we have mostly seen vibe coded, interesting, but nevertheless hobby projects, what we are going to start seeing is devs who have been working on much larger projects start to release things.

I'm talking about software projects that would have previously taken large teams months or even years of effort. That can now be achieved by solo developers over a few focussed months. It's going to be really interesting to see as these projects start to surface. I might be one of such devs :)

There's a real potential for very niche products to start emerging. Great time to to be a developer and / or a tech enthusiast.

The gang stalkers were out in force again today, even if they were being more subtle. Part last night's harassment was an individual, who had clearly been waiting for me to arrive walked out in front of me, he was holding a very distinctive red bag. There were also several gangs on either side of the street at specific points making it difficult to cross. It was pretty clearly a setup, they wanted me to walk behind red bag bloke.

It was so obviously a setup too. Everything had been normal, and then when I got to the choke point, if you looked up the street you could see all the various little gangs on either side of the road going on for several hundred meters. I crossed the road anyway, took a diagonal line, and that's when one of the gangs got verbally abusive, several shouting No! at me loudly as I walked out of their trap. It was pretty dangerous as their shouting caused me to look the wrong way, and I very nearly got hit by passing traffic.

Well wouldn't you know it today in the local shop, where I often go for groceries, the girl at the counter started putting my things in a transparent unbranded bag (very unusual), but also didn't ask if I wanted a bag before doing so (very unusual). I politely said I no thank you for the bag, I always bring my own. She obviously got offended in some way (apparently), and started randomly saying No! and Bad! and laughing with here colleague. I said nothing, packed my bag with the things I bought, politely said thank you to them both, and departed.

Perhaps you think I am over reacting? Guess what happened next. On the way back, no less that 3 individuals, in 3 different locations, who were just waiting, loudly said No! to me as I passed. One was on a motorbike who dangerously pulled up directly in front of me. All these events are planned. They are all part of yet another intimidation campaign, carried out by just regular looking people of all shapes and sizes, all races were represented. What had I done to deserve such treatment? The only thing I can think of is it's writing this blog, because I've very much been keeping to myself lately.

People are worried about AI and super intelligence or whatever. I worry much more about people. Whatever they learn training these new AI models can, will and in my opinion clearly is being used by humans on other humans. It's horribly horribly ugly. I personnaly believe it's this sort of thing that causes societal decline, even though likely those doing it believe the opposite. I've seen it and experienced it in one way or another in many different countries, in 3 continents around the world, and it seems to me it's getting worse.

I'm just emerging from a bit of a nightmare related to higher level classes, hence this cautionary note. It‘s particularly relevant if you are coding with LLMs.

The crux of it is quite simple. I had a need to create some decorators, which is a way of dynamically adding new behaviors or responsibilities to an object or class without altering its underlying code. It is a quintessential example of composition over inheritance: instead of creating a rigid, deep subclass hierarchy to add a feature, you wrap the target with a decorator that intercepts or enhances its functionality. At it's core it's just a function that takes the class, method or property as input and wraps it with extra logic, and returns the enhanced version.

They are referred to as higher order function, or loosely as "higher-level" because they are functions that take other functions as arguments or return them. The annoying thing about higher-level functions is that they are tricky to reason about. Taken on their own, not so much, but when they are surrounded by a much bigger codebase, the level of complexity you have to hold in your head gets gnarly fast. But they can be very useful, and in some circumstances it's literally the only way of achieving what you want.

I have used decorators a lot before, in fact in nodejs you are using small versions of these all the time, but I hadn't had to use them to decorate classes before, and that is what the LLM I was working with suggested. As we were tackling a quite tricky thing, it made the case for using some class decorators. It made a lot of sense, and quite quickly we were off to the races. Of course I reviewed the code, but I didn't dig too much into the detail and I certainly didn't think about the longer term consequences.

As if often then case with software, as we continued to work on the feature, we discovered that the initial solution, and in fact the architecture it was embedded in, needed to change, and we set about doing that. This is where things started going off the rails, and at first I didn't notice. In my head it seemed that the higher order function solution was quite self contained, but as we re-architected the code, the LLM re-architected the higher order classes implementation, and in retrospect, it clearly got a bit confused, or just didn't think it through properly.

At a certain point I realised that the LLM had added several layers of indirection, which wasn't totally obvious because it was spread across several files in very different locations, and when I asked about these layers, it had very good arguments for them. They are acting as "runtime binding factories" was one that initially sounded like it could be a real thing that was needed. You have data at runtime that you need injecting into the class you are decorating, so of course you need a runtime binding factory. Duh. Yet somehow the more I asked about it, the more the explanations seemed contrived.

I eventually paused everything and dug into it myself, and painstakingly traced the code through and discovered all these horrific levels of totally unnecessary complexity, with very confusing function names, and to make it worse it had been importing various things and stuffing them inside closures at every level. A real tangled mess. Yet somehow it sort of worked, until you tested it properly, or refactored it slightly and it all fell apart.

I started by trying to rename all the function names to names that actually made sense. Often these ended up being ridiculously long names, which in itself was a sign things were not right. Anyway doing that enabled me to point out how unnecessary much of the cruft was, and soon enough we were able to drastically reduce the number of useless levels of complexity and unnecessary imports and closures.

All that said, the final solution is very neat, and actually not that complex. It's a little bit more complex than normal code, but not that much, and it's only in a very well understood place, and done in a repeatable way. The point is that if you are writing higher order functions with LLMs, it's worth slowing down and really make sure you understand the logic because it gets gnarly fast and the LLMs are unbelievably good at creating a giant knot out of everything and then telling you how great it is.

It‘s really terrible what‘s happening in France with all the school kids rioting. Protesting injustices isn't the issue, that should happen, but the tricky thing is that in this case the fact that they are tearing up the schools is literally making things worse for themselves. If the school system is already at breaking point, and by all accounts, with 45 kids in classes, it certainly sounds like it is, the last thing you want to do is make the situation even worse.

An interesting side note about language, I was looking up the translation of "self-defeating" in french. they have "contre-productif", but in my mind it lacks the "self" part, which is very important to get across the idea that you are hurting yourself. While they also have "auto-destructif", with "auto" from the Greek "autos", which means self, and I do remember it being used in this context, it‘s a strange one where I feel like somehow the modern use is somehow very linked to automatic, and so it‘s been sort of hijacked. To expresss this well you have to use a turn of phrase, like to shoot yourself in the foot ("Se tirer une balle dans le pied"), or to cut the branch you are sitting on ("Scier la branche sur laquelle on est assis").

Anyway while there will be some in the UK that will enjoy some sort of schadenfreude by seeing the french hurting themselves, it‘s a cautionary tale, because especially in a wider economic decline that we are in, and have been for years, this could very easily happen in the UK. It occurred to me that it might be worth getting ahead of this in some way. For universities you could make it into an excuse to have a cheeky pint with fellow students from another city, make it into a day trip, to forge connections, because if you ever do need to protest, you absolutely need it to be peaceful. And to do it right, you have to do it properly, tell authorities in advance, have a safe route etc, because there are those who will try to take it over because if it does lead to riots, they will benefit from you being in an even worse position later. This is the reality we live in, and that is only going to get worse the more along the decline road we get.

I'm not sure how you could extend this to schools, pints are no good for that, but it would be worth having some sort of forum, that doesn't in itself cause problems, because if we ever do get to that stage, where protests are needed, and they can be very powerful, it‘s perhaps the most important thing that it‘s Gandhi style sit downs rather than destroy the school and the neighborhood.

And of course while that's an important thing, equally important is to stop this infernal decline, something which the backs of napkins throughout history can attest to, is also very well suited to such forums.

I just mostly completed a massive refactor of the entire outer shell of my publishing server. A few days ago when I discovered it was necessary I was thinking to myself, oh no yet again Gemini has got me to a summit only to tell me that it all had to be completely redone. That has happened so many times.

It wasn't at all obvious how it could be achieved but the LLM came up withe a pretty awesome plan, though it did take me several hours to figure out what it was on about. Anyway long story short, what seemed completely impossible was actually very doable, as we had already laid the groundwork. So we were able to completely rewrite the entire outer shell, everything inside for the most part remained in the same place, but the outer shell was completely re-architected.

I'm still kind of amazed that it worked. And though I still have a few modules to convert to the new architecture, it's looking really really great.

Late last night, I had an important breakthrough in the next important feature of my publishing software. It's around user onboarding and setup. Very important, and it worked for the first time.

All the pieces got created in all the right places. Still need to write tests and general cleanup but seamless onboarding is on the horizon.

I haven't been posting many links recently. That‘s the thought that occurred to me earlier. I've been busy coding mostly. Anyway I decided to go for a bit of a search for some interesting posts. Pretty quickly I found 4 blog posts that sounded interesting from their titles. This post, this one, this one and this one. I go them all on Hacker News main page.

So I opened all four in 4 separate tabs, git myself a coffee and started reading. Each one starts out looking like it might be something kind of interesting, either because of the topic, or the design or the page, the way the information is organised. But each one upon reading a few paragraphs, I just wanted to die, overcome by such intense boredom, that I lost the will to live and was not able to finish any of the articles.

What is going on? I'm finding it hard to believe that all these articles are written by humans. It's like they have all the appearance of articles written by humans, but they are hollow, like biting into a really nice looking chocolate only to find it is completely empty inside. Just words. Blah blah blah blah. Nothing drawing you in. This is not the internet I remember. Where has the real internet gone?

Oh well. Perhaps tomorrow things will pick up.

I'm at the stage building my publishing server software where having a more defined plan makes sense. I've started using git tags and semantic versioning to plan out the next few releases. Each release happens in stages so you have times where you only have part of the feature set written but you still want a release to test, with uncompleted features behind feature gates. These are beta releases (e.g. 1.1.0-beta.1, 1.1.0-beta.2). Then when you have all the pieces ready you try to put it all together in a release candidate (e.g. 1.1.0-rc.1). Eventually when it's all working you drop the extra qualifiers and you are left with just the version number.

The core of the software is very solid, it basically never changes now, or if it does it's small tweaks. I haven't had to re-record the test fixtures in months. There are several layers that insulate the core business logic, both above it and below. It makes it much easier to change things in the frontend display, and in the backend storage. As well as the core, there are now several extension packages that you can add to get new features, and these layer ontop to create several distributions that work in different environments. There is an assembler that you use to build exactly what you want, with a particular feature set.

Since I'm working with all these packages, although it's a monorepo, the tagging works really well to co-ordinate all the PRs necessary for a release. Gives you something to aim for. When you list all the commits, you can see the ones that correspond to the releases. It really helps with how you think about the code, how you conceptualise what is still to do, and where you are at.

In the last few days I identified a crucial relationship in the core that needs to change slightly in order to move forward. As I was looking at the various distros I revisited an idea I had a while back, to unify all the route handlers. At the time it seemed too difficult, but now it looked possible. I was able to extract all the route handler logic across all the distributions into a core handlers package with the variations between distros neatly inside a thin layer in each distro. The complexity of all the distros has decreased significantly. And it was pretty easy updating the unit and integration tests.

I'm very well positioned now for the final push to make the small change in the core, necessary in order to get 2 very important features working. The world is so crazy at the minute, and I might not know exactly how I fit into it or what's going to happen next in my life, but I know that I'm pretty happy with where the publishing server and the rendering CLI are at. That's the thought what grounds my thinking most right now.