HOWTO: creating a new repository

<h1>HOWTO: creating a new repository</h1>

<p> The [/doc/tip/www/quickstart.wiki|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.</p>

The first thing we need to do is create a fossil repository file:

<verbatim>
stephan@ludo:~/fossil$ fossil new demo.fossil
project-id: 9d8ccff5671796ee04e60af6932aa7788f0a990a
server-id:  145fe7d71e3b513ac37ac283979d73e12ca04bfe
admin-user: stephan (initial password is ******)
</verbatim>

The numbers it spits out are unimportant (they are version
numbers).

Now we have an empty repository file named <tt>demo.fossil</tt>.
There is nothing magical about the extension <tt>.fossil</tt> - 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:

<verbatim>
stephan@ludo:~/fossil$ fossil ui demo.fossil
</verbatim>

The <tt>ui</tt> command starts up a server (with an optional <tt>-port
NUMBER</tt> 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.

<blockquote>
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.
</blockquote>

The next thing we need to do is <em>open</em> the repository. To do so
we create a working directory and then <tt>cd</tt> to it:

<verbatim>
stephan@ludo:~/fossil$ mkdir demo
stephan@ludo:~/fossil$ cd demo
stephan@ludo:~/fossil/demo$ fossil open ../demo.fossil
stephan@ludo:~/fossil/demo$  
</verbatim>

That creates a file called <tt>_FOSSIL_</tt> 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.

<verbatim>
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
</verbatim>

Fossil doesn't know about those files yet. Telling fossil about
a new file is a two-step process. First we <em>add</em> the file
to the repository, then we <em>commit</em> the file. This is a familiar
process for anyone who's worked with SCM systems before:

<verbatim>
stephan@ludo:~/fossil/demo$ fossil add *.{c,h}
stephan@ludo:~/fossil/demo$ fossil commit -m "egg"
New_Version: d1296b4a08b9f8b943bb6c73698e51eed23f8f91
</verbatim>

We now have a working repository! The file <tt>demo.fossil</tt>
is the central storage, and we can share it amongst an arbitrary
number of trees. As a silly example:

<verbatim>
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
</verbatim>

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 <tt>cgi-bin</tt> (or equivalent) directory, create a file
which looks like this:

<verbatim>
#!/path/to/fossil
repository: /path/to/my_repo.fossil
</verbatim>

Make that script executable, and you're all ready to go:

<verbatim>
~/www/cgi-bin> chmod +x myrepo.cgi
</verbatim>

Now simply point your browser to
<tt>http://my.domain/cgi-bin/myrepo.cgi</tt> and you should
be able to manage the repository from there.

To check out a copy of your remote repository, use the
<em>clone</em> command:

<verbatim>
stephan@ludo:~/fossil$ fossil clone \
  http://MyAccountName:MyAccountPassword@my.domain/cgi-bin/myrepo.cgi
</verbatim>

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 <tt>autosync</tt> on then this sync
happens automatically, otherwise you will need to use the
<em>pull</em> command to get remote changes and the <em>push</em>
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 <em>server</em> or <em>ui</em> 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.