Versioning (easy Git)

Git, GitHub and the cloud

Git is local. It is a free program that runs on your computer and keeps the version history inside the folder itself, in the hidden .git folder. Turning versioning on sends nothing to the internet and needs no account: the versions stay on this machine only — and if the disk fails or the computer is lost, they go with it.

GitHub is something else: a cloud service that keeps a copy of the repository. It is to GitHub, or to a similar service, that LightNote sends the versions when you sync. With that copy somewhere else you get a backup and can use the same notes on another computer: you send from one and receive on the other. GitHub is free for personal use, with unlimited private repositories that only you can see.

In short: Git is the versions, on your computer; the remote is a copy of them somewhere else — GitHub, another service, a OneDrive or Google Drive folder, or a server of your own. While the folder has no remote, the versioning panel says Versions only on this computer. and offers the Back up and sync… link, explained below.

Clone a repository

To work on a repository that already exists, use File → Clone Git repository... — the item is also on the start screen and in the versioning panel of a folder that has no repository yet. Paste the HTTPS or SSH address the repository page shows; the URL of the page itself works too, and so does a whole git clone ... command copied as it is. Choose the base folder and the folder name: the wizard shows where it will be created and warns when something is already there. Advanced options holds the branch, the shallow clone (only the last commit) and the submodules.

When the server asks for a login, LightNote asks in a window: username and token, the SSH key passphrase, or the confirmation of the key of a server this computer has never seen — in that case the window shows the fingerprint and the link to the list the service publishes, and the default is do not trust. The answer goes straight to Git and LightNote does not store it; what stores it is Git's credential manager, when it is installed (Git for Windows ships the Git Credential Manager). Trusting the key writes it to ~/.ssh/known_hosts, as ssh itself would.

If the clone fails, the screen says what happened and offers the way out: try over HTTPS when the SSH key was refused, use the Windows certificates when the company proxy inspects HTTPS, download only the last commit when the connection drops midway, or use long paths when Windows will not create the file. Technical details carries Git's message, and what is not recognized can go to the AI. When it finishes, the wizard opens the cloned folder in this window or in a new one.

Version the open folder

Versioning is opt-in per workspace. Enable it in Tools → Workspace → Workspace settings...: LightNote creates the Git repository (if one does not exist yet) and shows the versioning sidebar (Ctrl+Shift+G).

In automatic mode, LightNote saves versions (commits) by itself at the moments chosen in the General Settings (on save, on tab close or on window close). During the session, a commit takes only what LightNote wrote — whatever an AI CLI or another program changed stays pending, for whoever changed it to commit; Ctrl+S saves the version right away, and what auto-save writes goes into a commit every 10 minutes. On window close (on by default), the commit takes everything that changed in the folder, including outside LightNote: the safety net at the end of the session. In manual mode, you write the message and save the version in the panel. The status bar indicator shows the state (no changes, X changed…) and, when clicked, opens the Git menu (see below) — in a folder that is not versioned yet, it opens the workspace settings at Integrations. You can view each file's diff and restore (discard) unsaved changes.

Automation has 3 levels per folder (in Workspace Settings): Manual (nothing automatic), Auto-commit (saves versions by itself, but does not sync) and Fully automatic (commits and syncs — push after commit + periodic pull; requires prompt-less Git credentials). The panel shows a status line with ↑ to send / ↓ to receive relative to the remote, and the main button changes from commit to Sync when there are versions to send — making it clear that, after saving, you still need to sync.

The Git panel and the tree's Git menu offer Add (git add) and Restore (git restore) per file, plus a single See what changed, which opens the comparison screen. The panel's list follows the natural order of paths, and a file's context menu also has Copy... and Show in Explorer (disabled for a deleted file).

The comparison screen shows both versions side by side, aligned: identical passages always face each other and each side shows the line number of its own file. A changed line appears in amber, with the part that changed highlighted inside it. The Unified mode button switches to the patch format, Swap sides changes the comparison base, and F8 / Shift+F8 jump from change to change.

The Git menu in the status bar. In a versioned folder, the indicator shows the branch and, next to it, what is left to sync (↓ to receive, ↑ to send); the dot is green when everything is saved in a version, amber with pending changes and red with conflicted files. Clicking opens a menu that starts with the full state and offers Save a version of everything (commit)… — it takes every change in the folder, including those made by other programs; with the message left blank, it is automatic —, Open the Git panel and, with a remote repository, Sync (receive and send), Receive (pull with merge), Send (push) and Check the remote (fetch). Receive always merges and never rebases, whatever the machine's Git configuration; if the merge has conflicts, the send does not happen and the menu offers Undo the conflicted merge…. In Automatic actions you change the folder's automation level without opening the settings. In Advanced, Run git command… runs any command in the repository folder and shows the output — there is no terminal, so a command that asks for input (message editor, password in the console) gives up instead of waiting; for those, use the terminal. If Git is not installed, clicking opens the installation guide.

