Fossil-SCM: Simple Tutorials

Miscellaneous Notes

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.

Home About Me
Copyright © Neil Carter

Last updated: 2015-07-23