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