DEV Community: Mohammad Rafiq

TIL - How to Fix Flaky macOS Screen Capture on OBS

Mohammad Rafiq — Sat, 25 Oct 2025 02:35:48 +0000

On macOS, when switching scenes in OBS, if you move from a scene with a Display Capture source to one without it, macOS stops the screen capture session. When you switch back, the display stays frozen until you re-enable it in the source properties.

The workaround is to include the Display Capture source in every scene, even the ones that don’t use it. Just hide it by clicking the eye icon or placing it below another layer. This keeps the capture session active and prevents interruptions when switching scenes.

You may still encounter issues where the macOS Screen Capture source still keeps freezing and requires manual restarting in the properties of the source. The best (for now) fix for this is to use this script which will monitor the source and restart it if it's frozen.

I have a Nix Flake setup here if you prefer that (or have to like me).

git init ~/repos/cathedral

Mohammad Rafiq — Fri, 03 Oct 2025 14:49:47 +0000

okay, ive been using NixOS with this flake for a while but I've kind of let it lie sallow for a while out of a kind of dissatisfaction with how I've done things. I'd love a proper rewrite with all the experience I have gained doing this.

i have moped around about doing this for months on end but it is time i cannot take not being able to deploy random shit and my servers are all down anyway IT IS TIME to go.

i broke down the issue and the number one thing that matters to me is having the product I can see and play with. To just "get there", I decided let's just start with the easiest and the edge node, the raspberry pi that will be my reverse proxy. The first step would simply be flashing a microSD card with a NixOS image with my SSH keys on there.

I almost instantly got ganked by my job (new company btw, finally SOFTWARE ENGINEERING) on the day I chose to do this small task, but managed to get er' done!

With Some Caveats:

It took 6 hours. I ran into issues with git when I was working off of two branches on pantheon. I decided on a whole new name change (obviously very inspired by CatB). I got distracted by a myriad other tasks, mostly also nix-related.

Anyway,

Next step is going to be getting my very static website back up on my domain:

           services = {
             ...
             nginx.enable = true;
-            nginx.virtualHosts."_".root = "/var/www/veil";
+            nginx.virtualHosts."_".root = ../www/rrv.sh;
           };

What I'm doing here is essentially adding the static files into the project and using Nix's paths to add it into the Nginx configuration.

Detour:

My ACME validation (for SSL) uses DNS-01, for which I need a Cloudflare API key, which I obviously don't want in plaintext in my repo, so it is time to add declarative secrets management with sops-nix.

diff --git a/docs/runbook.md b/docs/runbook.md
+ssh-to-age -private-key -i ~/.ssh/id_ed25519 > ~/.config/sops/age/keys.txt

diff --git a/flake.nix b/flake.nix
   inputs = {
+    sops-nix.url = "github:Mic92/sops-nix";
+    sops-nix.inputs.nixpkgs.follows = "nixpkgs";
   };
 }

diff --git a/nix/users.yaml b/nix/users.yaml
+rafiq:
+    password: ENC[AES256_GCM,data:8KAfatz+YSaNozd5VGo=,iv:LNRxt47iBKSWzMZuBHSxv/qDZ2h6JiTIPps7OK/o7uU=,tag:oiSfLyRVswb/wxSTE69QMA==,type:str]
+    hashedPassword: ENC[AES256_GCM,data:NogYQ3kR1TseC79HIXARrXhIncCnvxzf9zMF2QrUyTmojTffPXRGtMdjNpfMEFj5dkKfZujBL/QTIpPFFTm1py7Dreg5/9VSKQ==,iv:IwfZsrsJbLYG1ELte6aBHUtff6hIQu9rHT5tSvILIGQ=,tag:oav3paDcUY+cl4FJlZa90A==,type:str]

