initial commitHEADmaster

1 files changed, 163 insertions, 0 deletions

diff --git a/www/newrepo.wiki b/www/newrepo.wiki
new file mode 100644
index 0000000..fef3716
--- /dev/null
+++ b/www/newrepo.wiki
@@ -0,0 +1,163 @@
+<title>How To Create A New Fossil Repository</title>
+
+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.
+
+The first thing we need to do is create a fossil repository file:
+
+<verbatim>
+$ 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>
+$ 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.
+
+<div class="sidebar">
+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.
+</div>
+
+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>
+$ mkdir demo
+$ cd demo
+$ fossil open ../demo.fossil
+</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. Under Linux, the BSDs or
+macOS, this will instead be called <tt>.fslckout</tt>. 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>
+$ cp ../csnip/*.{c,h} .
+$ ls
+clob.c  clob.h  clobz.c  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>
+$ fossil add *.{c,h}
+$ 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>
+$ cd ~/fossil
+$ mkdir demo2
+$ cd 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 the fossil repository file to your web server (it doesn't matter
+where, really, but it "should" be unreachable by web browser traffic).
+
+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>
+$ chmod +x ~/www/cgi-bin/myrepo.cgi
+</verbatim>
+
+Now simply point your browser to
+<tt>https://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>
+$ fossil clone \
+  https://MyAccountName:MyAccountPassword@my.domain/cgi-bin/myrepo.cgi
+</verbatim>
+
+If you do not provide your password in the URL, fossil will
+interactively prompt you for it.
+
+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.