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.
Start KiwiFS normally.
KiwiFS pushes to the configured remote on the backup interval.
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.
The command uses the same rebase-before-push behavior by default.
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.
Troubleshooting
Dirty worktree
If KiwiFS reports worktree has uncommitted changes; refusing automatic rebase, inspect the repository and save or discard the local changes.
Rebase conflict
If the rebase conflicts, resolve the conflicted markdown files with normal git tools.
Abort if you need to stop and return to the pre-rebase state.
Recover the pre-rebase HEAD
KiwiFS records the previous local HEAD before rebasing.
