SHA1 Hash:	a5f1c79f28b46b249b5316c6d7b66d92741925d5
Date:	2008-05-20 15:45:58
User:	stephan
Comment:	new HOWTO: setting up a repo
Timelines:	ancestors | descendants | both | trunk
Other Links:	files | ZIP archive | manifest

• branch=trunk inherited from [a28c83647d]
• sym-trunk inherited from [a28c83647d]

Added www/newrepo.wiki version [5136040a41]

@@ -1,1 +1,163 @@
+<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 (no password set yet!)
+baseline:   84e81a150535f031722f815d59c0c5e96ab7f122
+</verbatim>
+
+The numbers it spits out are unimportant (they are version
+numbers). It gets the admin-user name from your $USER environment
+variable, so you can override this by setting that variable before
+calling fossil, like so:
+
+<verbatim>
+stephan@ludo:~/fossil$ USER=myAlias fossil new demo.fossil
+</verbatim>
+
+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 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 laying 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 repo, 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...
+
+The first thing you need to do is run fossil as a local server so
+that you can configure the access rights to your repo:
+
+<verbatim>
+stephan@ludo:~/fossil/demo$ fossil ui
+</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 Setup menu, then the Users link, and
+set your password and grant your account all access priviledges. (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.
+
+Now 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
+in the 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 Setup/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 the remote.