diff --git a/nix/veil.nix b/nix/veil.nix
   flake.nixosConfigurations.veil = lib.nixosSystem {
     modules = [
       "${inputs.nixpkgs}/nixos/modules/installer/sd-card/sd-image-aarch64.nix"
+      inputs.sops-nix.nixosModules.sops
       (
         {
           # Use the nix-community binary cache so we don't have to compile sops for aarch64-linux ourselves
+          nix.settings = {
+            substituters = [ "https://nix-community.cachix.org" ];
+            trusted-substituters = [ "https://nix-community.cachix.org" ];
+            trusted-public-keys = [ "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs=" ];
+          };
           users = {
+            mutableUsers = false;
             users.rafiq = {
+              hashedPasswordFile = config.sops.secrets."rafiq/hashedPassword".path;
             };
           };
+          sops = {
+            age.sshKeyPaths = [ "/home/rafiq/.ssh/id_ed25519" ];
+            secrets."rafiq/hashedPassword" = {
+              neededForUsers = true;
+              sopsFile = ./users.yaml;
+            };
+          };
         }
       )
     ];

I'm a bit out of practice since I first touched sops in March, so I was a little confused why my sops config was working (which was the goal) but the hashedPasswordFile option wasn't kicking in. Luckily I figured out I just forgot to set mutableUsers = false. Now we have our password in our git repo!

Lastly:

Now we have declarative secret managment, I'll add the cloudflare key:


diff --git a/nix/keys.yaml b/nix/keys.yaml
+keys:
+    cloudflare: ENC[AES256_GCM,data:p2IISOuU/ShoifW5OFY/6Bi6PI0iIiQoBfnV512f2z84U9QS/KEhzA==,iv:5AkwtNAK8mD2DbvXCtTeNeIrpF/GIsSyOYxy8G4Jsqo=,tag:u2xJcRBR5WTMWdzupx4tbQ==,type:str]

Now let's use it in sops:


diff --git a/nix/veil.nix b/nix/veil.nix
           sops = {
+            secrets."keys/cloudflare".sopsFile = ./keys.yaml;
           };

and finally use it for our DNS-01 validation:

diff --git a/nix/veil.nix b/nix/veil.nix
           services = {
-            nginx.virtualHosts."_".root = ../www/rrv.sh;
+            nginx.virtualHosts."rrv.sh" = {
+              addSSL = true;
+              useACMEHost = "rrv.sh";
+              acmeRoot = null; # needed for DNS validation
+              locations."/".root = ../www/rrv.sh;
+            };
           };
           users = {
+            users.nginx.extraGroups = [ "acme" ];
           };
           security = {
+            acme = {
+              acceptTerms = true;
+              defaults = {
+                email = "rafiq@rrv.sh";
+                dnsProvider = "cloudflare";
+                credentialFiles."CLOUDFLARE_DNS_API_TOKEN_FILE" = config.sops.secrets."keys/cloudflare".path;
+              };
+              certs."rrv.sh".extraDomainNames = [ "*.rrv.sh" ];
+            };
           };

and that's it! A quick ssh and nixos-rebuild switch --sudo --flake . later, veil is up and more importantly, so is my website.

Here's the repo at this point. I'm trying to document any other interesting things I come up with in the process, so hopefully you see more blog posts soon. Side note: still pretty crazy that i can go from a dead Raspberry Pi to a live, SSL-secured website in a single rebuild — if that doesn't make you wanna try nix, idk what does.

Next step is getting my DnD wiki back up, which is unfortunately going to involve me learning how to declare docker compose with nix. see ya next time

mise en place

Mohammad Rafiq — Thu, 18 Sep 2025 10:32:35 +0000

Context

I have an issue with premature optimisation. Not with my software projects, but in my life. I often, when trying to implement some kind of routine change or enhancement to my workflow, overdo it and try to hit the nail on the head the first time. This leads to the classic analysis by paralysis, where I'm stuck perfecting a system for a given task and end up never actually putting into practice, or worse, I invest so much time into perfecting it and it ends up not working for me.

Perfect is the enemy of good enough.

The New Routine

Today, I put the following simple rules into practice, and will be following these to the tee to the best of my ability:

Write down every single task you want to accomplish on one easily referenced notepad. Tasks MUST be small in scope and be able to be completed within a day.
Before starting a task, plan how to accomplish that task in step-by-step, excruciating detail.
Construct a "mise-en-place" for each task, both in terms of physical and mental preparation needed.

Why?

This workflow forces the following to happen:

When I take the time to plan out exactly what I need to do to accomplish a certain task, I visualise potential pitfalls and am able to think through everything except the nitty gritty of the tasks, leading to an easy step into "deep work" mode when I am executing without having to stop and think through the problem mid-task.
The mise step lets me mentally and physically reduce the barrier to entry of starting the task. The philosophy of reducing the ratio of perceived effort to reward (task completion) has already helped me form my workflows in the past.

Conclusion

Okay that's it see you in a month and I'll update if this works

Live Syncing to a Git Repository with a VS Code Extension

Mohammad Rafiq — Mon, 10 Feb 2025 01:03:03 +0000

by Mohammad Rafiq

Last updated on 10/02/2025

Psst! The source code talked about below is up at https://github.com/bwfiq/git-livesync :)

Foreword

As mentioned in the last post, I keep my notes in git repositories. I originally used Obsidian for years as my note-taking application of choice after migrating away from Google Keep, using the vast library of community plugins (namely obsidian-livesync and obsidian-git) to back up and sync my notes on an interval to my 3 remotes; GitHub, my private Gitea instance for my private "second brain" type notes, and my Otterwiki instance (a wiki that runs on a git server of markdown files).

A recent issue I've run into is that since I started working my first big boy job, I've been unable to download or install any software. I already foresaw this, though, as the main reason I use Obsidian (other than how great it is as a note-taking app) is that all the notes are stored in a very transparent directory structure as markdown files. I simply spun up a code-server instance, cloned my notes repository, and was off to the races.

The actual issue was me missing my automatic sync. Thankfully, I almost immediately found GitDoc, which I mentioned in the last post as something I was looking into to replicate the live sync functionality I was used to.

I used it quite happily for a few hours, until I realised it stopped committing my changes randomly and would sometimes not even work even on startup. I dug through the VS Code logs, but none of my extensions were logging any warnings or errors.

Of course, I did the sane thing at this point, and manually committed my changes in a normal, human way.

...

Just kidding. Here's how I made my own extension to watch for file changes in VS Code and automatically syncs them to a configured remote.

By the way, when writing this post, I found a Github Issue that gave me more information about why GitDoc wasn't working for me; its latest version is for some reason incompatible with Foam, which I use to get Obsidian-like functionality in VS Code. Unfortunately, it seems like there is no resolution yet.

Typescript

So, some background. I grew up on C and Python, and mostly used C in my education, with the occasional module teaching me JS or Java. Even my first dev job in 2022 was as a Unity developer, so I continued in C#. I also recently picked up Rust for a side project.

If you have ever worked with VS Code or its extensions, you know where this is going. As soon as I cloned the vs code tutorial repository, I figured out I would have to use Typescript. As someone who really disliked using Javascript, I dreaded this (slightly).

Luckily though this project taught me that the general positive opinion on Typescript by its users is not unfounded. I lowkey loved using it and am excited to try and use it in an actual web dev project.

Anyway, on to the actual project.

Writing git-livesync

Since I didn't have any experience with Typescript or the VS Code API, I started with a goal of a prototype that could live sync any changed files to a git repository, regardless of the implementation.

The MVP

I quickly followed the VS Code extension tutorial, which basically taught me jack shit except the file structure of VS Code extensions. (No hate to the authors, though. The people at VS Code write damn good tutorials; I learned a lot from their Django one)

Regardless, I started the project by using the yeoman generator for vs code extensions with:

yo code .

Take note you need to have NVM and NPM set up on your local machine.

This set up my local development environment with the proper project structure. I'm lazy and didn't bother with writing unit tests for this project, so the only files we are concerned with are package.json and src/extension.ts.

package.json is a node thing that defines a lot of information about the project, and VS Code extends this by including extension metadata for the marketplace and the extension view, as well as using it to add Activation Events and configuration settings.

src/ is gonna contain all our typescript files that define the extension's logic, and extension.ts is compiled to out/extension.js, which is the entrypoint defined in our package.json for the extension.

As an aside, I have recently adopted the Conventional Commit syntax for my commits, hoping that this will improve both readability of my repos and also force me to think more carefully about what I commit. This first task of this project however, was totally not in sync with this philosophy; I just wrote the entire intended logic of the extension, tested it, and pushed it. Later commits are better separated.

We use the VS Code API to watch the filesystem for changes, and this does not change throughout the project.

// Creates a file system watcher
const watcher = vscode.workspace.createFileSystemWatcher("**/*");

// Run our logic on events sent from the watcher
watcher.onDidChange((e) => {
  handleFileEvent(e, "changed");
});

watcher.onDidCreate((e) => {
  handleFileEvent(e, "created");
});

watcher.onDidDelete((e) => {
  handleFileEvent(e, "deleted");
});
context.subscriptions.push(watcher);

For now, I ran a simple terminal window that runs my git commands, though I will be changing this later to use simple-git.

const handleFileEvent = (event: vscode.Uri, action: string) => {
  // We'll first get the path of the file that was modified.
  const file_path = event.fsPath;
  const relative_file_path = path.relative(
    vscode.workspace.workspaceFolders[0].uri.fsPath,
    file_path
  );
  // This handles the .gitignore exclusions; it will be explained in the next section.
  if (!ig.ignores(relative_file_path)) {
    const date = new Date();
    const commit_message = `${action} ${relative_file_path} at ${date.toISOString()}`;
    // We create a terminal and send the commands.
    const terminal = vscode.window.createTerminal("Git LiveSync");
    terminal.sendText(`cd ${vscode.workspace.workspaceFolders[0].uri.fsPath}`);
    terminal.sendText(
      `git pull && git add . && git commit -m "${commit_message}" && git push`
    );
  }
};

Finally, this MVP includes one of the key features of respecting excluded files and folders from the .gitignore. This ensures we only initiate a commit-and-sync when only files we want to commit are modified. We'll use the ignore module for this.

import ignore from "ignore";
// We first retrieve the .gitignore...
const gitignorePath = path.join(
  vscode.workspace.workspaceFolders[0].uri.fsPath,
  ".gitignore"
);
// then extract the exclusion patterns from it.
let git_ignore_patterns: string[] = [];
if (fs.existsSync(gitignorePath)) {
  const gitignoreContent = fs.readFileSync(gitignorePath, "utf8");
  git_ignore_patterns = gitignoreContent
    .split("\n")
    .filter((line) => line && !line.startsWith("#"));
}
git_ignore_patterns.push(".git"); // Include the .git/ directory as well.
// We then add these patterns to our ignorer to use.
const ig = ignore().add(git_ignore_patterns);

You can see the extension.ts at this point here.

Refactoring

With this simple implementation of the extension's goals, we now have a working MVP. Whenever a file is changed, created, or deleted, the extension commits-and syncs (aka pulling changes from the remote before committing and pushing).

Here's a non-exhaustive list of the problems right now before we can use this extension, though:

There is no cooldown on the file watching or terminal functionality; it will spam commits as soon as any file is changed for every single change detected.
The current implementation of the git command runner spawns new VS Code terminals that are visible in the terminal view in VS Code. This is technically not an issue, but it's ugly.
This functionality does not respect what workspace you are in, instead running the commands on any change in any workspace, irrespective of if you want it to or if the workspace even has a git repository.

I wanna fix these issues, but first, I decided to refactor the current logic into a collection of source files. We will handle git operations using a GitHandler class in src/gitHandler.ts, exclusion patterns using a IgnoreHandler class in src/ignoreHandler.ts, and file system watching using a Watcher class in src/watcher.ts.

For the sake of brevity, I won't include the refactor here, but you can see the commit here.

I was tempted to improve the code during the refactoring process as I am wont to do, but in keeping spirit with Conventional Commit syntax, I refrained from doing so. However, we are now in a great position to begin working on the issues that we have identified.

Improving

My next step was to tackle the issues of workspace-specific functionality and the cooldown between running git commands, which can both be solved with VS Code configuration settings. I want the extension to be disabled by default, and have the user enable it in the workspaces they want to have live synced (exactly like GitDoc!).

Doing this for a VS Code extension necessitates first defining the config settings in the package.json:

    "configuration": [
        {
            // We can have our settings under different headings, but we just want them to be under the main heading so the title will be the name of the extension
            "title": "git-livesync",
            "properties": {
                // This is the name of the config setting that we will later interface with through the API
                "git-livesync.enabled": {
                    "type": "boolean",
                    "default": false,
                    "scope": "resource",
                    "description": "CAUTION: DO NOT ENABLE THIS FOR THE USER! Specifies whether to enable this extension in this workspace."
                },
                "git-livesync.commitDelay": {
                    "type": "integer",
                    "default": 30,
                    "scope": "resource",
                    "description": "Set the time in seconds since the last commit before the extension will auto commit your changes."
                }
            }
        }
    ]

I didn't mention it in the previous section, but I also wrote a small src/utils.ts for holding global variables and functions. I make use of it now to look up the config settings and also initialise a reference to them upon the extension starting up:

let commitDelay: number;

export function getCommitDelay(): number {
  return commitDelay; // This lets us call getCommitDelay() from anywhere else in the code.
}

export function initializeCommitDelay() {
  // We call this in the activate function to make sure the first time getCommitDelay() is called, it has a value.
  const configuredCommitDelay = vscode.workspace
    .getConfiguration("git-livesync")
    .get<number>("commitDelay");
  if (typeof configuredCommitDelay === "number") {
    // We implement error checking here in case we fucked up our package.json.
    // Ordinarily, though, there is no way a number could be here.
    commitDelay = configuredCommitDelay;
  }

  // This subscribes to the VS Code API's event system, updating the value of commitDelay whenever the config changes.
  vscode.workspace.onDidChangeConfiguration((event) => {
    if (event.affectsConfiguration("git-livesync.commitDelay")) {
      const newDelay = vscode.workspace
        .getConfiguration("git-livesync")
        .get<number>("commitDelay");
      if (typeof newDelay === "number") {
        commitDelay = newDelay;
      }
    }
  });
}

// git-livesync.enabled follows the exact same code as above

In hindsight, a better implementation would have been looking up the config setting everytime our getter functions were called instead of having it subscribe to the configuration event.

Now we can call the functions and retrieve our config settings, we can use them. Here's an excerpt from watcher.ts that shows how we use the enabled config setting to only call the commit function when the config setting is enabled:

if (!this.ignoreHandler.ignores(relativeFilePath)) {
  if (getEnabled()) {
    // Calling the function from utils.ts
    this.gitHandler.commit(relativeFilePath, action);
  }
}

The if statements are split up here so I can add debug messages if a file is supposed to be committed but the extension is disabled. I have removed the debug statements from the code snippets in this article, but you can feel free to dig through them in the source repo.

The way I chose to implement the original cooldown was unfortunately pretty shoddy. In essence, it is:

// If we can get the last commit's timestamp (through git log) and it was longer ago than the configured commit delay...
if (!(lastCommitTimestamp && now - lastCommitTimestamp < getCommitDelay())) {
  // ...run the commit commands in the terminal.
}

Again, the weird not operator in this if statement is due to me having debug messages.

This initial attempt at a debounce mechanism was not great. The keen eyed among you will spot the immediate problem: some file changes get skipped completely. To explain this, imagine if you were using the extension in this current state. You would start editing a file, type one character that initiates a commit, and the next few characters you typed would be skipped while the delay resolves. This is not a problem on shorter delays, but given a longer configured delay or a slower (in terms of network speed and compute) machine, this could potentially lead to some work being lost in the worst case, or even possible merge conflicts if you are using the extension on multiple machines. Luckily, I do fix this later, so keep reading.

simple-gitting

I obviously wasn't very happy about this implementation, because the next four hours and five commits (minus documentation or chores) were all about trying to fix this. I'm not used to working with node, and generally try and implement everything from the ground up like an idiot low level programmer, so I had no idea about node's wonderful library of packages that can do everything I wanted better and faster. Introducing simple-git! Instead of me trying to run git commands in the VS Code terminal or using node's child process exec, simple-git lets me literally just call git.pull() and everything works automagically.

Anyway, here's what the refactor looked like in gitHandler.ts:

// I initialise the simpleGit object in the class constructor and give it some parameters.
constructor(context: vscode.ExtensionContext) {
  this.context = context;
  this.inProgress = false;
  const options: Partial<SimpleGitOptions> = {
    baseDir: getWorkspacePath(), // So it will use the current workspace (as is the point of the extension)
    binary: "git", // So it will use all your sneaky little configs
    maxConcurrentProcesses: 6, // This part was in the example so I left it in
    trimmed: false, // Trims whitespace from the commits. Completely unnecessary but also it was in the example
  };
  this.git = simpleGit(options);
}

// Here is the function to commit and sync to the remote. It is now approximately 435% prettier.
public async commit() {
  // Here's a much more elegant debouncing solution.
  // Only one commit process runs at a time (which makes me leaving in maxConcurrentProcesses even dumber) and...
  if (this.inProgress) { return; }
  this.inProgress = true;

  const lastCommitTimestamp = await this.getLastCommitTimestamp();
  const now = Math.floor(Date.now() / 1000);
  const timeSinceLastCommit = now - lastCommitTimestamp;
  const timeDelta = getCommitDelay() - timeSinceLastCommit;
  const sleepDuration = Math.max(0, timeDelta);
  await sleep(1000 * sleepDuration); // ...we just queue up the last commit so it commits all the changes after the delay.

  const commitMessage = new Date().toLocaleString();
  await this.git.pull().add(".").commit(commitMessage).push(); // Doesn't this look a million times better
  this.inProgress = false;
}

private async getLastCommitTimestamp(): Promise<number> {
  // git log -1 --format=%ct returns the UNIX timestamp of the latest commit.
  const log = await this.git.log(["-1", "--format=%ct"]);
  return log.latest
    ? parseInt(log.latest.hash, 10) // It took me like 30 minutes to figure out that log.latest.date is not the date, but instead log.latest.hash
    : Math.floor(Date.now() / 1000);
}

Joking aside, I liked learning about how await and async works in Typescript. The concept of Promises, while not an alien one due to me using callbacks in Unity with C#, is a pretty cool one. It's a much more elegant way (IMO) to handle callbacks than all the other implementations I have seen.

Anyway, with my gitHandler class being refactored to be #sexy, we can review what we've achieved so far: an extension that watches for file changes, commits and syncs those changes to a git remote, waits to commit until a configured time has passed, and is also able to be enabled in specific workspaces. We have basically achieved all the functionality we originally planned!

Documentating

I think its a good time to mention that I preceded each commit, whether it be a refactor, feature, or fix, with an update to README.md. I had a known issues and TODO section that I religiously kept updated. I kinda used to hate planning out what I wanted to do before I did it, but I have to say that setting goals for the next commit and limiting myself to them have definitely led to some better habits, and improved productivity probably by 2 or 3x. This project took me only about ~8 hours of work, compared to the rough week I would have spent on it before I started sticking to best practises. Anyway, back to the project:

Polishing

There was one more thing I wanted to do before I built the .vsix and tested it on any other repos than a burner; making the extension activate on startup rather than how it currently activated, which was by running a command from the command palette. I have no idea why it took this long for me to figure out that this was literally one line of code to be added to my package.json:

  "activationEvents": [
    "workspaceContains:**/.git", // just in case
    "onStartupFinished"
  ]

, but this "feature" ended up being the quickest one to implement at a whopping 10 minutes. Thank you VS Code for making it as easy as possible for the Cro Magnon devs of the world <3

Packaging

Anyway, at that was left to do was to package the extension as an installable .vsix file. This is easily accomplished with:

vsce package

The VSIX file is dropped in the root project directory, and the console output helpfully informs you what is packaged, serving as a useful reference for what to exclude using the .vscodeignore file, which for me, ended up being:

.vscode/**
.vscode-test/**
src/**
node_modules
out
webpack.config.js
esbuild.js
.gitignore
.yarnrc
vsc-extension-quickstart.md
**/tsconfig.json
**/eslint.config.mjs
**/*.map
**/*.ts
**/.vscode-test.*
core
not
output*.*

It is messy because I just appended exclude patterns to whatever the yeoman generator gave me to start with.

Along with this, I also (following the tutorial) bundled my extension, which reduced the size of the packaged VSIX file from 10.9MB to 43.63KB (a 2498% size reduction!).

Excited and quivering at finally being able to release a finished piece of software for the first time, I wrote a CI pipeline with Github Actions (which promptly failed) and tagged my latest commit with v0.0.1.

Releasing

Actually, that was a lie because I had to fuck with git for an hour before I figured out how to use release branches and SemVer tagging. This is how I ended up doing it (thank you LLMs):

# Begin on the latest commit on your main branch
git checkout -b release/v0.0.1
# Do whatever changes you need to make for your release (I removed debug messages and updated the readme)
git commit
git tag v0.0.1 -m "Release v0.0.1" # Tags the latest commit
git push origin v0.0.1 # Or alternatively git push --tags if you have nothing to commit

Now that I officially had a commit up on my GitHub remote with the v0.0.1 tag, all I had to do was write a quick changelog (thank you LLMs) and publish it as a release, adding my VSIX file as a binary.

You can find the release here!

Cleanup

Before we end, I'll just cover what else I did with the project before abandoning it for the foreseeable future.

git checkout main
git merge release/v0.0.1
git branch -d release/vX.Y.Z

This cleaned up my repository by getting rid of the release branch, merging the commits into my main.

Conclusion

As sardonic as my tone is in this post, I really enjoyed working on this project. First of all, it's my first actual piece of software that I have released, which feels grand. Also, it helps me feel more like a developer now that I have gone through the rite of passage of being annoyed at something and being actually able to code it away.

It's a shame I couldn't just use GitDoc, but I don't regret it. I learned a new language and understand the VS Code extension framework, and by proxy Node and NPM much better. I'm also pretty proud of the entire project only taking two days and for how focused I was on implementing the core functionality and not getting sidetracked as usual, either by irrelevant features, avoidable bugs, or other projects.

The source code for this project is up at https://github.com/bwfiq/git-livesync/ under a GNU GPL-3.0 license, so feel free to peruse it. All due credit to GitDoc for inspiring this project, and I hope the maintainers figure out how to fix the problem with Foam. Heck, I might try my hand at contributing to an open-source project other than my own for once.

Anyway, I'm planning to write a blog post every week this year and work on something either homelab or code-related every day (minus when I'm not at my desk and touching grass instead). You can follow my exploits on Github. See you guys next week where I will be using the dreaded Python snake

