Fossil SCM

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

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button