My Markdown vault is synchronized with Git, but in normal use I rarely run Git commands or even vaultctl manually. That is mostly the result of where I chose to put the synchronization.

Rather than treating sync as a separate maintenance task, I attached it to events that already divide my day: logging in, shutting a machine down, closing a laptop lid, getting out of bed, and other transitions where I am likely to move from one device to another. The repository is still using ordinary Git underneath, but the client setup tries to make keeping it current something I do by accident. The broader design is covered in Self-Hosted Git as Document Infrastructure, and the server-side implementation in Inside My Git-Backed Markdown Infrastructure; this article focuses on the clients.

vaultctl on desktop clients

On Windows and Linux, the vault is an ordinary local Git clone. Obsidian reads and writes the Markdown files directly, while vaultctl handles the routine Git synchronization.

A normal vaultctl sync can commit local changes, fetch the canonical repository, determine whether the local history is ahead, behind, equal, or diverged, and perform the routine operations needed to bring the two sides back together. That is useful interactively, but the more important part of my client setup is that most of those runs happen without me asking for them.

Windows

On Windows, I use Task Scheduler to run vaultctl automatically at predetermined times and around normal workstation use.

There is a scheduled synchronization late in the day, and synchronization is also tied to session boundaries so that the machine updates the vault when I begin or finish using it. Shutdown gets an additional safeguard through my PowerShell environment: my normal shutdown command synchronizes the vault first, so powering off the workstation also becomes a sync point rather than an opportunity to leave the last few edits stranded on that machine.

The result is that I generally do not need to remember whether I synchronized the desktop before walking away from it.

Ubuntu

The same idea is implemented with Linux-native mechanisms on my Ubuntu laptop. A systemd user timer runs vaultctl sync periodically in the background, but the important part is the event-driven synchronization around suspend and resume.

Closing a laptop lid is exactly the sort of moment when I may immediately continue working somewhere else, so I wanted the laptop to synchronize before it disappears from the network. The implementation takes control of the normal lid-close path rather than allowing systemd-logind to suspend the machine immediately.

The sequence is roughly:

lid closes
    ↓
vaultctl sync
    ↓
suspend
    ↓
lid opens
    ↓
wait for network/server availability
    ↓
vaultctl sync

That gives the machine a chance to publish its most recent changes before sleeping and then catch up with anything that happened elsewhere as soon as it wakes. Periodic synchronization still provides a safety net, but suspend and resume are much more useful boundaries because they correspond to how the laptop is actually used.

iPhone

iOS needs a different approach because I cannot run vaultctl there or rely on an unrestricted background process. Instead, I use Working Copy as the Git client for the vault. The repository is cloned there and exposed to Obsidian so the same Markdown files are available on the phone.

Rather than trying to remember to open Working Copy throughout the day, I include its Git operations inside Shortcuts that I already use at major transition points. Getting out of bed, moving into another part of my routine, and similar boundaries can include a repository synchronization as one step in a larger shortcut.

The flow is roughly:

normal daily transition
    ↓
Shortcut runs
    ↓
Working Copy synchronizes vault
    ↓
continue with the rest of the routine

That means syncing the phone is usually incidental to doing something else. iOS imposes more constraints on unattended execution, so this is not continuous background synchronization, but it happens at enough predictable points that the repository generally stays current anyway.

Synchronization follows transitions

The common pattern across all three platforms is not a particular scheduler or operating-system feature. It is choosing synchronization points based on when ownership of the work is likely to move.

On the desktop, login and shutdown are useful boundaries. On the laptop, suspend and resume are particularly important. On the phone, recurring daily transitions provide convenient opportunities to run Shortcuts. Periodic runs on the desktop systems provide an additional fallback.

Together, these mechanisms make the Git repository behave much more like ambient synchronization without hiding the fact that Git is underneath it.

Manual synchronization is the exception

I can still run vaultctl sync whenever I want, and sometimes I do. The usual reason is that I am actively moving between systems while working on the same files. If I edit something on one machine and immediately want it on another, waiting for the next automatic synchronization point would be unnecessary.

In that situation I simply synchronize explicitly, but that is an exception rather than the normal workflow. Most of the time I edit the vault, move through my day, and the synchronization happens at the boundaries I have already built into the machines and routines around me.

That is the client-side goal of the system: not to make Git invisible, but to make routine Git housekeeping rare enough that I normally do not have to think about it.