💥 FAQ

Why is my ssh-key not working?

Please check if your remote url looks like git@github.com:{USERNAME}/{REPOSITORY}.git

• You can find it in Logseq graph folder/.git/config.

How to fix error: The current repository is not synchronized with the remote repository, please check.

cd in your Logseq graph folder in terminal and type git fetch --prune.

How to fix error: Permission denied:(publickey).

Have you established ssh connection with github yet?

If you haven't, please refer to this tutorial

If you did, you might need to add a config telling ssh to use a specific credential !

Here's how it work:

1. Add a file named config (without any extension) under ~/.ssh
2. Edit it using your preferred text editor, add following text into the file

# github
Host github.com
    User git
    HostName github.com
    PreferredAuthentications publickey
    IdentityFile <path to your private key file>
    ServerAliveInterval 300
    ServerAliveCountMax 10

3. Test if it worked using command

ssh -T git@github.com

NOTE: Don't drop the git@. ssh -T github.com is a frequent typo that GitHub will reject.

How to fix error: Connection closed by ... port 22 / kex_exchange_identification: Connection closed by remote host?

This usually means a firewall or a proxy (common on some corporate networks and in some regions) is blocking outbound port 22, so SSH never reaches GitHub. GitHub offers SSH over the HTTPS port (443) for exactly this case.

Add this to your ~/.ssh/config:

Host github.com
    Hostname ssh.github.com
    Port 443
    User git

Then test with:

ssh -T git@github.com

