Manabu Ninja: Fossil Version Control Guide

This guide covers everything you need to work with Fossil on this project. If you've only used Git before, you'll find most concepts familiar with a few key differences.

🤔 Why Fossil

Fossil is a single binary that bundles version control, a bug tracker, wiki, forum, and web UI into one tool. There's no need for a separate hosting platform -- fossil ui gives you a full browser-based interface that works offline. Commits auto-sync to the remote by default, so there's no separate push step.

📦 Installing Fossil

Windows: Download the zip from fossil-scm.org/home/uv/download.html, extract fossil.exe, and add it to your PATH.

macOS:

brew install fossil

Linux:

# Debian/Ubuntu
sudo apt install fossil

# Fedora
sudo dnf install fossil

Verify: fossil version

🔑 Key Concepts

Concept	Git	Fossil
Repository storage	`.git/` directory in project	Single `.fossil` file separate from working directory
Commit & push	Separate steps (`git commit` then `git push`)	`fossil commit` auto-syncs to remote
Branch creation	`git checkout -b name`	`fossil branch new name`
Staging area	`git add` stages changes	No staging area -- `fossil commit` commits all changes (use `--include` to select files)
Web UI	Requires external tool (GitHub, etc.)	Built-in: `fossil ui`
Issue tracker	External (GitHub Issues, etc.)	Built-in

📥 Getting the Code

# Clone the repository (downloads a single .fossil file)
fossil clone https://fossil.manabu.ninja manabu-ninja.fossil

# Create a working directory and open the repository into it
mkdir manabu-ninja && cd manabu-ninja
fossil open ../manabu-ninja.fossil

What just happened? Unlike Git, Fossil separates the repository database (the .fossil file) from the working directory. clone downloads the database, and open checks out files. You can open the same .fossil file in multiple directories if needed.

🔄 Daily Workflow

See what's changed

fossil status          # Working directory status (like git status)
fossil diff            # Show uncommitted changes (like git diff)
fossil extras          # Show untracked files

Add and remove files

Fossil doesn't auto-detect new or deleted files. Sync them before committing:

fossil addremove       # Stage all new files + mark deleted files for removal
fossil add newfile.dart         # Track a specific new file
fossil rm oldfile.dart          # Mark a file for removal

Tip: Run fossil addremove before every commit if you've been creating or deleting files.

Commit changes

fossil commit -m "Add new vocabulary set for colors"

No staging area -- commits all modified tracked files. To commit specific files:

fossil commit --include file1.dart --include file2.dart -m "Fix bug"

Update to latest

fossil update          # Pull + merge latest changes (like git pull)

Branches

fossil branch new my-feature       # Create a new branch
fossil checkout my-feature         # Switch to a branch
fossil branch list                 # List all branches

Stash changes

fossil stash save      # Stash uncommitted changes
fossil stash pop       # Restore stashed changes

Browse history

fossil timeline        # View recent commits
fossil ui              # Open the full web UI in your browser

Tip: fossil ui is one of Fossil's best features -- a local web interface for browsing the timeline, viewing diffs, managing tickets, and more. Works offline.

Submitting Changes

Direct push (established contributors) Commit to a named branch and it syncs automatically.

Fossil bundles (external contributors) Bundles package one or more commits into a single file:

fossil bundle export --branch my-feature my-feature.bundle
# Maintainer imports with: fossil bundle import my-feature.bundle

Plain patches (small fixes)

fossil diff > my-fix.patch

Unversioned Files

Fossil's "unversioned files" are binary artifacts distributed alongside the repo but not version-controlled. This project uses them to host release builds:

APK: fossil.manabu.ninja/uv/manabu_ninja.apk
EXE: fossil.manabu.ninja/uv/manabu_ninja.exe

# Upload a file (--as controls the filename on the server)
fossil uv add build/app/outputs/flutter-apk/app-release.apk --as manabu_ninja.apk
fossil uv sync

# List / remove
fossil uv list
fossil uv remove manabu_ninja.apk

The task release command automates this.

UV setup requirements

For unversioned file sync to work:

Your Fossil user needs the y capability on the server (s alone is not enough)
Your remote URL must include your username:

   fossil remote https://<username>@fossil.manabu.ninja/repo.fossil

UV sync must be enabled locally:

   fossil setting uv-sync 1

📋 Quick Reference

What you want to do	Command
See what changed	`fossil status`
Show untracked files	`fossil extras`
Show diff	`fossil diff`
Add new + remove deleted files	`fossil addremove`
Commit (auto-pushes)	`fossil commit -m "message"`
Pull latest	`fossil update`
Create branch	`fossil branch new name`
Switch branch	`fossil checkout name`
Stash changes	`fossil stash save`
Restore stash	`fossil stash pop`
View history	`fossil timeline`
Open web UI	`fossil ui`
Undo last operation	`fossil undo`
Get help	`fossil help` / `fossil help <command>`

⚠️ Gotchas

Auto-sync is on by default -- fossil commit pushes immediately. Use fossil commit --private or fossil setting autosync off for local-only commits.

No staging area -- fossil commit commits all modified tracked files. Use --include/--exclude to select specific files.

The .fossil file is your entire repository -- a single SQLite database. Don't delete it. The working directory is just a checkout you can recreate at any time.

fossil ui is your debugging friend -- confused about repo state? fossil ui gives you a visual overview faster than CLI commands.

Merge conflicts work like Git -- <<<<<<< / >>>>>>> markers in the file. Edit to resolve, then fossil commit.