diegosouzapw 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
fossil init myproject.fossil
mkdir myproject && cd myproject
fossil open ../myproject.fossil
fossil add .
fossil commit -m "Initial commit"
Cloning and Working
fossil clone https://example.com/repo project.fossil
mkdir work && cd work
fossil open ../project.fossil
Feature Branch Workflow
# 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:
# Alice commits - automatically pushes
fossil commit -m "Alice's changes"
# Bob updates - automatically pulls Alice's changes
fossil update
Handling Mistakes
# 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
# 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
fossil sync # Full sync (push + pull)
fossil push # Push only
fossil pull # Pull only
fossil sync --private # Include private branches
Remote Management
fossil remote # Show current remote
fossil remote add URL # Set default remote
fossil remote list # List all remotes
Stash Operations
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
# 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 |
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
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.