Fossil: Git to Fossil Translation Guide

Introduction

Fossil shares many similarities with Git. In many cases, the<br>sub-commands are identical: fossil bisect does essentially the<br>same thing as git bisect, for example.

Yet, Fossil is not merely Git with a bunch of commands misspelled. If<br>that were the case, we could give you a two-column translation table<br>which would tell you how to say things like “git reset --hard HEAD” in<br>this funny ol’ Fossil dialect of Git and be done. The purpose of this<br>document is to cover all the cases where there is no simple 1:1 mapping,<br>usually because of intentional design differences in Fossil that prevent<br>it from working exactly like Git. We choose to explain these differences<br>since to understand the conversion, you need to know why each difference<br>exists.

We focus on practical command examples here, leaving discussions of the<br>philosophical underpinnings that drive these command differences to another<br>document. The case studies do get a bit philosophical, but<br>it is with the aim of illustrating how these Fossil design differences<br>cause Fossil to behave materially differently from Git in everyday<br>operation.

We present this from the perspective of Git users moving to Fossil, but<br>it is also possible to read this document as a Fossil user who speaks<br>only pidgin Git, who may often have questions of the form, “Now how do I<br>do X in Git again?”

This document’s authors are intimately familiar with Fossil, so it is<br>difficult for us to anticipate the perspective of people who are<br>intimately familiar with Git. If you have a lot of prior Git<br>experience, we welcome your contributions and questions on the Fossil<br>Forum.

While we do try to explain Fossil-specific terminology inline here<br>as-needed, you may find it helpful to skim the Fossil glossary.<br>It will give you another take on our definitions here, and it may help<br>you to understand some of the other Fossil docs better.

Repositories and Checkouts Are Distinct

A repository and a check-out are distinct in Fossil, allowing them to be<br>stored in separate directory trees, whereas the two are commingled by<br>default with Git, with the repository stored in a .git subdirectory<br>underneath your working directory. This difference shows up in several<br>separate places when it comes to moving from Git to Fossil.

Checkout Workflows

A Fossil repository is an SQLite database storing the entire history of a<br>project. It is not normally stored inside the working tree.<br>A Fossil working tree — also called a check-out — is a directory<br>that contains a snapshot of your project that you are currently working<br>on, extracted for you from the repository database file by the fossil<br>program.

There are ways to<br>emulate the Fossil working style in Git, but because they’re not<br>designed into the core concept of the tool, Git tutorials usually<br>advocate a switch-in-place working mode instead, so that is how most<br>users end up working with Git. Contrast Fossil’s check-out workflow<br>document to see the practical differences.

There is one Git-specific detail we wish to add beyond what that<br>document already covers. This command:

git checkout some-branch

…is best given as:

fossil update some-branch

…in Fossil. There is a fossil checkout command, but it has<br>several differences that make it less broadly useful<br>than fossil update in everyday operation, so we recommend that<br>Git users moving to Fossil develop a habit of typing fossil up rather<br>than fossil checkout. That said, one of those differences does match<br>up with Git users’ expectations: fossil checkout doesn’t pull changes<br>from the remote repository into the local clone as fossil update does.<br>We think this is less broadly useful, but that’s the subject of the next<br>section.

Update vs Pull

The closest equivalent to git pull is not<br>fossil pull, but in fact fossil up.

This is because<br>Fossil tends to follow the CVS command design: cvs up pulls<br>changes from the central CVS repository and merges them into the local<br>working directory, so that’s what fossil up does, too. (This design<br>choice also tends to make Fossil feel comfortable to Subversion<br>expatriates.)

The fossil pull command is simply the reverse of<br>fossil push, so that fossil sync is functionally equivalent<br>to:

fossil push ; fossil pull

There is no implicit “and update the local working directory” step in Fossil’s<br>push, pull, or sync commands, as there is with git pull.

Someone coming from the Git perspective may perceive that fossil up<br>has two purposes:

Without the optional VERSION argument, it updates the working<br>check-out to the tip of the current branch, as git pull does.

Given a VERSION argument, it updates to the named version. If that’s the<br>name of a branch, it updates to the tip of that branch, as<br>git checkout BRANCH does.

In fact, these are the same operation, so they’re the same command in<br>Fossil. The first form simply allows the VERSION to be implicit: the<br>tip of the current branch.

We think this is a more sensible command design than git pull...