The quickstart guide explains how to get up and running with fossil. But once you're running, what can you do with it? This document will walk you through the process of creating a fossil repository, populating it with files, and then sharing it over the web.
The first thing we need to do is create a fossil repository file:
stephan@ludo:~/fossil$ fossil new demo.fossil project-id: 9d8ccff5671796ee04e60af6932aa7788f0a990a server-id: 145fe7d71e3b513ac37ac283979d73e12ca04bfe admin-user: stephan (initial password is ******)
The numbers it spits out are unimportant (they are version numbers).
Now we have an empty repository file named demo.fossil. There is nothing magical about the extension .fossil - it's just a convention. You may name your files anything you like.
The first thing we normally want to do is to run fossil as a local server so that you can configure the access rights to the repo:
stephan@ludo:~/fossil$ fossil ui demo.fossil
The ui command starts up a server (with an optional -port NUMBER argument) and launches a web browser pointing at the fossil server. From there it takes just a few moments to configure the repo. Most importantly, go to the Admin menu, then the Users link, and set your account name and password, and grant your account all access privileges. (I also like to grant Clone access to the anonymous user, but that's personal preference.)
Once you are done, kill the fossil server (with Ctrl-C or equivalent) and close the browser window.
Tip: it is not strictly required to configure a repository this way, but if you are going to share a repo over the net then it is highly recommended. If you are only going to work with the repo locally, you can skip the configuration step and do it later if you decide you want to share your repo.
The next thing we need to do is open the repository. To do so we create a working directory and then cd to it:
stephan@ludo:~/fossil$ mkdir demo stephan@ludo:~/fossil$ cd demo stephan@ludo:~/fossil/demo$ fossil open ../demo.fossil stephan@ludo:~/fossil/demo$
That creates a file called _FOSSIL_ in the current directory, and this file contains all kinds of fossil-related information about your local repository. You can ignore it for all purposes, but be sure not to accidentally remove it or otherwise damage it - it belongs to fossil, not you.
The next thing we need to do is add files to our repository. As it happens, we have a few C source files lying around, which we'll simply copy into our working directory.
stephan@ludo:~/fossil/demo$ cp ../csnip/*.{c,h} .
stephan@ludo:~/fossil/demo$ ls
clob.c clob.h clobz.c _FOSSIL_ mkdep.c test-clob.c
tokenize_path.c tokenize_path.h vappendf.c vappendf.h
Fossil doesn't know about those files yet. Telling fossil about a new file is a two-step process. First we add the file to the repository, then we commit the file. This is a familiar process for anyone who's worked with SCM systems before:
stephan@ludo:~/fossil/demo$ fossil add *.{c,h}
stephan@ludo:~/fossil/demo$ fossil commit -m "egg"
New_Version: d1296b4a08b9f8b943bb6c73698e51eed23f8f91
We now have a working repository! The file demo.fossil is the central storage, and we can share it amongst an arbitrary number of trees. As a silly example:
stephan@ludo:~/fossil/demo$ cd ~/fossil stephan@ludo:~/fossil$ mkdir demo2 stephan@ludo:~/fossil$ cd demo2 stephan@ludo:~/fossil/demo2$ fossil open ../demo.fossil ADD clob.c ADD clob.h ADD clobz.c ADD mkdep.c ADD test-clob.c ADD tokenize_path.c ADD tokenize_path.h ADD vappendf.c
You may modify the repository (e.g. add, remove, or commit files) from both working directories, and doing so might be useful when working on a branch or experimental code.
Making your repository available over the web is trivial to do. We assume you have some web space where you can store your fossil file and run a CGI script. If not, then this option is not for you. If you do, then here's how...
Copy copy the fossil repository file to your web server (it doesn't matter where, really).
In your cgi-bin (or equivalent) directory, create a file which looks like this:
#!/path/to/fossil repository: /path/to/my_repo.fossil
Make that script executable, and you're all ready to go:
~/www/cgi-bin> chmod +x myrepo.cgi
Now simply point your browser to http://my.domain/cgi-bin/myrepo.cgi and you should be able to manage the repository from there.
To check out a copy of your remote repository, use the clone command:
stephan@ludo:~/fossil$ fossil clone \ http://MyAccountName:MyAccountPassword@my.domain/cgi-bin/myrepo.cgi
Note that you should pass your fossil login name and password (as set via local server mode) during the clone - that ensures that fossil won't ask you for it on each commit!
A clone is a local copy of a remote repository, and can be opened just like a local one (as shown above). It is treated identically to your local repository, with one very important difference. When you commit changes to a cloned remote repository, they will be pushed back to the remote repository. If you have autosync on then this sync happens automatically, otherwise you will need to use the pull command to get remote changes and the push command to push your local commits to the remote repository. You must of course have authorization to commit changes (access is configured via the Admin/Users page mentioned above).
You may always use the server or ui commands to browse a cloned repository. You can even edit create or wiki entries, etc., and they will be pushed to the remote side the next time you push data to the remote.