FossRec > doc > Fossil For New Users
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, an easy and more certain way to find it via a search engine 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 also yield useful results.
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 should give you the same help output at the shell:
$ fossil --help
$ fossil help
You can get even more helpful information more with the -a or --all option:
$ fossil help -a
In addition to telling you what commands are available, you can also get the help command to tell you specific usage information 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 help command.
The Fossil Quick Start provides the necessary steps to get going quickly, but it may not clearly address some of the more practical concerns that help make the best use of Fossil for the long term. 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.
Creating A Repository
To create a brand new repository, use the fossil init command. The canonical approach applies the .fossil extension to the end of the repository filename. By default, the .fossil extension is used to identify suitable fossil repository files when setting up a CGI repository server.
A common approach is to designate a directory where you want to store most of your repository files, and initialize new repositories there. This directory can be whatever you wish to call it. One common choice is ~/repos -- a subdirectory within your home directory called "repos", from the word "repositories". A convenient approach to handling clones from FossRec, if you want to keep them separate from other Fossil repositories, is to create a ~/fossrec/repos directory. Whatever directory you choose to house your Fossil repository files, these are not the checked out source code files for a project. Unlike most popular open source DVCSes, Fossil has a project database file, the "repository file", that is distinct from where the checked out project files are stored. This distinction between repository database and checkout has some advantages, such as making it extremely easy to make backups, without having to back up whole checked out source trees, just by copying the repository database file.
To create a brand new repository, using ~/repos as the repository file directory, do something like the following. This example assumes your username for the local system is bob.
$ cd ~/repos
$ fossil init hello_world.fossil
project-id: 1ff654d7db1fef6770f44dba49e9704c62d59ed2
server-id: 1c535da8afac73a7d72f1953b37a27333d203bac
admin-user: bob (initial password is "ac3ed3")
$ ls
hello_world.fossil
This does not give you a working copy, however, as explained above. For that, you must "open" a checkout of your repository inside an appropriate working copy directory. Assuming you use ~/src as the location for checked out projects, you then might do the following to open a working copy of your project.
$ cd ~/src
$ mkdir hello_world
$ cd hello_world
$ fossil open ~/repos/hello_world.fossil
$ ls -a
. .. .fslckout
Your working copy is managed by the .fslckout file. Unlike the .hg and .git directories to which you may be accustomed if you have used Mercurial or Git, this is not a directory. You can safely ignore its presence for now, but do not delete it.
You can check the current status of your working copy of this Fossil managed project with the status command.
$ fossil status
repository: /usr/home/bob/frepos/hello_world.fsl
local-root: /usr/home/bob/src/hello_world/
config-db: /usr/home/bob/.fossil
checkout: f662ef63c8fa67b4a46a031bf6d5be99c80dd432 2013-08-08 19:24:38 UTC
tags: trunk
comment: initial empty check-in (user: bob)
There you have it, then: a working copy of an empty repository for Fossil SCM.
Cloning From FossRec
Cloning a repository from FossRec is a little different from creating a repository from scratch, though no more difficult. The simplest approach, if you do not have commit access to the FossRec repository and just want to have a local copy, uses the clone command. This example assumes you are cloning a project maintained by someone whose FossRec username is alice.
$ cd ~/repos
$ fossil clone http://fossrec.com/u/alice/projectname/index.cgi projectname.fossil
If you have commit access to the repository, and want to be able to push changes back with encrypted authentication via HTTPS, you will need to include your username in the cloning process and enter your password when prompted. It will ask you whether you wish to have Fossil remember your password, so that you do not have to enter it every time you synchronize the local repository with the FossRec repository, as well.
$ cd ~/repos
$ fossil clone https://bob@fossrec.com/u/alice/projectname/index.cgi projectname.fossil
password for user:
remember password (Y/n)?
Importing From Git
Fossil makes it easy to migrate a project from Git to Fossil. Because Git and Fossil are not identical systems, some metadata may not make the transition 100% intact, but a fully functional repository with all the trimmings should be the result, suitable for ongoing development. For the vast majority of use cases, any discrepancies should be unimportant and ignorable.
Given a Git project at ~/src/projectname, use Git's fast-export command and Fossil's import command to migrate a project from a local Git repository to a local Fossil repository, creating a new Fossil repository file in the process.
$ cd ~/src/projectname
$ git fast-export --all | fossil import --git ~/repos/projectname.fossil
Configuring A Repository
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.
$ cd ~/src/hello_world
$ fossil user password bob
New password for bob:
Retype new password:
By default, Fossil's autosync feature, which ensures that every time you commit to the local repository it will attempt to sync with a configured remote repository, is turned on. This may conflict with many team-oriented workflows, where members of a distributed team make many changes to a local repository before committing a completed feature, bugfix, or other change, to the upstream repository on FossRec. To turn off autosync, use the setting command.
$ cd ~/src/hello_world
$ fossil setting autosync off
If you turn off autosync, you will then have to manually use the push, pull, and sync commands, as appropriate, to perform the operations otherwise performed automatically by Fossil's autosync feature.
If you clone your repository from FossRec, it will automatically make the FossRec repository you cloned the default upstream repository. This means that the push, pull, and sync commands will cause your local repository to connect to the FossRec repository to send and/or receive updates.
Managing Project Files
After creating a new file in your project, you will probably want to check it in to your repository.
$ cd ~/src/hello_world
$ echo 'Fossil Test Project' > README
$ fossil add README
ADDED README
$ fossil status
repository: /usr/home/bob/frepos/hello_world.fsl
local-root: /usr/home/bob/src/hello_world/
config-db: /usr/home/bob/.fossil
checkout: f662ef63c8fa67b4a46a031bf6d5be99c80dd432 2013-08-08 19:24:38 UTC
tags: trunk
comment: initial empty check-in (user: bob)
ADDED README
$ fossil commit -m 'created README stub'
New_Version: 99ff416ebb1ee784d373ef364bafb02393685b23
$ fossil status
repository: /usr/home/bob/frepos/hello_world.fsl
local-root: /usr/home/bob/src/hello_world/
config-db: /usr/home/bob/.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: bob)
To check for files in the project checkout directory that have not been added to the repository, use the extras command.
$ cd ~/src/hello_world
$ fossil extras
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.
$ cd ~/src/hello_world
$ echo 'This is just a test.' >> README
$ fossil commit -m 'added a line to README'
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 delete it outright at this point without Fossil later recreating it when you check out changes.
$ rm README
$ ls -a
. .. .fslckout
Done For Now
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, as normal for comparing similar applications, 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.
NOTE: If you have been invited to host a repository at FossRec and have any questions about how best to handle things, or suggestions for more material to be provided in documentation here, contact Chad.