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?

Self Managed Sync Diagram, by @danzu

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¹.
• Steps to auto sync iOS + Windows, by @Caps².
• Gitea - self-hosted git server, by @Sawhney³.
• Self Managed Sync + Android setup, by @danzu⁴ and @Abulafia⁵.
• 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⁶.
• [Tutorial] How to enable automatic logseq graph sync on iOS with git & shortcut, by @sickmz⁷.

🎉 Acknowledgment

Credits to @danieltomasz¹, @Sawhney³, @Caps², @Abulafia⁵ @qwxlea⁴ for the workflow build up. And credits to @danzu⁸ for the incredible diagram!

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

Footnotes

1. danieltomasz#5748 ↩ ↩²

2. Caps#0219 ↩ ↩²

3. Sawhney#7320 ↩ ↩²

4. qwxlea#3490 ↩ ↩²

5. Abulafia#3734 ↩ ↩²

6. https://discuss.logseq.com/u/Petrush ↩

7. https://github.com/sickmz ↩

8. danzu#6567 ↩