1<title>How To Create A New Fossil Repository</title> 2 3<p> The [/doc/tip/www/quickstart.wiki|quickstart guide] explains how 4to get up and running with fossil. But once you're running, what can 5you do with it? This document will walk you through the process of 6creating a fossil repository, populating it with files, and then 7sharing it over the web.</p> 8 9The first thing we need to do is create a fossil repository file: 10 11<verbatim> 12stephan@ludo:~/fossil$ fossil new demo.fossil 13project-id: 9d8ccff5671796ee04e60af6932aa7788f0a990a 14server-id: 145fe7d71e3b513ac37ac283979d73e12ca04bfe 15admin-user: stephan (initial password is ******) 16</verbatim> 17 18The numbers it spits out are unimportant (they are version 19numbers). 20 21Now we have an empty repository file named <tt>demo.fossil</tt>. 22There is nothing magical about the extension <tt>.fossil</tt> - it's 23just a convention. You may name your files anything you like. 24 25The first thing we normally want to do is to run fossil as a local server so 26that you can configure the access rights to the repo: 27 28<verbatim> 29stephan@ludo:~/fossil$ fossil ui demo.fossil 30</verbatim> 31 32The <tt>ui</tt> command starts up a server (with an optional <tt>-port 33NUMBER</tt> argument) and launches a web browser pointing at the 34fossil server. From there it takes just a few moments to configure the 35repo. Most importantly, go to the Admin menu, then the Users link, and 36set your account name and password, and grant your account all access 37privileges. (I also like to grant Clone access to the anonymous user, 38but that's personal preference.) 39 40Once you are done, kill the fossil server (with Ctrl-C or equivalent) 41and close the browser window. 42 43<blockquote> 44Tip: it is not strictly required to configure a repository 45this way, but if you are going to share a repo over the net then it 46is highly recommended. If you are only going to work with the repo 47locally, you can skip the configuration step and do it later if 48you decide you want to share your repo. 49</blockquote> 50 51The next thing we need to do is <em>open</em> the repository. To do so 52we create a working directory and then <tt>cd</tt> to it: 53 54<verbatim> 55stephan@ludo:~/fossil$ mkdir demo 56stephan@ludo:~/fossil$ cd demo 57stephan@ludo:~/fossil/demo$ fossil open ../demo.fossil 58stephan@ludo:~/fossil/demo$ 59</verbatim> 60 61That creates a file called <tt>_FOSSIL_</tt> in the current 62directory, and this file contains all kinds of fossil-related 63information about your local repository. You can ignore it 64for all purposes, but be sure not to accidentally remove it 65or otherwise damage it - it belongs to fossil, not you. 66 67The next thing we need to do is add files to our repository. As it 68happens, we have a few C source files lying around, which we'll 69simply copy into our working directory. 70 71<verbatim> 72stephan@ludo:~/fossil/demo$ cp ../csnip/*.{c,h} . 73stephan@ludo:~/fossil/demo$ ls 74clob.c clob.h clobz.c _FOSSIL_ mkdep.c test-clob.c 75tokenize_path.c tokenize_path.h vappendf.c vappendf.h 76</verbatim> 77 78Fossil doesn't know about those files yet. Telling fossil about 79a new file is a two-step process. First we <em>add</em> the file 80to the repository, then we <em>commit</em> the file. This is a familiar 81process for anyone who's worked with SCM systems before: 82 83<verbatim> 84stephan@ludo:~/fossil/demo$ fossil add *.{c,h} 85stephan@ludo:~/fossil/demo$ fossil commit -m "egg" 86New_Version: d1296b4a08b9f8b943bb6c73698e51eed23f8f91 87</verbatim> 88 89We now have a working repository! The file <tt>demo.fossil</tt> 90is the central storage, and we can share it amongst an arbitrary 91number of trees. As a silly example: 92 93<verbatim> 94stephan@ludo:~/fossil/demo$ cd ~/fossil 95stephan@ludo:~/fossil$ mkdir demo2 96stephan@ludo:~/fossil$ cd demo2 97stephan@ludo:~/fossil/demo2$ fossil open ../demo.fossil 98ADD clob.c 99ADD clob.h 100ADD clobz.c 101ADD mkdep.c 102ADD test-clob.c 103ADD tokenize_path.c 104ADD tokenize_path.h 105ADD vappendf.c 106</verbatim> 107 108You may modify the repository (e.g. add, remove, or commit files) from 109both working directories, and doing so might be useful when working on 110a branch or experimental code. 111 112Making your repository available over the web is trivial to do. We 113assume you have some web space where you can store your fossil file 114and run a CGI script. If not, then this option is not for you. If 115you do, then here's how... 116 117Copy copy the fossil repository file to your web server (it doesn't 118matter where, really). 119 120In your <tt>cgi-bin</tt> (or equivalent) directory, create a file 121which looks like this: 122 123<verbatim> 124#!/path/to/fossil 125repository: /path/to/my_repo.fossil 126</verbatim> 127 128Make that script executable, and you're all ready to go: 129 130<verbatim> 131~/www/cgi-bin> chmod +x myrepo.cgi 132</verbatim> 133 134Now simply point your browser to 135<tt>http://my.domain/cgi-bin/myrepo.cgi</tt> and you should 136be able to manage the repository from there. 137 138To check out a copy of your remote repository, use the 139<em>clone</em> command: 140 141<verbatim> 142stephan@ludo:~/fossil$ fossil clone \ 143 http://MyAccountName:MyAccountPassword@my.domain/cgi-bin/myrepo.cgi 144</verbatim> 145 146Note that you should pass your fossil login name and password (as set 147via local server mode) during the clone - that ensures that fossil 148won't ask you for it on each commit! 149 150A clone is a local copy of a remote repository, and can be opened just 151like a local one (as shown above). It is treated identically to your 152local repository, with one very important difference. When you commit 153changes to a cloned remote repository, they will be pushed back to the 154remote repository. If you have <tt>autosync</tt> on then this sync 155happens automatically, otherwise you will need to use the 156<em>pull</em> command to get remote changes and the <em>push</em> 157command to push your local commits to the remote repository. You must 158of course have authorization to commit changes (access is configured 159via the Admin/Users page mentioned above). 160 161You may always use the <em>server</em> or <em>ui</em> commands to 162browse a cloned repository. You can even edit create or wiki entries, 163etc., and they will be pushed to the remote side the next time you 164push data to the remote. 165