Fossil Cheat Sheet

A quick reference for working with Fossil repositories on Isurus. Create a repository with the VCS type set to Fossil, then use the standard fossil client (Fossil ≥ 2.26 recommended).

Fossil differs from Git and Mercurial in two ways worth knowing up front:

A Fossil repository is a single .fossil file. You clone that file, then fossil open a working check-out from it.
Isurus serves Fossil over both HTTP and SSH. Over HTTP you authenticate with the --httpauth flag; over SSH you authenticate with an SSH key (Settings → SSH Keys) — no --httpauth needed.

Fossil calls a commit a check-in.

Getting Started

Clone a Repository

Copy the exact URL from the repository's Clone widget. The general shapes:

# Public repository
fossil clone https://your-isurus-instance/org/repo repo.fossil

# Private repository — authenticate with your username/token
fossil clone --httpauth <user>:<token> https://your-isurus-instance/org/repo repo.fossil

This writes a single-file repository, repo.fossil.

Clone over SSH

Isurus also serves Fossil over SSH, authenticated by your SSH key (add one under Settings → SSH Keys) — no --httpauth is required:

# Over SSH — authenticate with your SSH key
fossil clone ssh://fossil@your-isurus-instance:2222/org/repo repo.fossil
fossil open repo.fossil

The fossil@ login name in the SSH URL matches the VCS. Isurus authenticates by SSH key, not by that name. Copy the exact URL from the repository's Clone widget.

Fossil does not accept user:pass@host in the URL against Isurus — over HTTP, use the --httpauth <user>:<token> flag. The <token> may be your account password or an API token. Create a token under Settings → Security → API Tokens or a repository's Settings → Integration → Tokens; scope it repo:read to clone/pull and repo:write to push. SSO (SAML/OIDC) users have no account password and must use a token.

Open a Working Check-Out

mkdir repo && cd repo
fossil open ../repo.fossil

Configure Your Identity

Fossil records the local USER on check-ins. To set an explicit author:

fossil user default <your-name>
# or override per check-in with:  fossil commit --user-override <name> ...

Daily Workflow

Check Status

# Changes in the working check-out
fossil status

# Files not yet under management
fossil extras

Add Files and Check In

# Start managing a file
fossil add path/to/file.go

# Check in (commit) with a message
fossil commit -m "Add new feature"

Sync, Pull, and Push

Fossil remembers the remote it was cloned from, so from an open check-out:

# Push local check-ins to Isurus
fossil push

# Pull remote check-ins
fossil pull

# Two-way sync (pull + push)
fossil sync

# Update the working check-out to the latest tip
fossil update

For a private repository, add --httpauth <user>:<token> (and the repo URL) if Fossil prompts for credentials:

fossil push --httpauth <user>:<token> https://your-isurus-instance/org/repo

Branches

Fossil branches are created at check-in time:

# List branches
fossil branch list

# Start a new branch with your next check-in
fossil commit --branch my-feature -m "Begin feature work"

# Switch the working check-out to a branch
fossil update my-feature

# Show the current check-out's branch and status
fossil status

History

# Timeline of recent check-ins
fossil timeline

# Details for a specific check-in
fossil info <check-in-hash>

# Show the diff of the working check-out
fossil diff

# Blame a file
fossil blame path/to/file.go

Pull Request Workflow

Isurus pull requests for Fossil repositories are branch based: you push a branch, then open a PR to merge it into the repository's mainline branch (typically trunk).

# 1. Clone and open a check-out
fossil clone --httpauth <user>:<token> https://your-isurus-instance/org/repo repo.fossil
mkdir repo && cd repo
fossil open ../repo.fossil

# 2. Start a feature branch with your first check-in
fossil commit --branch add-search-api -m "Add search endpoint to API"

# 3. Continue working and check in as needed
fossil commit -m "Add search tests"

# 4. Push the branch to Isurus
fossil push

# 5. Open a Pull Request on the Isurus web UI:
#    Repository > Pull Requests > New Pull Request
#    (source = add-search-api, target = trunk)

To address review feedback, check in more changes on the same branch and fossil push again — the PR updates automatically.

See Pull Requests for the review, merge, and issue-linking flow (identical across all VCS types).

Browsing Locally

Fossil ships its own local web UI, handy for exploring a check-out offline:

fossil ui

This opens a browser against the local .fossil file. It is entirely separate from your Isurus instance — Isurus remains the source of truth you push to.

CI/CD

A fossil push triggers CI exactly like any other backend. Commit a .isurus-ci.yml to the repository root; pushes and tags fire pipelines. See the CI/CD Guide.