Fossil-SCM: Simple Tutorials

Miscellaneous Notes

• Fossil keeps track of everything (commits, files, edits, etc.) by treating them as distinct "artefacts", each of which has a GUID. When running commands that apply to specific items (artefacts), it is usually necessary to supply the ID in the command, although fossil will default to the relevant artefact if none is given. As a convenience, you don't have to type in the entire, lengthy, GUID; just type enough characters to uniquely identify it.
• In certain circumstances, in a check-out that already contains the trunk's code, running "fossil diff" and "fossil status" will reveal no changes, even though the trunk has been changed.
• To move between versions, run "fossil update <ID>". You can also use "fossil checkout <ID>", but the consensus on the forum seems to favour "update".
• When selecting a file-version to diff against, do not use the artefact-ID in the main project timeline. Instead, you should use the ID for the file-artefect in the required commit (check-in), which can be found by clicking the commit-ID, then clicking the "to" file-ID for the file's entry under the "Changes" heading.
• Where commands are given here, anything between angle brackets "<>" is a placeholder that you should replace with the appropriate value. And ID stands for the artefact ID in the Fossil repository, which can represent a specific version of a file, sets of contemporaneous files (commits), and so forth.
• There are two special types of tags, symbolic and raw. Symbolic tags have values that start with "sym-", raw tags are
• All artefacts have a raw tag called "branch". If its value is "trunk" then it is considered to be the trunk, but any other value means a branch with that name. Another raw tag is "closed", which marks an artefact such that it is excluded from Fossil's lists of open items. In that sense, it acts like a read-only flag. The closed tag is typically used on the last commit in a branch, to indicate that development along this branch is complete (or just at an end).
• Symbolic tags are used to 'name' artefacts; this name (without the "sym-" prefix) can be used as a shorthand (or more meaningful) way of referring to items in the repository.

Applying a fix to an old version

When fixing a bug in a published version, make sure that the version used as the baseline-code for the fix is the same as the one that has been published (not an interim in-house-only version). This will make it easier to apply the fix to published installations. To make it easier to identify the version present in an installation, record the fossil artefact number in a 'NEWS' file.

1. Obtain the broken old version by running "fossil checkout <ID>" or "fossil open <repository_file> <ID>".


2. Repair the code.
3. Store the repaired code in a branch of the repository with: "fossil commit --branch <branch_name> --close". The "--close" option closes the branch, which you should do if the changes are complete (presumably, once the fix has been applied, the branch is no longer needed, except to obtain the patched old version).

4. 5. Run "fossil update trunk" in order to obtain the trunk's current (unrepaired, assuming the repair to the old version is relevant to the current version) code. NOTE: the repaired code in the current check-out will not be lost now that it has been committed to the repository.
5. Run "fossil merge <branch_name>" to apply the repaired code (from the branch) to the trunk's check-out.
6. Make sure that the merged code works properly (e.g. a line added from the repaired old version might look fine, but uses an variable name that has since been changed).
7. Run "fossil commit" to store the repaired trunk code in the repository.

Closing a Branch

The simplest command for closing a branch is by adding a raw-tag with the value "closed", thus: "fossil tag add --raw closed <ID>".

Also, a branch can be closed when applying the final commit to it, with the command "fossil commit --close".

Note that the "--close" option can even be used when creating a new branch (e.g. "fossil commit --branch <branch_name> --close"), which one might do when only a single change is anticipated on the branch.

This is how the timeline view depicts a branch that was closed after its final commit:

Managing a Fork

After checking-out an old version, and then submitting some changes by running "fossil commit" (without a branch option), a fork will occur. Thus, Fossil rejects the commit with the error message "would fork, "update" first, or use "--allow-fork"".

To commit the changes anyway, use the command "fossil commit --allow fork".

This is how the timeline view depicts a fork (as opposed to a branch); note the two "trunk"s:

But now you might want to make the fork into a proper branch. This can be achieved with the following commands, performed in sequence:

"fossil tag add --raw branch <ID> <branch_name>"
"fossil tag cancel --raw sym-trunk <ID>"

Publishing a version

When sending out an installation of a project maintained in Fossil, ensure that the NEWS file contains the ID number of the commit containing the published set of files. Also, add a tag to the fossil artefact, indicating that this version has been published.

Undoing a commit

A commit can't be undone in the sense of removing it, so the recommended procedure is to move the unwanted commit to a branch, which is then immediately closed.

Using the Command Line

1. Move the unwanted commit to a branch and give it a tag (which will act as the branch's name) "Mistake", using the following command: "fossil tag add --raw branch <ID> Mistake".
2. Close the branch with "fossil tag add --raw closed <ID>"
3. Remove the trunk tag from the branch with "fossil tag cancel --raw sym-trunk <ID>"
4. In order to return the check-out's code back to the correct version, use "fossil update <ID>".

Using the Web Interface ("fossil ui")

1. Go to the timeline and click on the artifact that needs changing.
2. Click on "Other Links: Edit".
3. Tick the "Branching" box, and name the branch something like "Mistake".
4. Tick the "Leaf Closure" box.
5. Run "fossil update trunk" to revert the working directory back to the trunk.
6. Keep "-merge" files, discard the others.

Last updated: 2015-07-23