Fossil workflow and cheats

2026-02-17

My goto to version control for everything (scripts, codes, wiki, art) is fossil. The main reason is low barrier to self host the instance, especially with OBSD's httpd and CGI setup. As an added bonous it's dependency free! (frowns at git).

After my bug excavation (2020), I didn't face problems with fossil. I use it across all my boxes, and sync some repository on displ as well.

Over the course of time, I developed a preference for fossil workflow. Since fossil repository gulps revision histories, wikis, cvs all together into a single *.fossil file, it works for every case. Most of my working repositories have extensive documention along with code. Depending upon the viewer interest, one could gain just from navigating wiki pages.

Fossil has in-built function of integrating wiki into source true. In my case, I usually have README under each sub directories, so fossil generates the info page and files in web ui. Due to this structure of multile READMEs, I cannot use the in-built embedded function, instead I sync REAMDE on each sub directories with the dedicated wiki pages.

Following is the workflow I folllow, below is taken from the hosted project - Sci_c_test.

Cheat Sheet

Clone a repository

The usual clone command opens the content of *.fossil file in a new directory, this is redundant in my workflow because when I clone on the ./test_project, I get

$ pwd
./test_project
$ ls
$ fossil clone  https://fsl.displ.nl/test_project
$ ls 
test_project test_project.fossil

To avoid creating such structure ./test_project/test_project, open the fossil manually,

$ fossil clone -A <user> https://<user>@fsl.displ.nl/Sci_c_test --no-open
$ fossil open *.fossil 
$ fossil add <files>
$ fossil commit -m <message>

Sync wiki and *.md files

Listing all the wiki pages,

$ fossil wiki list --all

Viewing contents on the stdout,

$ fossil wiki export <page_name> - 

Export to a file for local edits

$ fossil wiki export  <page_name> local_edit.md

Append back into the fossil-scm

$ fossil commit <page_name> local_edit.md

To reflect only the wiki changes before any commit,

$ fossil sync

To add local markdown *.md into fossil wiki,

$ fossil wiki create <wiki_name> local.md -M text/x-markdown

Actual usecase of syncing REAMDE.md files

$ mkdir  RAMSES-code
$ vim    RAMSES-code/README.md # do the edits here, fossil will auto read in web ui.
$ fossil add RAMSES-code/REAMDE.md

Sync this RAMSES-code/REAMDE.md as the RAMSES-code.wiki

$ fossil wiki create RAMSES-code-intro RAMSES-code/README.md
$ fossil wiki ls # entry should be visible here. 

Commit all the changes now in the newer branch.

$ fossil commit -m "Created new branch, README and corresponding wiki files" --branch RAMSES-code

Suppose if you happen to edit the RAMSES-code/README.md and want that reflect
the wiki page as well

$ vim RAMSES-code/README.md  # Secondary edits. 
$ fossil status              # Check the changes are tracked in the corresponding
                             # branch. (extra line after 'comment')
                             # Following updates the corresponding wiki  
$ fossil wiki commit RAMSES-code-intro  RAMSES-code/README.md 
$ fossil wiki export RAMSES-code-intro -
                             # Above should show the updated wiki

Proceed to commit and push to the remote location, if everything is okay.

$ fossil commit -m "RAMSES wiki and README"

Both wiki pages and web ui under RAMSES-code/ should be synced now.

Final Merge into trunk

$ fossil update trunk       # Change to trunk branch.
$ fossil status             # Tags should reflect 'trunk' 
$ fossil merge  RAMSES-code # Merge the branch into main 'trunk'
$ fossil commit -m "Clean merge."