Version history with Git

Why Git

Because notes are plain text files, Git gives you a complete, inspectable history of your thinking for free — every version of every note, with the ability to go back. HelloNotes speaks Git directly, so you never need the command line, but everything it creates is a perfectly ordinary repository you can also use elsewhere.

Initialising a repository

Git is one of the collection’s rows at the top of the sidebar. The Git row is for the collection you have selected: it shows the current branch, with a dot beside it when there are uncommitted changes, and clicking it opens the Git pane. For a collection that is not yet a repository the row says so, and the pane offers Initialize Repository. After that the pane shows the current branch and how many files have changed. A collection opened directly from a cloud account is the provider’s to keep, so with one selected there is no Git row.

To start a new collection as a repository, choose New Collection ▸ Git Repository… under the + at the top of the sidebar.

Setting your identity

Commits need a name and email. Open the gear icon in the Git pane — or the Git tab of Settings — to set them for HelloNotes. If you set none, HelloNotes uses the repository’s own identity or your global one where it can read it, and otherwise your account’s name — which then travels with anything you push.

Committing

• Commit stages everything that changed and records it, under a message HelloNotes writes — “Update notes” and the date and time.
• A change you approve from the Assistant is committed too, whatever Auto-commit is set to — as a commit of its own, holding that note and nothing else. It is not made in a cloud folder, or when the collection is one folder of a larger repository, where Auto-commit is not allowed either — nor while another Git tool has something staged, which the commit would otherwise take with it.
• Auto-commit (an option in the pane) commits quietly in the background a little after you stop editing. It is off by default, and it never pushes — publishing is always something you do deliberately.

Browsing and restoring history

History, in the right panel, lists the commits that touched the open note. Select one to read that version, and restore it if you want it back. Restoring writes the old content as a new change, so nothing in the history is lost — but it replaces the note as it stands, and Undo does not bring that back. HelloNotes asks before it does, so commit first if you have edits since the last commit that you want to keep. History looks back over the last 300 commits.

Syncing with a remote

To back up or sync between machines, connect a remote — GitHub, GitLab, or any Git host.

1. Open Git settings (the gear in the Git pane) and add an account with a personal access token.
2. Use Connect Remote in the pane, or clone an existing repository into a new collection with Open Collection ▸ from Repository… under the sidebar’s +.
3. Once there is a remote, the pane’s Sync menu has Push, which uploads your commits, and Fetch, which retrieves what is on the remote.

Use an HTTPS remote with a personal access token. Tokens are stored in the Keychain.

Cloning shows a progress indicator and can be stopped with Stop if you change your mind or the repository turns out to be larger than expected.

Current limitations

• No merge or pull. HelloNotes can fetch and push, but does not merge diverged histories. If two machines have both committed, reconcile them with a Git client or the command line.
• Auto-commit is disabled in cloud folders — see Cloud storage for why — and in a collection that is a folder inside a larger repository.

Tips

• A private repository is a good backup: complete history, under your control, off your Mac.
• Add a .gitignore for .DS_Store and any large binaries you would rather not version.
• Push before switching machines; fetch when you arrive.