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://hg@your-isurus-instance:2222/org/repo repo.fossil
fossil open repo.fossil

The hg@ login name in the SSH URL is not significant — 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 → 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.