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:

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

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

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.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.