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