KiwiFS can back up a knowledge root by pushing its git repository to a remote.
If another server, laptop, teammate, or git client pushes to the same backup branch first, a later backup push can fail with a non-fast-forward error. KiwiFS avoids the common clean case by fetching the backup branch and rebasing local backup commits before it pushes.
Add a [backup] section to .kiwi/config.toml inside your knowledge root.
[backup]
remote = "git@github.com:org/knowledge.git"
interval = "5m"
branch = "main"
# Optional. Defaults to true.
rebase_before_push = true
kiwifs serve --root ./knowledge
rebase_before_push defaults to true. You only need to set it when you want the config file to show the behavior explicitly.
Run a one-shot backup
Use kiwifs backup to push immediately.
kiwifs backup \
--root ./knowledge \
--remote git@github.com:org/knowledge.git \
--branch main
What happens before push
When rebase_before_push is enabled, KiwiFS does this for each backup push:
- Ensures the local git remote named
backup points to your configured remote.
- Resolves the backup branch from
[backup].branch, the current git branch, then main.
- Checks whether the remote branch exists.
- Fetches
backup/<branch> when the remote branch exists.
- Refuses automatic rebase if the worktree has uncommitted changes.
- Rebases clean local commits onto
backup/<branch>.
- Pushes the branch to the backup remote.
- Verifies that the remote branch HEAD matches the local HEAD.
If the remote branch does not exist yet, KiwiFS skips the rebase and lets the push create it. This supports first-time backup setup.
Safety behavior
KiwiFS automates only the routine, safe path.
- It does not force-push.
- It only rebases a clean git worktree.
- It does not resolve conflicts for you.
- If rebase fails, KiwiFS aborts the rebase and records the backup error.
- Before rebasing, KiwiFS stores the previous local HEAD at
refs/kiwifs/backup-pre-rebase.
If two writers edit the same lines, resolve the git conflict yourself. KiwiFS will not choose one version over another.
Disable rebase-before-push
Disable this only when another process owns git synchronization and you want KiwiFS to perform 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
Dirty worktree
If KiwiFS reports worktree has uncommitted changes; refusing automatic rebase, inspect the repository and save or discard the local changes.
cd ./knowledge
git status --short
git add .
git commit -m "chore: save local knowledge changes"
kiwifs backup --root .
Rebase conflict
If the rebase conflicts, resolve the conflicted markdown files with normal git tools.
cd ./knowledge
git status
# Edit conflicted files.
git add <resolved-files>
git rebase --continue
kiwifs backup --root .
Recover the pre-rebase HEAD
KiwiFS records the previous local HEAD before rebasing.
git show refs/kiwifs/backup-pre-rebase
git branch recover-before-backup-rebase refs/kiwifs/backup-pre-rebase
