Fossil SCM is a distributed version control system, or DVCS. It is a lot more than that, though; it is also a wiki, an issue tracker, and a Web application, for instance. Probably because it is a lot more than a version control system, the easiest and more certain way to find it on google is by searching for
fossil scm (SCM for Source Code Management) rather than something like
fossil version control or
fossil dvcs, though those search terms should yield useful results too.
Fossil, at the time of this writing, is less popular than Git, Mercurial, and Bazaar, though it is growing in popularity. Users of popular DVCSes like Git, Mercurial, and Bazaar should find much of its command line interface familiar, but there are some differences that need to be observed to use it effectively.
The first and most obvious thing to know about using it, of course, is command line help. Either of these commands will give you the same help output at the shell:
fossil --help fossil help
You can get more with the
fossil help -a
In addition to telling you what commands are available, you can also get the
help command to tell you specific usage help for each of the commands:
Usage: fossil help COMMAND
That syntax help comes first, a list of commands next, and version information last, when you use the
The Fossil Quick Start provides the necessary steps to get going quickly, but I found it did not give a very simple and smooth introduction to getting started. For that reason, I offer the benefit of my experience here. The following assumes you have used a DVCS before, or at least understand them in the abstract and know what the common jargon means and why you would want to perform various tasks with a DVCS.
To create a brand new repository, use the
fossil init command. I tack
.fsl onto the end of my repository names when using Fossil's
init command because of the fact that, by default, it creates a file in the current directory with whatever name you specify when initializing a repository.
A smart move might be to designate a directory where you want to store most of your repository files, and initialize new repositories there. I typically use
~/frepos (that's a "frepos", for "fossil repositories", directory inside my home directory) as the location where I store my repository files. These repository files are not the checked out source code files for a project. Unlike most popular DVCSes, Fossil has a separate project database file on any system where you want to have checkouts. This distinction between repository database and checkout has some advantages, such as making it extremely easy to make backups without having whole checked out source trees just by copying the repository database file, though some people might find it strange at first. Your mileage may vary, and you may wish to keep the repository database file with your working checkout; it is entirely a personal choice.
Assuming you use the same process as me, you might do the following.
$ cd ~/frepos $ fossil init hello_world.fsl project-id: 1ff654d7db1fef6770f44dba49e9704c62d59ed2 server-id: 1c535da8afac73a7d72f1953b37a27333d203bac admin-user: ren (initial password is "ac3ed3") $ ls hello_world.fsl
This does not give you a working copy, however. For that, you need to "open" your repository inside an appropriate working copy directory. I usually keep my project source code directories in
~/src, though different people have different ways of doing things. Assuming you use
~/src, just for ease of explaining things, you then might do the following to open a working copy of your project.
$ cd ~/src $ mkdir hello_world $ cd hello_world $ fossil open ~/frepos/hello_world.fsl $ ls -a . .. .fslckout
As you can see here, your working copy is managed by a
.fslckout file. Unlike the
.git directories to which users of Mercurial and Git might be accustomed, this is not a directory. You can safely ignore its presence for now, but don't delete it.
You can check the current status of your working copy of this Fossil managed project.
$ fossil status repository: /usr/home/ren/frepos/hello_world.fsl local-root: /usr/home/ren/src/hello_world/ config-db: /usr/home/ren/.fossil checkout: f662ef63c8fa67b4a46a031bf6d5be99c80dd432 2013-08-08 19:24:38 UTC tags: trunk comment: initial empty check-in (user: ren)
There you have it, then: a working copy of an empty repository for Fossil SCM.
Once you have a repository, you may wish give it some non-default configuration settings. The first thing you might want to change is the password for your repository. You can accomplish this with a command line operation. Starting within the checked out project directory, use
fossil user password <username> to change the password for the admin user of the repository.
$ pwd /usr/home/ren/src/hello_world $ fossil user password ren New password for ren: Retype new password:
Not much else is likely to be important to change at first, so for now we'll leave it at that.
After creating a new file in your project, you will probably want to check it in to your repository.
$ echo 'Fossil Test Project' > README $ ls README $ fossil add README ADDED README $ fossil status repository: /usr/home/ren/frepos/hello_world.fsl local-root: /usr/home/ren/src/hello_world/ config-db: /usr/home/ren/.fossil checkout: f662ef63c8fa67b4a46a031bf6d5be99c80dd432 2013-08-08 19:24:38 UTC tags: trunk comment: initial empty check-in (user: ren) ADDED README $ fossil commit -m 'created README stub' New_Version: 99ff416ebb1ee784d373ef364bafb02393685b23 $ fossil status repository: /usr/home/ren/frepos/hello_world.fsl local-root: /usr/home/ren/src/hello_world/ config-db: /usr/home/ren/.fossil checkout: 99ff416ebb1ee784d373ef364bafb02393685b23 2013-08-08 19:36:54 UTC parent: f662ef63c8fa67b4a46a031bf6d5be99c80dd432 2013-08-08 19:24:38 UTC tags: trunk comment: created README stub (user: ren)
You do not need to use
fossil status every time you do something, of course, but it might be instructive to see what output you get for the
status command after each version control management operation. When you edit files that are already checked into your repository, you commit the changes without having to
add the files first; you only have to add a file once.
Deleting a file is as simple as in any other popular DVCS as well.
$ fossil rm README DELETED README $ fossil commit -m 'removed README' New_Version: 88a9b40b38b9eb5a3e1e7c1b3f45427d02c19e17 $ ls README
Notice the README file is still there. It has simply been removed from version control for the current repository state. You can just delete it outright at this point without Fossil later recreating it when you check out changes.
$ rm README $ ls -a . .. .fslckout
Those are the basics. Read up on the various commands using
fossil help <command> to find out how things work. Most of it should be fairly familiar to users of other popular DVCSes and, like them, there are some subtle differences in how things are done.
From here on, the
help command and the official Fossil Quick Start should serve you well.