Fossil SCM Command Line Reference
Comprehensive guidance for managing projects with Fossil SCM from the command line, covering repository management, commits, branching, multi-user workflows, and the ticketing system.
Overview
Fossil is a distributed version control system combining source code management with an integrated wiki, ticketing system, and web interface—all in a single executable. Unlike Git, Fossil emphasizes simplicity, autosync by default, and feature-centric branching.
Key Concepts:
| Concept | Description |
|---|---|
| Repository | SQLite database file (.fossil) containing all project history |
| Working checkout | Directory where files are edited, linked via fossil open |
| Artifact | Any versioned item (file, commit, ticket) identified by SHA hash |
| Autosync | Default behavior that automatically pushes/pulls on commit/update |
Core Differences from Git
Understanding these differences prevents common mistakes:
- •Autosync is ON by default - Commits automatically push, updates automatically pull
- •Branches created during commit - Use
fossil commit --branch namenotgit checkout -b - •Single repository file - All history in one
.fossilSQLite file - •Built-in features - Wiki, tickets, forum included (not separate tools)
- •No staging area - All changed files commit together (use
fossil commit file1 file2for partial)
Essential Workflows
Starting a New Project
bash
fossil init myproject.fossil mkdir myproject && cd myproject fossil open ../myproject.fossil fossil add . fossil commit -m "Initial commit"
Cloning and Working
bash
fossil clone https://example.com/repo project.fossil mkdir work && cd work fossil open ../project.fossil
Feature Branch Workflow
bash
# Start feature (creates branch during commit) fossil commit --branch feature-login -m "Start login feature" # Work on feature fossil commit -m "Add login form" fossil commit -m "Add validation" # Merge back to trunk fossil update trunk fossil merge --integrate feature-login fossil commit -m "Merged feature-login"
Collaborative Workflow (Autosync)
With autosync enabled (default), collaboration is automatic:
bash
# Alice commits - automatically pushes fossil commit -m "Alice's changes" # Bob updates - automatically pulls Alice's changes fossil update
Handling Mistakes
bash
# Move bad commit to "mistake" branch fossil amend HEAD --branch mistake fossil amend HEAD --close fossil update trunk # Undo last update/merge/revert fossil undo # Revert uncommitted changes fossil revert
Quick Reference
| Task | Command |
|---|---|
| Create repo | fossil init repo.fossil |
| Clone repo | fossil clone URL repo.fossil |
| Open repo | fossil open repo.fossil |
| Check status | fossil status or fossil changes |
| Add files | fossil add file or fossil addremove |
| Commit | fossil commit -m "msg" |
| Update | fossil update |
| New branch | fossil commit --branch name |
| Switch branch | fossil update branchname |
| List branches | fossil branch list |
| Merge | fossil merge branchname |
| Cherry-pick | fossil merge --cherrypick HASH |
| View diff | fossil diff |
| View history | fossil timeline |
| File history | fossil finfo filename |
| Annotate/blame | fossil annotate filename |
| Stash changes | fossil stash save -m "msg" |
| Apply stash | fossil stash pop |
| Sync manually | fossil sync |
| Push only | fossil push |
| Pull only | fossil pull |
| Add ticket | fossil ticket add title "..." status "Open" |
| Update ticket | fossil ticket set UUID status "Closed" |
| Ticket history | fossil ticket history UUID |
| List tickets | fossil ticket show "All Tickets" |
| Web UI | fossil ui |
Sync and Remote Operations
Autosync Settings
bash
# Check current setting fossil settings autosync # Enable (default) fossil settings autosync on # Disable for manual control fossil settings autosync off # Pull only (no auto-push) fossil settings autosync pullonly
Manual Sync
bash
fossil sync # Full sync (push + pull) fossil push # Push only fossil pull # Pull only fossil sync --private # Include private branches
Remote Management
bash
fossil remote # Show current remote fossil remote add URL # Set default remote fossil remote list # List all remotes
Stash Operations
bash
fossil stash save -m "WIP" # Save and revert working dir fossil stash snapshot -m "msg" # Save but keep working dir fossil stash list # List stashes fossil stash show # Show most recent as diff fossil stash pop # Apply and remove fossil stash apply # Apply but keep fossil stash drop 1 # Delete specific stash
Tags
bash
# Add during commit fossil commit --tag v1.0.0 -m "Release" # Add to existing commit fossil tag add v1.0.0 HASH # List tags fossil tag list # Remove tag fossil tag cancel v1.0.0 HASH
Important Settings
| Setting | Description |
|---|---|
autosync | Auto push/pull on commit/update |
editor | Text editor for commit messages |
ignore-glob | Patterns for files to ignore |
binary-glob | Patterns for binary files |
case-sensitive | Case sensitivity for filenames |
bash
fossil settings # List all fossil settings autosync off # Set local fossil settings autosync off --global # Set global fossil unset autosync # Revert to global
Detecting Fossil Repositories
A Fossil working checkout contains either:
- •
_FOSSIL_file (Unix/Linux) - •
.fslckoutfile (Windows or when using--dotfiles)
Check with: ls -la _FOSSIL_ .fslckout 2>/dev/null
Web Interface
bash
fossil ui # Open local web UI in browser fossil ui --port 9000 # Specific port fossil server --port 8080 # External access
Additional Resources
Reference Files
For comprehensive command documentation with all options and examples:
- •
references/commands.md- Complete Fossil command reference including:- •Repository setup (init, clone, open, close)
- •File operations (add, rm, mv, status)
- •Commit options and amending
- •Branching operations
- •Merging and conflict resolution
- •Ticketing system commands
- •Diff and history commands
- •Undo and revert operations
Consult references/commands.md for detailed syntax and options not covered in this quick reference.
Version Information
Based on Fossil SCM version 2.27. Use fossil help COMMAND for authoritative documentation on the installed version.