I’m Blake. I write about probability, stochastic processes, Python tooling, and the practical side of building things with code. More about me →

  • Git branch justfiles

    A new recent trick I’ve added to my repertoire: justfiles for each branch I work on.

    It’s well worth reading int the just task runner, it’s become indispensable for all of my projects. My main use for it is documenting and recording those sequences of ad-hoc steps I occasionally need to do in a project.

    But of course, I don’t want to maintain a single massive justfile for every change and branch I do. So I added this script to a new directory called ~/.gitalias:

    #!/bin/sh
    branch=$(git rev-parse --abbrev-ref HEAD)
    
    branch=$(echo "$branch" | tr '[:upper:]' '[:lower:]')
    branch=$(echo "$branch" | sed -E 's/[^a-zA-Z0-9-]+/-/g')
    branch=$(echo "$branch" | sed -E 's/^-+//g')
    branch=$(echo "$branch" | sed -E 's/-+$//g')
    
    justfile=.$branch.just
    
    if [ ! -f "$justfile" ]; then
        $EDITOR "$justfile"
    elif [ "$#" -eq 0 ]; then
        $EDITOR "$justfile"
    else
        just -f "$justfile" "${@}"
    fi

    Then I added this alias to my ~/.gitconfig:

    [alias]
        just = "!~/.gitalias/just"

    So that git just opens a justfile called .name-of-branch.just in my project directory when called without any args (or if the file doesn’t exist yet). Once I’ve defined some steps, I can execute them immediately by using git just <name-of-step> [args] to select the branch justfile with -f, and pass through all arguments.

    If I don’t want to commit these files, I tend to declare them in .git/info/exclude so that they’re only ignored on my local copy of the repo (and I don’t need to declare and commit them to the shared .gitignore)

    echo "*.just" >> .git/info/exclude

    You can define scripts inline a justfile with a shebang, and use the usual substitution syntax:

    my-shell-script my-arg:
        #!/usr/bin/env sh
        echo {{ my-arg }}
    
    my-uv-python-script my-arg:
        #!/usr/bin/env -S uv run --script --quiet
        # /// script
        # requires-python = ">=3.12"
        # dependencies = [
        #     "rich",
        # ]
        # ///
        from rich import print
        print("Hello, [bold magenta]{{ my-arg }}[/bold magenta]!", ":wave:")

    You can even “layer” justfiles by importing rules from another justfile (such as the roles for the main branch at .main.just) by adding import '.main.just' at the top of the file opened by git just

    Every time I look at the amazing documentation of this tool I seem to learn something new! Thank you for this @casey

  • Bringing certainty to new AI norms with a contract

    Further into this technological chapter, I’m noticing a few more voices out there who appear to have scaled the cliff of anxiety and inexperience that we’ve all felt (to some degree) when faced with new AI tools.

    From what I’ve observed, the roots of a lot of the discourse around AI tool and their discourse is split into 3 categories:

    • Snake oil being peddled to hype products and financial investments
    • People are buying into the hype in search of the mythical silver bullet (Which, is much less straightforward than it appears — something to write about another day)
    • People are genuinely worried about their future and how it’s impacting their industries and practice

    I wont address the first two groups (my cynicism can wait for another day). But since the imprecise start of this gold rush, I’ve been thinking a lot about the third group — which I hypothesise is the largest share of the AI-concious population.

    Different industries have had vastly different experiences to this age, a complete picture is outside my scope of expertise. Creative industries for instance have had to face quasi-existential questions in response to the advent of generative AI, which I’m not equipped to answer. My industry of software engineering has probably been the most receptive industry as there are less issues with ownership of code. Aside from ill-advised layoffs, I’ve relatively made peace with it here. But in academia and education, I’ve been considerably more worried.

    I want to focus on the realm of education today, because I think there’s some emergent lessons here (pun intended) that may have wider application to our collective experience today.

    Education is more than a passion for me. I think it’s a source of hope, and core to the human experience in how we tell stories and help one another. It’s why I love mentorship opportunities throughout my career. It seems my roots as a mathematics tutor have never left me, and don’t plan on going anytime soon

    A year ago, an article by Piers Gully — an English professor at UVA — shared his experience in the modern classroom with the “homework machine”. As I had feared, his personal account revealed how AI was negatively affecting students critical reasoning skills. When you’re being judged on your performance, it’s hard to argue against using these tools since your peers are likely to be using them too, leading to an imbalance of grades where higher grades are no longer proportional to the amount of work you put into your submissions.

    As a consequence, the overuse of this crutch is seriously impacting the refinement of critical thinking skills. The emphasised quote touches on — what I think — is the only productive way out of this mess:

    In the present technological moment, this may be the only choice we have, students and teachers alike: whether or not to fall back on trust.

    This morning an article by Tomasz Głowacki showed me a concrete idea on how we can use trust to address the AI issues in the classroom. He writes about a student who felt they were in a genuine impasse with submitting an assignment. They observe that AI is becoming standard in the workforce, so they need practice to stay ahead of the curve. But how can they effectively do this on top of learning the fundamental critical thinking skills?

    In a nutshell: treat your students as equals, talk to them about it. Provide a moderated forum for them to discuss and negotiate an contract for AI use:

    At my next lecture, I projected a blank screen onto the wall and invited my students to negotiate an “AI contract.” At first, they were guarded, but as I shared my own experience with AI, the classroom dynamic shifted. We stopped playing cat and mouse and became partners. Students opened up about their AI use and began to ask questions. After some debate, we drew a line separating mechanical churning from actual thinking. Automating repetitive tasks or literature searches was acceptable. Bypassing critical analysis was not: System architecture and design would remain strictly human tasks.

    AI tools are powerful, and like it or not they’re here to stay. But the scope for using them incorrectly is far wider than any tool that has come before. Establishing an AI contract puts up guardrails, and helps share learning that help others use AI to genuinely benefit without causing more problems than they set out to solve (like sacrificing ones own development and learning).

    It’s not perfect, after all there will be those who decide not to follow the rules since course grades have a string influence on future career opportunities. But this could paired with more fair assessment methods where AI cannot help. I’m a supporter of weighting oral presentation assessments, but I worry this introduces bias against those who don’t speak English as a first language or others in our neurodiverse community. A recent method I’ve heard sounded quite interesting though:

    • Assess students on the (handwritten) notes they take throughout classes leading up to an assessment

    I’m sure there are more strategies to come. Taking a step back, I feel this advice might help with establishing boundaries with people you work with by clarifying what we agree is acceptable (and what is unacceptable)

    In my field of software engineering, I would argue in favor of the following clauses in my “AI contract”:

    • We want to minimise work — not expand it. No slop grenades!

    • You are responsible for what you commit, you must understand your own proposal even if AI writes it

    • Integrity matters. AI authored sections should be declared as such

    I can see some potential in this strategy broadly, and I hope it helps address some of the anxieties we have with AI in our daily routines. With clear communication, shared goals and understanding, I feel there is hope for our students and the next generations of society to get the most out of their education while also learning how to improve their practice further with AI.

  • HTTP Requests in Java

    After almost 10 years in Python, I’m making my way into the land of Java. There’s a heap to learn, and I learn best by doing. My first project is fairly simple — hit an API and process the returned data. Using the requests package in Python is immediately what I reach for, but Java seems to have a nicer interface out-of-the-box.

    import java.net.URI;
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;
    
    HttpClient client = HttpClient.newHttpClient();

    GET Request

    Python:

    resp = requests.get(
        url,
        headers={"Authorization": f"Bearer {token}"},
    )
    data = resp.json()

    Java:

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("Authorization", "Bearer " + token)
        .build();
    
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

    Python does it in one call, Java splits it into build the request then send the request. The builder pattern is everywhere in Java (for better or worse, the meme of the FooFactory, FooFactoryFactory and FooFactoryFactoryFactory in Java is something to watch out for)

    POST Request

    Python:

    resp = requests.post(
        url,
        headers={"Content-Type": "application/x-www-form-urlencoded"},
        data=body,
    )

    Java:

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("Content-Type", "application/x-www-form-urlencoded")
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();
    
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

    The only new concept: BodyPublishers.ofString() wraps your string into the request body. GET is the default, so you must explicitly call .POST().

    JSON Parsing

    Python: response.json(). Done.

    Java: no built-in JSON parsing (?), use the jackson package:

    import com.fasterxml.jackson.databind.JsonNode;
    import com.fasterxml.jackson.databind.ObjectMapper;
    
    ObjectMapper mapper = new ObjectMapper();
    JsonNode data = mapper.readTree(response.body());
    String name = data.get("name").asText();

    JsonNode is a generic tree - you traverse it with .get("key") and convert types with .asText(), .asInt(), etc.

    The Full Pattern

    Here’s what a real API client looks like - this is the pattern I used everywhere to hit the Spotify API:

    public class SpotifyClient {
        private static HttpClient client = HttpClient.newHttpClient();
        private String accessToken;
    
        public SpotifyClient() throws IOException, InterruptedException {
            this.accessToken = getAccessToken();
        }
    
        private JsonNode callEndpoint(String endpoint) throws IOException, InterruptedException {
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(endpoint))
                .header("Authorization", "Bearer " + accessToken)
                .build();
    
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            return new ObjectMapper().readTree(response.body());
        }
    }
  • Migrating to GitLab

    GitHub’s reliability has gone down the drain. What used to be a rock-solid platform now feels uncomfortably fragile. During this period at my last workplace, incidents would grind our pipelines to a total halt, PRs couldn’t be merged, and some reviews were even lost!

    Many predicted this after the Microsoft acquisition. This downtime is incredibly costly for teams that rely on GitHub for daily work. Momentum is lost, and trust is eroded.

    If I couldn’t use GitHub anymore in the worst-case scenario, what would I do?

    This really shouldn’t be an issue. After all, GitHub is just a wrapper around git — a distributed version control system. The lock-in of the platform is the issue. Network effects result in GitHub being the main place for a developers portfolio. But I set that aside and found that GitLab is still well-equipped to provide a stable platform that mirrors content to GitHub (or several other platforms)!

    So let’s swap over to GitLab, what steps do we need?

    1. Create a personal access token on GitHub

    2. Create an account on GitLab

    3. Follow the dialogues and use the GitHub token to import repositories

    Done!

    One caveat with the one-click repo migration: sometimes the repo name might be slightly different when the repo names contain . or - characters, but this can be fixed in the GitLab repo settings afterwards if necessary.

    Now all I need to do is update the origin remote for all my local repos. I prefer using CLI interfaces, and to my surprise the GitLab CLI is as impressive as the GitHub CLI!

    brew install gh glab

    Then some “nice” git aliases for these do I can use git hub <command> and git lab <command>:

    # ~/.gitconfig
    [alias]
        hub = "!NO_COLOR=true gh"
        lab = "!NO_COLOR=true glab"

    Using the GitLab CLI, I wrote this git alias to update the remote on a local repo from GitHub to GitLab:

    # ~/.gitconfig
    [alias]
        lab-remote = "!f() { \
            repo_guess=$(git remote get-url origin | sed 's/.*://' | sed \"s|.*/|$GITLAB_USER/|\" | sed 's/.git$//'); \
            echo "try switching to ${repo_guess}" ; \
            if git lab repo view $repo_guess; then \
                git remote set-url origin git@gitlab.com:${repo_guess}; \
                git remote -v; \
            fi; \
        }; f"

    Once I’ve exported GITHUB_USER=... and GITLAB_USER=... in my .bashrc, I just need to call git lab-remote in my local repo to update it!

    (alternatively I could’ve just deleted my local repos and re-cloned them from the new GitLab repo address — but why spend 5 mins doing something manually when you can spend 20 mins scripting it?)

    To maintain my presence on GitHub as the “public” interface, each repo allows you to use your GitHub token to mirror content from GitLab to GitHub! This can be set up through the web UI, but of course I’ve also written a git alias for this as well. This one requires exporting the token as GITLAB_MIRROR=..., but the basic gist of it is:

    # ~/.gitconfig
    [alias]
        lab-mirror = "!f() { \
            repo=$(git remote get-url origin | sed 's/.*://' | sed \"s/$GITLAB_USER/$GITHUB_USER/\") ; \
            key=${GITLAB_MIRROR} ; \
            if [ -z ${key} ]; then \
                echo No key found ; \
                exit 1; \
            fi; \
            git lab repo mirror --direction push --url https://${GITHUB_USER}:${key}@github.com/$repo; \
        }; f"

    And that’s it. With the mirroring in place, you get the best of both worlds: GitLab as your stable daily driver and GitHub as the public face for your portfolio and external contributions.

    When you push to GitLab, changes automatically flow to GitHub. Your collaborators, CI pipelines, and review processes stay on the reliable platform, while the GitHub world sees your projects as active as ever.

    But What about CI? GitLab has you covered as well! (Though keep in mind GitLab offers 400 free minutes whereas GitHub offers 2000)

    GitHub Actions uses a flat YAML file with on: triggers and a jobs: section. GitLab CI uses .gitlab-ci.yml at the root of your repo with stages: and individual jobs.

    Here’s a typical GitHub Actions workflow:

    # .github/workflows/main.yml
    name: CI
    on: [push]
    jobs:
      test:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: "20"
          - run: npm ci
          - run: npm test

    And here’s the GitLab equivalent:

    # .gitlab-ci.yml
    stages:
      - test
    
    test:
      stage: test
      image: node:20
      script:
        - npm ci
        - npm test
      only:
        - push

    For a single-job pipeline, the migration is almost a direct translation:

    # .gitlab-ci.yml
    default:
      image: node:20
    
    stages:
      - test
    
    test:
      stage: test
      script:
        - npm ci
        - npm test

    An observation: GitHub leans heavily on reusing steps across projects through a “marketplace” of actions, whereas GitLab forces writing explicit scripts. This is a massive advantage in my eyes. GitHub actions are a common attack vector for vulnerabilities that have been exploited in the latest high-profile hacks. Auditing GitHub actions is a bit of a goose chase!

    In GitHub Actions, you’d set secrets in the repo settings under Settings > Secrets and variables. In GitLab, it’s Settings > CI/CD > Variables. The syntax for using them is slightly different:

    • GitHub: ${{ secrets.MY_SECRET }}
    • GitLab: $MY_SECRET (or $SECRET for protected variables)

    Once you’ve tested the GitLab pipeline, you can delete the .github/ directory from your repo — GitLab runs the show now!

    More complex CI/CD pipelines are out of my scope for now, but GitLab offers

    All considered, this process took me about 3 hours across most of my projects. I’d highly encourage anyone to follow this path for personal projects and small teams!