Syncing with GitHub

Nodez has no sync service and no account. If your vault folder is a git repository, Nodez drives git on your behalf - and shows you exactly what it is doing.

That is a deliberate choice. Sync you cannot inspect is sync you cannot trust, and git has been solving this problem reliably for twenty years. It also means your vault syncs perfectly well without Nodez: it is a normal repository, and every other git tool works on it.

Getting set up#

Your vault folder needs to be a git repository with a remote - set up the usual way, on GitHub or anywhere else. Nodez picks it up automatically the next time you open that vault.

There is no connect-a-repository wizard inside Nodez yet, so cloning or creating the repository is something you do outside the app for now. That is on the list.

Where the controls are#

The sync icon sits in the footer of the notes list, next to the note count. That is the main way in.

The command palette - ⌘K, then GitHub sync - opens the same panel.

The status bar tells you when the remote has commits you do not, showing how many you are behind. Clicking that opens the sync panel too. Nodez checks with the remote when you open a vault; that check only reads, and never changes anything in your files.

What the panel does#

Action	What happens
Refresh	Re-checks the state of your repository
Pull	Brings down remote changes
Commit	Saves your current changes, with a message if you want one
Push	Sends your commits to the remote
Sync	Pull, then commit, then push - the whole round trip

The panel also shows the branch you are on, how far ahead or behind you are, and which files have changed.

After a successful pull or sync, your notes reload from disk, so what you are reading is what just arrived.

When things conflict#

Nodez stops. It will not pick a winner, and it will not overwrite your notes to make a conflict go away. If the same note changed in two places, the sync halts and the conflicting files are listed.

Pulls are attempted as a fast-forward first, and Nodez never force-pushes.

Resolving a conflict currently means opening the files and sorting it out the way you would in any git repository. A guided side-by-side resolution screen is planned - see What's next.

Signing in#

Nodez does not ask for a GitHub password or token, and does not store one. It uses whatever git authentication your machine already has:

• an SSH key
• the GitHub CLI (gh auth login)
• a credential helper, such as the one Git for Windows installs

If pushing works from your terminal, it works from Nodez. If it does not, fixing it in your terminal fixes it here too.

Signing in through GitHub from inside the app is a possibility for later, but using your existing setup means there is one less place holding a credential.

What sync will not do#

• Nothing happens unattended. No background commits, pulls or pushes. Nodez will check whether you are behind and tell you; acting on that is always your decision.
• No silent overwrites. See above - conflicts stop the operation.
• No force pushes. Ever.