Automating Submodule Updates with Git Hooks

Mohammad Rafiq — Thu, 06 Feb 2025 06:24:44 +0000

by Mohammad Rafiq
Last updated on 02/02/25 @ 2010hrs UTC+8

Introduction

I have a public wiki for my DnD setting up at https://aenyrathia.wiki/. It runs on Otterwiki, which means I have access to the entire wiki of markdown files as a git repository. While this is amazing for accessing my wiki from anywhere and having version control, it also means I don't have an easy way to add my own private DM notes.

To this end, I'd like to have my own private repository that pulls in the wiki as a submodule so I can easily reference it for my own notes without having to consult the website. Here's the problem: normally, submodules are locked at a specific commit, which makes sense because they are meant to act as dependencies for the parent repository. The thing is, I'm not working with code in this case. I want the submodule to be constantly up to date and have the latest changes pulled from the wiki.

Problems

Right now, I can have git pull (and the other commands) recursively update the module through a simple:

git config pull.recursesubmodules true

THe issue now is that because of the way submodules work (primarily the fact that they are a specific checked out commit of the other repository), this doesn't pull in the latest changes from the submodule repository. To actually achieve that, I have to run the command:

git submodule update --remote

which pulls in the changes from the remote.

Drawbacks to this method

We have to acknowledge why this "workaround" is not more widely used. I am using git submodules in a non-standard way here, and this approach would lead to some potential issues, revolving around the fact that if the rest of your code depends on these submodules, pulling in random changes could lead to modifications or errors in the logic of the parent repository's code. However, this doesn't apply to this project, because markdown files aren't gonna blow up when I change other files. If you want to use this method though, do be warned!

