Skip to content

docs: require unconfined Logseq (AppImage) on Linux, not snap/Flatpak #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
pihalf wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: require unconfined Logseq (AppImage) on Linux, not snap/Flatpak #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,20 @@ In Logseq: **Settings > Advanced > Developer mode** (on) → **Plugins > Load un

</details>

### Linux: install the AppImage, not snap or Flatpak

gitseq runs git through Logseq's bundled `dugite`, inheriting Logseq's `HOME` and `PATH`. Sandboxed Logseq builds break this:

| Install | Works | Why |
|---|---|---|
| **AppImage** / unpacked `.deb` / AUR | ✅ | Unconfined: reads your real `~/.gitconfig`, and git's filters/hooks resolve host `git-crypt`/`git-lfs` on `PATH`. |
| **Snap** | ❌ | Remaps `HOME` (→ "Author identity unknown") and its mount namespace hides host `/usr/bin` (→ "git-crypt: not found", exit 127). |
| **Flatpak** | ⚠️ | Real `HOME` fixes identity + SSH, but the sandboxed `/usr` still hides `git-crypt`/`git-lfs`. |

This affects any clean/smudge filter (`git-crypt`) and any hook-invoked binary (`git-lfs`), not just encryption. **On Linux, install the [AppImage](https://github.com/logseq/logseq/releases).**

**Ubuntu 24.04+:** the AppImage needs an AppArmor `userns` profile to launch (or run it with `--no-sandbox`).

## Prerequisites

Before using gitseq, your Logseq graph needs to be a git repo with a remote:
Expand Down Expand Up @@ -151,6 +165,8 @@ git-crypt unlock ~/.git-crypt-my-graph.key

Open the graph in Logseq. Install gitseq. Done.

> **Linux:** install Logseq as the AppImage, not snap or Flatpak — see [Linux: install the AppImage](#linux-install-the-appimage-not-snap-or-flatpak).

## CLI companion (optional)

A Rust CLI for syncing outside Logseq (terminal, cron, automation):
Expand All @@ -170,6 +186,8 @@ cd cli && cargo build --release

**Cmd+S doesn't work** — another plugin may have claimed it. Use `Cmd+Shift+P` → "gitseq: Sync Now".

**"Author identity unknown" or "git-crypt: not found" (exit 127) on Linux** — you're on a sandboxed Logseq (snap/Flatpak). Install the [AppImage](#linux-install-the-appimage-not-snap-or-flatpak) instead.

## License

MIT