About me: My name is Solène Rapenne, pronouns she/her. I like learning and sharing knowledge. Hobbies: '(BSD OpenBSD Qubes OS Lisp cmdline gaming security QubesOS internet-stuff). I love percent and lambda characters. OpenBSD developer solene@. No AI is involved in this blog.

Contact me: solene at dataswamp dot org or @solene@bsd.network (mastodon).

You can sponsor my work financially if you want to help me writing this blog and contributing to Free Software as my daily job.

[Cheatsheet] Fossil version control software

Written by Solène, on 29 January 2023.
Tags: #fossil #versioning #nocloud

Comments on Fediverse/Mastodon

1. Introduction §

Fossil is a DVCS (decentralized version control software), an alternative to programs such as darcs, mercurial or git. It's developed by the same people doing sqlite and rely on sqlite internally.

Fossil official website

2. Why? §

Why not? I like diversity in software, and I'm unhappy to see Git dominating the field. Fossil is a viable alternative, with simplified workflow that work very well for my use case.

One feature I really like is the autosync, when a remote is configured, fossil will automatically push the changes to the remote, then it looks like a centralizer version control software like SVN, but for my usage it's really practical. Of course, you can disable autosync if you don't want to use this feature. I suppose this could be reproduced in git using a post-commit hook that run git push.

Fossil is opinionated, so you may not like it if that doesn't match your workflow, but when it does, it's a very practical software that won't get in your way.

3. Fossil repository is a file §

A major and disappointing fact at first is that a fossil repository is a single file. In order to checkout the content of the repository, you will need to run fossil open /path/to/repo.fossil in the directory you want to extract the files.

Fossil supports multiple checkout of different branches in different directories, like git worktrees.

4. Cheatsheet §

Because I'm used to other versionning software, I need a simple cheatsheet to learn most operations, they are easy to learn, but I prefer to note it down somewhere.

4.1. View extra files §

You can easily find non-versioned files using the following command:

fossil extras

4.2. View changes §

You can get a list of tracked files that changed:

fossil changes

Note that it only display a list of files, not the diff that you can obtain using fossil diff.

4.3. Commit §

By default, fossil will commit all changes in tracked files, if you want to only commit a change in a file, you must pass it as a parameter.

fossil commit

4.4. Change author name §

fossil user new solene@t470 and fossil user default solene@t470

More possibilities are explained in Fossil documentation

4.5. Add a remote §

Copy the .fossil file to a remote server (I'm using ssh), and in your fossil checkout, type fossil remote add my-remote ssh://hostname//home/solene/my-file.fossil, and then fossil remote my-remote.

Note that the remote server must have the fossil binary available in $PATH.

4.6. Display the Web Interface §

fossil ui will open your web browser and log in as admin user, you can view the timeline, bug trackers, wiki, forum etc... Of course, you can enable/disable everything you want.

4.7. Get changes from a remote §

This is a two-step operation, you must first get changes from the remote fossil, and then update your local checkout:

fossil pull
fossil update

4.8. Commit partial changes in a file §

Fossil doesn't allow staging and committing partial changes in a file like with git add -p, the official way is to stash your changes, generate a diff of the stash, edit the diff, apply it and commit. It's recommended to use a program named patchouli to select hunks in the diff file to ease the process.

Fossil documentation: Git to Fossil translation

The process looks like this:

fossil stash -m "tidying for making atomic commits"
fossil stash diff > diff
$EDITOR diff
patch -p0 < diff
fossil commit

Note that if you added new files, the "add" information is stashed and contained in the diff.