Moving and renaming. When you move or rename a file or folder in LightNote (dragging in the tree, cutting and pasting, renaming), the version takes both halves together and Git records a rename. Only what was already versioned goes in; a new file inside the moved folder waits, like the others. It follows the same rule as Ctrl+S: with commit on save turned off, the move waits for the next commit. Large files stay out — see Large files and the services' limits.

History and the change stripe

The code editor and note toolbars have two buttons for the file's versions. Save version writes the file and keeps this version: in a folder versioned with Git it makes a commit of this file only — whatever another program or an AI session changed in other files stays out —, and outside a repository it keeps a point in the local history. It turns gray, with the reason in the tooltip, when nothing changed since the last version.

Versions opens the list of versions of the open file (the same sidebar section), and its arrow offers Save version with message…, See what changed since the last version and Discard the changes since the last version…, which brings the file back to the last version, with or without Git — the discarded text stays in the local history, and Ctrl+Z also brings it back. The list brings together the commits and the local saves: LightNote records one on every Ctrl+S and, with auto-save, at most one every 10 minutes per file, plus the file as it was before the first write — so it also works in a folder that is not a repository. Each row shows the subject, the author, when it happened and how many lines came and went; the dot tells apart a commit of yours, a save by LightNote itself and a commit from an AI session. When there are uncommitted changes, they are the first row. Clicking a version shows what changed in it; opening the whole version, comparing with the current one and comparing two selected versions are on the right-click menu.

A coloured strip in the margin marks the lines changed since the last version — in the code editor and in the note, and it follows what you type: it disappears when you undo back to the original, without waiting for a save. The last version is the last commit at the moment you opened the file — without Git, the file as it was when opened. Saving and the automatic commit do not move it: the marks stay until you click Save version or close the tab. To turn it off use View → Change strip; switched off it is not merely hidden — nothing is computed at all. Clicking the strip shows how the passage used to be, with Revert this chunk (Ctrl+Z undoes it), Copy original and Open in diff, which opens the full comparison already positioned on that line. When the open file changes outside LightNote — an AI CLI writing to it, for example —, a tab with no pending edits is reloaded silently and the strip shows what changed; with your edits elsewhere in the file, the two are merged (Ctrl+Z undoes it); and if both touched the same lines, a yellow bar at the top of the tab offers Compare, Use the one on disk and Keep mine — until you choose, auto-save does not write that file, and the version that goes away stays in the local history. One caveat about the local history: it is kept by path, so renaming the file loses its local saves — the Git commits, no.

Line authorship and switching branch

Who wrote this line. In the status bar's Git menu, Line authorship (blame) puts at the end of the cursor line who wrote it, when, and the summary of the version — for example Ana · 3 days ago · fix the total. Only the cursor line is annotated, and the annotation follows the cursor. A line that has not entered any version yet says Unversioned; with unsaved changes, the annotation asks Save to see the authorship, because the lines of the file on disk no longer match those on screen.

