Backup sync

Every write in KiwiFS is a git commit, so backing up means pushing that repository somewhere else. Backup sync pushes to a git remote on an interval while the server runs, and kiwifs restore clones it back. Before each push, KiwiFS fetches the remote branch and rebases local commits onto it. This avoids the routine non-fast-forward failure you’d get when another server, laptop, or teammate pushed to the same branch first.

Turn on backup sync

Add a backup section

.kiwi/config.toml

[backup]
remote = "git@github.com:org/knowledge.git"
interval = "5m"
branch = "main"

Make sure the server can push

The KiwiFS process pushes with your system git, so it needs SSH keys or credentials for the remote.

Start the server

Terminal

kiwifs serve --root ./knowledge

KiwiFS pushes once at startup, then on every interval, and once more on shutdown.

Key	Default	Description
`remote`		Git remote URL. Backup sync is off when it’s empty.
`interval`	`5m`	Go duration between pushes. The minimum is `30s`.
`branch`	Current branch, then `main`	Branch to push
`rebase_before_push`	`true`	Fetch and rebase onto the remote branch before pushing

In containers, set KIWI_BACKUP_REMOTE, KIWI_BACKUP_INTERVAL, and KIWI_BACKUP_REBASE_BEFORE_PUSH instead. They override the TOML values.

Check the last push

Terminal

curl http://localhost:3333/api/kiwi/backup/status

Response

{ "enabled": true, "status": { "last_push_at": "2026-10-19T18:46:15Z", "success": true } }

When a push fails, success is false and error holds the reason.

Push once from the CLI

Terminal

kiwifs backup --root ./knowledge

Without --remote, the command reads remote, branch, and rebase_before_push from [backup] in .kiwi/config.toml.

Flag	Default	Description
`--root`, `-r`	`./knowledge`	Knowledge root
`--remote`	From config	Remote URL. When set, KiwiFS ignores the config file.
`--branch`	Current branch	Branch to push
`--rebase-before-push`	`true`	Fetch and rebase before pushing

Restore from a remote

kiwifs restore clones a backup into an empty directory.

Terminal

kiwifs restore --from git@github.com:org/knowledge.git --to ./knowledge --branch main
kiwifs serve --root ./knowledge

Flag	Description
`--from`	Remote URL to clone (required)
`--to`	Target directory. It must not exist or must be empty. (required)
`--branch`	Branch to check out. Defaults to the remote’s default branch.

Search indexes aren’t part of the backup. KiwiFS rebuilds them in .kiwi/state/ when the server starts.

What happens before a push

With rebase_before_push on, each push:

Points a git remote named backup at your configured URL.
Resolves the branch from [backup].branch, then the current branch, then main.
Checks whether the branch exists on the remote. If it doesn’t, KiwiFS skips the rebase and the push creates it.
Fetches backup/<branch>.
Refuses to rebase if the worktree has uncommitted changes.
Saves the current HEAD at refs/kiwifs/backup-pre-rebase, then rebases local commits onto backup/<branch>.
Pushes the branch.
Checks that the remote branch now matches the local HEAD, and logs a warning if it doesn’t.

KiwiFS automates only this clean path. It never force-pushes and never resolves conflicts. If the rebase fails, KiwiFS aborts it and reports the error in the backup status. Turn the rebase off only when another process owns git synchronization and you want a plain push:

[backup]
rebase_before_push = false

KIWI_BACKUP_REBASE_BEFORE_PUSH=false kiwifs serve --root ./knowledge

kiwifs backup --root ./knowledge --rebase-before-push=false

Troubleshooting

worktree has uncommitted changes; refusing automatic rebase

Commit or discard the local changes, then push again.

Terminal

cd ./knowledge
git status --short
git add .
git commit -m "Save local knowledge changes"
kiwifs backup --root .

Rebase conflict

Two writers changed the same lines. Resolve the conflicted markdown files with normal git tools.

Terminal

cd ./knowledge
git status
# Edit the conflicted files, then:
git add <resolved-files>
git rebase --continue
kiwifs backup --root .

Run git rebase --abort to give up and return to the pre-rebase state.

Recover the pre-rebase HEAD

Terminal

git show refs/kiwifs/backup-pre-rebase
git branch recover-before-backup-rebase refs/kiwifs/backup-pre-rebase

Versioning

How every write becomes a commit.

Docker

Configure backup with environment variables.

Getting Started

Core Concepts

Widgets

Guides

Data Import

Data Export

Deployment

Turn on backup sync

Check the last push

Push once from the CLI

Restore from a remote

What happens before a push

Troubleshooting

Versioning

Docker

​Turn on backup sync

​Check the last push

​Push once from the CLI

​Restore from a remote

​What happens before a push

​Troubleshooting

​Related

Versioning

Docker

Turn on backup sync

Check the last push

Push once from the CLI

Restore from a remote

What happens before a push

Troubleshooting

Related