Logseq-Git-Sync-101

Description

This repo aims to help Logseq users to sync their data via Git and GitHub.

Why use Git + GitHub to sync Logseq graph?

From the above diagram, it's pretty obvious that Git is the most robust way to sync your graph. iCloud is slow and problematic. Syncthing has no first-party iOS/iPadOS app, but it can be used there through a compatible third-party client such as Möbius Sync — see #40 for a community-tested setup.

However, Git is quite scary for non-programmers, so this doc is here to help!

---

🎩 Suit up

Please check Prerequisite and get yourself a cup of coffee ☕.

🤔 So how does this method work?

Please check Workflow.

Now you need another cup of coffee

For Windows users

Please check Windows.

For macOS users

Please check macOS.

For iOS/iPadOS users

Please check iOS/iPadOS.

For Android users

Please check Android.

For Linux users

Linux users click here

If you are a Linux user, why are you still watching this repo? Shooo. 😎

Lol, just a joke. Take the steps in macOS section as reference if you need it.

💥 Omg, Something blows up

Please check FAQ.

---

Change log

• 2026-06-11: Harden the git hooks. pre-commit now surfaces git pull failures with an actionable message instead of silently committing on a broken sync (and stays quiet on success); post-commit pushes the current branch via git push origin HEAD so repos whose default branch isn't main work, and reports push failures. Both fail fast on credential prompts (GIT_TERMINAL_PROMPT=0). The Android push-graph.sh no longer aborts before pushing when there is nothing new to commit. See the pre-commit / post-commit messages FAQ.
• 2026-06-11: Issue cleanup. Fixed dead GitHub docs links (set-up-git) and the ssh -T git@github.com test command in Workflow/FAQ; added FAQ entries for SSH-over-443 (blocked port 22), HTTPS auth inside Logseq, Snap ssh-keys permission, and how pulls are automated; clarified the iOS Working Copy shortcut steps; added optional .gitattributes (merge=union) guidance; hardened git-hooks/pre-commit with merge/rebase guards; noted Möbius Sync for Syncthing on iOS; and listed related community tools in Home.
• 2024-04-18: Add ssh config in Workflow to avoid Permission denied:(publickey) issue.
• 2023-12-27: Fix For Android users Termux path to ~/storage/shared to avoid issue#34.
• 2023-11-21: Update For iOS/iPadOS users (Working-Copy) for updated version of Working Copy.
• 2023-10-21: Add deprecation warning at For iOS/iPadOS users (a-Shell-Deprecated)
• 2023-10-12: Add Why and how to fix error: "fatal: not in a git directory"? to FAQ.
• 2023-01-09: Add a-Shell support for iOS/iPadOS users as a free althernative.
• 2022-11-01: Update Prerequisite, For macOS users, For Android users, FAQ wiki.

---

🪨 References

• Working Copy on iOS, by @danieltomasz^1.
• Steps to auto sync iOS + Windows, by @Caps^3.
• Gitea - self-hosted git server, by @Sawhney^2.
• Self Managed Sync + Android setup, by @danzu^5 and @Abulafia^4.
• Git hooks settings
• What is GitHub?
• How does Git work?
• Repository size limits for GitHub.com
• About large files on GitHub
• Differences between CRLF and LF, in Chinese.
• Alternative way of git syncing on iOS using a-shell for free, by Petrus Hyvönen^7.
• [Tutorial] How to enable automatic logseq graph sync on iOS with git & shortcut, by @sickmz^8.

🎉 Acknowledgment

Credits to @danieltomasz^1, @Sawhney^2, @Caps^3, @Abulafia^4 @qwxlea^5 for the workflow build up. And credits to @danzu^6 for the incredible diagram!

FYI, those IDs are IDs in Logseq Discord Server if not specified.