If you now get the Hi <username>! You've successfully authenticated... message, you're good. (See GitHub's docs: Using SSH over the HTTPS port.)

Logseq makes local commits but never pushes / fatal: cannot exec 'ssh': Permission denied (Snap / Flatpak)

If you installed Logseq as a Snap (or Flatpak) package, the sandbox may not grant access to your SSH keys, so commits happen locally but the push silently fails. A regular git commit from the terminal works, but Logseq's hook can't reach ssh.

For Snap, connect the ssh-keys interface:

sudo snap connect logseq:ssh-keys

You can verify the package's interface connections with:

snap connections logseq

(Confirmed on Ubuntu 24.04.) Flatpak users need to grant the equivalent filesystem/SSH access to the Logseq sandbox.

Can I use HTTPS instead of SSH? / HTTPS authentication fails only inside Logseq (macOS)

Short answer: SSH is strongly recommended. The catch with HTTPS is that Logseq runs git as a child process that has no access to interactive credential prompts, so a push that works in your terminal can fail when triggered from inside Logseq.

If you want to stay on HTTPS, you need a credential helper that can answer non-interactively:

• On macOS, use the keychain helper and prime it once from the terminal so the credential is stored:

  git config --global credential.helper osxkeychain
  

  Then run a manual git push once in the terminal and enter your username + a personal access token (not your password). After the credential lands in the keychain, Logseq's child process can reuse it.

If commits are also being rejected, check your commit-signing config — a misconfigured GPG setup can block commits before the push even starts. One user reported the following working config. Note this particular example is from a Windows machine, so adjust it for your OS — on macOS the gpg.program path is different (e.g. /opt/homebrew/bin/gpg) and signing is often unnecessary, so you can simply leave GPG signing off if you don't need it:

user.name=githubUsername
user.email=youremail@gmail.com
user.signingkey=ABCDEFAAAAAAAABBBBBBCCCCCCDDDDABC12345
commit.gpgsign=true
gpg.program=C:/Program Files/Git/usr/bin/gpg.exe
tag.gpgsign=true

How are pulls/fetches automated? How do my changes show up on another device?

This workflow automates the push side and pulls on activity, not in the background. Here's the full picture:

• Pull on commit: the pre-commit hook runs git pull --no-rebase before each commit (see git-hooks/pre-commit), so any edit that triggers a commit also pulls remote changes first.
• Pull on app open: the mobile setups pull when Logseq launches — iOS via the On App Open Shortcut (Pull Repository), Android via the pull-graph script.
• Auto-commit: turning on Logseq Settings → Editor → Version control (auto-commit) makes Logseq commit periodically, which in turn fires the pull-on-commit hook above.

The key limitation: when Logseq is closed, nothing fetches in the background. So a change pushed from device A appears on device B the next time you open Logseq (or start editing) on device B — not instantly while the app is closed. If you need an explicit refresh after opening, a Re-index/Refresh (or Ctrl/Cmd + R) forces Logseq to pick up the pulled files. For true background fetch you'd have to schedule git fetch/git pull yourself (e.g. cron/systemd on desktop), which is outside this guide's scope.

What do the pre-commit / post-commit git pull/push failed messages mean?

The git hooks sync your graph automatically, and they now tell you when a sync step fails instead of failing silently. You might see one of these as a Logseq notification:

• pre-commit: 'git pull' failed (...). Committing LOCALLY only. — Before committing, the hook tried to pull remote changes and couldn't. The most common cause is that the note you just edited also changed on another device, so git won't merge over your unsaved edits. Your edit is still committed locally (nothing is lost), but it hasn't been reconciled with the remote yet, so the next push will likely fail until you do.
• post-commit: 'git push' failed (...). — The commit was made but couldn't be pushed, usually because the remote has commits you don't have yet — a rejected push.

What to do: open a terminal in your graph folder and run git pull to bring in the remote changes (resolve any conflict it reports), then let Logseq commit again on your next edit, or git push from the terminal. This is the same reconciliation described in Rejected push and Git Conflict below — the hooks just make it visible now instead of leaving you wondering why a change didn't show up on another device.

Why and how to fix error: "fatal: not in a git directory"?

It happens after git v2.35.2. git v2.35.2 add safe.directory option to solve CVE-2022-24765.

If user haven't add the path of the repo to ~/.gitconfig, it will show similar error to prevent user to use git commands.

Use git config --global --add safe.directory <git folder> to solve the issue.

What is Rejected push?

Rejected push happens when the remote (eg, GitHub) contains modifications that you have yet to download. This can happen if you forgot to do a pull in your local version before commitng new changes to it.

What is Git Conflict?

Git conflict happens when you have two commits, one local and the other remote, which modify the same file in the same lines.

What is Trailing whitespace?

Trailing whitespace happens due to two reasons:

1. CRLF : Windows uses CRLF(carriage return line feed: \r\n) and Unix uses LF(line feed \n).
2. Trailing whitespace: File contains lines ending with space.

Why do I need to know how to solve rejected push & Git conflict?

Rejected push and Git conflict are something every Git users will meet eventually. It's important to know how to solve them.

Case study

For example, You type "I'm faithful to Logseq." in your journal on your pc, but you also type "Na, I also use other note-taking tools." in your journal on your phone at the same time. GitHub will accept the first commit you push to it. But when you push the second commit, Git will say something like:

error: failed to push some refs to 'github.com:{your-username}/{your-reponame}.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

which basically means: "WTF Bruh, I can't believe you just lied to me. How can I trust you again?"

So you type git pull in your Git Bash/iTerms/Termux to gain GitHub's trust again, like what Git suggested in hint:. And that's how to resolve most of the rejected push.

However, sometimes that's not enough. After using git pull to update your local repo, Git will say:

Auto-merging {the conflict file} #e.g. journals/2022_04_23.md
CONFLICT (content): Merge conflict in {the conflict file}
Automatic merge failed; fix conflicts and then commit the result.

which means you have to manually delete which part you don't want.

So you open {the conflict file} with whatever text editor you like and fix it.

In the text editor:

<<<<<<< HEAD
- I’m faithful to Logseq. # Ok, I choose to keep this part.
=======
- Na, I also use other note-taking tools.
>>>>>>> 744f5cf94a46da43f5b318dab74c0f672bae31e2

After deletion:

- I’m faithful to Logseq.

Open Logseq and that let Logseq do the rest (Logseq will commit and push due to git hooks setting.) for you, and the Git conflict should be resolved. Now you should only see the chosen part remain in your GitHub repo. And you are again a happy Logseq user now! 😍

NOTE: For Android users, you have to manually commit and push the changes since your workflow does not contain git hooks I provided.

NOTE: Sometimes, it's the logseq/metadata.edn or logseq/pages-metadata.edn having Git conflicts. This is trickier because you cannot tell easily which part is the one you need to keep. In this case I would suggest simply remove logseq/metadata.edn or logseq/pages-metadata.edn and do a git pull again, that will restore it from the one coming from GitHub. After pulling logseq/metadata.edn or logseq/pages-metadata.edn from GitHub, Re-index and Refresh Logseq are advised.

Trailing whitespace handling

In your Git Bash/iTerms/Termux, turn off crlf check in your Git config.

git config --global core.autocrlf false
git config --global core.safecrlf false

and try to push again.

If that's not enough, add below code in your .git/hooks/pre-commit to remove trailing whitespace.

if git rev-parse --verify HEAD >/dev/null 2>&1
then
    against=HEAD
else
    # Initial commit: diff against an empty tree object
    against=4b825dc642cb6eb9a060e54bf8d69288fbee4904 # <the first commit id of your repo>
fi

# Find files with trailing whitespace
for FILE in `exec git diff-index --check $against -- | sed '/^[+-]/d' | (sed -r 's/:[0-9]+:.*//' > /dev/null 2>&1 || sed -E 's/:[0-9]+:.*//') | uniq` ; do
    # Fix them!
    (sed -i 's/[[:space:]]*$//' "$FILE" > /dev/null 2>&1 || sed -i '' -E 's/[[:space:]]*$//' "$FILE")
    git add "$FILE"
    echo "NOTE: removed trailing whitespace from $FILE"
done

and try to push again.