fx_example_peer_git - fx - Example of mirroring to git peers.
Welcome to fx, an application and set of packages providing extended management commands for the fossil SCM. This is an introductory document to fx, an application with supporting packages providing users of the Fossil SCM with extended management facilities going beyond the regular command line.
It is one in a set of related examples demonstrating the abilities of the system. The interested reader can then go on into to reference documentation via fx - Introduction to fx.
You have to manage one or more git mirrors of your repository. It assumed that the fossil repository is the master, with the git mirror serving as a read-only backup.
You have (full) access to a repository file of the project.
You have git-mediated access to the mirror.
Exporting to git repositories (the only thing we can currently do with fx) is nearly as easy to do as setting up a fossil mirror.
Simply run something like:
fx peer add-git git@github.com:${user}/${repository}.git
with suitable settings for user and repository. Assuming that your mirror is on github. To suit other hosting service change the reference per their instructions.
For multiple git mirrors simply add each separately.
The one non-obvious difference to mirroring to other fossil repositories is the need for a state directory. This directory holds a local git repository which is a copy of the fossil repository in question. New commits found in fossil are first imported into this copy, and then pushed out from there to the actual git mirrors.
Hopefully the above makes it clear that we have only one state directory for the fossil repository, regardless of the number of git mirrors. This directory is further only created and initalized if we have git mirrors at all.
Assuming that the local fossil repository is found at
"/path/to/repository/file"
the default location of the state directory is
"/path/to/repository/file.peer-state"
I.e. the path of the directory is derived from the repository file by appending the suffix ".peer-state".
If that location is not suitable for some reason it is possible to explicitly set its location to a path of the user choice, using the command
fx peer state /path/to/the/chosen/state/directory
Similary
fx peer state
will print the path of the state directory used by the fossil repository we are working with.
ATTENTION: It is very bad to point multiple fossil repositories to the same state directory. The files and directories in the state directory have fixed names, causing the fossil repositories to fight over they contents. They do not share. Do not do this.
With all the preparatory work finally done we can go and start the mirroring. Note however that fx does not fully do everything by itself.
It assumes that it will be called from a cron job, i.e. that all the timing-related things are handled by the system, as is the prevention of multiple parallel mirroring runs, and where log files will be located.
As we have full access to the fossil repository file of the project the only fx command we need in the core job script is peer exchange, i.e.
fx peer exchange -R /path/to/the/fossil/repository/file
A few things to remember however:
cron is notoriously fiddly with regard to the environment variables provided to the jobs. Make sure that:
Your PATH provides access to
git,
awk,
sed,
ssh. This last is required if and only if you have git destination repositories which are accessed through ssh urls. In that case you will aslo have to make sure that ssh has access to an ssh-agent loaded with all the necessary keys so that it can run without having to interactively ask for passwords.
That a proper USER variable is set for fossil to pick up.
This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such at the fx Tracker. Please also report any ideas for enhancements you may have for either package and/or documentation.
Fossil support