Zefina  Zefina: Fossil: Tips

Fossil is the best software configuration management system you never heard of. Out of the box, Fossil has:

• Source Code tracking (like cvs,git,svn)
• A ticketing system for bugs and features
• A wiki
• A forum
• plus other project management features

Fossil is free and is available for many different systems.

Help

Fossil has a built-in help.

> fossil help

This will show a list of the most common commands. To learn more about the commands:

> fossil help COMMAND

Fossil's help command has many available options. To find out more:

> fossil help help

Tip: Most of Fossil's command expect to be run from inside a checkout repository.

Clone

The first step to using Fossil is to clone a repository: fossil clone URL

The basic syntax will clone the repo and set the admin user to be your current username. This is fine when working with personal projects. When working with a group, it is better to specify a few options.

> fossil clone \
  --admin-user YOUR_PROJECT_USERNAME \
  --no-open \
  --unversioned \
  https://YOUR_PROJECT_USERNAME@URL \
  Zefina.fossil

• --admin-user : set the admin user of your clone to be YOUR_PROJECT_USERNAME. This will be the username used by default when your local repo is sync'ed with the remote repo.
• --no-open : do not open the repository. (See "Open" below)
• --unversioned : also clone the "unversioned" data
• https://USERNAME@... : Fossil allows for usernames to be embedded in the URLs

Tip: DO NOT copy the repository (cp foo.fossil foo-backup.fossil). Use fossil clone to make copies.

Open

Use the open command to open the repository. The default behavior of open is to dump the repo contents into the current directory.

> mkdir /my/checkout/path
> cd /my/checkout/path
> fossil open /path/to/repo

Or you can tell Fossil where to open the repo:

> mkdir /my/checkout/path
> fossil open /path/to/repo --workdir /my/checkout/path

You can have a single repository opened in multiple directories at the same time.

Tip: DO NOT open a repository in the same directory as the repository file.

UI

Fossil has a built-in http server allowing you to interact with the repository using a web browser.

> fossil ui

After you close the web browser, you will need to Ctrl-C the fossil ui command to stop it.

Add/Remove/Revert/Undo

To add file to the repo and remove files from the repo:

> fossil add FILE
> fossil rm FILE

To reset a file back to what is in the repo:

> fossil revert FILE

If you did an action and want to undo it:

> fossil undo

Sometimes Fossil will tell you when undo is or is not possible.

Tip: undo is only one level deep.

Commit

Fossil does not use a "staging" area, all changes will be committed to the repo.

> fossil commit

Pull/Push/Sync

To get the latest changes from the remote repo:

> fossil pull

To push your local changes to the remote repo:

> fossil push

The sync command will do a pull and a push with the remote repo:

> fossil sync

If you have problems like Fossil saying you don't have access, try the following:

> fossil push 'https://USERNAME@URL'

or

> fossil sync 'https://USERNAME@URL'

Close

There is an open command, what about close? When you are done working in a checkout directory, just delete the directory when you are done. No need to close it.

Versioned Vs Unversioned

Fossil can store versioned files like any other SCM.

Unversioned files are files that are stored in Fossil without the versioning data/info. This allows Fossil to store binary data (which can not be versioned) or other data files in its SCM.

To view the repository's unversioned files:

> fossil uv list