Switching branch. The same menu has the Branch: main submenu (with the current branch's name), which lists the local branches: the current one is checked, and clicking another one switches to it (git checkout). Create branch… asks for the name, checks it before calling Git (no spaces, no .., not starting with -) and creates the branch from the current one, already working on it. Switching is disabled while a file is in conflict or a synchronization is in progress.

Backup and sync: GitHub step by step

The panel's Back up and sync… link — the same as Add remote repository…, in the panel's ⋯ menu and in the status bar's Git menu — opens the Backup and sync screen, with three paths: GitHub, the recommended one; Other service; and a Synced folder (OneDrive, Google Drive, Dropbox, a USB drive or a network folder). They all work; GitHub is the simplest way to use your notes on several computers and the safest backup. For GitHub:

1. Create the account at github.com/signup: email, password and a username; GitHub sends a code to confirm the email. The Free plan is enough.
2. Create a repository at github.com/new: give it a name (for example notes), select Private and do not tick Add a README, .gitignore or a license. It has to start empty: with a README the first send is refused, because GitHub would already have a history that is not yours.
3. Copy the HTTPS address the page shows (something like https://github.com/you/notes.git) and paste it into Repository address on LightNote's screen. Leave Send the versions now ticked and click Connect.
4. Sign in: on the first send, Git opens a GitHub window so you can authorize in the browser. After that Windows keeps the access — what keeps it is the Git Credential Manager, which ships with Git for Windows — and you do not need to sign in again.
5. On the other computer, install Git and LightNote and use File → Clone Git repository... with the same address. From then on, Sync receives what the other computer sent and sends what you did here.

So you do not have to remember to sync, choose Fully automatic in the folder settings: LightNote sends after every commit and receives from time to time. Two limits worth knowing: GitHub refuses files larger than 100 MB and recommends repositories of up to about 1 GB — keep videos and large files outside the versioned folder. And private means only you (and whoever you invite) can see the repository, but the content lives on GitHub's servers: for what is confidential, use Secure Markdown, which is encrypted before it leaves the computer.

On the phone. With the remote connected, Open on phone… (in the panel's ⋯ menu and in the Git menu of the status bar) shows a QR code. In LightNote on the phone, tap the workspace name and choose Scan the QR code from the computer: the repository becomes a new workspace on the phone. The QR carries only the address, never the password — if the repository is private, the phone uses the Git account it has for that server, or asks for an access token. The phone clones over HTTPS: a remote that is a folder on this computer (OneDrive, below) does not reach it.

Large files and the services' limits

The limits. GitHub warns from 50 MB per file and refuses files over 100 MB; GitLab, Bitbucket and Azure Repos also refuse files over 100 MB. For the whole repository, GitHub recommends up to about 1 GB (5 GB at most), and Bitbucket's free plan gives 1 GB. A synced folder (OneDrive, Google Drive) has no such ceiling.

Why the care is at commit time. The limit applies to every version in the history, not just to today's files: once a 120 MB file goes into a version, sending is refused — and stays refused after you delete the file, because the old version still contains it.

What LightNote does. A file over 100 MB stays out of every version the app saves — the auto-commit, Ctrl+S, Save version, the commit on window close, the snapshot and the phone's sync. It stays in the folder, and a notice offers Ignore in Git (.gitignore). Over 50 MB the file goes in, with a warning in the status bar. A file marked for Git LFS (which keeps only a pointer in the repository) is not held back.

If sending was already refused (the version was saved outside LightNote, in a terminal), the Git panel says so. Deleting the file does not fix it. If the version has not been sent yet, run reset @{u} in Advanced → Run git command… of the status bar's Git menu: the unsent versions are undone and the files stay as they are; put the large file in .gitignore and save the version again. To keep the file in the repository, use Git LFS (git-lfs.com).

Other services, OneDrive/Google Drive and your own server

Other services. Git works the same way with any service; only the place where you create the repository changes. The best known: GitLab (gitlab.com, free, with private repositories of up to 10 GB each), Bitbucket (bitbucket.org, free for up to 5 users, with 1 GB in total), Azure DevOps (dev.azure.com, by Microsoft, free for up to 5 users with unlimited private repositories) and Codeberg (codeberg.org, non-profit, but only for open-source projects — not for private notes). Create an empty, private repository there, copy the address and choose Other service on the Backup and sync screen. Plan limits change over time: check each service's website.

OneDrive, Google Drive or Dropbox, with no new account. Choose Synced folder and point to the service's folder on this computer (for example C:\Users\you\OneDrive or G:\My Drive). LightNote creates a bare repository inside it — a Notes.git folder that holds only the versions, without the working files — and uses it as the remote; the cloud service takes care of copying that folder. On the other computer, wait for the folder to show up synced and use File → Clone Git repository..., pasting its path. The same option works for a USB drive or a network folder, as a backup.

• Why a bare repository, and not the whole notes folder inside OneDrive? The .git folder changes all the time while you work, and two computers syncing it through the cloud can corrupt it. In the bare repository only sending writes, and what it writes never changes afterwards.
• One computer at a time. Before working on the other computer, wait for OneDrive or Drive to finish syncing; sending from both sides before that can create conflicting copies. If that happens often, GitHub is the calmer way.
• If the working folder is already in the cloud — Windows often puts the Documents folder in OneDrive —, the screen warns you. On a single computer, OneDrive works as the backup; to use the notes on several, prefer GitHub, or move the notes folder out of the cloud and keep only the bare repository there.
• Without Git it works too: sync the whole notes folder through the cloud service and leave versioning off — the local history keeps saving the versions of each file. That is the path of Your notes on your phone.

A server of your own. To depend on no company at all, you can host your own Git server. Gitea and Forgejo are lightweight, have a web interface similar to GitHub's and run in Docker — on a home computer, a Raspberry Pi, a NAS or a rented VPS. The simplest of all is a server with SSH and a repository created with git init --bare. The price is looking after the server: installing, updating and backing it up; the installation guides are on each project's website. Once the server is ready, the repository address goes in Other service, like any other.