Using Fossil
These instructions are the minimum needed to get going with the Fossil hosting service provided for Haplo developers. You can do much more with Fossil, see the Fossil website for more details.
Installation
First, download Fossil for your platform. Alternatively, download the source code and build it with ./configure; make
, or use your platform’s packaging system.
In all cases, you’ll end up with a single fossil
or fossil.exe
executable. This is completely self-contained, and can be placed anywhere convenient on your PATH
or otherwise.
Cloning the repository
First, you need to make a local ‘clone’ of the repository. This is a copy of all the code, the history, wiki and tickets. You commit changes to your local repository, and sync them to the repository on the server. However, we’ll be using the default ‘autosync’ mode, which automatically syncs changes to the main server.
You’ll be provided with a repository URL like https://fossil.example.com/project
, a username and a password. The username is likely to be the same as the path of the repository, in this case, project
.
Create a directory to keep your Fossil repositories. Unlike other source control systems, this is separate from the working directory. cd
into that directory, then type
fossil clone https://project@fossil.example.com/project project.fossil
Note that you need to add the username to the URL, just before the hostname.
Checking out the repository
Next, you need to make an empty directory, cd
into it, then ‘open’ the repository. For example:
cd mkdir project cd project fossil open ~/path/to/project.fossil
IMPORTANT: Always cd
into your empty directory. Fossil will write the files into the current directory, even if it’s full of other files. This can be annoying if you forget.
Write your plugin
Make changes to your code. Remember your plugin should be created in a sub-directory of the repository root.
To see what changes you’ve made, type
fossil changes fossil extras
The changes
command shows you all the files you have changed, and the extras
command shows any new files which aren’t currently under source control.
If you’ve created any new files or deleted any redundant files, you need to tell fossil with
fossil addremove
This adds any new files, and removes any files which are no longer present. You can use the fossil add
and fossil delete
commands to do this on each file individually.
To review all the changes you’ve made, type
fossil diff -N
This shows the changes to existing files, and the -N
flag shows new files.
When you’re ready to commit your changes, type
fossil commit -m "A short description of the changes"
This will commit the changes to your local repository, and since autosync is on by default, send these changes to the server.
Web interface
You can use your web browser to view the repository timeline, edit the wiki, and manage tickets. You can either use the interface on the server, at the main repository URL, or use the local repository on your computer.
IMPORTANT: If you’re typing the URL manually, make sure you remember it starts with https
. The server does not respond to http
addresses.
Typing
fossil ui
in your working directory will start an embedded web server and launch your web browser, automatically logging you in.
To send changes you’ve made locally to the server, type
fossil sync
This will also pull changes made on the server to your local repository.
Creating additional users
We provide you with a generic administration user. To create additional users, use the web interface on the server. Click ‘Admin’ in the toolbar, then ‘Users’, then the ‘Add’ button hidden in the top right.
You only need to check the ‘Developer’ capability for the new user.