Fossil SCM Usage

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:

1. Autosync is ON by default - Commits automatically push, updates automatically pull
2. Branches created during commit - Use fossil commit --branch name not git checkout -b
3. Single repository file - All history in one .fossil SQLite file
4. Built-in features - Wiki, tickets, forum included (not separate tools)
5. No staging area - All changed files commit together (use fossil commit file1 file2 for 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)
• .fslckout file (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.