Automation

So, now we have identified the problem and a solution. How do we then prevent having to always run the git submodule update command every time we pull?

Git Hooks!

Literally as I was researching potential solutions for this earlier problem, I was messing with my VS Code configs in an attempt to find out why my .git folder wasn't being shown in the explorer pane. I found out through a blog post that these excluded folders were in the settings and promptly removed all the default rules, but the post also mentioned why the author wanted to include the .git folder in their explorer, namely because they were using git hooks.

I had absolutely no idea what these were and skimmed past it since it wasn't related to my issue, but when I was thinking of how I could automate this solution, the git hooks came back to mind as something to look into. Thankfully, I was right in my hunch, and git hooks turned out to be the solution. All I had to do was drop a shell script named post-merge into the .git/hooks folder and make it executable, and whatever commands were in that file would be run upon a pull command.

The contents I put in my .git/hooks/post-merge script were as follows:

git submodule update --init --recursive --remote

You'll notice the --init and --recursive flags being included which weren't mentioned above, but all they are for is for when you clone my parent repository (which doesn't automatically initialise the submodule repository) and are more for if I forget to also init the submodule when cloning this repo next time.

With that being said, now whenever I pull the repository, the submodule nicely populates itself with whatever changes has been made to the wiki.

Next steps are to see if I can't make this easier to work with by using the GitDoc extension to be able to work with my wiki like I'm used to in Obsidian with livesync!